C

HandleInputMode

Show Usages
An IInputMode implementation that can handle a collection of IHandles.
ImplementsInheritance Hierarchy

Remarks

This mode will render a visual representation of IHandles in the CanvasComponent and deal with mouse gestures that drag the visual representations accordingly.

This mode is exclusive by default.

Examples

Typically, the HandleInputMode is installed as child mode of a GraphEditorInputMode and can be retrieved from the handleInputMode property.

Getting the HandleInputMode from its parent input mode
const handleInputMode = mode.handleInputMode

If one needs to execute some code after some items have been moved by the HandleInputMode, he can register a handler to its drag-finished event. The moved items can be retrieved from the affectedItems property:

mode.handleInputMode.addEventListener('drag-finished', () => {
  for (const item of mode.handleInputMode.affectedItems) {
    // these items have been moved
  }
})
The following example shows how to configure touch gestures without long press.
Configure touch gestures without long press
mode.moveViewportInputMode.allowSinglePointerMovement = true
mode.createBendInputMode.beginRecognizerTouch =
  EventRecognizers.TOUCH_PRIMARY_DOWN
mode.createEdgeInputMode.beginRecognizerTouch =
  EventRecognizers.TOUCH_PRIMARY_DOWN
mode.handleInputMode.beginRecognizerTouch =
  EventRecognizers.TOUCH_PRIMARY_DOWN
mode.lassoSelectionInputMode.beginRecognizerTouch =
  EventRecognizers.TOUCH_PRIMARY_DOWN
mode.marqueeSelectionInputMode.beginRecognizerTouch =
  EventRecognizers.TOUCH_PRIMARY_DOWN
mode.moveSelectedItemsInputMode.beginRecognizerTouch =
  EventRecognizers.TOUCH_PRIMARY_DOWN

See Also

Developer's Guide

API

IHandle

Members

Show:

Constructors

HandleInputMode

()
Creates a new mode with no handles initially.

Parameters

See Also

API
handles

Properties

affectedItems

: IEnumerable<IModelItem>
readonly
Gets an immutable snapshot of the IModelItems affected by the currently modified handle gesture.

When the gesture is starting and the currentHandle is initialized, the implementation can register the affected item(s) through the IModelItemCollector instance that is bound to the context available via its lookup.

Client code can register with the drag-started event, as well as the drag-finished event to get notified of the elements that may be or have been affected respectively by this input mode.

readonlyfinal

Property Value

A snapshot of the current collection of the items that are affected by the handle drag operation.

Examples

If one needs to execute some code after some items have been moved by the HandleInputMode he can register a handler to its drag-finished event. The moved items can be retrieved from the affectedItems property:
mode.handleInputMode.addEventListener('drag-finished', () => {
  for (const item of mode.handleInputMode.affectedItems) {
    // these items have been moved
  }
})

See Also

Developer's Guide

beginRecognizer

: function(EventArgs, unknown): boolean
Gets or sets the event recognizer that determines whether to start moving the handle.
The default instance value detects MOUSE or PEN DOWN events.
final

beginRecognizerTouch

: function(EventArgs, unknown): boolean
Gets or sets the event recognizer that determines whether to start moving the handle via TOUCH input.
The default recognizer is TOUCH_PRIMARY_DOWN which reacts to the user making touch contact with the main touch device. Using TOUCH_PRIMARY_LONG_PRESS allows for an intuitive alternative configuration.
final

cancelRecognizer

: function(EventArgs, unknown): boolean
Gets or sets the event recognizer that determines whether to cancel moving the handle.
The default recognizer detects ESCAPE_DOWN, CANCEL or DRAG_CAPTURE_LOST events.
final

clickRecognizer

: function(EventArgs, unknown): boolean
Gets or sets the event recognizer that determines whether a handle was clicked.
The default recognizer detects CLICK events for MOUSE and PEN.
final

clickRecognizerTouch

: function(EventArgs, unknown): boolean
Gets or sets the event recognizer that determines whether a handle was tapped via TOUCH input.
The default recognizer is TOUCH_PRIMARY_TAP.
final

controller

: ConcurrencyController
protectedreadonly
Gets the installed controller.
protectedreadonlyfinal

