GraphInputMode

GraphInputMode

GraphEditorInputMode

GraphViewerInputMode

Implemented Interfaces

: IObservableCollection<Command>

Remarks

This class is not supposed to and in fact cannot be extended from user code. It only exists to provide common functionality to the two aforementioned input modes. If customizations are wanted or needed, both GraphViewerInputMode and GraphEditorInputMode can be extended.

This class cannot be instantiated

Type Details

yFiles module: view

Properties

allowClipboardOperations

: boolean

Gets or sets a property that determines whether clipboard operations with the usual shortcuts are enabled on the canvas.

Remarks

Default value is true

Examples

Disabling clipboard operations

mode.allowClipboardOperations = false

availableCommands

Gets a collection of commands that this input mode will handle.

Remarks

This collection can be modified by removing commands to prevent the input mode from handling them. Previously removed commands can also be re-added again to enable them again. However, the input mode will never handle commands that weren't in the initial collection. Adding those will do nothing.

clickableItems

Gets or sets which types of items should be reported through the item click events.

Remarks

This also affects taps.

The default is ALL.

Examples

mode.clickableItems = GraphItemTypes.NODE | GraphItemTypes.EDGE

clickablePredicate

: function(IModelItem):boolean

Gets or sets a predicate that is queried to determine whether an item can be clicked.

Remarks

The default value returns the result of the clickableItems property for the given item.

Signature Details

function(obj: IModelItem) : boolean

Represents the method that defines a set of criteria and determines whether the specified object meets those criteria.

Parameters

obj - IModelItem: The object to compare against the criteria defined within the method represented by this delegate.

Returns

boolean: true if obj meets the criteria defined within the method represented by this delegate; otherwise, false.

clickHitTestOrder

Gets or sets the order of the types of items that should be used to determine what item has been clicked or tapped.

Remarks

Change this field to adjust which items will be selected if there are multiple items at a given location. The default order is the Z-Order but with a prioritization for elements behind labels. shouldSkipHitLabel.

Arrays that contain strings describing the name of GraphItemTypes are converted to an array of GraphItemTypes. For example:

['node', 'edge']
['NODE', 'EDGE']

Examples

The following example defines the order 1. bends, 2. nodes and edges (with equal priority), 3. labels.

mode.clickHitTestOrder = [
  GraphItemTypes.BEND,
  GraphItemTypes.NODE | GraphItemTypes.EDGE,
  GraphItemTypes.LABEL,
]

clickInputMode

: ClickInputMode

Gets or sets the ClickInputMode that is used by this instance to determine clicks.

Remarks

Whenever the mode detects a click, this mode will use the IHitTester from the parentInputModeContext to determine the items being hit. If they match the clickableItems type, the item-clicked event will be triggered. If they are focusable, the item will be set as the current item.

Upon change, the onClickInputModeChanged method will be called.

By default, this input mode has a priority of 20.

Examples

Disabling the ClickInputMode on its parent input mode

mode.clickInputMode.enabled = false

clickSelectableItems

Gets or sets which types of items should be selectable by mouse clicks.

Remarks

The default is ALL.

Examples

Determine which items should be selectable by different selection gestures

// Nodes, edges, and bends are selectable
mode.selectableItems =
  GraphItemTypes.NODE | GraphItemTypes.EDGE | GraphItemTypes.BEND
// Only nodes and bends are selectable by marquee selection
mode.marqueeSelectableItems = GraphItemTypes.NODE | GraphItemTypes.BEND
// Only nodes and edges are selectable by click selection
mode.clickSelectableItems = GraphItemTypes.NODE | GraphItemTypes.EDGE

clickSelectablePredicate

: function(IModelItem):boolean

Gets or sets a predicate that is queried to determine whether an item should be selected when clicked with the primary mouse button.

Remarks

The default value returns the result of selectablePredicate and the clickSelectableItems property for the given item.

Signature Details

function(obj: IModelItem) : boolean

Represents the method that defines a set of criteria and determines whether the specified object meets those criteria.

Parameters

obj - IModelItem: The object to compare against the criteria defined within the method represented by this delegate.

Returns

boolean: true if obj meets the criteria defined within the method represented by this delegate; otherwise, false.

contextMenuInputMode

: ContextMenuInputMode

Gets or sets the ContextMenuInputMode which handles context menus on a CanvasComponent.

Remarks

Upon change, the onContextMenuInputModeChanged method will be called.

By default, this input mode has a priority of 220.

Examples

Disabling the ContextMenuInputMode on its parent input mode

mode.contextMenuInputMode.enabled = false

It is recommended to configure the context menu handling on the parent GraphEditorInputMode or GraphViewerInputMode instead of the contextMenuInputMode. This involves registering for the populate-item-context-menu event instead of the populate-menu event:

// mode is either an instance of GraphEditorInputMode or GraphViewerInputMode
mode.contextMenuItems = GraphItemTypes.NODE
mode.addEventListener('populate-item-context-menu', (evt) => {
  // Get the node which is handled or null if the item is not a node
  const node = evt.item
  // Create the context menu items
  if (node !== null) {
    // Create a menu item to delete the node

    // Show the menu
    evt.contextMenu = [
      { label: 'Delete Item', action: () => graph.remove(node) },
    ]
  }
})

contextMenuItems

Gets or sets the types of items a context menu should be queried for.

Remarks

The items for which a context menu should be queried. The default value is NODE|EDGE.

Examples

// mode is either an instance of GraphEditorInputMode or GraphViewerInputMode
mode.contextMenuItems = GraphItemTypes.NODE
mode.addEventListener('populate-item-context-menu', (evt) => {
  // Get the node which is handled or null if the item is not a node
  const node = evt.item
  // Create the context menu items
  if (node !== null) {
    // Create a menu item to delete the node

    // Show the menu
    evt.contextMenu = [
      { label: 'Delete Item', action: () => graph.remove(node) },
    ]
  }
})

