Pointer¶

Overview¶

A pointer is an abstraction that includes a mouse and touch points (and possibly keys). The mouse is a single pointer, and each finger (for touch) is a pointer.

Listeners that can be added to the pointer, and events will be fired on these listeners before any listeners are fired on the Node structure. This is typically very useful for tracking dragging behavior (where the pointer may cross areas where the dragged node is not directly below the pointer any more).

A valid listener should be an object. If a listener has a property with a Scenery event name (e.g. 'down' or 'touchmove'), then that property will be assumed to be a method and will be called with the Scenery event (like normal input listeners, see Node.addInputListener).

Pointers can have one active "attached" listener, which is the main handler for responding to the events. This helps when the main behavior needs to be interrupted, or to determine if the pointer is already in use. Additionally, this can be used to prevent pointers from dragging or interacting with multiple components at the same time.

A listener may have an interrupt() method that will attemp to interrupt its behavior. If it is added as an attached listener, then it must have an interrupt() method.

@author Jonathan Olson <jonathan.olson@colorado.edu>

Class Pointer¶

import { Pointer } from 'scenerystack/scenery';

Constructor¶

new Pointer( initialPoint : Vector2, type : PointerType )¶

Instance Methods¶

setCursor( cursor : string | null ) : this¶

Sets a cursor that takes precedence over cursor values specified on the pointer's trail.

Typically this can be set when a drag starts (and returned to null when the drag ends), so that the cursor won't change while dragging (regardless of what is actually under the pointer). This generally will only apply to the Mouse subtype of Pointer.

NOTE: Consider setting this only for attached listeners in the future (or have a cursor field on pointers).

getCursor() : string | null¶

Returns the current cursor override (or null if there is one). See setCursor().

addInputListener( listener : TInputListener, attach? : boolean )¶

Adds an input listener to this pointer. If the attach flag is true, then it will be set as the "attached" listener.

removeInputListener( listener : TInputListener )¶

Removes an input listener from this pointer.

getAttachedListener() : TAttachableInputListener | null¶

Returns the listener attached to this pointer with attach(), or null if there isn't one.

isAttached() : boolean¶

Returns whether this pointer has an attached (primary) listener.

isTouchLike() : boolean¶

Some pointers are treated differently because they behave like a touch. This is not exclusive to `Touch and touch events though. See https://github.com/phetsims/scenery/issues/1156

interruptAttached()¶

If there is an attached listener, interrupt it.

After this executes, this pointer should not be attached.

interruptAll()¶

Interrupts all listeners on this pointer.

updatePoint( point : Vector2, eventName ) : boolean¶

@returns - Whether the point changed

hasPointChanged( point : Vector2 ) : boolean¶

(protected)

Determines whether the point of the pointer has changed (used in mouse/touch/pen).

addIntent( intent : Intent )¶

Adds an Intent Pointer. By setting Intent, other listeners in the dispatch phase can react accordingly. Note that the Intent can be changed by listeners up the dispatch phase or on the next press. See Intent enum for valid entries.

removeIntent( intent : Intent )¶

Remove an Intent from the Pointer. See addIntent for more information.

hasIntent( intent : Intent ) : boolean¶

Returns whether or not this Pointer has been assigned the provided Intent.

reserveForDrag()¶

Set the intent of this Pointer to indicate that it will be used for mouse/touch style dragging, indicating to other listeners in the dispatch phase that behavior may need to change. Adds a listener to the pointer (with self removal) that clears the intent when the pointer receives an "up" event. Should generally be called on the Pointer in response to a down event.

reserveForKeyboardDrag()¶

Set the intent of this Pointer to indicate that it will be used for keyboard style dragging, indicating to other listeners in the dispatch that behavior may need to change. Adds a listener to the pointer (with self removal) that clears the intent when the pointer receives a "keyup" or "blur" event. Should generally be called on the Pointer in response to a keydown event.

onGotPointerCapture()¶

This is called when a capture starts on this pointer. We request it on pointerstart, and if received, we should generally receive events outside the self.

onLostPointerCapture()¶

This is called when a capture ends on this pointer. This happens normally when the user releases the pointer above the sim or outside, but also in cases where we have NOT received an up/end.

See https://github.com/phetsims/scenery/issues/1186 for more information. We'll want to interrupt the pointer on this case regardless,

dispose()¶

Releases references so it can be garbage collected.

toString() : string¶

Instance Properties¶

point : Vector2¶

The location of the pointer in the global coordinate system.

type : PointerType¶

(readonly)

Each Pointer subtype should implement a "type" field that can be checked against for scenery input.

trail : Trail | null¶

The trail that the pointer is currently over (if it has yet been registered). If the pointer has not yet registered a trail, it may be null. If the pointer wasn't over any specific trail, then a trail with only the display's rootNode will be set.

inputEnabledTrail : Trail | null¶

The subset of Pointer.trail that is Node.inputEnabled. See Trail.getLastInputEnabledIndex() for details. This is kept separately so that it can be detected when inputEnabled changes.

isDownProperty : TProperty<boolean>¶

@deprecated Whether this pointer is 'down' (pressed). Will be phased out in https://github.com/phetsims/scenery/issues/803 to something that is specific for the actual mouse/pen button (since this doesn't generalize well to the left/right mouse buttons).

attachedProperty : TProperty<boolean>¶

Whether there is a main listener "attached" to this pointer. This signals that the listener is "doing" something with the pointer, and that it should be interrupted if other actions need to take over the pointer behavior.

Static Properties¶

PointerIO : IOType¶

(readonly)

Pointer is not a PhetioObject and not instrumented, but this type is used for toStateObject in Input

Class Intent¶

import { Intent } from 'scenerystack/scenery';

Static Properties¶

DRAG : Intent¶

(readonly)

listener attached to the pointer will be used for dragging

KEYBOARD_DRAG : Intent¶

(readonly)

listener attached to pointer is for dragging with a keyboard

enumeration : Enumeration¶

(readonly)

Source Code¶

See the source for Pointer.ts in the scenery repository.