currentHandle

: IHandle
readonly
Gets the handle that is currently being moved or null otherwise.
readonlyfinal

Property Value

The current handle or null.

directionalConstraintRecognizer

: function(EventArgs, unknown): boolean
Gets or sets the event recognizer that can be used by handle implementations to constrain the handle movement.
The default recognizer is SHIFT_IS_DOWN
final

See Also

API
isDirectionalConstrained

disableSnappingRecognizer

: function(EventArgs, unknown): boolean
Gets or sets the event recognizer that determines whether to temporarily disable snapping.
The default is ALT_DOWN
final

See Also

API
enableSnappingRecognizer

enabled

: boolean
Gets or sets the enabled state of this input mode.

Clients can use this property to disable or reenable this instance. This will set the enabled property of the installed controller so a disabled instance should never try to acquire the input mutex.

Disabling this mode will hide the handles and prevent the user from interacting with them.

Examples

Disabling the HandleInputMode on its parent input mode
mode.handleInputMode.enabled = false

enableSnappingRecognizer

: function(EventArgs, unknown): boolean
Gets or sets the event recognizer that determines whether to re-enable temporarily disabled snapping.
The default is ALT_UP
final

See Also

API
disableSnappingRecognizer

exclusive

: boolean
Gets or sets a value indicating whether this mode will be the only one running when it has the mutex.

The value of this property will be delegated to the exclusive property of the controller.

If this mode is marked as exclusive and has the mutex, all other modes added to the same MultiplexingInputMode will be deactivated. Otherwise, it will always run concurrently with all other modes.

final

finishRecognizer

: function(EventArgs, unknown): boolean
Gets or sets the event recognizer that determines whether to finish moving the handle.
The default recognizer detects MOUSE or PEN UP events.
final

finishRecognizerTouch

: function(EventArgs, unknown): boolean
Gets or sets the event recognizer that determines whether to finish moving the handle via touch.
The default recognizer is TOUCH_PRIMARY_UP.
final

handles

: IObservableCollection<IHandle>
Gets or sets the collection of IHandles this mode manages.
final

handlesRenderer

: IObjectRenderer<HandlesRenderTag>
Gets or sets the IObjectRenderer<HandlesRenderTag> that visualizes this input mode's handles.

When queried for an IVisualCreator to obtain the visualizations for the handles, this renderer is passed instances of HandlesRenderTag as render tag.

The default handlesRenderer is HandlesRenderer which automatically uses WebGL when WebGLGraphModelManager is set as graphModelManager, otherwise the SVG is used.

Custom renderers must not use the handle's location directly when positioning handles, since handles may have an offset. To apply this offset, the handle location must first be transformed into intermediate coordinates before applying the handle offset.

final

Property Value

The renderer for the handles.

isDragging

: boolean
readonly
Gets a value indicating whether a drag operation is currently in progress.
readonlyfinal

moveRecognizer

: function(EventArgs, unknown): boolean
Gets or sets the event recognizer that determines whether to move the handle.
The default recognizer detects MOUSE or PEN DRAG events with the MOUSE_LEFT button.
final

moveRecognizerTouch

: function(EventArgs, unknown): boolean
Gets or sets the event recognizer that determines whether to move the handle via TOUCH input.
The default recognizer is TOUCH_PRIMARY_DRAG.
final

parentInputModeContext

: IInputModeContext
protectedreadonly
Retrieves the IInputModeContext this mode has been installed in.
The value will be null if this mode is currently not installed. Use createInputModeContext to obtain a context that has this IInputMode as the inputMode.
protectedreadonlyfinal

priority

: number
Gets the priority of this input mode.
The priority will influence the order in which the modes will be installed into the CanvasComponent. The lower the priority value, the earlier it will be installed. If two modes are using the same priority value, the first one to be registered will be installed earlier.
final

requestMutexOnPress

: boolean
Gets or sets whether to request the mutex when beginRecognizer or beginRecognizerTouch was triggered.
If set to true this will discard other concurrent input modes when a handle was pressed. Otherwise, the mutex is only requested as soon as the drag gesture starts. The default is true.
final

See Also

API
moveRecognizerTouch

snapContext