controller

: ConcurrencyController?

Gets the installed controller.

Defined in

cyclicSelectionRecognizer

: function(EventArgs, unknown):boolean

Gets or sets the event recognizer that determines if a click or tap should cycle through all the items that are currently under the mouse cursor.

Remarks

If the recognizer determines that the user wanted to use the cyclic click selection behavior, the hitTester will be queried for the given item and previously reported items will be ignored. E.g. if multiple nodes are overlapping each other, clicking on them will report the first item for the first click, the second one for the second click and so on. If all elements have been reported previously, the first one is going to be reported again. If the order of the elements at the clicked location changes, the cyclic selection is restarted anew.

The default is ALT_IS_DOWN.

Property Value

An event recognizer which determines that the user wants to use the cyclic click selection behavior.

Signature Details

function(evt: EventArgs, eventSource: unknown) : boolean

A callback that recognizes events.

Given a sender and an event argument, delegates decide whether the event is treated as a match depending on the context.

Parameters

evt - EventArgs: The arguments of the event to be decided to handle.
eventSource - unknown: The source of the event.

Returns

boolean: true if the evt is considered to be handled.

Sample Graphs

defaultCursor

: Cursor?

Gets or sets the cursor to use whenever no child mode prefers a different cursor.

Remarks

The default is null

Defined in

detailSelectionRecognizer

: function(EventArgs, unknown):boolean

Gets or sets the event recognizer that determines if a click or tap should select the item that is currently visible under the pointer cursor, without giving more important items higher priority.

Remarks

If the recognizer determines that the user wanted to use the detail clicking behavior, the hitTester will be queried for the given item and the first item that is returned will be considered a hit. Otherwise, all hit items are examined and are prioritized by item type. E.g. by default clicking on a node will select the node, even if there is a node label which has been clicked at the same point. If detail selection is recognized, the label will be selected.

The default is SHIFT_IS_DOWN.

Property Value

An event recognizer which determines that the user wants to use the detail clicking behavior.

Signature Details

function(evt: EventArgs, eventSource: unknown) : boolean

A callback that recognizes events.

Given a sender and an event argument, delegates decide whether the event is treated as a match depending on the context.

Parameters

evt - EventArgs: The arguments of the event to be decided to handle.
eventSource - unknown: The source of the event.

Returns

boolean: true if the evt is considered to be handled.

Examples

mode.detailSelectionRecognizer = EventRecognizers.SHIFT_IS_DOWN

Sample Graphs

doubleClickablePredicate

: function(IModelItem):boolean

Gets or sets a predicate that is queried to determine whether an item can be double clicked.

Remarks

The default value returns the result of the clickablePredicate property for the given item.

Signature Details

function(obj: IModelItem) : boolean

Represents the method that defines a set of criteria and determines whether the specified object meets those criteria.

Parameters

obj - IModelItem: The object to compare against the criteria defined within the method represented by this delegate.

Returns

boolean: true if obj meets the criteria defined within the method represented by this delegate; otherwise, false.

doubleClickHitTestOrder

Gets or sets the order of the types of items that should be used to determine what item has been double-clicked or double-tapped.

Remarks

Change this field to adjust which items will be considered when double-clicked if there are multiple items at a given location. The default order is

Arrays that contain strings describing the name of GraphItemTypes are converted to an array of GraphItemTypes. For example:

['node', 'edge']
['NODE', 'EDGE']

Examples

The following example defines the order 1. bends, 2. nodes and edges (with equal priority), 3. labels.

mode.doubleClickHitTestOrder = [
  GraphItemTypes.BEND,
  GraphItemTypes.NODE | GraphItemTypes.EDGE,
  GraphItemTypes.LABEL,
]

enabled

: boolean

Gets or sets the enabled state of this input mode.

Remarks

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.

Defined in

exclusive

: boolean

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

Remarks

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.

Defined in

focusableItems

Gets or sets the items that can be given focus via the setCurrentItem method.

Remarks

The focusable items. The default is NODE.

Examples

mode.focusableItems = GraphItemTypes.NODE | GraphItemTypes.EDGE

focusablePredicate

: function(IModelItem):boolean

Gets or sets a predicate that is queried to determine whether an item should be set to the current item.

Remarks

The default value returns the result of the focusableItems property for the given item. It also honors the ignoreVoidStyles property.

Signature Details

function(obj: IModelItem) : boolean

Represents the method that defines a set of criteria and determines whether the specified object meets those criteria.

Parameters

obj - IModelItem: The object to compare against the criteria defined within the method represented by this delegate.

Returns

boolean: true if obj meets the criteria defined within the method represented by this delegate; otherwise, false.

graph

: IGraph?

Gets the graph instance from the parentInputModeContext.

Property Value

The graph to use, which can be null.

graphSelection

: IGraphSelection?

Gets the graph selection from the parentInputModeContext.

hitTester

: IHitTester

Gets or sets the hitTester property.

Remarks

The implementation will be queried by findItems to find IModelItems at a given location, e.g. if the user clicks on the canvas.

ignoreVoidStyles

: boolean

Gets or sets a value indicating whether void styles should be ignored when selecting or focusing items.

Remarks

Void styles are styles which render their styled elements invisible. These are VOID_NODE_STYLE, VOID_EDGE_STYLE, VOID_LABEL_STYLE, and VOID_PORT_STYLE. Typically, one does not want to interact with these elements, either. The value of this property is considered by selectablePredicate and focusablePredicate. Note that even if this property is set to false the invisible elements are not selectable by mouse clicks or marquee selection since their hit testable always returns false.

