pointer/dragValue

Interfaces

AxisOptions

Defined in: dom/src/pointer/dragValue.ts:20

How the 0-1 travel of one axis maps onto a value.

Extends ValueRange so that a drag and an applyDelta nudge from a wheel or an arrow key share one description of the scaling.

Extends

• ValueRange

Properties

max

max: number;

Defined in: functions/dist/index.d.ts:243

Inherited from

ValueRange.max

min

min: number;

Defined in: functions/dist/index.d.ts:242

Inherited from

ValueRange.min

reverse?

optional reverse?: boolean;

Defined in: dom/src/pointer/dragValue.ts:29

Flip the axis so that its far end is min.

Positions follow the screen: x grows to the right, y downwards. A vertical slider whose maximum is at the top therefore reverses its y axis.

Default

false

scale?

optional scale?: Scale;

Defined in: functions/dist/index.d.ts:253

How the value is distributed across the travel.

Default

linearScale

Inherited from

ValueRange.scale

step?

optional step?: number;

Defined in: functions/dist/index.d.ts:247

Rounding applied to the value. Left unrounded when omitted.

Inherited from

ValueRange.step

---

DragValueInstance

Defined in: dom/src/pointer/dragValue.ts:259

Properties

destroy

destroy: () => void;

Defined in: dom/src/pointer/dragValue.ts:267

Returns

void

update

update: (options) => void;

Defined in: dom/src/pointer/dragValue.ts:266

Replace the given options. Lets a wrapper feed fresh values in without tearing down the listeners, which would abort a drag in progress.

mapping is fixed for the lifetime of the instance and is ignored here.

Parameters

Parameter	Type
options	Partial<DragValueOptions>

Returns

void

---

DragValueMapping

Defined in: dom/src/pointer/dragValue.ts:45

Turns pointer movement into a position on each axis: 0 is the min end of the travel and 1 the max end, before reverse and the scaling of AxisOptions are applied.

A mapping holds the state of the drag in progress, so an instance belongs to a single createDragValue instance.

Properties

move

move: (state, context) => XY<number> | null;

Defined in: dom/src/pointer/dragValue.ts:51

Parameters

Parameter	Type
state	DragState
context	MappingContext

Returns

XY<number> | null

start

start: (state, context) => XY<number> | null;

Defined in: dom/src/pointer/dragValue.ts:50

Parameters

Parameter	Type
state	DragState
context	MappingContext

Returns

XY<number> | null

the position, or null when it cannot be determined and the event should be ignored.

---

DragValueOptions

Defined in: dom/src/pointer/dragValue.ts:214

Properties

axis

axis: 
  | AxisOptions
  | readonly [AxisOptions, AxisOptions];

Defined in: dom/src/pointer/dragValue.ts:216

Scaling of each axis; a single value applies to both.

cursor?

optional cursor?: string;

Defined in: dom/src/pointer/dragValue.ts:242

See

DragOptions.cursor

getValue?

optional getValue?: () => XY<number>;

Defined in: dom/src/pointer/dragValue.ts:225

The current value of each axis. Read when a drag starts, by mappings that move the value relative to it, such as relativeMapping.

Returns

XY<number>

mapping

mapping: DragValueMapping;

Defined in: dom/src/pointer/dragValue.ts:219

How pointer movement becomes a position.

onChange?

optional onChange?: (value, state) => void;

Defined in: dom/src/pointer/dragValue.ts:254

Parameters

Parameter	Type
value	XY<number>
state	DragState

Returns

void

onDragEnd?

optional onDragEnd?: (value, state) => void;

Defined in: dom/src/pointer/dragValue.ts:256

Parameters

Parameter	Type
value	XY<number>
state	DragState

Returns

void

onDragStart?

optional onDragStart?: (value, state) => void;

Defined in: dom/src/pointer/dragValue.ts:255

Parameters

Parameter	Type
value	XY<number>
state	DragState

Returns

void

pointerLock?

optional pointerLock?: boolean;

Defined in: dom/src/pointer/dragValue.ts:250

See

DragOptions.pointerLock

Only for a mapping that moves the value relative to where it stood, such as relativeMapping. elementMapping reads the pointer position, and there is none while it is locked.

shouldStart?

optional shouldStart?: (event) => boolean;

Defined in: dom/src/pointer/dragValue.ts:252

Parameters

Parameter	Type
event	PointerEvent

Returns

boolean

See

DragOptions.shouldStart

threshold?

optional threshold?: number;

Defined in: dom/src/pointer/dragValue.ts:240

See

DragOptions.threshold

updateOnPointerDown?

optional updateOnPointerDown?: boolean;

Defined in: dom/src/pointer/dragValue.ts:237

Report the value on pointer down, before any movement.

Enable it where the pointer position is the value, so that a plain click jumps to it. Leave it off where the element being dragged is an object in its own right, so that grabbing its edge does not shift it under the pointer.

Default

false

---

MappingContext

Defined in: dom/src/pointer/dragValue.ts:33

Where the value of each axis currently sits, as a position (see DragValueMapping).

Properties

position

position: () => XY<number>;

Defined in: dom/src/pointer/dragValue.ts:34

Returns

XY<number>

Functions

createDragValue()

function createDragValue(element, options): DragValueInstance;

Defined in: dom/src/pointer/dragValue.ts:277

Drive a value with a pointer drag.

Combines createDrag with the scaling of @tremolo-ui/functions: the mapping decides where the pointer sits on the 0-1 travel of each axis, and the axis options turn that into a value.

Parameters

Parameter	Type
element	Element
options	DragValueOptions

Returns

DragValueInstance

---

elementMapping()

function elementMapping(getElement, __namedParameters?): DragValueMapping;

Defined in: dom/src/pointer/dragValue.ts:61

Map the pointer onto the bounding rect of an element: the value is the position pointed at, so the middle of the element is 0.5.

The element is read on every event, so it may be mounted after the drag is set up and may change size while a drag is in progress.

Parameters

Parameter	Type	Description
getElement	() => Element | null | undefined	-
__namedParameters	{ sensitivity?: (state) => number; }	-
__namedParameters.sensitivity?	(state) => number	How much the movement counts, read on every move. 1 is the pointer position itself; 0.1 makes the same movement cover a tenth of the travel, which is what a fine-adjustment modifier wants. Anything but 1 turns the mapping relative: the value stops being the position pointed at and starts being where it stood when the sensitivity changed, plus the movement since. The pointer and the value stay apart for the rest of the drag rather than snapping back together when the key is released, since snapping would move the value nobody asked to move.

Returns

DragValueMapping

---

relativeMapping()

function relativeMapping(__namedParameters?): DragValueMapping;

Defined in: dom/src/pointer/dragValue.ts:150

Move the value away from where it stood when the drag started, by the distance dragged. The pointer position itself carries no meaning, so the value can be adjusted from anywhere on the screen.

Parameters

Parameter	Type	Description
__namedParameters	{ pixelRange?: number | readonly [number, number]; sensitivity?: (state) => number; }	-
__namedParameters.pixelRange?	number | readonly [number, number]	Pixels of movement that span the whole range. Default 100
__namedParameters.sensitivity?	(state) => number	How much the movement counts, read on every move. 1 is pixelRange as given; 0.1 makes the same movement cover a tenth of the range, which is what a fine-adjustment modifier wants. Changing it mid-drag does not disturb the value: the travel so far is folded into the origin and measuring starts again from there.

Returns

DragValueMapping