documentationfor yFiles for HTML 2.6

Mouse Clicks

GraphEditorInputMode and GraphViewerInputMode allow convenient handling of mouse clicks on items. Both dispatch a number of events for different kinds of mouse clicks (e.g. single, double, left, right, and combinations thereof) as listed in the table below.

Related events
Event Occurs when …​
ItemLeftClicked…​ a left click on a clickable item occurred.
ItemRightClicked…​ a right click on a clickable item occurred.
ItemClicked…​ any mouse click on a clickable item occurred. This event is dispatched after the event for left or right click.
ItemLeftDoubleClicked…​ a double click with the left button on a clickable item occurred.
ItemRightDoubleClicked…​ a double click with the right button on a clickable item occurred.
ItemDoubleClicked…​ a double click with any button on a clickable item occurred. This event is dispatched after the event for left or right double click.
CanvasClicked…​ a mouse click is performed at a location where no clickable item can be found. Note that this may be on another item if that item is not clickable. The default action in this case is to create a new node (cf. Customizing Creating Nodes). Handling this event will prevent that.

In most cases handling click events only will suffice. If you need complete control over what happens on clicks within GraphEditorInputMode or GraphViewerInputMode you can override the click method which handles all the default actions, such as raising click events, propagating them to items that are at the clicked location and also handling default actions, such as selection and focus.

The items for which mouse 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 overriding the shouldClick method.

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 looks at the given location for the topmost item of the type (or types) which 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 will be preferred as 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, the topmost label will be 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 will be handled after handling mouse clicks. This has a few consequences:

  • Click selection will not be handled for items which do not report mouse clicks. Therefore, clickSelectableItems is treated as a subset of clickableItems.
  • Setting handled on the ItemClickedEventArgs<T> will stop the event from being further processed internally. Therefore, setting handled to true for an item will prevent this item from being selected by this mouse 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 and DoubleClicked events to handle mouse clicks.

Related events
Event Occurs when …​
Clicked…​ a mouse click has been detected.
LeftClicked…​ a left click has been detected.
RightClicked…​ a right click has been detected.
DoubleClicked…​ a double click has been detected.
LeftDoubleClicked…​ a double click with the left mouse button has been detected.
RightDoubleClicked…​ a double click with the right mouse button has been detected.

You may want to listen for these events, if GraphEditorInputMode’s or GraphViewerInputMode’s item click events are not applicable for your use case.

ClickInputMode provides a number of properties to further customize click handling:

doubleClickPolicy
Uses the values defined in DoubleClickPolicy to determine how to dispatch single click events for double clicks. By default, both the first and second click are reported before the double click itself is reported.
validClickHitTestable
Allows to restrict the area where mouse clicks should be recognized. By default the area is unrestricted.
activeButtons
Determines for which buttons mouse clicks should be reported. By default left and right clicks are reported.
swallowFocusClick
Whether clicks should be discarded if they occur within 100ms after the canvas got the focus. By default this is disabled.