Skip to content

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:

FieldTypeMeaning
locationCGPoint or nullThe 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()
numberOfTouchesNumberThe 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:

RecognizerEvent object typeFieldTypeMeaning
UIPanGestureRecognizer, UIScreenEdgePanGestureRecognizerUIPanGestureRecognizerEventtranslationCGPointHow 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
velocityCGPointThe speed of the finger's movement, in the same coordinate system, in pt per second
UIPinchGestureRecognizerUIPinchGestureRecognizerEventscaleNumberThe distance between the two fingers as a multiple of the distance at the start of the gesture
velocityNumberHow much scale changes per second
UIRotationGestureRecognizerUIRotationGestureRecognizerEventrotationNumberThe angle turned since the start of the gesture, in radians
velocityNumberThe 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 ​

RecognizerWhen it fires
UILongPressGestureRecognizerWhen the finger has been held for minimumPressDuration, 0.5 seconds by default (measured)
UIPanGestureRecognizer, UIScreenEdgePanGestureRecognizerWhen the finger touches down and moves a short distance
UIPinchGestureRecognizer, UIRotationGestureRecognizerWhen a two-finger pinch or rotation is recognized
UITapGestureRecognizer, UISwipeGestureRecognizerNever. They fire only ended
  • Once per gesture. It is followed by zero or more changed events, and finally ended or cancelled.
  • 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 allowableMovement before the time is up.
  • Firing for pan, pinch, rotation, and screen-edge pan is not verified in the simulator.

Examples ​

js
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'.

See also ​