CreateEdgeInputMode

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

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

final

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.

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

final

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.

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

final

cancelCreationOnFocusLost

: boolean

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

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.

final

cancelEditImplicitly

: boolean

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

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.

final

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.

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.

final

cancelRecognizer

: function(EventArgs, unknown): boolean

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

final

cancelRecognizerTouch

: function(EventArgs, unknown): boolean

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

The default recognizer detects secondary double tap events.

final

controller

: ConcurrencyController

protectedreadonly

Gets the installed controller.

protectedreadonlyfinal

createBendRecognizer

: function(EventArgs, unknown): boolean

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

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

final

createBendRecognizerTouch

: function(EventArgs, unknown): boolean

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

The default is TOUCH_PRIMARY_UP.

final

directionalConstraintRecognizer

: function(EventArgs, unknown): boolean

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

The default recognizer is SHIFT_IS_DOWN

final

disableSnappingRecognizer

: function(EventArgs, unknown): boolean

Gets or sets the event recognizer that temporarily disables snapping.

The default recognizer is ALT_DOWN

final

dragCursor

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

The default cursor is DEFAULT.

conversionfinal

dragPoint

: IPoint

readonly

Gets the dynamically updated dragging point for the edge creation.

readonlyfinal

edgeCreator

: function(IInputModeContext, IGraph, IPortCandidate, IPortCandidate, IEdge): any

Gets or sets the ports-based edge creation callback.

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.

final

Property Value

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

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.

This property directly delegates to the edgeDefaults of the previewGraph.

final

edgeDirectionPolicy

: EdgeDirectionPolicy

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

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.

conversionfinal

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

The default recognizer is ALT_UP

final

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.

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.

final

endPointMoveRecognizer

: function(EventArgs, unknown): boolean

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

The default recognizer detects DRAG events for MOUSE and PEN.

final

endPortCandidate

: IPortCandidate

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

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

final

enforceBendCreationRecognizer

: function(EventArgs, unknown): boolean

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

The default is ALT_IS_DOWN.

final

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

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.

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

final

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.

The default is TOUCH_PRIMARY_UP.

final

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.

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.

final

graph

: IGraph

readonly

Gets the graph this mode is acting upon.

readonlyfinal

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

readonly

Gets whether currently an edge creation is in progress.

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

readonly

minimumSelfLoopBendCount

: number

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

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.

final

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.

The default recognizer is MOUSE_DRAG.

final

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.

The default is TOUCH_PRIMARY_DRAG.

final

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.

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

final

orthogonalEdgeCreation

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

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.

conversionfinal

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.

The default value is 5.

final

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 obtain a context that has this IInputMode as the inputMode.

protectedreadonlyfinal

portCandidateRenderer

: IObjectRenderer<PortCandidateRenderTag>

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

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.

final

portCandidateResolutionRecognizer

: function(EventArgs, unknown): boolean

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

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

final

preferredMinimalEdgeDistance

: number

Gets or sets the preferred minimal distance of orthogonal edges.

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

final

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.

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.

final

previewEdge

: IEdge

readonly

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

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.

readonlyfinal

previewEndNode

: INode

readonly

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

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.

readonlyfinal

previewEndNodePort

: IPort

readonly

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

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.

readonlyfinal

previewGraph

: IGraph

readonly

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

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.

readonlyfinal

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

Implements

IInputMode.priority

removeBendRecognizer

: function(EventArgs, unknown): boolean

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

final

removeBendRecognizerTouch

: function(EventArgs, unknown): boolean

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

The default recognizer detects secondary long press events.

final

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.

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.

final

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.

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.

final

reversedEdgeCreation

: boolean

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

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.

final

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.

The default is true.

final

showPortCandidates

: ShowPortCandidates

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

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.

conversionfinal

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.

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

conversionfinal

showStartPortCandidatesHitTestable

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

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.

final

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

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.

final

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.

The default value is 20.

final

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.

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.

final

startOverCandidateOnly

: boolean

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

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.

final

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

readonly

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

readonlyfinal

startPortCandidate

: IPortCandidate

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

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

final

startPortCandidateHitRadius

: number

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

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.

final

startPortOwnerDraggingCursor

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.

The default cursor is DEFAULT.

conversionfinal

startPortOwnerDraggingFinishedRecognizer

: function(EventArgs, unknown): boolean

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

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

final

toggleDirectionRecognizer

