CreateEdgeInputMode

Remarks

This class provides a factory callback that the final edge creation will be delegated to. The styling of the newly created edge can be customized via the edgeDefaults. Defaults can be automatically adjusted in response to the various events that will be triggered by this instance during the edge creation.

Use the previewGraph property to modify the appearance of the preview edge. This class uses IPortCandidateProvider instances found in the ILookup of the nodes in the graph to display port candidates and to finally create the edges.

The CreateEdgeInputMode provides a well-defined event lifecycle to track the progression of the edge creation:

gesture-starting – Occurs when the edge creation gesture is initiated. This happens before the edge becomes visible and marks the beginning of the interaction sequence.
gesture-started – Occurs immediately after gesture-starting, indicating that the gesture has been fully initialized and is now in progress. This event precedes any visible feedback or edge creation operations.
edge-creation-started – Occurs when the creation of an edge visibly begins. This happens when the cursor moves outside the source node during the gesture. At this point, the target port candidate becomes relevant.
gesture-canceling – Occurs when the edge creation gesture is about to be canceled. This event is always followed by gesture-canceled.
gesture-canceled – Occurs when the gesture has been canceled. No edge will be created, and the gesture sequence ends.
gesture-finishing – Occurs when the gesture is about to be successfully completed. This event allows the target port candidate to be updated one last time before finalization.
edge-created – Occurs after an edge has been successfully created as a result of the interaction.
gesture-finished – Occurs when the edge creation gesture has successfully completed and all operations are finalized.

Additionally, the following auxiliary events provide specific feedback during the gesture:

moving and moved – These events occur at the start and end of every drag or move action during the gesture.
edge-direction-reversed – Occurs if the direction of the edge creation is reversed during the gesture.

This event sequence ensures symmetry between the initialization and finalization of gestures, and provides fine-grained control for handling cancellations and completions.

This mode is exclusive by default.

Examples

Typically the CreateEdgeInputMode is installed as child mode of a GraphEditorInputMode and can be retrieved from the createEdgeInputMode property.

Getting the CreateEdgeInputMode from its parent input mode

const createEdgeInputMode = mode.createEdgeInputMode

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

Type Details

yFiles module: view

Constructors

CreateEdgeInputMode

()

Creates a new instance that will use the IGraph from the parentInputModeContext to create edges in.

Remarks

Setting the graph property can be used to optionally set a different graph to work on.

ParametersOptions Overload

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

priority - number

exclusive - boolean

A value indicating whether this mode will be the only one running when it has the mutex. This option sets the exclusive property on the created object.

enabled - boolean

The enabled state of this input mode. This option sets the enabled property on the created object.

validBeginCursor - Cursor

The cursor that indicates a valid place to begin an edge creation. This option sets the validBeginCursor property on the created object.

validBendCursor - Cursor

The cursor that indicates a valid place to create a bend. This option sets the validBendCursor property on the created object.

dragCursor - Cursor

The cursor that is used while a new edge is created when there is no valid location to create a bend. This option sets the dragCursor property on the created object.

startPortOwnerDraggingCursor - Cursor

The cursor that is used once edge creation has started but the mouse is still over the new edge's start node. This option sets the startPortOwnerDraggingCursor property on the created object.

validEndCursor - Cursor

The cursor that indicates a valid place to finish creation. This option sets the validEndCursor property on the created object.

disableSnappingRecognizer - function(EventArgs, unknown):boolean

The event recognizer that temporarily disables snapping. This option sets the disableSnappingRecognizer property on the created object.

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.

enableSnappingRecognizer - function(EventArgs, unknown):boolean

The event recognizer that re-enables temporarily disabled snapping. This option sets the enableSnappingRecognizer property on the created object.

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.

directionalConstraintRecognizer - function(EventArgs, unknown):boolean

The event recognizer that constrains the current edge segment to be orthogonal or diagonal. This option sets the directionalConstraintRecognizer property on the created object.

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.

toggleSegmentOrientationRecognizer - function(EventArgs, unknown):boolean

The event recognizer that toggles the orientation of the first orthogonal segment. This option sets the toggleSegmentOrientationRecognizer property on the created object.

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.

toggleDirectionRecognizer - function(EventArgs, unknown):boolean

The event recognizer that recognizes gestures which toggle the direction of the created edge. This option sets the toggleDirectionRecognizer property on the created object.

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.

finishRecognizer - function(EventArgs, unknown):boolean

The event recognizer that recognizes the finishing gesture that is used to end the edge creation on the end node. This option sets the finishRecognizer property on the created object.

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.

beginRecognizer - function(EventArgs, unknown):boolean

The event recognizer that recognizes the start gesture that is used to prepare the edge creation on the start node or edge. This option sets the beginRecognizer property on the created object.

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.

moveRecognizer - function(EventArgs, unknown):boolean

The event recognizer that recognizes the initial gesture that is used to initiate the creation after the preparation. This option sets the moveRecognizer property on the created object.

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.

endPointMoveRecognizer - function(EventArgs, unknown):boolean

The event recognizer that recognizes the movement of the end point of the edge. This option sets the endPointMoveRecognizer property on the created object.

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.

createBendRecognizer - function(EventArgs, unknown):boolean

The event recognizer that determines whether to create a bend. This option sets the createBendRecognizer property on the created object.

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.

enforceBendCreationRecognizer - function(EventArgs, unknown):boolean

The event recognizer that will be queried to decide if bend creation is enforced. This option sets the enforceBendCreationRecognizer property on the created object.

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.

cancelRecognizer - function(EventArgs, unknown):boolean

The event recognizer that determines whether to cancel edge creation. This option sets the cancelRecognizer property on the created object.

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.

removeBendRecognizer - function(EventArgs, unknown):boolean

The event recognizer that determines whether to remove the last created bend. This option sets the removeBendRecognizer property on the created object.

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.

portCandidateResolutionRecognizer - function(EventArgs, unknown):boolean

The event recognizer that determines whether dynamic port candidates should be resolved. This option sets the portCandidateResolutionRecognizer property on the created object.

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.

finishRecognizerTouch - function(EventArgs, unknown):boolean

The event recognizer that recognizes the touch gesture that is used to end the edge creation on the end node. This option sets the finishRecognizerTouch property on the created object.

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.

beginRecognizerTouch - function(EventArgs, unknown):boolean

The event recognizer that recognizes the touch gesture that is used to prepare the edge creation on the start node. This option sets the beginRecognizerTouch property on the created object.

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.

moveRecognizerTouch - function(EventArgs, unknown):boolean

The event recognizer that recognizes the touch gesture that is used to initiate the edge creation after the preparation. This option sets the moveRecognizerTouch property on the created object.

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.

createBendRecognizerTouch - function(EventArgs, unknown):boolean

The event recognizer that determines whether to create a bend via touch. This option sets the createBendRecognizerTouch property on the created object.

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.

cancelRecognizerTouch - function(EventArgs, unknown):boolean