Property Value

true if void styles should be ignored for selection and focus; false otherwise. Default is true.

itemHoverInputMode

: ItemHoverInputMode

Gets or sets the ItemHoverInputMode that is provided by this instance to detect when the cursor hovers over a graph item.

Remarks

Note that initially the hoverItems property is set to NONE, which effectively disables the functionality of the mode initially. In order to get the mode to fire events, the property should be set to a corresponding value.

If the backing field has not yet been initialized upon first access, a new instance will be assigned. Upon change, onItemHoverInputModeChanged will be called.

By default, this input mode has a priority of 200.

Examples

Disabling the ItemHoverInputMode on its parent input mode

mode.itemHoverInputMode.enabled = false

The itemHoverInputMode raises the hovered-item-changed event each time cursor hovers over a different item or the canvas in which case the hovered item is null. One can also configure the item types which are reported:

Configuring the ItemHoverInputMode to handle nodes and edges

// mode is either an instance of GraphEditorInputMode or GraphViewerInputMode

// enable the ItemHoverInputMode and let it handle edges and nodes
mode.itemHoverInputMode.enabled = true
mode.itemHoverInputMode.hoverItems =
  GraphItemTypes.EDGE | GraphItemTypes.NODE
// handle changes on the hovered items
mode.itemHoverInputMode.addEventListener(
  'hovered-item-changed',
  (evt) => {
    const oldItem = evt.oldItem
    // e.g. remove the highlight from oldItem here
    const newItem = evt.item
    // e.g. add a highlight to newItem here
  },
)

keyboardInputMode

: KeyboardInputMode

Gets or sets the KeyboardInputMode associated with this instance.

Remarks

By default, this input mode has a priority of 0.

Property Value

The keyboardInputMode.

Examples

Disabling the KeyboardInputMode on its parent input mode

mode.keyboardInputMode.enabled = false

Adding a handler for a keyboard event

// Execute the command if the Insert key is pressed
graphEditorInputMode.keyboardInputMode.addKeyBinding(
  'Insert',
  ModifierKeys.NONE,
  () => {
    graphEditorInputMode.createNode(
      graphEditorInputMode.graphComponent!.viewport.center,
    )
  },
)

lassoSelectionInputMode

: LassoSelectionInputMode

Gets or sets the LassoSelectionInputMode which handles the selection of multiple elements by drawing a polygon around them.

Remarks

Upon change, the onLassoSelectionInputModeChanged method will be called.

The lassoSelectionInputMode respects the selectableItems and the marqueeSelectableItems used by marqueeSelectablePredicate.

By default, this input mode has a priority of 150 and is disabled.

marqueeSelectableItems

Gets or sets which types of items should be selected during marquee selections or lasso selection.

Remarks

The default is a combination of NODE, EDGE, and BEND.

Examples

Determine which items should be selectable by different selection gestures

// Nodes, edges, and bends are selectable
mode.selectableItems =
  GraphItemTypes.NODE | GraphItemTypes.EDGE | GraphItemTypes.BEND
// Only nodes and bends are selectable by marquee selection
mode.marqueeSelectableItems = GraphItemTypes.NODE | GraphItemTypes.BEND
// Only nodes and edges are selectable by click selection
mode.clickSelectableItems = GraphItemTypes.NODE | GraphItemTypes.EDGE

marqueeSelectablePredicate

: function(IModelItem):boolean

Gets or sets a predicate that is queried to determine whether an item can be selected by marquee or lasso selection.

Remarks

The default value returns the result of the marqueeSelectableItems property for the given item and takes selectablePredicate into account.

Signature Details

function(obj: IModelItem) : boolean

Represents the method that defines a set of criteria and determines whether the specified object meets those criteria.

Parameters

obj - IModelItem: The object to compare against the criteria defined within the method represented by this delegate.

Returns

boolean: true if obj meets the criteria defined within the method represented by this delegate; otherwise, false.

marqueeSelectionInputMode

: MarqueeSelectionInputMode

Gets or sets the MarqueeSelectionInputMode which handles the selection of multiple elements by drawing a rectangle around them.

Remarks

Upon change, the onMarqueeSelectionInputModeChanged method will be called.

The marqueeSelectionInputMode respects the selectableItems and the marqueeSelectableItems used by marqueeSelectablePredicate.

By default, this input mode has a priority of 160.

For GraphViewerInputMode, the default values of beginRecognizer and subtractSelectionRecognizer conflict, so in this case you will usually want to change one of these recognizers.

Examples

Disabling the MarqueeSelectionInputMode on its parent input mode

mode.marqueeSelectionInputMode.enabled = false

moveViewportInputMode

: MoveViewportInputMode

Gets or sets the MoveViewportInputMode associated with this instance.

Remarks

Upon change, the onMoveViewportInputModeChanged method will be called.

By default, this input mode has a priority of 190.

Examples

Disabling the MoveViewportInputMode on its parent input mode

mode.moveViewportInputMode.enabled = false

multiSelectionRecognizer

: function(EventArgs, unknown):boolean

Gets or sets the event recognizer that determines if a click or tap is deemed a multi-selection gesture.

Remarks

If the multiSelectionRecognizer returns true for the current gesture, the element which is selected with that gesture will be added to the current selection. Otherwise, the selection will be cleared before adding the newly selected element.

The default detects the current system and delegates either to META_IS_DOWN (macOS) or CTRL_IS_DOWN (other systems).

Signature Details

function(evt: EventArgs, eventSource: unknown) : boolean

A callback that recognizes events.

Given a sender and an event argument, delegates decide whether the event is treated as a match depending on the context.

Parameters