: GraphSnapContext
Gets or sets the GraphSnapContext which manages snapping model items to certain coordinates (for instance, other items).

If set to null (the default) this input mode tries to obtain the GraphSnapContext from the IInputModeContext. To explicitly disable snapping, a GraphSnapContext implementation that is disabled needs to be set.

Default is null.

final

useViewCoordinates

: boolean
Gets or sets a value indicating whether handles are drawn in view coordinates or intermediate coordinates.

This only makes a difference if the projection is different from the IDENTITY transform.

The default value is to draw handles in the intermediate coordinate system.

final

See Also

Developer's Guide

Methods

addHandle

(handle: IHandle)
Adds a handle to the collection of handles managed by this instance.
final

Parameters

handle: IHandle
The handle to add.

addHandle

(
location: IMutablePoint
cursor?: Cursor
type?: HandleType
): IHandle
Factory method that creates and adds a handle to this mode by wrapping a given IMutablePoint instance.
The cursor and type are used to initialize the IHandle instance.
final

Parameters

location: IMutablePoint
The point to use as a handle.
cursor?: Cursor
The cursor to use.
type?: HandleType
The type of the handle to create.

Return Value

IHandle
The handle created.

arm

(handle: IHandle)
protected
Invoked when this mode gets "armed".
This happens when the mouse pointer hovers over a handle. This changes the mouse cursor to the handle's cursor.
protected

Parameters

handle: IHandle
The handle from which the cursor is queried.

cancel

()
Will be called to unconditionally cancel all ongoing edits.

This will be called prior to the uninstalling of this instance and when other input modes temporarily acquire the mutex.

In order to stop an active input mode manually, client code should use the following idiom:

if (!mode.tryStop()) {
  mode.cancel()
}

createInputModeContext

(): IInputModeContext
protected
Creates an IInputModeContext for use with the IHandle interface for the upcoming drag operation.

createInputModeEventArgs

(): InputModeEventArgs
protected
Helper method that yields a suitably configured InputModeEventArgs for this input mode.

disarm

()
protected
Invoked when this mode gets "disarmed".
This happens when the mouse stops hovering over a handle. This resets the mouse cursor.
protected

getClosestHandleAt

(location: Point): IHandle
protected
Finds the closest hit handle for the given world coordinate pair.
The default implementation first dispatches the query-closest-handle event and evaluates whether it was handled. If the event was not handled, it delegates to getClosestHitHandle.
protected

Parameters

location: Point
The coordinates in the world coordinate system.

Return Value

IHandle
The closest handle that has been hit or null

See Also

API
query-closest-handle, getClosestHitHandle

getClosestHitHandle

(location: Point, pointerType: PointerType): IHandle
protected
Finds the closest hit handle for the given world coordinate pair.
The default implementation compares the Manhattan distance of the handles to find the closest handle.
protected

Parameters

location: Point
The coordinates in the world coordinate system.
pointerType: PointerType
The pointer-type of the last input event.

Return Value

IHandle
The closest handle that has been hit or null

getHandleOffset

(handle: IHandle): Point
Calculates the offset between the given handle's visual location and its logical location.
Uses handle offset of the theme and the handle's type to position the handle.

Parameters

handle: IHandle
The handle to hit test or render.

Return Value

Point
A coordinate pair representing the offsets in x- and y-direction.

handleClick

(
context: IInputModeContext
evt: ClickEventArgs
handle: IHandle
)
protected
Calls handleClick of the handle with the evt.
This method is called when clickRecognizer or clickRecognizerTouch were triggered.
protected

Parameters

context: IInputModeContext
The current input mode context.
evt: ClickEventArgs
Arguments describing the click.
handle: IHandle
The handle that was clicked.

handleIsHit

(
handle: IHandle
location: Point
distance: Point
pointerType: PointerType
): boolean
protected
Determines whether a given handle has been visually hit by the mouse at the given world coordinates.
This implementation uses the Manhattan distance as a metric to determine if the handle was hit.
protected

Parameters

handle: IHandle
The handle to check
location: Point
The view coordinates to check.
distance: Point
The distance of the handle to the location. In the default implementation, this is a tuple representing the x- and y-distance of the handle to the location.
pointerType: PointerType
The last event's pointer type to consider.