The event recognizer that determines whether to cancel edge creation via touch. This option sets the cancelRecognizerTouch property on the created object.

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.

removeBendRecognizerTouch - function(EventArgs, unknown):boolean

The event recognizer that determines whether to remove the last created bend via touch. This option sets the removeBendRecognizerTouch property on the created object.

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.

showPortCandidates - ShowPortCandidates

Whether and where to display possible port candidates during the creation of the edge. This option sets the showPortCandidates property on the created object.

allowEdgeToEdgeConnections - boolean

Whether or not edges are allowed to connect to other edges. This option sets the allowEdgeToEdgeConnections property on the created object.

snapDistance - number

The distance in the view coordinate system that determines how far the mouse should be snapped to a port candidate if snapToEndCandidate is enabled. This option sets the snapDistance property on the created object.

snapContext - GraphSnapContext

The GraphSnapContext which manages snapping model items to certain coordinates (for instance, other items). This option either sets the value directly or recursively sets properties to the instance of the snapContext property on the created object.

portCandidateRenderer - IObjectRenderer<PortCandidateRenderTag>

The IObjectRenderer<PortCandidateRenderTag> that visualizes IPortCandidates while creating edges. This option sets the portCandidateRenderer property on the created object.

orthogonalSnapDistance - number

The distance in the view coordinate system that determines how far the mouse should be snapped to a horizontal or vertical line. This option sets the orthogonalSnapDistance property on the created object.

forceSnapToCandidate - boolean

A property that determines whether the mouse should be forced to snap to the nearest valid port candidate if the mouse hovers over an end node. This option sets the forceSnapToCandidate property on the created object.

useHitItemsCandidatesOnly - boolean

Whether this mode should use the end port candidates of the node the pointer currently hovers over, only. This option sets the useHitItemsCandidatesOnly property on the created object.

orthogonalEdgeCreation - OrthogonalEdgeEditingPolicy

The policy that controls whether edges will be created orthogonally. This option sets the orthogonalEdgeCreation property on the created object.

preferredMinimalEdgeDistance - number

The preferred minimal distance of orthogonal edges. This option sets the preferredMinimalEdgeDistance property on the created object.

resolveStartPortCandidates - boolean

A value indicating whether DYNAMIC ports that are part of the start port candidates should be resolved for the current mouse location. This option sets the resolveStartPortCandidates property on the created object.

resolveEndPortCandidates - boolean

A value indicating whether DYNAMIC ports that are part of the end port candidates should be resolved for the current pointer location. This option sets the resolveEndPortCandidates property on the created object.

edgeDirectionPolicy - EdgeDirectionPolicy

A value that determines how the direction of a newly created edge is determined. This option sets the edgeDirectionPolicy property on the created object.

reversedEdgeCreation - boolean

A value indicating whether the current edge creation should be created from its targetPort to its sourcePort. This option sets the reversedEdgeCreation property on the created object.

nodeBorderWidthRatio - number

The width of a node's border which is taken into account when deciding which way to route the first segment of an orthogonal edge. This option sets the nodeBorderWidthRatio property on the created object.

edgeCreator - function(IInputModeContext, IGraph, IPortCandidate, IPortCandidate, IEdge):Promise<IEdge|null>

The ports-based edge creation callback. This option sets the edgeCreator property on the created object.

Signature Details

function(context: IInputModeContext, graph: IGraph, sourcePortCandidate: IPortCandidate, targetPortCandidate: IPortCandidate, templateEdge: IEdge) : Promise<IEdge | null> | IEdge

The delegate method that is used by CreateEdgeInputMode to create edges between instances of IPort.

The edgeCreator uses this type of callback to actually create edges between nodes.

Parameters

context - IInputModeContext: The context of the input mode this action is used in.
graph - IGraph: The graph to create the edge in.
sourcePortCandidate - IPortCandidate: The source port candidate.
targetPortCandidate - IPortCandidate: The target port candidate. If null the callback either has to create the target port itself or cancel the edge creation by returning null.
templateEdge - IEdge: The dummy edge instance that serves as template for the actual edge creation. This edge is not part of the graph

Returns

Promise<IEdge | null> | IEdge: The newly created edge, null, or a Promise resolving with an edge or null.

allowSelfLoops - boolean

Whether or not to allow the creation of self-loops. This option sets the allowSelfLoops property on the created object.

cancelGestureOnInvalidEnd - boolean

Whether an edge creation gesture will be canceled when the gesture is ended on an invalid end point and no bend may be created there. This option sets the cancelGestureOnInvalidEnd property on the created object.

allowCreateBend - boolean

Whether to allow the creation of bends. This option sets the allowCreateBend property on the created object.

startPortCandidate - IPortCandidate

The candidate for the sourcePort of the edge to be created. This option sets the startPortCandidate property on the created object.

endPortCandidate - IPortCandidate

The current candidate for the end point of the dragged edge to be created. This option sets the endPortCandidate property on the created object.

showEndHighlight - boolean

Whether the owner of the current endPortCandidate should be highlighted. This option sets the showEndHighlight property on the created object.

cancelEditImplicitly - boolean

Whether after calls to createEdge the current undo edit should be canceled if the method returns null. This option sets the cancelEditImplicitly property on the created object.

edgeDefaults - IEdgeDefaults

The appearance of newly created edges. This option either sets the value directly or recursively sets properties to the instance of the edgeDefaults property on the created object.

snapToEndCandidate - boolean

Whether or not the edge's end point should snap to the current end port candidate during the creation of the edge. This option sets the snapToEndCandidate property on the created object.

showStartPortCandidatesHitTestable - IHitTestable

A IHitTestable that determines whether to show start port candidates if the cursor hovers over the provided location. This option sets the showStartPortCandidatesHitTestable property on the created object.

beginHitTestable - IHitTestable

A IHitTestable that determines whether it is valid to start an edge creation gesture here. This option sets the beginHitTestable property on the created object.

endHitTestable - IHitTestable

A IHitTestable that determines whether it is valid to finish an edge creation gesture here if valid IPortCandidates are available. This option sets the endHitTestable property on the created object.

prematureEndHitTestable - IHitTestable

A IHitTestable that determines whether it is valid to finish an edge creation gesture here even if no IPortCandidates are available. This option sets the prematureEndHitTestable property on the created object.

validBendHitTestable - IHitTestable

A IHitTestable that determines whether it is valid to create a bend here. This option sets the validBendHitTestable property on the created object.

startOverCandidateOnly - boolean

Whether edge creation should only start if the pointer is located directly over a valid port candidate. This option sets the startOverCandidateOnly property on the created object.

startPortCandidateHitRadius - number

The radius from within a valid port candidate will be considered as hit. This option sets the startPortCandidateHitRadius property on the created object.

startPortOwnerDraggingFinishedRecognizer - function(EventArgs, unknown):boolean

The event recognizer that starts the actual edge creation while dragging. This option sets the startPortOwnerDraggingFinishedRecognizer property on the created object.

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.

showStartPortCandidateDelay - TimeSpan