evt - EventArgs: The arguments of the event to be decided to handle.
eventSource - unknown: The source of the event.

Returns

boolean: true if the evt is considered to be handled.

mutexOwner

: IInputMode?

Gets the IInputMode that currently owns the mutex.

Property Value

The IInputMode that currently owns the mutex or null.

Defined in

navigationInputMode

: NavigationInputMode

Gets or sets the NavigationInputMode which is responsible for navigating and traversing the elements in the IGraph.

Remarks

Upon change the onNavigationInputModeChanged method will be called.

By default, this input mode has a priority of 210.

Examples

Disabling the NavigationInputMode on its parent input mode

mode.navigationInputMode.enabled = false

The navigationInputMode supports e.g. opening and closing group nodes. These actions can be configured in details:

// mode is either an instance of GraphEditorInputMode or GraphViewerInputMode

// enable expanding and collapsing group nodes
mode.navigationInputMode.allowCollapseGroup = true
mode.navigationInputMode.allowExpandGroup = true
// do not fit the content after expand/collapse
mode.navigationInputMode.fitContentAfterGroupActions = false
// expand/collapse group nodes in a way that their
// top right corner stays at its current coordinates
mode.navigationInputMode.autoGroupNodeAlignmentPolicy =
  NodeAlignmentPolicy.TOP_RIGHT

It also reports when groups are opened or collapsed interactively by raising the following events:

// mode is either an instance of GraphEditorInputMode or GraphViewerInputMode
mode.navigationInputMode.addEventListener('group-expanding', (evt) => {
  const node = evt.item
  // do something with the node before it will be expanded
})
mode.navigationInputMode.addEventListener('group-expanded', (evt) => {
  const node = evt.item
  // do something with the node after it has been expanded
})
mode.navigationInputMode.addEventListener('group-collapsing', () => {
  /* same for collapse operations */
})
mode.navigationInputMode.addEventListener('group-collapsed', () => {
  /* same for collapse operations */
})

parentInputModeContext

: IInputModeContext?

Retrieves the IInputModeContext this mode has been installed in.

Remarks

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.

Defined in

populateContextMenuPredicate

: function(IModelItem):boolean

Gets or sets a predicate that is queried to determine whether a context menu should be shown for an item.

Remarks

The default value returns the result of the contextMenuItems property for the given item.

Signature Details

function(obj: IModelItem) : boolean

Represents the method that defines a set of criteria and determines whether the specified object meets those criteria.

Parameters

obj - IModelItem: The object to compare against the criteria defined within the method represented by this delegate.

Returns

boolean: true if obj meets the criteria defined within the method represented by this delegate; otherwise, false.

priority

: number

Gets the priority of this input mode.

Remarks

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.

Implements

queryToolTipPredicate

: function(IModelItem):boolean

Gets or sets a predicate that is queried to determine whether a tool tip should be queried for an item.

Remarks

The default value returns the result of the toolTipItems property for the given item.

Signature Details

function(obj: IModelItem) : boolean

Represents the method that defines a set of criteria and determines whether the specified object meets those criteria.

Parameters

obj - IModelItem: The object to compare against the criteria defined within the method represented by this delegate.

Returns

boolean: true if obj meets the criteria defined within the method represented by this delegate; otherwise, false.

selectableItems

Gets or sets which types of items should be selectable at all.

Remarks

The default is ALL.

Examples

Determine which items should be selectable by different selection gestures

// Nodes, edges, and bends are selectable
mode.selectableItems =
  GraphItemTypes.NODE | GraphItemTypes.EDGE | GraphItemTypes.BEND
// Only nodes and bends are selectable by marquee selection
mode.marqueeSelectableItems = GraphItemTypes.NODE | GraphItemTypes.BEND
// Only nodes and edges are selectable by click selection
mode.clickSelectableItems = GraphItemTypes.NODE | GraphItemTypes.EDGE

selectablePredicate

: function(IModelItem):boolean

Gets or sets a predicate that is queried to determine whether a given IModelItem is selectable.

Remarks

This allows to further restrict which items are selectable, compared to selectableItems. The default value uses and honors the selectableItems and ignoreVoidStyles. This property is by default also used by clickSelectablePredicate and marqueeSelectablePredicate, so turning selection off here also turns it off in other places.

Signature Details

function(obj: IModelItem) : boolean

Represents the method that defines a set of criteria and determines whether the specified object meets those criteria.

Parameters

obj - IModelItem: The object to compare against the criteria defined within the method represented by this delegate.

Returns

boolean: true if obj meets the criteria defined within the method represented by this delegate; otherwise, false.

Examples

In the following example items are only selectable if their tag is the string "I am selectable":

mode.selectablePredicate = (item: IModelItem): boolean =>
  item.tag === 'I am selectable'

skipHitLabels

: boolean

Gets or sets a value that specifies whether during hit testing, labels should be skipped at all.

Remarks

Since typically users don't want to click a label when it covers a node or edge, but they typically want to click the label, but otherwise the Z-order should be considered, this setting will determine whether shouldSkipHitLabel should be queried during hit test enumeration if labels are hit before other elements.

This is only applicable when the respective clickHitTestOrder or doubleClickHitTestOrder is not explicit about the order.

This setting will influence the ILookup behavior of the IInputModeContext via childInputModeContextLookup so that the IHitTester interface swaps the order of the hits to report skipped labels only after the items behind the labels.

By default, this feature is enabled.

toolTipInputMode

: ToolTipInputMode

Gets or sets the toolTipInputMode which is responsible for displaying Tooltips on a CanvasComponent.

Remarks

Upon change, the onToolTipInputModeChanged method will be called.

By default, this input mode has a priority of 400.

Examples

Disabling the ToolTipInputMode on its parent input mode