Return Value

boolean
Whether the handle has been hit.

install

(context: IInputModeContext, controller: ConcurrencyController)
Installs the visual representation of the handles into the canvas into the inputModeGroup.

Parameters

context: IInputModeContext
The context that this instance shall be installed into. The same instance will be passed to this instance during uninstall. A reference to the context may be kept and queried during the time the mode is installed.
controller: ConcurrencyController
The controller for this mode.

invalidate

()
protected
Invalidates the canvas this mode is currently installed in.
protectedfinal

isDirectionalConstrained

(): boolean
Returns whether this input mode has the mutex and the directionalConstraintRecognizer recognized a directional constrained move for the lastInputEvent.
final

Return Value

boolean
true, if this input mode has the mutex and the last input event was recognized by the directionalConstraintRecognizer, false otherwise.

isSnappingDisabled

(): boolean
Returns whether this input mode has the mutex and the disableSnappingRecognizer recognized that snapping shall be temporarily disabled.
final

Return Value

boolean
true, if this input mode has the mutex and snapping is temporarily disabled, false otherwise.

onCanceled

()
protected
Called after cancel has been called.

Can be overridden in subclasses to perform additional actions after the mode has been canceled.

This implementation does nothing.

protected

onClicked

(evt: ClickEventArgs)
protected
Triggers the clicked event.
This method triggers the clicked event.
protected

Parameters

evt: ClickEventArgs
The event argument that contains context information.

onConcurrencyControllerActivated

()
protected
Called after the active property of the installed ConcurrencyController has been set to true.

Can be overridden in subclasses to perform additional actions after the mode has been activated.

Overriding implementations should call the base implementation.

protected

onConcurrencyControllerDeactivated

()
protected
Called after the active property of the installed ConcurrencyController has been set to false.

Can be overridden in subclasses to perform additional actions after the mode has been deactivated.

Overriding implementations should call the base implementation.

protected

onDragCanceled

(evt: InputModeEventArgs)
protected
Triggers the drag-canceled event.
protected

Parameters

evt: InputModeEventArgs
The event argument that contains context information.

onDragCanceling

(evt: InputModeEventArgs)
protected
Triggers the drag-canceling event.
protected

Parameters

evt: InputModeEventArgs
The event argument that contains context information.

onDragFinished

(evt: InputModeEventArgs)
protected
Triggered once the drag has been finalized.
This method triggers the drag-finished event.
protected

Parameters

evt: InputModeEventArgs
The event argument that contains context information.

onDragFinishing

(evt: InputModeEventArgs)
protected
Triggered before the drag will be finalized.
This method triggers the drag-finishing event.
protected

Parameters

evt: InputModeEventArgs
The event argument that contains context information.

onDragged

(evt: InputModeEventArgs)
protected
Triggered at the end of each drag.
This method triggers the dragged event.
protected

Parameters

evt: InputModeEventArgs
The event argument that contains context information.

onDragging

(evt: InputModeEventArgs)
protected
Triggered at the start of each drag.
This method triggers the dragging event.
protected

Parameters

evt: InputModeEventArgs
The event argument that contains context information.

onDragStarted

(evt: InputModeEventArgs)
protected
Triggers the drag-started event.
protected

Parameters

evt: InputModeEventArgs
The event argument that contains context information.

onDragStarting

(evt: InputModeEventArgs)
protected
Triggers the drag-starting event.
protected

Parameters

evt: InputModeEventArgs
The event argument that contains context information.

onQueryClosestHandle

(evt: QueryClosestHandleEventArgs)
protected
Raises the query-closest-handle event.
protected

Parameters

evt: QueryClosestHandleEventArgs
The query-closest-handle instance containing the event data.

onStopped

()
protected
Called after tryStop has been called.

Can be overridden in subclasses to perform additional actions after the mode has been stopped.

This implementation does nothing.

protected

removeHandle

(handle: IHandle)
Removes a handle from the collection of handles managed by this instance.
final

Parameters

handle: IHandle
The handle to remove.

startDrag

(handle: IHandle): Promise<boolean>
Method that can be used to initialize the dragging of a given handle manually.
This will simulate the user having initialized a drag of the given handle.