The amount of time to wait until the start port candidates are displayed, when the user hovers over a start port candidate owner. This option sets the showStartPortCandidateDelay property on the created object.

minimumSelfLoopBendCount - number

The minimum number of bends to create before a self-loop is created. This option sets the minimumSelfLoopBendCount property on the created object.

cancelCreationOnFocusLost - boolean

A value that specifies whether moving the input focus away from the canvasComponent cancels edge creation. This option sets the cancelCreationOnFocusLost property on the created object.

Properties

allowCreateBend

: boolean

Gets or sets whether to allow the creation of bends.

Remarks

The default is true.

Examples

To disable bend creation during edge creation and on existing edges one has to disable the createBendInputMode, too.

Disabling the bend creation during edge creation and on existing edges

// mode is an instance of GraphEditorInputMode
mode.createBendInputMode.enabled = false
mode.createEdgeInputMode.allowCreateBend = false

allowEdgeToEdgeConnections

: boolean

Gets or sets whether or not edges are allowed to connect to other edges.

Remarks

The default is false.

Examples

Enabling edge to edge connections (the red edge)

createEdgeInputMode.allowEdgeToEdgeConnections = true

allowSelfLoops

: boolean

Gets or sets whether or not to allow the creation of self-loops.

Remarks

The default is true, which enables that an edge is connected to a sourcePort and targetPort that have the same owner.

Examples

Enabling self-loops:

createEdgeInputMode.allowSelfLoops = true

beginHitTestable

Gets or sets a IHitTestable that determines whether it is valid to start an edge creation gesture here.

Remarks

The default implementation returns true if the cursor is located over a port owner.

Examples

To avoid showing port candidates for selected nodes (e.g. to move them instead of considering them as the start point of an edge creation), developers might set a hit testable which excludes selected items.

class UnselectedNodesHitTestable extends BaseClass<IHitTestable>(
  IHitTestable,
) {
  isHit(context: IInputModeContext, location: Point): boolean {
    const graphComponent = context.canvasComponent as GraphComponent
    return graphComponent.graph.nodes.some(
      (node) =>
        !graphComponent.selection.includes(node) &&
        node.style.renderer
          .getHitTestable(node, node.style)
          .isHit(context, location),
    )
  }
}

Note that the same hit testable should be set to showStartPortCandidatesHitTestable, too.

beginRecognizer

: function(EventArgs, unknown):boolean

Gets or sets the event recognizer that recognizes the start gesture that is used to prepare the edge creation on the start node or edge.

Remarks

The default recognizer detects primary down events for MOUSE or PEN.

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.

beginRecognizerTouch

: function(EventArgs, unknown):boolean

Gets or sets the event recognizer that recognizes the touch gesture that is used to prepare the edge creation on the start node.

Remarks

The default is TOUCH_PRIMARY_LONG_PRESS. If showPortCandidates includes START, this will also show the port candidates.

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.

cancelCreationOnFocusLost

: boolean

Gets or sets a value that specifies whether moving the input focus away from the canvasComponent cancels edge creation.

Remarks

By default, moving the focus to another component will cancel edge creation. If you need fine control and allow certain focus targets, override method isValidTemporaryFocusTarget.

cancelEditImplicitly

: boolean

Gets or sets whether after calls to createEdge the current undo edit should be canceled if the method returns null.

Remarks

This should be set to false if you want to perform some undoable actions in these methods and/or in the edgeCreator callback, but need to return null from any of these methods. Default value is true, meaning that returning null results in canceling the composite undo entry.

cancelGestureOnInvalidEnd

: boolean

Gets or sets whether an edge creation gesture will be canceled when the gesture is ended on an invalid end point and no bend may be created there.

Remarks

If bend creation is allowed at the current location (i.e. validBendHitTestable returns true), the gesture will always continue by creating a bend. Otherwise, if this property is true, the gesture will be canceled automatically.

The default is true, meaning that the gesture ends when continuing is not possible.

cancelRecognizer

: function(EventArgs, unknown):boolean

Gets or sets the event recognizer that determines whether to cancel edge creation.

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.

cancelRecognizerTouch

: function(EventArgs, unknown):boolean

Gets or sets the event recognizer that determines whether to cancel edge creation via touch.

Remarks

The default recognizer detects secondary double tap events.

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.

controller

: ConcurrencyController?

Gets the installed controller.

createBendRecognizer

: function(EventArgs, unknown):boolean

Gets or sets the event recognizer that determines whether to create a bend.

Remarks

The default recognizer detects primary DOWN events for MOUSE or PEN.

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.

createBendRecognizerTouch

: function(EventArgs, unknown):boolean

Gets or sets the event recognizer that determines whether to create a bend via touch.

Remarks

The default is TOUCH_PRIMARY_UP.

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.

directionalConstraintRecognizer

: function(EventArgs, unknown):boolean

Gets or sets the event recognizer that constrains the current edge segment to be orthogonal or diagonal.

Remarks

The default recognizer is SHIFT_IS_DOWN

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.

disableSnappingRecognizer

: function(EventArgs, unknown):boolean

Gets or sets the event recognizer that temporarily disables snapping.

Remarks

The default recognizer is ALT_DOWN

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.

dragCursor

: Cursor?

Gets or sets the cursor that is used while a new edge is created when there is no valid location to create a bend.

Remarks

The default cursor is DEFAULT.

dragPoint

: IPoint

Gets the dynamically updated dragging point for the edge creation.

edgeCreator

: function(IInputModeContext, IGraph, IPortCandidate, IPortCandidate, IEdge):Promise<IEdge|null>

Gets or sets the ports-based edge creation callback.

Remarks

The default creator will delegate to createEdge and obtain the tag from the previewEdge. It will then copy over all bends, labels, and ports from the previewEdge.

When a Promise is returned, this mode will keep the mutex until it is resolved, thereby blocking any user interaction.

Property Value

The ports-based edge creation callback that will be used during createEdge.

Signature Details

function(context: IInputModeContext, graph: IGraph, sourcePortCandidate: IPortCandidate, targetPortCandidate: IPortCandidate, templateEdge: IEdge) : Promise<IEdge | null> | IEdge

The delegate method that is used by CreateEdgeInputMode to create edges between instances of IPort.

The edgeCreator uses this type of callback to actually create edges between nodes.

Parameters

context - IInputModeContext: The context of the input mode this action is used in.
graph - IGraph: The graph to create the edge in.
sourcePortCandidate - IPortCandidate: The source port candidate.
targetPortCandidate - IPortCandidate: The target port candidate. If null the callback either has to create the target port itself or cancel the edge creation by returning null.
templateEdge - IEdge: The dummy edge instance that serves as template for the actual edge creation. This edge is not part of the graph

Returns

Promise<IEdge | null> | IEdge: The newly created edge, null, or a Promise resolving with an edge or null.

Throws

Exception({ name: 'ArgumentError' }): If the argument is null

Examples

A custom edge creator

