pointer/drag
Interfaces
DragInstance
Defined in: dom/src/pointer/drag.ts:94
Properties
destroy
destroy: () => void;
Defined in: dom/src/pointer/drag.ts:103
Returns
void
update
update: (options) => void;
Defined in: dom/src/pointer/drag.ts:102
Replace the given options. Lets a wrapper feed fresh handlers in without tearing down the listeners, which would abort a drag in progress.
multiPointer is fixed for the lifetime of the instance and is ignored
here.
Parameters
| Parameter | Type |
|---|---|
options | DragOptions |
Returns
void
Type Aliases
DragOptions
type DragOptions = object;
Defined in: dom/src/pointer/drag.ts:19
Properties
cursor?
optional cursor?: string;
Defined in: dom/src/pointer/drag.ts:39
CSS cursor to show while dragging. Applied to the element itself: pointer capture keeps it in effect even once the pointer leaves the element, so there is no need to touch the document.
With DragOptions.multiPointer it is set for the first pointer and restored once the last one is up.
multiPointer?
optional multiPointer?: boolean;
Defined in: dom/src/pointer/drag.ts:87
Track every pointer that goes down on the element, rather than only the
first. Each one gets its own onDragStart / onDrag / onDragEnd and
carries its own totals; DragState.pointerId says which is which.
Fixed for the lifetime of the instance: switching part way through a drag
has no meaning, so update() ignores it.
Default
false
onDrag?
optional onDrag?: (state) => void;
Defined in: dom/src/pointer/drag.ts:90
Parameters
| Parameter | Type |
|---|---|
state | DragState |
Returns
void
onDragEnd?
optional onDragEnd?: (state) => void;
Defined in: dom/src/pointer/drag.ts:91
Parameters
| Parameter | Type |
|---|---|
state | DragState |
Returns
void
onDragStart?
optional onDragStart?: (state) => void;
Defined in: dom/src/pointer/drag.ts:89
Parameters
| Parameter | Type |
|---|---|
state | DragState |
Returns
void
pointerLock?
optional pointerLock?: boolean;
Defined in: dom/src/pointer/drag.ts:75
Hide the pointer and read its movement directly, instead of following it around the screen.
A relative drag — a knob, a stepper — does not care where the pointer is, only how far it moved, and letting it wander has two costs: the cursor ends up far from what it is holding, and the drag stops at the edge of the screen, where the operating system pins the pointer and the coordinates stop changing. A fine drag reaches that edge quickly.
Not for a drag whose value is the position pointed at — anything on
elementMapping. clientX / clientY freeze while the pointer is
locked, so there is no position left to read.
The request needs a user gesture, which a pointerdown is, but it can still
be refused; the drag then carries on as an ordinary one. Read on
pointerdown, so update() reaches the next drag rather than the current.
Default
false
shouldStart?
optional shouldStart?: (event) => boolean;
Defined in: dom/src/pointer/drag.ts:53
Decide whether a pointerdown starts a drag at all.
Checked before anything else — before the pointer is captured — so declining here leaves the whole gesture to whatever else is listening. Deciding later would be too late: the capture has already been taken from the element that was going to handle it.
The use for it is a drag on a container that also holds draggable things of its own, such as a rubber-band selection that must not begin on top of one of the objects it would select.
Parameters
| Parameter | Type |
|---|---|
event | PointerEvent |
Returns
boolean
threshold?
optional threshold?: number;
Defined in: dom/src/pointer/drag.ts:29
Minimum movement in pixels before onDrag fires. Movement below it is
carried over to the next event rather than discarded, so a slow drag still
reports once it adds up.
Prevents onDrag from firing on, for example, a double click.
Default
0
DragState
type DragState = object;
Defined in: dom/src/pointer/drag.ts:1
Properties
clientX
clientX: number;
Defined in: dom/src/pointer/drag.ts:9
Pointer position in viewport coordinates.
clientY
clientY: number;
Defined in: dom/src/pointer/drag.ts:10
deltaX
deltaX: number;
Defined in: dom/src/pointer/drag.ts:6
Movement since the previous event, in screen coordinates.
deltaY
deltaY: number;
Defined in: dom/src/pointer/drag.ts:7
event
event: PointerEvent;
Defined in: dom/src/pointer/drag.ts:16
pointerId
pointerId: number;
Defined in: dom/src/pointer/drag.ts:15
Which pointer this is. Always the same value for one drag; with DragOptions.multiPointer it tells concurrent drags apart.
x
x: number;
Defined in: dom/src/pointer/drag.ts:3
Total movement from the drag start, in screen coordinates.
y
y: number;
Defined in: dom/src/pointer/drag.ts:4
Functions
createDrag()
function createDrag(element, options?): DragInstance;
Defined in: dom/src/pointer/drag.ts:163
Track a pointer drag on an element.
Uses Pointer Events only, and pointer capture so that the drag keeps working
once the pointer leaves the element. For the lifetime of the instance the
element gets touch-action: none so that touch dragging does not scroll the
page, plus user-select: none so that a long press does not start a text
selection instead.
One pointer at a time by default; see DragOptions.multiPointer.
Parameters
| Parameter | Type |
|---|---|
element | Element |
options | DragOptions |