mode.toolTipInputMode.enabled = false

It is recommended to configure the tooltip handling on the parent GraphEditorInputMode or GraphViewerInputMode instead of the toolTipInputMode. This involves registering for the query-item-tool-tip event instead of the query-tool-tip event:

// mode is either an instance of GraphEditorInputMode or GraphViewerInputMode
mode.toolTipItems = GraphItemTypes.NODE
// register a listener
mode.addEventListener('query-item-tool-tip', (evt) => {
  if (evt.handled) {
    // A tooltip has already been assigned -> nothing to do.
    return
  }
  // We can safely cast here because we set ToolTipItems to only Node.
  const hitNode = evt.item as INode
  if (hitNode.labels.size > 0) {
    // Show the text of the first label as tooltip.
    evt.toolTip = hitNode.labels.get(0).text

    // Indicate that the tooltip content has been set.
    evt.handled = true
  }
})

toolTipItems

Gets or sets the types of the items that should be queried for a tooltip.

Remarks

The items for which a tooltip text should be queried. The default value is a combination of NODE, EDGE, LABEL, and PORT, i.e. everything except bends.

Examples

Configuring the ToolTipInputMode to display tooltips for nodes

// mode is either an instance of GraphEditorInputMode or GraphViewerInputMode
mode.toolTipItems = GraphItemTypes.NODE
// register a listener
mode.addEventListener('query-item-tool-tip', (evt) => {
  if (evt.handled) {
    // A tooltip has already been assigned -> nothing to do.
    return
  }
  // We can safely cast here because we set ToolTipItems to only Node.
  const hitNode = evt.item as INode
  if (hitNode.labels.size > 0) {
    // Show the text of the first label as tooltip.
    evt.toolTip = hitNode.labels.get(0).text

    // Indicate that the tooltip content has been set.
    evt.handled = true
  }
})

waitInputMode

: WaitInputMode

Gets or sets the WaitInputMode that is provided by this instance for those who need to make use of it.

Remarks

Upon change, the onWaitInputModeChanged method will be called.

By default, this input mode has a priority of -1.

Examples

Disabling the WaitInputMode on its parent input mode

mode.waitInputMode.enabled = false

Blocking user interaction during an asynchronous process

graphEditorInputMode.waiting = true
await longRunningAsyncProcess()
graphEditorInputMode.waiting = false

Methods

add

(mode: IInputMode)

Adds the given mode.

Remarks

The input modes will be ordered according to their priority: Input modes with lower priority will be installed earlier.

Input modes will run exclusively if the exclusive property of their installed controller is set to true. Otherwise they cannot and will not be deactivated if another IInputMode acquires the mutex.

Parameters

options - Object
A map of options to pass to the method.

mode - IInputMode: The input mode to add to this mode.

Throws

Exception({ name: 'ArgumentError' }): If the same mode is already added to this instance.

Examples

const multiplexingInputMode = new MultiplexingInputMode()
const waitInputMode = new WaitInputMode()
waitInputMode.priority = 0
multiplexingInputMode.add(waitInputMode)
const moveInputMode = new MoveViewportInputMode()
moveInputMode.priority = 5
multiplexingInputMode.add(moveInputMode)
graphComponent.inputMode = multiplexingInputMode

const mode = new GraphEditorInputMode()
const customInputMode = new CustomInputMode()
customInputMode.priority = 10
mode.add(customInputMode)

Defined in

adjustCursor

()

Adjusts the cursor of the CanvasComponent according to the current input mutex owner or the first mode in the list whose ConcurrencyController returns a non-null preferredCursor.

Remarks

This method will set defaultCursor as the current cursor if no other preferredCursor has been specified.

Defined in

cancel

()

Cancels all modes.

Implements

MultiplexingInputMode.childInputModeContextLookup

childInputModeContextLookup

(type: Constructor) : any

Called by the child context's lookup method.

Parameters

options - Object
A map of options to pass to the method.

type - Constructor: The type argument passed to lookup.

Returns

↪any?: The result of the lookup query, or null.

Overrides

clearSelection

()

Clears the selection on the current graphSelection.

Remarks

This implementation may be overridden for customizations. All it does is call clear.

click

(item: IModelItem, evt: ClickEventArgs)

Actually performs the click or tap on the given item.

Remarks

This will raise the item-left-clicked, item-right-clicked (depending on the button), and item-clicked events. If either event is unhandled by all its event handlers, the item will be selected and focused. Before selection, the current selection will be cleared, unless the multiSelectionRecognizer is triggered.

Parameters

options - Object
A map of options to pass to the method.

item - IModelItem: The item that has been clicked.
evt - ClickEventArgs: The original event arguments for the click. Setting its handled property to true will indicate that the click was handled. By default, this happens when the clicked item is either selected or focused.

clickClearSelection

(context: IInputModeContext) : boolean

Clears the selection on click if the click is not recognized by multiSelectionRecognizer.

Remarks

This method is only called if no item has been hit and at least one item is currently selected.

This will use the clearSelection method to deselect all items.

Parameters

options - Object
A map of options to pass to the method.

context - IInputModeContext: The context where the click appeared.

Returns

↪boolean: Whether the selection has been cleared by this method.

copy

()

Copies the currently selected elements to the clipboard.

Examples

mode.copy()

createInputModeContext

() : IInputModeContext

Yields an IInputModeContext for the child modes of this mode.

Remarks

This method is called during installation to create a new context for the child modes and can be used by client code to obtain a suitable context object. The parentInputModeContext property is already set when this method is called. lookup calls for the created context will be resolved by this instance's childInputModeContextLookup method.

Returns

↪IInputModeContext: A new instance that delegates to the parent's context.

Defined in

createInputModeEventArgs