// set a custom edge creator which creates a label on the new edge
createEdgeInputMode.edgeCreator = (
  context: IInputModeContext,
  graph: IGraph,
  sourceCandidate: IPortCandidate,
  targetCandidate: IPortCandidate | null,
  dummyEdge: IEdge,
): IEdge | null | Promise<IEdge | null> => {
  if (targetCandidate === null) {
    return null
  }
  // get the source and target ports from the candidates
  const sourcePort =
    sourceCandidate.port !== null
      ? sourceCandidate.port
      : sourceCandidate.createPort(context)
  const targetPort =
    targetCandidate.port !== null
      ? targetCandidate.port
      : targetCandidate.createPort(context)

  // create the edge between the source and target port
  const edge = graph.createEdge(sourcePort, targetPort, dummyEdge.style)
  // create a label
  graph.addLabel(edge, 'A new edge')
  // return the created edge
  return edge
}

edgeDefaults

: IEdgeDefaults

Gets or sets the appearance of newly created edges.

Remarks

This property directly delegates to the edgeDefaults of the previewGraph.

edgeDirectionPolicy

: EdgeDirectionPolicy

Gets or sets a value that determines how the direction of a newly created edge is determined.

Remarks

This property is START_AT_SOURCE by default which means that edges are created from the source to the target. Setting the value to DETERMINE_FROM_PORT_CANDIDATES will query both source and target port candidates during getStartPortCandidates. Depending on which candidate is chosen in getStartPortCandidate the edge creation will either be reversed or not.

Setting the property to another value during edge creation will not affect the current edge. Set reversedEdgeCreation to control the direction of a currently active edge creation.

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.

Examples

Disabling the CreateEdgeInputMode on its parent input mode

mode.createEdgeInputMode.enabled = false

enableSnappingRecognizer

: function(EventArgs, unknown):boolean

Gets or sets the event recognizer that re-enables temporarily disabled snapping.

Remarks

The default recognizer is ALT_UP

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.

endHitTestable

: OrthogonalEdgeEditingPolicy

Gets or sets a IHitTestable that determines whether it is valid to finish an edge creation gesture here if valid IPortCandidates are available.

Remarks

This hit testable is only queried if forceSnapToCandidate is disabled.

If this IHitTestable returns true a valid port candidate is searched. If and only if one is found the current location is considered as possible end for an edge creation. If this IHitTestable returns false prematureEndHitTestable is queried.

The default implementation returns true if there is a port owner at the given location.

endPointMoveRecognizer

: function(EventArgs, unknown):boolean

Gets or sets the event recognizer that recognizes the movement of the end point of the edge.

Remarks

The default recognizer detects DRAG events for MOUSE and PEN.

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.

endPortCandidate

: IPortCandidate?

Gets or sets the current candidate for the end point of the dragged edge to be created.

Remarks

Note that depending on whether reversedEdgeCreation is currently set, this could also become the sourcePort at the end of the creation.

enforceBendCreationRecognizer

: function(EventArgs, unknown):boolean

Gets or sets the event recognizer that will be queried to decide if bend creation is enforced.

Remarks

The default is ALT_IS_DOWN.

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.

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.

finishRecognizer

: function(EventArgs, unknown):boolean

Gets or sets the event recognizer that recognizes the finishing gesture that is used to end the edge creation on the end node.

Remarks

The default recognizer detects primary up or down events for MOUSE or PEN.

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.

finishRecognizerTouch

: function(EventArgs, unknown):boolean

Gets or sets the event recognizer that recognizes the touch gesture that is used to end the edge creation on the end node.

Remarks

The default is TOUCH_PRIMARY_UP.

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.

forceSnapToCandidate

: boolean

Gets or sets a property that determines whether the mouse should be forced to snap to the nearest valid port candidate if the mouse hovers over an end node.

Remarks

If the nearest port candidate is farther away than snapDistance and the mouse hovers over a valid end, this property will cause the mouse to snap to the nearest valid candidate. The default is true.

graph

: IGraph

Gets the graph this mode is acting upon.

Throws

Exception({ name: 'NotSupportedError' }): If there is no input mode context available or the context does not contain the graph in the lookup.

isCreationInProgress

: boolean

Gets whether currently an edge creation is in progress.

Remarks

This property yields true after the edge creation has been started and before it has been cancelled or finalized.

minimumSelfLoopBendCount

: number

Gets or sets the minimum number of bends to create before a self-loop is created.

Remarks

By default, this is set to 2 so if you accidentally start an edge creation, you can cancel edge creation by going back to the start node. This limit is only considered when the edge allows adding bends, at all.

moveRecognizer

: function(EventArgs, unknown):boolean

Gets or sets the event recognizer that recognizes the initial gesture that is used to initiate the creation after the preparation.

Remarks

The default recognizer is MOUSE_DRAG.

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.

moveRecognizerTouch

: function(EventArgs, unknown):boolean

Gets or sets the event recognizer that recognizes the touch gesture that is used to initiate the edge creation after the preparation.

Remarks

The default is TOUCH_PRIMARY_DRAG.

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.

nodeBorderWidthRatio

: number

Gets or sets the width of a node's border which is taken into account when deciding which way to route the first segment of an orthogonal edge.

Remarks

An edge starting inside a given margin is always pointing away from it.

orthogonalEdgeCreation

Gets or sets the policy that controls whether edges will be created orthogonally.

Remarks

By default, orthogonal edge creation is enabled if orthogonal edge editing is enabled on the parent input mode and the isOrthogonallyEditedEdge decides that the previewEdge should be edited orthogonally.

orthogonalSnapDistance

: number

Gets or sets the distance in the view coordinate system that determines how far the mouse should be snapped to a horizontal or vertical line.

Remarks

The default value is 5.

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.

portCandidateRenderer

: IObjectRenderer<PortCandidateRenderTag>

Gets or sets the IObjectRenderer<PortCandidateRenderTag> that visualizes IPortCandidates while creating edges.

Remarks

When queried for an IVisualCreator to obtain the visualizations for port candidates, this renderer is passed instances of PortCandidateRenderTag as render tag. The renderer may change the appearance of a port candidate depending on isCurrentCandidate and validity.

By default, an instance of PortCandidateRenderer is used.

portCandidateResolutionRecognizer

: function(EventArgs, unknown):boolean

Gets or sets the event recognizer that determines whether dynamic port candidates should be resolved.

Remarks

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

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.

preferredMinimalEdgeDistance

: number

Gets or sets the preferred minimal distance of orthogonal edges.

Remarks

This information is needed when deciding which way to route the first segment of an orthogonal edge.

prematureEndHitTestable

Gets or sets a IHitTestable that determines whether it is valid to finish an edge creation gesture here even if no IPortCandidates are available.

Remarks

This hit testable is only queried if forceSnapToCandidate is disabled and endHitTestable returns false or no valid port candidate is found.

If this IHitTestable returns true, the current location is considered as a possible end for an edge creation, even if no valid IPortCandidate is available as an end port candidate.

