UIGestureRecognizer: began event
The began event fires the moment a continuous gesture is recognized.
Syntax
addEventListener('began', (event) => { })Event object
The event object's type is UIGestureRecognizerEvent. Besides type and target, it carries two read-only fields:
| Field | Type | Meaning |
|---|---|---|
location | CGPoint or null | The position of the gesture, in the coordinate system of the view the recognizer is attached to, in pt. With several fingers, it is their center point. To convert to another view, use the view's convertPoint() |
numberOfTouches | Number | The number of fingers taking part in the gesture when the event occurred |
The event objects of three kinds of recognizer each carry two more read-only fields, all values as of the moment the event occurred:
| Recognizer | Event object type | Field | Type | Meaning |
|---|---|---|---|---|
UIPanGestureRecognizer, UIScreenEdgePanGestureRecognizer | UIPanGestureRecognizerEvent | translation | CGPoint | How far the finger has moved from the start of the gesture up to this event, in the coordinate system of the view the recognizer is attached to, in pt |
velocity | CGPoint | The speed of the finger's movement, in the same coordinate system, in pt per second | ||
UIPinchGestureRecognizer | UIPinchGestureRecognizerEvent | scale | Number | The distance between the two fingers as a multiple of the distance at the start of the gesture |
velocity | Number | How much scale changes per second | ||
UIRotationGestureRecognizer | UIRotationGestureRecognizerEvent | rotation | Number | The angle turned since the start of the gesture, in radians |
velocity | Number | The speed of rotation, in radians per second |
The callback parameter is declared as Event; to read these fields, cast the type, as in the example. These values can only be read from the event object: callbacks run later than the gesture, so reading the recognizer afterward does not give the values as they were.
Not cancelable: preventDefault() has no effect. The event fires only on the recognizer itself and is not passed to the view or its parent views.
When it fires
| Recognizer | When it fires |
|---|---|
UILongPressGestureRecognizer | When the finger has been held for minimumPressDuration, 0.5 seconds by default (measured) |
UIPanGestureRecognizer, UIScreenEdgePanGestureRecognizer | When the finger touches down and moves a short distance |
UIPinchGestureRecognizer, UIRotationGestureRecognizer | When a two-finger pinch or rotation is recognized |
UITapGestureRecognizer, UISwipeGestureRecognizer | Never. They fire only ended |
- Once per gesture. It is followed by zero or more
changedevents, and finallyendedorcancelled. - Does not fire when the gesture is not recognized. For example, a long press lifted before the time is up, or a finger that moves more than
allowableMovementbefore the time is up. - Firing for pan, pinch, rotation, and screen-edge pan is not verified in the simulator.
Examples
const card = new UIView();
const press = new UILongPressGestureRecognizer();
press.addEventListener('began', (e) => {
const { location } = /** @type {UIGestureRecognizerEvent} */ (e);
if (location !== null) {
console.log('Held down', location.x, location.y);
}
});
card.addGestureRecognizer(press);Effect: Hold card for 0.5 seconds and the console prints Held down followed by the finger's coordinates within card.
Corresponding iOS API
UIGestureRecognizerStateBegan. Natively, the action method receives every phase and checks state inside the method; here you listen for 'began'.