(context: IInputModeContext) : InputModeEventArgs

Helper method that yields a suitably configured InputModeEventArgs for this input mode.

Parameters

options - Object
A map of options to pass to the method.

context - IInputModeContext: An input mode context that is available in the InputModeEventArgs.
Can be null in which case a new context for this instance is created automatically.

Returns

↪InputModeEventArgs: An input mode event argument that is configured for this instance.

Defined in

doubleClick

(item: IModelItem, evt: ClickEventArgs)

Actually performs a double-tap on the given item.

Remarks

This will raise the item-left-double-clicked and item-right-double-clicked (depending on the button), and item-double-clicked events.

Parameters

options - Object
A map of options to pass to the method.

item - IModelItem: The item that has been double-clicked.
evt - ClickEventArgs: The original event arguments for the click. Setting its handled property to true will indicate that the double-click was handled and events on other items in the same location are no longer raised.

findItems

(location: Point, tests: GraphItemTypes[], filter?: function(IModelItem):boolean) : IEnumerable<IModelItem>

Used as a callback to find the items hit underneath a certain point.

Remarks

This implementation uses the hitTester to determine the hit items.

Parameters

options - Object
A map of options to pass to the method.

location - Point

The location to test.

tests - GraphItemTypes[]

An array of GraphItemTypes values that encode for which model items the hit test should be performed for prioritizing. Arrays that contain strings describing the name of GraphItemTypes are converted to an array of GraphItemTypes. For example:

['node', 'edge']
['NODE', 'EDGE']

filter - function(IModelItem):boolean

The predicate that can be used to filter the results. May be null.

Signature Details

function(obj: IModelItem) : boolean

Represents the method that defines a set of criteria and determines whether the specified object meets those criteria.

Parameters

obj - IModelItem: The object to compare against the criteria defined within the method represented by this delegate.

Returns

boolean: true if obj meets the criteria defined within the method represented by this delegate; otherwise, false.

Returns

↪IEnumerable<IModelItem>: An enumerable over the items that have been found for the location.

Examples

function HandleItemAtLocation(
  context: IInputModeContext,
  location: Point,
): void {
  const graphEditorInputMode = context.lookup(
    GraphEditorInputMode,
  ) as GraphEditorInputMode

  const graphItem = graphEditorInputMode
    .findItems(location, [GraphItemTypes.NODE | GraphItemTypes.EDGE])
    .at(0)

  if (graphItem instanceof INode) {
    // ... handle node
  } else if (graphItem instanceof IEdge) {
    // ... handle edge
  }
}

findItems

(context: IInputModeContext, location: Point, tests: GraphItemTypes[], filter?: function(IModelItem):boolean) : IEnumerable<IModelItem>

Used as a callback to find the items hit underneath a certain point.

Remarks

This implementation uses the hitTester to determine the hit items and also queries the IBendSelectionTester for bends at hit edges, as well as the IPortSelectionTester for ports at hit port owners.

Parameters

options - Object
A map of options to pass to the method.

context - IInputModeContext

The context to use for the isHit callback.

location - Point

The location to test.

tests - GraphItemTypes[]

['node', 'edge']
['NODE', 'EDGE']

filter - function(IModelItem):boolean

The predicate that can be used to filter the results. May be null.

Signature Details

function(obj: IModelItem) : boolean

Represents the method that defines a set of criteria and determines whether the specified object meets those criteria.

Parameters

obj - IModelItem: The object to compare against the criteria defined within the method represented by this delegate.

Returns

boolean: true if obj meets the criteria defined within the method represented by this delegate; otherwise, false.

Returns

↪IEnumerable<IModelItem>: An enumerable over the items that have been found for the location.

Examples

function HandleItemAtLocation(
  context: IInputModeContext,
  location: Point,
): void {
  const graphEditorInputMode = context.lookup(
    GraphEditorInputMode,
  ) as GraphEditorInputMode

  const graphItem = graphEditorInputMode
    .findItems(location, [GraphItemTypes.NODE | GraphItemTypes.EDGE])
    .at(0)

  if (graphItem instanceof INode) {
    // ... handle node
  } else if (graphItem instanceof IEdge) {
    // ... handle edge
  }
}

getSortedModes

() : IList<IInputMode>

Returns a list of all modes managed by this instance sorted by their priority.

Returns

↪IList<IInputMode>: A list of the modes.

Defined in

handleClickListener

(context: IInputModeContext, item: IModelItem, location: Point) : boolean

Called by click to query the item for an IClickListener in its lookup and handle it appropriately.

Remarks

This method will query the IClickListener and check whether it was hit by the click, and if so, will invoke onClicked and return true.

Parameters

options - Object
A map of options to pass to the method.

context - IInputModeContext: The context for the click.
item - IModelItem: The item that has been clicked.
location - Point: The click location.

Returns

↪boolean: Whether the action has been invoked and handling should be stopped.

initialize

()

Performs one-time initialization of this instance.

Remarks

This method should not be invoked by subclasses. This will be done automatically upon first installation of this mode.

This code will be executed only once per instance. The parentInputModeContext property will be null when this code is executed. This method should not be used to install this mode into a specific canvas. Subclasses should always call base.Initialize() first.

Defined in

install

(context: IInputModeContext, controller: ConcurrencyController)

Installs this mode into the given context that is provided by the canvas.

Remarks

In general a mode can only be installed into a single canvas at all times.

This method is called to initialize this instance. Implement this method to register the corresponding event handlers for the various input events this mode will listen to.

When this instance gets uninstalled from the context the same context instance will be passed to it.

Implementations may hold a reference to the context instance and use it while installed.

Parameters

options - Object
A map of options to pass to the method.

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 while the mode is installed.
controller - ConcurrencyController: The ConcurrencyController for this mode.