The default implementation always returns false.

previewEdge

: IEdge

Gets the preview edge instance that will be used to render a preview of the edge to be created.

Remarks

Depending on the edgeDirectionPolicy and then the value of the reversedEdgeCreation property, this edge will either have its targetPort or sourcePort dragged with the pointer. Edge creation always starts at the startPortCandidate and ends at the endPortCandidate. This instance will be used for rendering the edge during the gesture. Its appearance may be changed via previewGraph. Upon completion or canceling, a new instance will be created the next time an edge gets created. The default implementation of previewGraph will use SimpleEdge instances, that may be decorated.

previewEndNode

: INode

The INode which is used as a moving end node for the temporarily created previewEdge during edge creation.

Remarks

By default, this node is invisible and is only used for holding the moving end of the edge currently being created. The appearance of it can be changed via previewGraph.

previewEndNodePort

: IPort

The IPort which is used as the end port for the temporarily created previewEdge during edge creation.

Remarks

This port's owner is the previewEndNode. This port is used as end port of the previewEdge unless the preview edge snaps to a valid endPortCandidate in which case the edge is connected to the port represented by that candidate.

The appearance of it can be changed via previewGraph.

previewGraph

: IGraph

Gets the preview graph instance that will hold the items that will render a preview of the newly created edge.

Remarks

The preview graph can be used to change the appearance and other properties of the preview edge, either when starting a gesture or during it in response to certain events. Possible actions are:

Changing the style of the preview edge.
Adding bends to the preview edge.
Adding labels to the preview edge.
Changing style and other properties of the added labels.

All changes made to the preview edge during the gesture will be persisted to the created edge in the original graph. This behavior can be changed by setting a custom edgeCreator.

The preview graph only allows operations on the preview edge.

Changing style of the preview edge's source or target port has no effect. The style for these is controlled by the IPortCandidates and hence by an IPortCandidateProvider.

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

removeBendRecognizer

: function(EventArgs, unknown):boolean

Gets or sets the event recognizer that determines whether to remove the last created bend.

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.

removeBendRecognizerTouch

: function(EventArgs, unknown):boolean

Gets or sets the event recognizer that determines whether to remove the last created bend via touch.

Remarks

The default recognizer detects secondary long press events.

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.

resolveEndPortCandidates

: boolean

Gets or sets a value indicating whether DYNAMIC ports that are part of the end port candidates should be resolved for the current pointer location.

Remarks

By default, this feature is enabled and the portCandidateResolutionRecognizer is configured so that the resolution mechanism is used if the user holds the shift modifier during the gesture.

resolveStartPortCandidates

: boolean

Gets or sets a value indicating whether DYNAMIC ports that are part of the start port candidates should be resolved for the current mouse location.

Remarks

By default, this feature is enabled and the portCandidateResolutionRecognizer is configured so that the resolution mechanism is used if the user holds the shift modifier during the gesture.

Note that "start" refers to the port candidate where the edge creation started. In case of reversedEdgeCreation this will actually become the targetPort of the edge in the end.

reversedEdgeCreation

: boolean

Gets or sets a value indicating whether the current edge creation should be created from its targetPort to its sourcePort.

Remarks

This property is automatically set at the start of the edge creation according to the value of edgeDirectionPolicy. It can be set to a different value during edge creation to change the direction of the created edge immediately. Note that the currently assigned startPortCandidate will stay the same, then, and is not queried again from the start port candidates. Depending on the context of the application, this could result in an edge connecting to the wrong ports, so consider updating the ports by handling the edge-direction-reversed event.

Examples

Setting the reversedEdgeCreation in a listener to the start-port-candidate-changed event allows for fully customizing the edge creation direction. The example shows how to set the direction according to the candidate's tag.

createEdgeInputMode.addEventListener(
  'start-port-candidate-changed',
  (evt) =>
    (createEdgeInputMode.reversedEdgeCreation =
      evt.item.owner.tag === 'createFromTarget'),
)

Setting this value as shown above will override the edgeDirectionPolicy.

showEndHighlight

: boolean

Gets or sets whether the owner of the current endPortCandidate should be highlighted.

Remarks

The default is true.

showPortCandidates

: ShowPortCandidates

Gets or sets whether and where to display possible port candidates during the creation of the edge.

Remarks

Setting this property to START or ALL will result in displaying start port candidates for each item the pointer is hovering over. For a CreateEdgeInputMode as child of a default GraphEditorInputMode selected nodes will rather be moved than serve as start of an edge creation. To disable showing port candidates for selected nodes developers might set appropriate showStartPortCandidatesHitTestable and beginHitTestables. An example IHitTestable is shown there.

The default is ALL.

showStartPortCandidateDelay

: TimeSpan

Gets or sets the amount of time to wait until the start port candidates are displayed, when the user hovers over a start port candidate owner.

Remarks

This will only be used when showPortCandidates has the START specified. By default, this is set to zero, so candidates are shown immediately.

showStartPortCandidatesHitTestable

Gets or sets a IHitTestable that determines whether to show start port candidates if the cursor hovers over the provided location.

Remarks

If showPortCandidates is set to START or ALL, the start port candidates will be shown as soon as this testable returns true.

The default implementation returns true if the cursor is located over a port owner.

Examples

class UnselectedNodesHitTestable extends BaseClass<IHitTestable>(
  IHitTestable,
) {
  isHit(context: IInputModeContext, location: Point): boolean {
    const graphComponent = context.canvasComponent as GraphComponent
    return graphComponent.graph.nodes.some(
      (node) =>
        !graphComponent.selection.includes(node) &&
        node.style.renderer
          .getHitTestable(node, node.style)
          .isHit(context, location),
    )
  }
}

Note that the same hit testable should be set to beginHitTestable, too.

snapContext

: GraphSnapContext?

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

Remarks

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.

snapDistance

: number

Gets or sets the distance in the view coordinate system that determines how far the mouse should be snapped to a port candidate if snapToEndCandidate is enabled.

Remarks

The default value is 20.

snapToEndCandidate

: boolean

Gets or sets whether or not the edge's end point should snap to the current end port candidate during the creation of the edge.

Remarks

This will make the edge's end point snap to the position of the end port candidate. This will result in the preview edge looking exactly like the edge after creation. By default this feature is enabled.

startOverCandidateOnly

: boolean

Gets or sets whether edge creation should only start if the pointer is located directly over a valid port candidate.

Remarks

If set to false edge creation can start if the pointer is located anywhere over a port owner. In this case, the closest valid port candidate will be chosen as the start port.

If set to true edge creation can only start if the pointer is located over a valid port candidate. This candidate will be chosen as the start port. The radius within which a port is considered as hit can be set using startPortCandidateHitRadius. Showing start port candidates can be enabled using showPortCandidates.

Default is true.

Examples

A possible use case is to support edge creation at selected nodes without disabling the moveSelectedItemsInputMode. The following example sets a higher priority to the createEdgeInputMode but restricts possible start points to valid port candidates. That way, if a user drags from a valid port candidate, edge creation will start. If he drags from other regions of the selected node, the node will be moved:

graphEditorInputMode.moveSelectedItemsInputMode.priority = 45
graphEditorInputMode.createEdgeInputMode.priority = 40
graphEditorInputMode.createEdgeInputMode.showPortCandidates =
  ShowPortCandidates.ALL
graphEditorInputMode.createEdgeInputMode.startOverCandidateOnly = true

startPoint

: Point

Gets a copy of the start point at which the edge creation gesture started.

startPortCandidate

: IPortCandidate?

Gets or sets the candidate for the sourcePort of the edge to be created.

Remarks

This property will be populated automatically when edge creation has started.

startPortCandidateHitRadius

: number

Gets or sets the radius from within a valid port candidate will be considered as hit.

Remarks

The radius is in view coordinates and gets added to the hitTestRadius when checking for a hit.

This value will be considered if startOverCandidateOnly is set to true.

Default is 5.

startPortOwnerDraggingCursor

: Cursor?

Gets or sets the cursor that is used once edge creation has started but the mouse is still over the new edge's start node.

Remarks

The default cursor is DEFAULT.

startPortOwnerDraggingFinishedRecognizer

: function(EventArgs, unknown):boolean

Gets or sets the event recognizer that starts the actual edge creation while dragging.

Remarks

The default implementation starts edge creation after the mouse pointer has left the start port owner node for the first time.

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.

toggleDirectionRecognizer

: function(EventArgs, unknown):boolean

Gets or sets the event recognizer that recognizes gestures which toggle the direction of the created edge.

Remarks

The default instance never triggers. When setting this recognizer, depending on the context of the application, this could result in an edge connecting to the wrong ports, so consider updating the ports by handling the edge-direction-reversed event, if ports have special semantics.

Property Value

The recognizer that identifies the event that toggles the direction of the created edge.

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

createEdgeInputMode.toggleDirectionRecognizer =
  EventRecognizers.SHIFT_DOWN

toggleSegmentOrientationRecognizer

: function(EventArgs, unknown):boolean

Gets or sets the event recognizer that toggles the orientation of the first orthogonal segment.

Property Value

The recognizer instances that identifies the event that toggles the orientation of the first segment. The default instance recognizes if the user presses the space key.

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.

useHitItemsCandidatesOnly

: boolean

Gets or sets whether this mode should use the end port candidates of the node the pointer currently hovers over, only.

Remarks

The default is true.

validBeginCursor

: Cursor?

Gets or sets the cursor that indicates a valid place to begin an edge creation.

Remarks

The default cursor is POINTER.

validBendCursor

: Cursor?

Gets or sets the cursor that indicates a valid place to create a bend.

Remarks

The default cursor is DEFAULT.

validBendHitTestable

Gets or sets a IHitTestable that determines whether it is valid to create a bend here.

Remarks

The default implementation always returns true.

validEndCursor

: Cursor?

Gets or sets the cursor that indicates a valid place to finish creation.

Remarks

The default cursor is POINTER.

Methods

cancel

()

Cancels the editing of this mode.

Remarks

This implementation releases the mutex if it is currently owned by this instance and calls onCanceled.

Implements

createEdge

(graph: IGraph, sourcePortCandidate: IPortCandidate, targetPortCandidate: IPortCandidate) : Promise<IEdge | null> | IEdge

Called at the end of the edge creation process if both startPortCandidate and endPortCandidate have been set.

Remarks

This method will first create the new ports if necessary and then create the edge via the edgeCreator callback to the ports. After the ports are created the corresponding port-added events are triggered. If the edge creation is canceled by the creator callback, newly created ports will be removed again.

Parameters

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

graph - IGraph: The graph to create the edge for.
sourcePortCandidate - IPortCandidate: The candidate to use for the source end of the edge. Usually the startPortCandidate. In case reversedEdgeCreation, though, the value of endPortCandidate.
targetPortCandidate - IPortCandidate: The candidate to use for the target end of the edge. Usually the endPortCandidate. In case reversedEdgeCreation, though, the value of startPortCandidate.

Returns

↪Promise<IEdge | null> | IEdge?: The edge created, null, or a Promise resolving with an edge or null .

createInputModeContext

() : IInputModeContext

Returns the input mode context that will be passed to implementations that are called by this instance and require a context.

Remarks

This method caches the context for the current edge creation.

Returns

↪IInputModeContext: A context to use for the implementations that are called by this instance.

createPreviewBend

(location: Point) : IBend

Creates a preview bend at the given location and adds it to the previewEdge that will be displayed by the input mode during the creation.

Remarks

The bend must be part of the previewGraph.

Depending on reversedEdgeCreation, the bend is added at the start or end of the previewEdge's bend list.

Parameters

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

location - Point: The coordinates to create the bend at.

Returns

↪IBend?: The newly created bend or null.

getEndPortCandidateProvider

(startPortCandidate: IPortCandidate, location: Point) : IPortCandidateProvider

Retrieves the IPortCandidateProvider instance that provides the possible candidates for the end of the edge given the current start candidate.

Remarks

This implementation queries all nodes in the graph for their provider and returns a composite unless useHitItemsCandidatesOnly is set to true in which case the getEndPortCandidateProvider is queried using the current end.

Note that "end" refers to the port candidate where the edge creation finishes. In case of reversedEdgeCreation this will actually become the sourcePort of the edge.

Parameters

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

startPortCandidate - IPortCandidate: The candidate at the other end of the edge that has been chosen for the edge creation. In case of reversedEdgeCreation this is actually the candidate for the target end of the edge.
location - Point: The location of the mouse.

Returns

↪IPortCandidateProvider?: The provider to get the port candidates from.

getEndPortCandidateProvider

(startPortCandidate: IPortCandidate, endPortOwner: IPortOwner, location: Point) : IPortCandidateProvider

Retrieves the port candidate provider instance given a start port candidate and a possible ending item.

Remarks

This implementation uses the endPortOwner's lookup to retrieve an IPortCandidateProvider implementation.

Parameters

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

startPortCandidate - IPortCandidate: The current start port candidate at the other end of the edge.
endPortOwner - IPortOwner: The IPortOwner to find the candidates for.
location - Point: The location of the pointer.

Returns

↪IPortCandidateProvider?: A provider instance or null.

getEndPortCandidates

(location: Point, resolveCandidates: boolean) : IEnumerable<IPortCandidate>

Retrieves the end port candidates for a given location in world coordinates.

Remarks

The resolveCandidates parameter determines whether DYNAMIC port candidates should be resolved with respect to location or simply be discarded.

This implementation delegates to getEndPortCandidateProvider or returns an empty enumerable if no provider has been found.

Note that "end" refers to the port candidate where the edge creation ends. In case of reversedEdgeCreation this will actually become the sourcePort of the edge.

Parameters

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

location - Point: The location of the pointer in world coordinates.
resolveCandidates - boolean: Determines whether DYNAMIC ports should be resolved with respect to the location or not.