: function(EventArgs, unknown): boolean

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

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.

final

Property Value

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

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.

final

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.

useHitItemsCandidatesOnly

: boolean

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

The default is true.

final

validBeginCursor

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

The default cursor is POINTER.

conversionfinal

validBendCursor

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

The default cursor is DEFAULT.

conversionfinal

validBendHitTestable

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

The default implementation always returns true.

final

validEndCursor

InputModeItemEventArgs<IEdge>

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

The default cursor is POINTER.

conversionfinal

Methods

cancel

()

Cancels the editing of this mode.

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

Implements

IInputMode.cancel

createEdge

(

graph: IGraph

sourcePortCandidate: IPortCandidate

targetPortCandidate: IPortCandidate

): any

protected

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

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.

protected

Parameters

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.

Return Value

any: The edge created, null, or a Promise resolving with an edge or null .

createInputModeContext

(): IInputModeContext

protected

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

This method caches the context for the current edge creation.

protected

Return Value

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

createPreviewBend

(location: Point): IBend

protected

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.

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.

protected

Parameters

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

Return Value

IBend: The newly created bend or null.

getEndPortCandidateProvider

(startPortCandidate: IPortCandidate, location: Point): IPortCandidateProvider

protected

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

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.

protected

Parameters

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.

Return Value

IPortCandidateProvider: The provider to get the port candidates from.

getEndPortCandidateProvider

(

startPortCandidate: IPortCandidate

endPortOwner: IPortOwner

location: Point

): IPortCandidateProvider

protected

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

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

protected

Parameters

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.

Return Value

IPortCandidateProvider: A provider instance or null.

getEndPortCandidates

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

protected

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

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.

protected

Parameters

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.

Return Value

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

getEndPortOwner

(endLocation: Point): IPortOwner

protected

Finds the end port owner at the specified location.

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.

protected

Parameters

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

Return Value

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

getFirstSegmentDirection

(): EdgeSegmentDirection

protected

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

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.

protected

Return Value

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

getPortOwner

(location: Point): IPortOwner

protected

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

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.

protected

Parameters

location: Point: The position in world coordinates.

Return Value

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

getPortOwners

(): IEnumerable<IPortOwner>

protected

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

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

protected

Return Value

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

getPreviewEdgeSnapLines

(context: GraphSnapContext): IEnumerable<OrthogonalSnapLine>

protected

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

protected

Parameters

context: GraphSnapContext: The graph snap context.

Return Value

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

getStartPortCandidate

(location: Point): IPortCandidate

protected

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

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.

protectedfinal

Parameters

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

Return Value

IPortCandidate: The candidate to use or null.

getStartPortCandidateProvider

(startLocation: Point): IPortCandidateProvider

protected

Finds the start port candidate provider at the specified location.

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

protected

Parameters

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

Return Value

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

getStartPortCandidateProvider

(startPortOwner: IPortOwner): IPortCandidateProvider

protected

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

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

protected

Parameters

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

Return Value

IPortCandidateProvider: A provider instance or null.

getStartPortCandidates

(location: Point): IEnumerable<IPortCandidate>

protected

Gets the start port candidates for the given location.

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.

protected

Parameters

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

Return Value

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

getStartPortOwner

(startingLocation: Point): IPortOwner

protected

Finds the start port owner at the specified location.

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

This default implementation simply delegates to getPortOwner.

protected

Parameters

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

Return Value

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.

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.

Implements

IInputMode.install

isValidTemporaryFocusTarget

(): boolean

protected

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.

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

protected

Return Value

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

protected

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

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

protectedfinal

Parameters

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

Return Value

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

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

onEdgeCreated

(evt: InputModeItemEventArgs<IEdge>)

protected

Called after the edge has been finalized.

This method will trigger the edge-created event.

protected

Parameters

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

onEdgeCreationStarted

(evt: InputModeItemEventArgs<IEdge>)

protected

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

protected

Parameters

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

onEdgeDirectionReversed

(evt: InputModeEventArgs)

protected

Triggers the edge-direction-reversed event.

protected

Parameters

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

onEndPortCandidateChanged

(evt: InputModeItemEventArgs<IPortCandidate>)

protected

Triggers the end-port-candidate-changed event.

protected

Parameters

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

onGestureCanceled

(evt: InputModeEventArgs)

protected

Triggers the gesture-canceled event.

protected

