UIPanGestureRecognizer
UIPanGestureRecognizer represents a pan (drag) recognizer: it recognizes the gesture when a finger touches down and moves. Use it to make a view follow the finger, or to run a momentum animation based on the velocity when the finger lifts.
Pan is a continuous gesture: began fires once the finger has moved a short distance, changed fires on every move after that, and ended fires when all fingers lift. The event object carries the translation accumulated since the gesture began, translation, and the velocity, velocity.
Panning hasn't been checked with real touches yet. Both the gesture itself and the data on its events are not verified in the simulator.
UIScrollView scrolls using a pan recognizer of its own: its gestureRecognizers contains a UIPanGestureRecognizer (checked in the acceptance tests). The subclass UIScreenEdgePanGestureRecognizer recognizes only pans that start at the edge of the screen.
Inheritance: EventTarget → NSObject → UIGestureRecognizer → UIPanGestureRecognizer
For how to use it, see the guide Responding to gestures.
Constructor
Creates a recognizer for pans with one or more fingers.
Instance properties
It also inherits the properties of UIGestureRecognizer; the commonly used ones are isEnabled, view, and cancelsTouchesInView.
| Property | Description |
|---|---|
minimumNumberOfTouches | The minimum number of fingers that must be down for a pan |
maximumNumberOfTouches | The maximum number of fingers that can be down |
allowedScrollTypesMask | Which kinds of scroll input (mouse wheel, trackpad) also count as a pan |
Instance methods
It also inherits the methods of UIGestureRecognizer.
| Method | Description |
|---|---|
translationInView() | How far the finger has moved since the gesture began, converted to the coordinate system of a given view |
setTranslation() | Sets the accumulated translation to a given value |
velocityInView() | The finger's current velocity, converted to the coordinate system of a given view |
When you call these three methods in an event callback, they read and change the values as of the moment the callback runs. The translation and velocity at the moment the event occurred are on the event object.
Events
The events come from UIGestureRecognizer; listen with addEventListener(). This recognizer fires:
| Event | When it fires |
|---|---|
began | When the finger has moved a short distance and the pan is recognized |
changed | Every time the finger moves after that |
ended | When all fingers lift. velocity is the velocity at the moment of release |
cancelled | When the gesture is interrupted |
Examples
const card = new UIView();
const drag = new UIPanGestureRecognizer();
let start = card.center;
drag.addEventListener('began', () => {
start = card.center;
});
drag.addEventListener('changed', (e) => {
const { translation } = /** @type {UIPanGestureRecognizerEvent} */ (e);
card.center = new CGPoint(start.x + translation.x, start.y + translation.y);
});
card.addGestureRecognizer(drag);Effect: When you press on card and move your finger, card follows the finger. When you lift your finger, it stays where you released it. Not verified in the simulator.
Corresponding iOS API
| ObjC | JS |
|---|---|
[pan translationInView:view] | The event object's translation, or pan.translationInView(view) |
[pan velocityInView:view] | The event object's velocity, or pan.velocityInView(view) |
[pan setTranslation:CGPointZero inView:view] | pan.setTranslation(new CGPoint(0, 0), { inView: view }) |
pan.maximumNumberOfTouches = 2 | pan.maximumNumberOfTouches = 2 |
pan.allowedScrollTypesMask = UIScrollTypeMaskAll | pan.allowedScrollTypesMask = ['discrete', 'continuous'] |
See also
- Responding to gestures: dragging a view and reading the velocity on release
UIScreenEdgePanGestureRecognizer: subclassUIGestureRecognizer: superclass, with the events and shared properties