Overrides

IInputMode.install

invalidate

()

Invalidates the canvas this mode is currently installed in.

Defined in

lassoSelect

(lassoPath: GeneralPath, selectionPolicy?: SelectionPolicy)

Performs lasso-selection with the given path.

Remarks

It delegates directly to the onLassoSelect overload internally.

Parameters

options - Object
A map of options to pass to the method.

lassoPath - GeneralPath: The lasso selection path.
selectionPolicy - SelectionPolicy: The policy to use for changing the selection of the elements.

marqueeSelect

(marqueeRectangle: Rect, selectionPolicy?: SelectionPolicy)

Performs marquee selection with the given rectangle.

Remarks

It delegates directly to the onMarqueeSelect overload internally.

Parameters

options - Object
A map of options to pass to the method.

marqueeRectangle - Rect: The selection rectangle.
selectionPolicy - SelectionPolicy: The policy to use for changing the selection of the elements.

onCanvasClicked

(evt: ClickEventArgs)

Raises the canvas-clicked event.

Remarks

This implementation will stop the event propagation as soon as an event handler has set the handled property to true.

Parameters

options - Object
A map of options to pass to the method.

evt - ClickEventArgs: The ClickEventArgs instance that contains the information about the click.

onClickInputModeChanged

(oldMode: ClickInputMode, newMode: ClickInputMode)

Called when the clickInputMode property value changes and after initialization of the property.

Parameters

options - Object
A map of options to pass to the method.

oldMode - ClickInputMode: the old value, which may be null the first time
newMode - ClickInputMode: the new value

onConcurrencyControllerActivated

()

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

Remarks

This implementation reenables previously disabled concurrent child modes.

Defined in

MultiplexingInputMode.onConcurrencyControllerDeactivated

onConcurrencyControllerDeactivated

()

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

Remarks

This implementation sets the preferredCursor property to null and releases the mutex if the mutex is currently owned by this instance. Also, all concurrent child modes will be disabled.

Overrides

onContextMenuInputModeChanged

(oldMode: ContextMenuInputMode, newMode: ContextMenuInputMode)

Called when the ContextMenuInputMode property value changes and after initialization of the property.

Parameters

options - Object
A map of options to pass to the method.

oldMode - ContextMenuInputMode: the old value, which may be null the first time
newMode - ContextMenuInputMode: the new value

onItemClicked

Raises the item-clicked event.

Remarks

This implementation will stop the event propagation as soon as an event handler has set the handled property to true.

Parameters

options - Object
A map of options to pass to the method.

evt - ItemClickedEventArgs<IModelItem>: The ItemClickedEventArgs<T> instance that contains the item that has been clicked.

onItemDoubleClicked

Raises the item-double-clicked event.

Remarks

This implementation will stop the event propagation as soon as an event handler has set the handled property to true.

Parameters

options - Object
A map of options to pass to the method.

evt - ItemClickedEventArgs<IModelItem>: The ItemClickedEventArgs<T> instance that contains the item that has been double-clicked.

onItemHoverInputModeChanged

(oldMode: ItemHoverInputMode, newMode: ItemHoverInputMode)

Called when the itemHoverInputMode property value changes and after initialization of the property.

Parameters

options - Object
A map of options to pass to the method.

oldMode - ItemHoverInputMode: the old value, which may be null the first time
newMode - ItemHoverInputMode: the new value

onItemLeftClicked

Raises the item-left-clicked event.

Remarks

This implementation will stop the event propagation as soon as an event handler has set the handled property to true.

Parameters

options - Object
A map of options to pass to the method.

evt - ItemClickedEventArgs<IModelItem>: The ItemClickedEventArgs<T> instance that contains the item that has been clicked.

onItemLeftDoubleClicked

Raises the item-left-double-clicked event.

Remarks

This implementation will stop the event propagation as soon as an event handler has set the handled property to true.

Parameters

options - Object
A map of options to pass to the method.

evt - ItemClickedEventArgs<IModelItem>: The ItemClickedEventArgs<T> instance that contains the item that has been double-clicked.

onItemRightClicked

Raises the item-right-clicked event.

Remarks

This implementation will stop the event propagation as soon as an event handler has set the handled property to true.

Parameters

options - Object
A map of options to pass to the method.

evt - ItemClickedEventArgs<IModelItem>: The ItemClickedEventArgs<T> instance that contains the item that has been clicked.

onItemRightDoubleClicked

Raises the item-right-double-clicked event.

Remarks

This implementation will stop the event propagation as soon as an event handler has set the handled property to true.

Parameters

options - Object
A map of options to pass to the method.

evt - ItemClickedEventArgs<IModelItem>: The ItemClickedEventArgs<T> instance that contains the item that has been double clicked.

onKeyboardInputModeChanged

(oldMode: KeyboardInputMode, newMode: KeyboardInputMode)

Called when the keyboardInputMode changes.

Parameters

options - Object
A map of options to pass to the method.

oldMode - KeyboardInputMode: The old keyboardInputMode.
newMode - KeyboardInputMode: The new keyboardInputMode.

onLassoSelect

(context: IInputModeContext, lassoPath: GeneralPath, selectionPolicy: SelectionPolicy)

Performs lasso-selection with the given path.

Remarks

This method is called internally when either the lassoSelect method is called or the user performs a lasso-selection gesture via lassoSelectionInputMode.

Parameters

options - Object
A map of options to pass to the method.

context - IInputModeContext: The input mode context.
lassoPath - GeneralPath: The lasso selection path.
selectionPolicy - SelectionPolicy: The policy to use for changing the selection of the elements.

onLassoSelectionInputModeChanged

