UIGestureRecognizer: addEventListener() method
The addEventListener() method registers a callback for an event on the recognizer. When the recognizer recognizes a gesture, or the gesture progresses or ends, the event fires and the callback runs.
Syntax
addEventListener(type, callback)
addEventListener(type, callback, { once })Parameters
type
The event name, a string: one of began, changed, ended, and cancelled. Event names are the phases of the gesture; for which gestures fire which events, see Events.
There are no event names such as 'tap', 'longpress', or 'swipe'. For taps and swipes, listen for 'ended'; for long presses, listen for 'began'.
Listening for any other name does not throw: it is treated as a custom event and fires only when you dispatch it yourself with dispatchEvent().
callback
The callback function, which receives the event object; see each event page for its type. Passing null does nothing.
options.once
Optional, a boolean. true means the callback is removed automatically after running once. Defaults to false.
Return value
None (undefined).
Exceptions
TypeError
callback is neither a function nor null: Failed to execute 'addEventListener': parameter 2 is not of type 'Function'.
Description
- The listener goes on the recognizer, not on the view. The recognizer must also be attached to a view with the view's
addGestureRecognizer()to receive touches. The order of listening and attaching does not matter. - Registering the same function for the same event name more than once counts only once.
- Callbacks run only after the gesture happens; see Callbacks cannot read the state as it was.
- An exception thrown in a callback does not affect the recognizer, and the other callbacks for the same event still run. The exception fires
erroronapplication; if no listener cancels it, the console prints a log line starting withUncaught.
Examples
const card = new UIView();
const tap = new UITapGestureRecognizer();
tap.addEventListener('ended', () => {
console.log('Tapped');
});
card.addGestureRecognizer(tap);Effect: Tap card once and the console prints Tapped.
Corresponding iOS API
-[UIGestureRecognizer addTarget:action:]. Natively, one action method receives every phase of the gesture and tells them apart with state; here each phase is an event name.