Returns

↪IEnumerable<IPortCandidate>: A possibly empty enumeration over all end port candidates.

getEndPortOwner

(endLocation: Point) : IPortOwner

Finds the end port owner at the specified location.

Remarks

This always is a node if allowEdgeToEdgeConnections is set to false.

This default implementation simply delegates to getPortOwner.

Note that "end" refers to the end of the edge where creation finishes. In case of reversedEdgeCreation this will actually become the sourcePort's owner of the created edge.

Parameters

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

endLocation - Point: The location of the pointer at the end of the gesture.

Returns

↪IPortOwner?: The port owner or null if no valid owner is found at the given location.

getFirstSegmentDirection

() : EdgeSegmentDirection

Calculates the direction of the first edge segment of the PreviewNode.

Remarks

An edge starting at a border will always be orthogonal to the border's outer line. An edge starting at a corner will point in the direction the user dragged the mouse. An edge starting in the inner part of the node will be directed the way it was dragged unless another edge that is close to the new edge (preferredMinimalEdgeDistance) already went that way.

Returns

↪EdgeSegmentDirection: A EdgeSegmentDirection defining the direction of the first edge segment.

getPortOwner

(location: Point) : IPortOwner

Retrieves the port owner at a given position in world coordinates.

Remarks

If there is a IHitTester for type INode in the lookup of this mode's parentInputModeContext then this instance will be used for the query.

Parameters

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

location - Point: The position in world coordinates.

Returns

↪IPortOwner?: The IPortOwner or null if no suitable node or edge was found.

getPortOwners

() : IEnumerable<IPortOwner>

Retrieves the port owners from the graph in the order of their importance.

Remarks

This implementation only considers nodes in the graph unless allowEdgeToEdgeConnections is set to true, in which case edges are also added to the enumerable.

Returns

↪IEnumerable<IPortOwner>: An enumerable over all IPortOwners in this graph

getPreviewEdgeSnapLines

(context: GraphSnapContext) : IEnumerable<OrthogonalSnapLine>

Gets the snap references that are induced by the current preview edge.

Parameters

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

context - GraphSnapContext: The graph snap context.

Returns

↪IEnumerable<OrthogonalSnapLine>: The snap lines induced by the current preview edge.

getStartPortCandidate

(location: Point) : IPortCandidate

Finds the best matching start port candidate based on the given location.

Remarks

This implementation will use the candidates returned by getStartPortCandidates and delegates to selectStartPortCandidate to find the most appropriate one.

Note that "start" means the port candidate where the edge creation started. In case of reversedEdgeCreation this will actually become the target port of the edge.

Parameters

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

location - Point: The location where the gesture was initiated.

Returns

↪IPortCandidate?: The candidate to use or null.

getStartPortCandidateProvider

(startLocation: Point) : IPortCandidateProvider

Finds the start port candidate provider at the specified location.

Remarks

This default implementation simply delegates to getStartPortOwner to get a port owner and returns the IPortCandidateProvider returned by that port owner's lookup.

Parameters

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

startLocation - Point: The location of the mouse at the beginning of the gesture.

Returns

↪IPortCandidateProvider?: The port candidate provider to use for the start of the edge creation or null.

getStartPortCandidateProvider

(startPortOwner: IPortOwner) : IPortCandidateProvider

Retrieves the port candidate provider instance given a port owner for the start of the gesture.

Remarks

This implementation uses the startPortOwner's lookup to retrieve an IPortCandidateProvider implementation.

Parameters

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

startPortOwner - IPortOwner: The IPortOwner to find the candidates for.

Returns

↪IPortCandidateProvider?: A provider instance or null.

getStartPortCandidates

(location: Point) : IEnumerable<IPortCandidate>

Gets the start port candidates for the given location.

Remarks

This implementation first tries to get port candidate provider for the given location. If a provider is found its method getAllSourcePortCandidates or getAllTargetPortCandidates respectively (depending on the edgeDirectionPolicy) is called to get the candidates.

If no owner or provider is found, null is returned.

Note that "start" refers to the port candidate where the edge creation started. In case of reversedEdgeCreation this will actually become the targetPort of the edge, otherwise, it's the sourcePort.

Parameters

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

location - Point: The location to get the port candidates for.

Returns

↪IEnumerable<IPortCandidate>?: The port candidates for the given location or null if there are none.

getStartPortOwner

(startingLocation: Point) : IPortOwner

Finds the start port owner at the specified location.

Remarks

This always is a node if allowEdgeToEdgeConnections is set to false.

This default implementation simply delegates to getPortOwner.

Parameters

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

startingLocation - Point: The location of the pointer at the beginning of the gesture.

Returns

↪IPortOwner?: The port owner to use for the start of the edge creation or null.

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

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

Implements

isValidTemporaryFocusTarget

() : boolean

Gets or sets a value that specifies whether the current focus owner is valid as an intermediate focus owner and does not count against cancelCreationOnFocusLost.

Remarks

This implementation allows the focus to move to a GraphOverviewComponent and within the CanvasComponent.

Returns

↪boolean: Whether it is OK for the focus to be temporarily moved away from the CanvasComponent to the current focus owner. If false the edge creation will be canceled.

measureDistance

(candidate: IPortCandidate, location: Point) : number

Measures the distance between a port candidate and a given location.

Remarks

If a projection is set, this method returns the distance in view coordinates. Otherwise, the distance in world coordinates is returned.

Parameters

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

candidate - IPortCandidate: The port candidate.
location - Point: The location in world coordinates.

Returns

↪number: The distance between the candidate and the location (in world coordinates if no projection is set; in view coordinates if it has).

onCanceled

()

Called after cancel has been called.

Remarks

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

This implementation does nothing.

onConcurrencyControllerActivated

()

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

Remarks

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

Overriding implementations should call the base implementation.

onConcurrencyControllerDeactivated

()

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

Remarks

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

Overriding implementations should call the base implementation.

onEdgeCreated

(evt: InputModeItemEventArgs<IEdge>)

Called after the edge has been finalized.

Remarks

This method will trigger the edge-created event.

Parameters

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

evt - InputModeItemEventArgs<IEdge>: The event argument holding the edge.

onEdgeCreationStarted

(evt: InputModeItemEventArgs<IEdge>)

Raises the edge-creation-started event when the edge is dragged outside the start node.

Parameters

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

evt - InputModeItemEventArgs<IEdge>: The InputModeItemEventArgs<TModelItem> instance containing the preview edge that will be used during edge creation.

onEdgeDirectionReversed

Triggers the edge-direction-reversed event.

Parameters

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

evt - InputModeEventArgs: The event argument that contains context information.

onEndPortCandidateChanged

(evt: InputModeItemEventArgs<IPortCandidate>)

Triggers the end-port-candidate-changed event.

Parameters

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

evt - InputModeItemEventArgs<IPortCandidate>: The event argument that contains context information.

onGestureCanceled

Triggers the gesture-canceled event.

Parameters

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