Parameters

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

onGestureCanceling

(evt: InputModeEventArgs)

protected

Triggers the gesture-canceling event.

protected

Parameters

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

onGestureFinished

(evt: InputModeEventArgs)

protected

Called once the drag has been finalized.

This method triggers the gesture-finished event.

protected

Parameters

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

onGestureFinishing

(evt: InputModeEventArgs)

protected

Called before the drag will be finalized.

This method triggers the gesture-finishing event.

protected

Parameters

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

onGestureStarted

(evt: InputModeEventArgs)

protected

Triggers the gesture-started event.

protected

Parameters

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

onGestureStarting

(evt: InputModeEventArgs)

protected

Triggers the gesture-starting event.

protected

Parameters

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

onMoved

(evt: InputModeEventArgs)

protected

Called at the end of each drag.

This method triggers the moved event.

protected

Parameters

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

onMoving

(evt: InputModeEventArgs)

protected

Called at the start of each drag.

This method triggers the moving event.

protected

Parameters

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

onPortAdded

(evt: InputModeItemEventArgs<IPort>)

protected

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

protected

Parameters

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

onReversedEdgeCreationChanged

()

protected

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

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

protected

onStartPortCandidateChanged

(evt: InputModeItemEventArgs<IPortCandidate>)

protected

Triggers the start-port-candidate-changed event.

protected

Parameters

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

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

relocateDragPoint

(newLocation: Point)

protected

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

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

protected

Parameters

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

resolveCandidates

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

protected

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

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

protected

Parameters

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.

Return Value

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

selectClosestCandidate

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

protected

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

protected

Parameters

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

Return Value

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

selectClosestEndCandidate

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

protected

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

protected

Parameters

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

Return Value

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

selectClosestStartCandidate

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

protected

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

protected

Parameters

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

Return Value

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

selectStartPortCandidate

(

candidates: IEnumerable<IPortCandidate>

location: Point

resolveCandidates: boolean

): IPortCandidate

protected

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

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.

protected

Parameters

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.

Return Value

IPortCandidate: The candidate to use or null.

startEdgeCreation

(node: INode, initialEndLocation?: IPoint): any

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

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

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

Return Value

any: 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): any

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

Parameters

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

Return Value

any: 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): any

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

Parameters

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

Return Value

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

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

Return Value

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

Implements

IInputMode.tryStop

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.

Implements

IInputMode.uninstall

updateEndHighlight

(oldCandidate: IPortCandidate, newCandidate: IPortCandidate)

protected

Draws the highlight for the owner of the current endPortCandidate.

This implementation retrieves the HighlightIndicatorManager<T> from the parentInputModeContext's ILookup.

Overriders have to take care of removal of the highlight of the oldCandidate's owner, too.

protected

Parameters

oldCandidate: IPortCandidate: The port candidate whose owner is currently highlighted.
newCandidate: IPortCandidate: The port candidate whose owner should be highlighted.

updateEndLocation

(location: Point)

protected

Updates the dragged end point of the edge.

This method is called when the current drag location for the creation gesture changes.

protected

Parameters

location: Point: The new coordinates.

updatePreviewEdgeEndPort

(endPortCandidate: IPortCandidate)

protected

Updates the previewEdge to reflect the current end port candidate.

This implementation creates a self-loop of the preview edge if the endPortCandidate is the same as the owner of the startPortCandidate.

In case of edge creation in reversed direction, the updated port is the sourcePort of the preview edge.

protected

Parameters

endPortCandidate: IPortCandidate: The new end port candidate.

updatePreviewEdgeStartPort

(startPortCandidate: IPortCandidate)

protected

Updates the previewEdge to reflect the current start port candidate.

This implementation creates a self-loop of the preview edge if the startPortCandidate is the same as the owner of the endPortCandidate.

In case of edge creation in reversed direction, the updated port is the targetPort of the created edge.

protected

Parameters

startPortCandidate: IPortCandidate: The new start port candidate.

Events

'edge-created'

: InputModeItemEventArgs<IEdge>

Occurs after an edge has been created by this mode.

Properties of

context: IInputModeContext: Gets the context for the current event.
item: TModelItem: Gets the item which has been created or changed.

Examples

createEdgeInputMode.addEventListener('edge-created', () =>
  createEdgeInputMode.graph.applyLayout(new EdgeRouter()),
)

'edge-creation-started'

