C

LabelPositionHandler

Show Usages
An implementation of IPositionHandler that shows the various label position candidates and lets the user move a label to one of those candidate positions.
Implements
Inheritance Hierarchy

Remarks

Instances of this class can be used to change the visualization of labels while moving them.

The candidate positions rendered by the candidateRenderer provide the following CSS classes:

  • yfiles-label-position-candidate-template for all possible positions
  • yfiles-label-position-highlight-template for the position that would currently be taken

Examples

Setting the visualization mode for labels
graph.decorator.labels.positionHandler.addFactory((label) => {
  const positionHandler = new LabelPositionHandler(label)
  positionHandler.visualization = 'live'
  return positionHandler
})

See Also

An example for the CSS styling of the candidates is given in CSS Styling of the Label Position Suggestions .

Developer's Guide

Members

Show:

Constructors

LabelPositionHandler

(label: ILabel)
Initializes a new instance of the LabelPositionHandler class.

Parameters

label: ILabel
The label that shall be moved.

Properties

candidateRenderer

: IObjectRenderer<LabelCandidateRenderTag>
Gets or sets the IObjectRenderer<LabelCandidateRenderTag> that visualizes label candidates while moving labels.

When queried for an IVisualCreator to obtain the visualizations for label candidates, this renderer is passed instances of LabelCandidateRenderTag as render tag.

This property is not used if the visualization is set to Visualization.NONE.

final

graph

: IGraph
protectedreadonly
Gets the graph instance from the IInputModeContext that has been passed to the initializeDrag method.
protectedreadonlyfinal

label

: ILabel
protectedreadonly
Gets the label instance.
protectedreadonlyfinal

Property Value

The label.

location

: IPoint
readonly
Gets a view of the location of the item.
The point describes the current world coordinate of the element that can be modified by this handler.
readonlyfinal

preventConflictingMixedMoves

: boolean
Gets or sets a property that determines whether the handler should refuse to move the label when there are other, possibly conflicting items being moved at the same time.
To avoid difficult-to-follow and understand behavior when both items in a graph and labels are moved at the same time when they are part of a multi-selection, this property determines whether labels should only be moved when they are moved alone or as part of a multi-selection that consists of labels only. When set to true, and this instance is used in a composite IInputModeContext within a MoveInputMode that has MoveInputMode.affectedItems other than just labels, it will not move the label and basically act as a void implementation that does not influence the output.
final

useParameterFinderRecognizer

: function(EventArgs, unknown): boolean
Gets or sets the recognizer that determines whether the user wants to manually enable the usage of ILabelModelParameterFinder to specify the position for new label.
The default detects the current platform and delegates either to EventRecognizers.META_IS_DOWN (macOS) or EventRecognizers.CTRL_IS_DOWN (other platforms).
final

See Also

Developer's Guide

visualization

: Visualization
Gets or sets how the moved label should be shown during the gesture.

This property must not be changed during the gesture.

Default is Visualization.PLACEHOLDER.

conversionfinal

Examples

Decorate the LabelDecorator with a customized position handler to change the visualization mode.
Setting the visualization mode for labels
graph.decorator.labels.positionHandler.addFactory((label) => {
  const positionHandler = new LabelPositionHandler(label)
  positionHandler.visualization = 'live'
  return positionHandler
})

See Also

Developer's Guide

Methods

cancelDrag

(context: IInputModeContext, originalLocation: Point)
Called by clients to indicate that the dragging has been canceled by the user.
This method may be called after the initial initializeDrag and zero or more invocations of handleMove. Implementations should reset the position of the items they modify to their initial state. Alternatively to this method the dragFinished method might be called.

Parameters

context: IInputModeContext
The context to retrieve information about the drag from.
originalLocation: Point
The value of the coordinate of the location property at the time of initializeDrag.

dragFinished

(
context: IInputModeContext
originalLocation: Point
newLocation: Point
)
Called by clients to indicate that the repositioning has just been finished.
This method may be called after the initial initializeDrag and zero or more invocations of handleMove. Alternatively to this method the cancelDrag method might be called.

Parameters

context: IInputModeContext
The context to retrieve information about the drag from.
originalLocation: Point
The value of the location property at the time of initializeDrag.
newLocation: Point
The coordinates in the world coordinate system that the client wants the handle to be at. Depending on the implementation the location may or may not be modified to reflect the new value. This is the same value as delivered in the last invocation of handleMove.

getDistance

(rectangle: IOrientedRectangle, location: Point): number
protected
Calculates a distance value between a candidate rectangle and the mouse location.
protected

Parameters

rectangle: IOrientedRectangle
The rectangle candidate.
location: Point
The mouse location.

Return Value

number
A value indicating the closeness of the mouse to the rectangle.

getParameterCandidates

(label: ILabel): IEnumerable<ILabelModelParameter>
protected
Gets the candidates for the given label.
protected

Parameters

label: ILabel
The label.

Return Value

IEnumerable<ILabelModelParameter>
A possibly empty enumerator over possible label parameter candidates.

getParameterFinder

(label: ILabel): ILabelModelParameterFinder
protected
Provides the ILabelModelParameterFinder for calculating the label's candidates.
protected

Parameters

label: ILabel
The label for which to find the parameter

Return Value

ILabelModelParameterFinder
An ILabelModelParameterFinder provided in the lookup of the given label, or a default implementation that finds the closest matching parameter.

handleMove

(
context: IInputModeContext
originalLocation: Point
newLocation: Point
)
Called by clients to indicate that the element has been dragged and its position should be updated.
This method may be called more than once after an initial initializeDrag and the final call will be followed by either one dragFinished or one cancelDrag call.

Parameters

context: IInputModeContext
The context to retrieve information about the drag from.
originalLocation: Point
The value of the location property at the time of initializeDrag.
newLocation: Point
The coordinates in the world coordinate system that the client wants the handle to be at. Depending on the implementation, the location may or may not be modified to reflect the new value.

initializeDrag

(context: IInputModeContext)
Called by clients to indicate that the element is going to be dragged.
This call will be followed by one or more calls to handleMove, and a final dragFinished or cancelDrag.

Parameters

context: IInputModeContext
The context to retrieve information about the drag from.

setLayoutParameter

(label: ILabel, layoutParameter: ILabelModelParameter)
protected
Actually applies the given parameter at the end of the gesture.
protected

Parameters

label: ILabel
The label to set the parameter for.
layoutParameter: ILabelModelParameter
The new parameter.

shouldIgnoreMoves

(context: IInputModeContext): boolean
protected
Determines whether to ignore upcoming handleMove and dragFinished calls.
When preventConflictingMixedMoves is enabled, this predicate will be called when the MoveInputMode from the IInputModeContext has MoveInputMode.drag-started. This implementation checks whether the label is not using FreeLabelModel and the MoveInputMode.affectedItems contains elements that the position of this label might depend upon. E.g. if the ILabel.owner is also moved interactively, the label will not be moved along explicitly, but only implicitly through its owner.
protected

Parameters

Return Value

boolean
true when the label should not be updated for upcoming handleMove and dragFinished operations.

shouldUseParameterFinder

(context: IInputModeContext): boolean
protected
Determines whether to use a ILabelModelParameterFinder to find the best candidate.
This implementation returns true if there are either no candidates at all or useParameterFinderRecognizer matches for the last input event received by the ICanvasContext.canvasComponent.
protected

Parameters

context: IInputModeContext
The context that is currently being used.

Return Value

boolean
true if the ILabelModelParameterFinder should be used; otherwise, false.

See Also

API
useParameterFinderRecognizer