C

ItemHoverInputMode

Show Usages
An input mode for use in a GraphComponent that fires events when the pointer enters or leaves the visualization of a graph item.
ImplementsInheritance Hierarchy

Remarks

This mode can be used to determine when the pointer is being moved from one item to the next.

This mode is exclusive by default.

Examples

Typically, the ItemHoverInputMode is installed as child mode of a GraphEditorInputMode or GraphViewerInputMode and can be retrieved from the itemHoverInputMode property.

Getting the ItemHoverInputMode from its parent input mode
const itemHoverInputMode = mode.itemHoverInputMode

The ItemHoverInputMode raises the hovered-item-changed event each time the 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
  },
)

See Also

Demos

Displays sample graphs from various application domains.

Members

Show:

Constructors

ItemHoverInputMode

()
Initializes a new instance of the ItemHoverInputMode class.

Parameters

Properties

controller

: ConcurrencyController
protectedreadonly
Gets the installed controller.
protectedreadonlyfinal

currentHoverItem

: IModelItem
readonly
Gets the current item the pointer is hovering over.
readonlyfinal

Property Value

The current item or null if the pointer is not hovering over a valid item.

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.

Examples

Disabling the ItemHoverInputMode on its parent input mode
mode.itemHoverInputMode.enabled = false

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

hoverCursor

: Cursor
Gets or sets the cursor to use when the pointer is hovering over a isValidHoverItem valid hover item.
conversionfinal

Property Value

The hover cursor or null (the default).

hoverItems

: GraphItemTypes
Gets or sets which graph items are considered by this input mode.

The default is ALL.

Note that the default is set to a different value if this mode is a child mode of the GraphEditorInputMode or GraphViewerInputMode. and documented there.

conversionfinal

Examples

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
  },
)

ignoreInvalidItems

: boolean
Gets or sets a value indicating whether items that have been hit at the current location that are not valid items should be ignored (and an underlying valid item be considered instead) or reported as null.

This setting also has an influence, if the items you want to hover over are covered by "invalid" items in front of them. By default, these "invalid" items will stop the hover picking process and null will be reported, even if there is a valid item underneath the hovered item.

Set this to true to let hit test enumeration continue to find the next valid item. Set this to false if invalid items should be reported as null.

The default is true.

final

See Also

API
isValidHoverItem, getHitItemsAt

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 get 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

Methods

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 implementation of IInputModeContext that is specific to this mode.

This is needed for events that are triggered by this InputMode to signal where the event is coming from. A common usage for this is, for example, in isHit calls.

The result can be given to isHit or enumerateHits to let implementations of IHitTestable get access to the current IInputModeContext. This can be done by looking up IInputModeContext from the ICanvasContext's lookup method or simply down-casting.

protected

Return Value

IInputModeContext
A readily configured IInputModeContext.

See Also

API
enumerateHits, isHit, IInputModeContext

getHitItemsAt

(location: Point): IEnumerable<IModelItem>
protected
Gets the items that have been hit at the given location.
When ignoreInvalidItems is set, this will only query hoverItems from the enumerateHits. Otherwise, all items will be reported and later checked against isValidHoverItem.
protected

Parameters

location: Point
The location in world coordinates to query.

Return Value

IEnumerable<IModelItem>
An enumerable over the items that have been hit at the given location.

install

(context: IInputModeContext, controller: ConcurrencyController)
Installs this mode into the given context that is provided by the canvas.

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

This method is called to initialize this instance. Subclasses should override this method to register the corresponding event handler delegates for the various input events they need to register with.

Overriding implementations should call the base implementation, first.

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.

See Also

API
uninstall

isValidHoverItem

(item: IModelItem): boolean
protected
Determines whether the given item is a valid item to be considered for hovering.
This implementation checks whether the item is covered by the hoverItems set, only.
protected

Parameters

item: IModelItem
The item to check.

Return Value

boolean
true if it is valid to report a hover over the specified item; false otherwise.

See Also

API
getHitItemsAt, ignoreInvalidItems

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

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

onHoveredItemChanged

(evt: HoveredItemChangedEventArgs)
protected
Raises the hovered-item-changed event.
protected

Parameters

evt: HoveredItemChangedEventArgs
The HoveredItemChangedEventArgs 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

tryStop

(): boolean
Overridden to only return true if this instance does not currently have the input mutex.

Return Value

boolean
true iff this instance does not own the mutex.

uninstall

(context: IInputModeContext)
Uninstalls this mode from the given context.

This code should clean up all changes made to the canvas in the install method. After a mode has been uninstalled it can be installed again into the same or another canvas.

Overriding implementations should call the base implementation after their own code.

Parameters

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

updateHover

(location?: Point)
Forces a reevaluation of the item that the pointer is currently hovering over or at a specific location.
This method may be called by code that is aware of the fact that the visualization has changed, but the pointer may not have been moved. By default, this implementation will only re-query the items at the pointer location when the pointer was moved. This method can be called to force a reevaluation in other cases.
final

Parameters

location?: Point
The query location. If omitted, the last location is queried again.

Events

'hovered-item-changed'

: HoveredItemChangedEventArgs
Occurs when the item that is being hovered over with the pointer changes.
This event is also fired when the pointer leaves an item.
context: IInputModeContext
Gets the context for the current event.
item: IModelItem
Gets the item that is currently hovered or null if no item is hovered.
oldItem: IModelItem
Gets or sets the item that was previously hovered, possibly null.

Examples

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
  },
)