Skip to content

UIGestureRecognizerEvent ​

UIGestureRecognizerEvent represents an event of a gesture recognizer: a gesture about to begin, beginning, changing, ending, or being canceled.

It carries the gesture position and the number of fingers involved. The began, changed, ended, and cancelled events of the pan, pinch, and rotation recognizers are subclasses of it that carry a few more fields: UIPanGestureRecognizerEvent, UIPinchGestureRecognizerEvent, and UIRotationGestureRecognizerEvent.

Inheritance: Event → UIGestureRecognizerEvent

Constructor ​

UIGestureRecognizerEvent()

Creates a UIGestureRecognizerEvent. The runtime creates one itself when it fires the events below; app code can use it to build an event object and fire it with dispatchEvent() to try out a listener.

Instance properties ​

Also inherits the properties of Event; the most commonly used are type and target. The properties below are read-only; assigning to them throws TypeError.

PropertyDescription
location read-onlyThe gesture position, in the coordinate system of the recognizer's view
numberOfTouches read-onlyThe number of fingers in the gesture

These properties live on the prototype, not on the event object itself: Object.keys(event) and { ...event } don't include them, so read them one by one. See Events with fields.

Events that use this class ​

ObjectEvents
UIGestureRecognizer and all its subclassesbeforebegin
UITapGestureRecognizer, UILongPressGestureRecognizer, UISwipeGestureRecognizerbegan, changed, ended, cancelled

beforebegin can be canceled: cancelable is true, and calling preventDefault() keeps this gesture from beginning. The others can't be canceled.

The beforebegin of the pan, pinch, and rotation recognizers is this class too, not a subclass: the gesture hasn't begun, so there is no distance moved, scale, or similar value yet.

Examples ​

js
const page = new UIViewController();
const tap = new UITapGestureRecognizer();
tap.addEventListener('beforebegin', (e) => {
  if (e.location !== null && e.location.y < 100) {
    e.preventDefault();
  }
});
tap.addEventListener('ended', (e) => {
  console.log(e instanceof UIGestureRecognizerEvent, e.location?.y);
});
page.view.addGestureRecognizer(tap);

Effect: tapping within the top 100 pt of the page keeps the gesture from beginning, and nothing is printed. Tapping elsewhere prints true and the y of the tap.

Corresponding iOS API ​

A native action method receives the recognizer itself and reads the position and number of fingers from it. Here both are the values at the moment of the event, on the event object.

ObjCJS
[recognizer locationInView:recognizer.view]event.location
recognizer.numberOfTouchesevent.numberOfTouches
Returning NO from gestureRecognizerShouldBegin:Calling preventDefault() in beforebegin

See also ​