(oldMode: LassoSelectionInputMode, newMode: LassoSelectionInputMode)

Called when the lassoSelectionInputMode property value changes and after initialization of the property.

Parameters

options - Object
A map of options to pass to the method.

oldMode - LassoSelectionInputMode: the old value, which may be null the first time
newMode - LassoSelectionInputMode: the new value

onMarqueeSelect

(context: IInputModeContext, marqueeRectangle: Rect, selectionPolicy: SelectionPolicy)

Performs marquee selection with the given rectangle.

Remarks

This method is called internally when either the marqueeSelect method is called or the user performs a marquee-selection gesture via marqueeSelectionInputMode.

Parameters

options - Object
A map of options to pass to the method.

context - IInputModeContext: The input mode context.
marqueeRectangle - Rect: The selection rectangle.
selectionPolicy - SelectionPolicy: The policy for changing the selection.

onMarqueeSelectionInputModeChanged

(oldMode: MarqueeSelectionInputMode, newMode: MarqueeSelectionInputMode)

Called when the marqueeSelectionInputMode property value changes and after initialization of the property.

Parameters

options - Object
A map of options to pass to the method.

oldMode - MarqueeSelectionInputMode: the old value, which may be null the first time
newMode - MarqueeSelectionInputMode: the new value

onMoveViewportInputModeChanged

(oldMode: MoveViewportInputMode, newMode: MoveViewportInputMode)

Called when the moveViewportInputMode property value changes and after initialization of the property.

Parameters

options - Object
A map of options to pass to the method.

oldMode - MoveViewportInputMode: the old value, which may be null the first time
newMode - MoveViewportInputMode: the new value

onMultiSelectionFinished

(evt: SelectionEventArgs<IModelItem>)

Raises the multi-selection-finished event.

Parameters

options - Object
A map of options to pass to the method.

evt - SelectionEventArgs<IModelItem>: The SelectionEventArgs<IModelItem> that provides the selection.

onMultiSelectionStarted

(evt: SelectionEventArgs<IModelItem>)

Raises the multi-selection-started event.

Parameters

options - Object
A map of options to pass to the method.

evt - SelectionEventArgs<IModelItem>: The SelectionEventArgs<IModelItem> that provides the selection.

onNavigationInputModeChanged

(oldMode: NavigationInputMode, newMode: NavigationInputMode)

Called when the navigationInputMode property value changes and after initialization of the property.

Parameters

options - Object
A map of options to pass to the method.

oldMode - NavigationInputMode: the old value, which may be null the first time
newMode - NavigationInputMode: the new value

onPopulateItemContextMenu

(evt: PopulateItemContextMenuEventArgs<IModelItem>)

Raises the populate-item-context-menu event.

Parameters

options - Object
A map of options to pass to the method.

evt - PopulateItemContextMenuEventArgs<IModelItem>: The PopulateItemContextMenuEventArgs<TModelItem> instance containing the event data.

onQueryItemToolTip

(evt: QueryItemToolTipEventArgs<IModelItem>)

Raises the query-item-tool-tip event.

Parameters

options - Object
A map of options to pass to the method.

evt - QueryItemToolTipEventArgs<IModelItem>: The QueryItemToolTipEventArgs<TModelItem> instance containing the event data.

onToolTipInputModeChanged

(oldMode: ToolTipInputMode, newMode: ToolTipInputMode)

Called when the toolTipInputMode property value changes and after initialization of the property.

Parameters

options - Object
A map of options to pass to the method.

oldMode - ToolTipInputMode: the old value, which may be null the first time
newMode - ToolTipInputMode: the new value

onWaitInputModeChanged

(oldMode: WaitInputMode, newMode: WaitInputMode)

Called when the waitInputMode property value changes and after initialization of the property.

Parameters

options - Object
A map of options to pass to the method.

oldMode - WaitInputMode: the old value, which may be null the first time
newMode - WaitInputMode: the new value

remove

(mode: IInputMode)

Removes the given mode from this compound mode.

Parameters

options - Object
A map of options to pass to the method.

mode - IInputMode: The mode to remove.

Defined in

selectAll

()

Clears the current selection and selects all nodes and bends in this graph.

Remarks

By default, this method will be called in response to a Ctrl+A key press recognized by keyboardInputMode.

setCurrentItem

(item: IModelItem)

Called by this instance to set the current item on the NavigationInputMode

Parameters

options - Object
A map of options to pass to the method.

item - IModelItem: The item to set as the new "current" item.

setSelected

(item: IModelItem, selected: boolean)

Uses the graphSelection to select the given item.

Parameters

options - Object
A map of options to pass to the method.

item - IModelItem: The item to set the selection state on.
selected - boolean: The new selection state.

shouldSkipHitLabel

(context: IInputModeContext, hitLabel: ILabel, location: Point) : boolean

Callback function that is used during hit testing, when an ILabel was hit tested before another non-label underneath it was reported.

Remarks

This method can be used to prioritize the hit testing order for items below labels, depending on the label.

This implementation returns false if skipHitLabels is false or if the context's inputMode is not a GraphInputMode or MoveInputMode.

Parameters

options - Object
A map of options to pass to the method.

context - IInputModeContext: The context in which the hit testing is performed.
hitLabel - ILabel: The label that was hit before a non-label at the same location.
location - Point: The location the label was hit.

Returns

↪boolean: Whether to first report the non-label during hit testing.

subModePriorityChanged

()

Called when the priority of an installed sub mode has changed.

Remarks

This implementation uninstalls all sub modes and then re-installs them according to their new priorities.

Defined in

tryStop

() : boolean

Tries to stop all modes.

Returns

↪boolean: true if the editing process was successfully stopped, or if there was no edit in progress to stop; otherwise, false.

Implements