UIScrollView: beforedragend event
The beforedragend event fires the moment the user lifts their finger after dragging, before dragend. At that point the system has already worked out where the content will come to rest, and a listener can change that stopping position.
Syntax
scroller.addEventListener('beforedragend', (event) => { })Event object
UIScrollViewDragEndEvent. Besides type and target (this scroll view), it carries two fields:
| Field | Type | Readable | Writable | Meaning |
|---|---|---|---|---|
velocity | CGPoint | Yes | No | How fast the content was moving when the finger lifted, in pt per millisecond |
targetContentOffset | CGPoint | Yes | Yes | The contentOffset at which the content will stop, in pt. Its initial value is the stopping position the system computed |
The callback parameter is declared as Event, so cast it to read and write these fields; see the example.
Not cancelable: event.cancelable is false and preventDefault() has no effect. To keep the content where it is, write the current contentOffset to targetContentOffset.
The sign of velocity gives the direction, matching the direction in which contentOffset changes: a positive y means the content is sliding toward a larger contentOffset.y. Not verified with a real finger.
Writing targetContentOffset
- Write a
CGPoint, or a plain object with numericxandy, such as{ x: 0, y: 40 }. After all listeners have run, the content slides to that position and stops. - Writing any other value (a string, an object missing a field,
NaN) does not throw and logs no warning. This time the content stops where the system computed. - If nothing is written, the content stops where the system computed.
- How the content stops when the position written lies outside the content area is not verified in the simulator.
- How the content moves to a changed stopping position when the finger had no velocity on release (
velocityis 0) is not verified in the simulator.
When it fires
- Fires only when the user lifts their finger after dragging. Writing
contentOffsetor callingsetContentOffset()from code does not fire it (from the iOS definition, not verified in the simulator). - Fires on the spot. After firing the event, the system waits for all listeners to finish, then lets the content slide to
targetContentOffset. This differs from the other scroll events: they fire after the change, once the current JS finishes running. - When the event has several listeners, they run in the order they were added. A later listener reads the value an earlier one wrote to
targetContentOffset, and the last value wins. - If a listener throws, the other listeners for the same event still run. The exception fires
erroronapplication. A value written totargetContentOffsetbefore the throw still takes effect; if nothing was written, the content stops where the system computed. - With no listeners, the content stops where the system computed. The same holds after the last listener is removed.
- The firing, the values of both fields, and the position the system stops at after a write are all verified in the acceptance suite: the test asks the scroll view for its stopping position the way the system does when the finger lifts, and asserts the value handed back to the system. How the content slides to the new position under a real dragging finger is not verified with a real finger.
Note: The system waits while listeners run. In a listener, only compute the stopping position; do nothing time-consuming.
Examples
const scroller = new UIScrollView();
const rowHeight = 80;
scroller.addEventListener('beforedragend', (event) => {
const e = /** @type {UIScrollViewDragEndEvent} */ (event);
const y = Math.round(e.targetContentOffset.y / rowHeight) * rowHeight;
e.targetContentOffset = new CGPoint(0, y);
});Effect: after every drag and release, the content stops at a position where contentOffset.y is a multiple of 80. When the system computes a stop at 123, the content stops at 160. The value handed back to the system is verified in the acceptance suite; how the content slides there is not verified with a real finger.
Corresponding iOS API
scrollViewWillEndDragging:withVelocity:targetContentOffset: of UIScrollViewDelegate. The velocity argument is the event's velocity; the targetContentOffset out-parameter becomes the writable targetContentOffset on the event object.
See also
- Stopping on whole rows
dragend: fires right after; read the state after release thereisPagingEnabled: stops at multiples of the visible area, with no listenerdecelerationRate: how far the content slides after release