evt - InputModeEventArgs: The event argument that contains context information.

onGestureCanceling

Triggers the gesture-canceling event.

Parameters

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

evt - InputModeEventArgs: The event argument that contains context information.

onGestureFinished

Called once the drag has been finalized.

Remarks

This method triggers the gesture-finished event.

Parameters

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

evt - InputModeEventArgs: The event argument that contains context information.

onGestureFinishing

Called before the drag will be finalized.

Remarks

This method triggers the gesture-finishing event.

Parameters

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

evt - InputModeEventArgs: The event argument that contains context information.

onGestureStarted

Triggers the gesture-started event.

Parameters

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

evt - InputModeEventArgs: The event argument that contains context information.

onGestureStarting

Triggers the gesture-starting event.

Parameters

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

evt - InputModeEventArgs: The event argument that contains context information.

onMoved

Called at the end of each drag.

Remarks

This method triggers the moved event.

Parameters

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

evt - InputModeEventArgs: The event argument that contains context information.

onMoving

Called at the start of each drag.

Remarks

This method triggers the moving event.

Parameters

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

evt - InputModeEventArgs: The event argument that contains context information.

onPortAdded

(evt: InputModeItemEventArgs<IPort>)

Raises the port-added event if the mode has added a port for the source or target node to complete the edge creation.

Parameters

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

evt - InputModeItemEventArgs<IPort>: The InputModeItemEventArgs<TModelItem> instance containing the port that has been added.

onReversedEdgeCreationChanged

()

Called when the reversedEdgeCreation property changes and the edge creation is in progress.

Remarks

This implementation swaps source and target port of the preview edge and adjusts the bends by reversing their locations.

onStartPortCandidateChanged

(evt: InputModeItemEventArgs<IPortCandidate>)

Triggers the start-port-candidate-changed event.

Parameters

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

evt - InputModeItemEventArgs<IPortCandidate>: The event argument that contains context information.

onStopped

()

Called after tryStop has been called.

Remarks

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

This implementation does nothing.

relocateDragPoint

(newLocation: Point)

Sets the position of the dragged end of the edge during creation.

Remarks

Has to set the dragPoint and the center of the previewEndNode or previewEndNodePort to newLocation.

Parameters

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

newLocation - Point: The location of the tip of the edge.

resolveCandidates

(candidates: IEnumerable<IPortCandidate>, location: Point) : IEnumerable<IPortCandidate>

Returns an enumerable over the given candidates where no instance has DYNAMIC validity.

Remarks

If the location has a value, method getPortCandidateAt is used to resolve the dynamic candidate to a real candidate, otherwise that candidate is discarded.

Parameters

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

candidates - IEnumerable<IPortCandidate>: The candidates to possibly resolve.
location - Point: The location to resolve dynamic candidates against or null if they should be discarded instead.

Returns

↪IEnumerable<IPortCandidate>: An enumerable of non-DYNAMIC port candidates.

selectClosestCandidate

(candidates: IEnumerable<IPortCandidate>, location: Point) : IPortCandidate

Finds the closest VALID candidate given a number of IPortCandidates and a location in world coordinates.

Parameters

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

candidates - IEnumerable<IPortCandidate>: The candidates to find the closest from.
location - Point: The location of the mouse in world coordinates.

Returns

↪IPortCandidate?: The candidate to use or null if no candidate satisfies the needs

selectClosestEndCandidate

(candidates: IEnumerable<IPortCandidate>, location: Point) : IPortCandidate

Finds the closest end candidate given a number of IPortCandidates and a location in world coordinates.

Parameters

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

candidates - IEnumerable<IPortCandidate>: The candidates to find the closest from.
location - Point: The location of the mouse in world coordinates.

Returns

↪IPortCandidate?: The candidate to use or null if no candidate satisfies the needs or enforceBendCreationRecognizer yields true.

selectClosestStartCandidate

(candidates: IEnumerable<IPortCandidate>, location: Point) : IPortCandidate

Finds the closest candidate given a number of IPortCandidates and a location in world coordinates.

Parameters

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

candidates - IEnumerable<IPortCandidate>: The candidates to find the closest from.
location - Point: The location of the pointer in world coordinates.

Returns

↪IPortCandidate?: The candidate to use or null if no candidate satisfies the needs

selectStartPortCandidate

(candidates: IEnumerable<IPortCandidate>, location: Point, resolveCandidates: boolean) : IPortCandidate

Finds the best matching start port IPortCandidate for the given candidates at the provided location.

Remarks

The resolveCandidates parameter determines whether dynamic port candidates should be resolved with respect to location or simply be discarded.

Note that "start" refers to either source or target port candidates depending on the current value of reversedEdgeCreation.

Parameters

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

candidates - IEnumerable<IPortCandidate>: The candidates.
location - Point: The location where the gesture was initiated.
resolveCandidates - boolean: Determines whether DYNAMIC ports should be resolved with respect to the location or not.

Returns

↪IPortCandidate?: The candidate to use or null.

startEdgeCreation

(node: INode, initialEndLocation?: IPoint) : Promise<yfiles.graph.IEdge|null>

Synthetically starts the interactive edge creation process using the provided INode as the start node.

Remarks

This instance needs to be installed and enabled and it needs to be able to request the input mutex in order to proceed. If any of these conditions are not satisfied, this method will throw an InvalidOperationError.

Parameters

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

node - INode: The start node to use for the edge creation.
initialEndLocation - IPoint: The initial location that is passed to updateEndLocation.

Returns

↪Promise<yfiles.graph.IEdge|null>: A task that represents the asynchronous edge creation. The result of the task contains the newly created edge or null if the creation was canceled.

startEdgeCreation

(port: IPort, initialEndLocation?: IPoint) : Promise<yfiles.graph.IEdge|null>

Synthetically starts the interactive edge creation process using the provided IPort as the start port.

Remarks

Parameters

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

port - IPort: The start port to use for the edge creation.
initialEndLocation - IPoint: The initial location that is passed to updateEndLocation.

Returns

↪Promise<yfiles.graph.IEdge|null>: A task that represents the asynchronous edge creation. The result of the task contains the newly created edge or null if the creation was canceled.

startEdgeCreation

(startPortCandidate: IPortCandidate, initialEndLocation?: IPoint) : Promise<yfiles.graph.IEdge|null>

Synthetically starts the interactive edge creation process using the provided IPortCandidate as the start port.

Remarks

Parameters

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

startPortCandidate - IPortCandidate: The start port candidate to use for the edge creation.
initialEndLocation - IPoint: The initial location that is passed to updateEndLocation.

Returns

↪Promise<yfiles.graph.IEdge|null>: A task that represents the asynchronous edge creation. The result of the task contains the newly created edge or null if the creation was canceled.

tryStop

() : boolean

Will be called to request a stop of the current editing progress.

Remarks

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

Returns

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

Implements

uninstall

(context: IInputModeContext)

Uninstalls this mode from the given context.

Remarks

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

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

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

Implements