: InputModeItemEventArgs<IEdge>

Occurs when the edge creation has visibly started, that is when the cursor is dragged outside the start node.

This event only triggers after the gesture-starting and gesture-started events when start node dragging ended and the edge becomes visible for the user. The edge that is stored in the item property is the previewEdge that is used during creation. It may be modified during the gesture using previewGraph.

Properties of

InputModeItemEventArgs<IEdge>

context: IInputModeContext: Gets the context for the current event.
item: TModelItem: Gets the item which has been created or changed.

Examples

createEdgeInputMode.addEventListener('edge-creation-started', (evt) => {
  const polylineEdgeStyle = evt.item.style
  if (polylineEdgeStyle instanceof PolylineEdgeStyle) {
    polylineEdgeStyle.stroke = Stroke.RED
  }
})

'edge-direction-reversed'

Occurs when the direction of the edge creation changed during edge creation.

This indicates a change in the value of reversedEdgeCreation, but only triggers, when this happens while edge creation is in progress.

Properties of

: InputModeItemEventArgs<IPortCandidate>

context: IInputModeContext: Gets the context for the current event.

'end-port-candidate-changed'

Occurs when the value of the endPortCandidate property changes.

Properties of

InputModeItemEventArgs<IPortCandidate>

context: IInputModeContext: Gets the context for the current event.
item: TModelItem: Gets the item which has been created or changed.

'gesture-canceled'

Occurs when the gesture has been canceled.

Properties of

context: IInputModeContext: Gets the context for the current event.

Examples

createEdgeInputMode.addEventListener(
  'gesture-started',
  () => (statusLabel.innerText = 'Edge creation in progress...'),
)
createEdgeInputMode.addEventListener(
  'gesture-canceled',
  () => (statusLabel.innerText = ''),
)
createEdgeInputMode.addEventListener(
  'gesture-finished',
  () => (statusLabel.innerText = ''),
)

'gesture-canceling'

Occurs before the gesture will be canceled.

Properties of

context: IInputModeContext: Gets the context for the current event.

'gesture-finished'

Occurs once the gesture has been finished.

Properties of

context: IInputModeContext: Gets the context for the current event.

Examples

createEdgeInputMode.addEventListener(
  'gesture-started',
  () => (statusLabel.innerText = 'Edge creation in progress...'),
)
createEdgeInputMode.addEventListener(
  'gesture-canceled',
  () => (statusLabel.innerText = ''),
)
createEdgeInputMode.addEventListener(
  'gesture-finished',
  () => (statusLabel.innerText = ''),
)

'gesture-finishing'

Occurs before the gesture will be finished.

Properties of

context: IInputModeContext: Gets the context for the current event.

'gesture-started'

Occurs once the actual creation gesture is initialized and has started, that is when the edge is dragged from its start, but before edge-creation-started which fires only when it becomes visible.

Use this to reconfigure the previewEdge. This event fires after gesture-starting and will be followed by either gesture-canceling/gesture-canceled or edge-creation-started

Properties of

context: IInputModeContext: Gets the context for the current event.

Examples

createEdgeInputMode.addEventListener('gesture-started', () =>
  createEdgeInputMode.previewGraph.setStyle(
    createEdgeInputMode.previewEndNode,
    new ShapeNodeStyle({ fill: Color.ORANGE }),
  ),
)

createEdgeInputMode.addEventListener(
  'gesture-started',
  () => (statusLabel.innerText = 'Edge creation in progress...'),
)
createEdgeInputMode.addEventListener(
  'gesture-canceled',
  () => (statusLabel.innerText = ''),
)
createEdgeInputMode.addEventListener(
  'gesture-finished',
  () => (statusLabel.innerText = ''),
)

'gesture-starting'

Occurs once the actual creation gesture starts, that is when starting to drag gesture from the start, but before edge-creation-started, which fires only when it becomes visible.

This event fires before any of the startPortCandidate has been determined. It might even be gesture-canceled if no port candidates will be found. Use this for (re-)configuring the input mode. Consider using gesture-started for reconfiguring the previewEdge, instead, when the startPortCandidate has been configured and the edge has been fully prepared.

Properties of

context: IInputModeContext: Gets the context for the current event.

'moved'

Occurs at the end of every drag or move.

Properties of

context: IInputModeContext: Gets the context for the current event.

'moving'

Occurs at the start of every drag or move.

Properties of