Pointer Handling

GraphEditorInputMode and GraphViewerInputMode offer convenient handling of mouse and stylus clicks, as well as stylus and touch taps on items. In this chapter, clicks refers to both clicks and taps, unless otherwise specified.

GraphEditorInputMode and GraphViewerInputMode dispatch several events for different kinds of clicks, as listed in the table below.

In most cases, handling click events alone is sufficient for customization. If you need complete control over what happens on clicks within GraphEditorInputMode or GraphViewerInputMode, you can override the click method. This method handles all the default actions, such as raising click events, propagating them to items at the clicked location, and handling default actions like selection and focus.

The items for which clicks are reported (the clickable items) can be defined using the clickableItems property. This property defines the item types for which clicks are reported, using a combination of the values defined in GraphItemTypes. None of the above events are raised when clicking an item that is not considered clickable.

Finer control can be achieved by setting a custom clickablePredicate. The default clickablePredicate just compares an item with the clickableItems.

The hit testing order for single and double clicks is not necessarily the same as the display order of items. It is determined by the clickHitTestOrder and doubleClickHitTestOrder properties, respectively. These properties take an array of GraphItemTypes which is processed in the following way: The hit test searches the given location for the topmost item of the type (or types) that is first in the array. If none is found, it searches for items of the types defined in the next element.

graphEditorInputMode.clickHitTestOrder = [
  GraphItemTypes.NODE | GraphItemTypes.EDGE | GraphItemTypes.LABEL
]

In the above example, the topmost element of type node or edge is preferred as the hit item, even if there are other types of elements (like labels) on top of them. Only if neither a node nor an edge can be found at the given location, is the topmost label looked for. Note that when using combined values in this way, the visual order of those items (usually nodes are on top of edges) takes precedence. It’s often preferable to only use simple values in the hit testing order to avoid side effects when changing the rendering order of items.

Click handling and click selection are closely related. Click selection is handled after handling clicks. This has the following consequences:

• Click selection is not handled for items that do not report clicks. Therefore, clickSelectableItems is treated as a subset of clickableItems.
• Setting handled on the ItemClickedEventArgs<T> stops the event from being further processed internally. Therefore, setting handled to true for an item prevents this item from being selected by this click.
• The clickHitTestOrder is overridden by detail selection and cyclic selection. See also section Selection.

The actual click handling is delegated to GraphEditorInputMode’s and GraphViewerInputMode’s child input mode ClickInputMode. Both listen for ClickInputMode’s clicked event, process it, and dispatch the appropriate item clicked event.

You might want to listen for this event if GraphEditorInputMode’s or GraphViewerInputMode’s item clicked events are not applicable for your use case.

ClickInputMode provides several properties to further customize click handling:

clickReportingPolicy

Uses the values defined in ClickReportingPolicy to determine how to dispatch single click events for double clicks. By default, both the first and second clicks are reported before the double click itself is reported.

validClickHitTestable

validClickHitTestableTouch

Allows you to restrict the area where mouse or stylus clicks, or touch taps, are recognized. By default, the areas are unrestricted.

swallowFocusClick

Specifies whether clicks should be discarded if they occur within 100ms after the canvas receives focus. By default, this is disabled.