Parameters

handle: IHandle
The handle to be dragged.

Return Value

Promise<boolean>
A Promise<T> that resolves when the drag operation is done. It resolves to true if the operation is finished successfully and to false if the operation is canceled.

tryStop

(): boolean
Will be called to request a stop of the current editing progress.
This should stop the current edit, if one is in progress, and possibly commit all pending changes. If stopping is not possible, this method can return false

Return Value

boolean
true if and only if the editing has been stopped or there was no edit in progress

uninstall

(context: IInputModeContext)
Removes the IRenderTreeElement that displays the handles from the canvas.

Parameters

context: IInputModeContext
The context to deregister from. This is the same instance that had been passed to install during installation.

Events

'clicked'

: ClickEventArgs
Occurs when a handle has been clicked or tapped.

Properties of

ClickEventArgs
altKey: boolean
Gets a value indicating whether the alt modifier was pressed at the time of the click.
clickCount: number
Gets the number of clicks associated with this event.
context: IInputModeContext
Gets the context for the current event.
ctrlKey: boolean
Gets a value indicating whether the control modifier was pressed at the time of the click.
handled: boolean
writable
Gets or sets a value indicating whether this instance has been handled.
location: Point
Gets the location of the click.
metaKey: boolean
Gets a value indicating whether the meta modifier was pressed at the time of the click.
modifiers: ModifierKeys
Gets the state of the modifiers at the time of the click.
originalEventArgs: PointerEventArgs
Gets the pointer event args that caused this event.
pointerButtons: PointerButtons
Gets the PointerButtons that have changed for this event.
pointerType: PointerType
Gets the type of the pointer that was the source of this event.
shiftKey: boolean
Gets a value indicating whether the shift modifier was pressed at the time of the click.

'drag-canceled'

: InputModeEventArgs
Occurs when the drag has been canceled.

Properties of

InputModeEventArgs
context: IInputModeContext
Gets the context for the current event.

See Also

Developer's Guide

'drag-canceling'

: InputModeEventArgs
Occurs before the drag will be canceled.

Properties of

InputModeEventArgs
context: IInputModeContext
Gets the context for the current event.

See Also

Developer's Guide

'drag-finished'

: InputModeEventArgs
Occurs once the drag has been finished.

Properties of

InputModeEventArgs
context: IInputModeContext
Gets the context for the current event.

Examples

If one needs to execute some code after some items have been moved by the HandleInputMode he can register a handler to its drag-finished event. The moved items can be retrieved from the affectedItems property:
mode.handleInputMode.addEventListener('drag-finished', () => {
  for (const item of mode.handleInputMode.affectedItems) {
    // these items have been moved
  }
})

See Also

Developer's Guide

'drag-finishing'

: InputModeEventArgs
Occurs before the drag will be finished.

Properties of

InputModeEventArgs
context: IInputModeContext
Gets the context for the current event.

See Also

Developer's Guide

'drag-started'

: InputModeEventArgs
Occurs once the drag is initialized and has started.

Properties of

InputModeEventArgs
context: IInputModeContext
Gets the context for the current event.

See Also

Developer's Guide

'drag-starting'

: InputModeEventArgs
Occurs once the drag is starting.

Properties of

InputModeEventArgs
context: IInputModeContext
Gets the context for the current event.

See Also

Developer's Guide

'dragged'

: InputModeEventArgs
Occurs at the end of every drag.

Properties of

InputModeEventArgs
context: IInputModeContext
Gets the context for the current event.

See Also

Developer's Guide

'dragging'

: InputModeEventArgs
Occurs at the start of every drag.

Properties of

InputModeEventArgs
context: IInputModeContext
Gets the context for the current event.

See Also

Developer's Guide

'query-closest-handle'

: QueryClosestHandleEventArgs
Occurs when this mode queries the closest handle for a certain query location.
Handlers should set the handle property or set/respect the handled property accordingly.
context: IInputModeContext
Gets the context for the current event.
handle: IHandle
writable
Gets or sets the handle to use.
handled: boolean
writable
Gets or sets a value indicating whether this QueryClosestHandleEventArgs instance has been handled.
queryLocation: Point
Gets the query location in world coordinates.