com.yworks.yfiles.layout

Class EdgeLabelOrientationSupport

java.lang.Object

com.yworks.yfiles.layout.EdgeLabelOrientationSupport

public class EdgeLabelOrientationSupport
extends Object

EdgeLabelOrientationSupport provides orientation and mirroring support for layout algorithms with integrated edge labeling.

To calculate the position and orientation of edge labels whose placements are defined with the PreferredPlacementDescriptor, the OrientationLayout would need the direction of the associated edge. Since this direction is not available to the OrientationLayout, because it is a wrapper, the calculation must be done in the core layout algorithm itself with the help of the EdgeLabelOrientationSupport.

Important: Since layout algorithms with integrated edge labeling cannot deal with ambiguous preferred placement descriptors (combinations of the same setting, e.g., source or target for the PlaceAlongEdge), preProcessLabel(Graph, LabelLayoutData, Direction) removes combinations and replaces the original descriptor with a non-ambiguous one during the layout calculation.

Constructor Summary

Constructors

Constructor and Description
EdgeLabelOrientationSupport() Creates a new EdgeLabelOrientationSupport instance.

Method Summary

Modifier and Type	Method and Description
protected PreferredPlacementDescriptor	createNonAmbiguous(PreferredPlacementDescriptor ambiguous) Creates and returns a non-ambiguous PreferredPlacementDescriptor of the given potentially ambiguous one.
static YVector	getEdgeLabelUpVector(PreferredPlacementDescriptor descriptor, Direction segmentDirection) Calculates the up vector of an edge label considering the preferred placement of the label as well as the direction of the edge segment the label is attached to.
static YVector	getLabelUpVector(double rightVectorAngle) Calculates the up vector for a label whose right vector is rotated clockwise by the given angle.
static Direction	getOrientedDirection(Direction direction, LayoutOrientation orientation, MirrorModes mirrorMask) Transforms a direction of the layout to the oriented layout direction.
static boolean	isOrientationMirrored(LayoutOrientation orientation, MirrorModes mirrorMask) Returns whether or not the orientation is mirrored.
void	markPortLabelForFallbackPlacement(LabelLayoutData portLabel) Marks the given port label for a non-port placement (fallback).
void	postProcessLabel(Graph graph, LabelLayoutData label) Restores the original preferred placement and updates the label rotation according to the layout orientation.
void	preProcessLabel(Graph graph, LabelLayoutData label, Direction segmentDirection) Prepares the label for the core layout algorithm.
void	replaceAmbiguousLabelDescriptors(Graph graph) Replaces the PreferredPlacementDescriptors of all edge labels in the given graph with non-ambiguous descriptors.
void	resetAmbiguousLabelDescriptors(Graph graph) Restores the PreferredPlacementDescriptors of all edge labels in the given graph with their original descriptors.
static void	updateLabelOrientation(LabelLayoutData label, Direction segmentDirection) Calculates and sets the up vector of an edge label considering the preferred placement of the label as well as the direction of the edge segment the label is attached to.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EdgeLabelOrientationSupport

public EdgeLabelOrientationSupport()

Creates a new EdgeLabelOrientationSupport instance.

Since this class handles the orientation of the edge labels, the core layout algorithm should disable the edge label calculation in its OrientationLayout.

See Also:

OrientationLayout.setEdgeLabelConsiderationEnabled(boolean)

Method Detail

createNonAmbiguous

protected PreferredPlacementDescriptor createNonAmbiguous(PreferredPlacementDescriptor ambiguous)

Creates and returns a non-ambiguous PreferredPlacementDescriptor of the given potentially ambiguous one.

The created descriptor will be one without any combinations of settings, e.g., source or target for the PlaceAlongEdge.

Parameters:

ambiguous - an ambiguous PreferredPlacementDescriptor

Returns:

a non-ambiguous version of the given ambiguous PreferredPlacementDescriptor

getEdgeLabelUpVector

public static final YVector getEdgeLabelUpVector(PreferredPlacementDescriptor descriptor,
                                                 Direction segmentDirection)

Calculates the up vector of an edge label considering the preferred placement of the label as well as the direction of the edge segment the label is attached to.

Parameters:

descriptor - the data describing the preferred label orientation

segmentDirection - the direction the edge segment is pointing to

Returns:

the up vector for the edge label that considers the preferred placement of the label as well as the direction of the edge segment the label is attached to

getLabelUpVector

public static final YVector getLabelUpVector(double rightVectorAngle)

Calculates the up vector for a label whose right vector is rotated clockwise by the given angle.

The up vector starts in the lower-left corner of the label and points up. If the label is paraxial it is (0, -1). The right vector starts at the same point and points right. In a paraxial label it is (1, 0).

Parameters:

rightVectorAngle - the angle in radians the right vector is rotated by

Returns:

the up vector for a label whose right vector is rotated clockwise by the given angle

getOrientedDirection

public static final Direction getOrientedDirection(Direction direction,
                                                   LayoutOrientation orientation,
                                                   MirrorModes mirrorMask)

Transforms a direction of the layout to the oriented layout direction.

Parameters:

direction - direction in the layout

orientation - the orientation of the layout

mirrorMask - the mask to determine whether or not the orientation is mirrored

Returns:

the direction in the oriented layout

isOrientationMirrored

public static final boolean isOrientationMirrored(LayoutOrientation orientation,
                                                  MirrorModes mirrorMask)

Returns whether or not the orientation is mirrored.

Parameters:

orientation - the orientation of the layout

mirrorMask - the mask to determine whether or not the orientation is mirrored

Returns:

true if the orientation is mirrored, false otherwise

markPortLabelForFallbackPlacement

public void markPortLabelForFallbackPlacement(LabelLayoutData portLabel)

Marks the given port label for a non-port placement (fallback).

The given edge label's PreferredPlacementDescriptor will internally be changed such that its placement along edge is either LabelPlacements.AT_SOURCE or LabelPlacements.AT_TARGET.

Algorithms that are executed after this call and before resetAmbiguousLabelDescriptors(Graph) will handle port labels like normal source or target labels.

Throws:

IllegalStateException - if replaceAmbiguousLabelDescriptors(Graph) was never called for the graph containing the given label.

This method may only be called for labels that were also processed by an earlier call to replaceAmbiguousLabelDescriptors(Graph).

Parameters:

portLabel - an edge label that had a LabelPlacements.AT_SOURCE_PORT or LabelPlacements.AT_TARGET_PORT placement preference

See Also:

LabelPlacements.AT_SOURCE_PORT, LabelPlacements.AT_TARGET_PORT

postProcessLabel

public void postProcessLabel(Graph graph,
                             LabelLayoutData label)

Restores the original preferred placement and updates the label rotation according to the layout orientation.

The original PreferredPlacementDescriptor that has been replaced in preProcessLabel(Graph, LabelLayoutData, Direction) gets restored. Then it moves and rotates the label box in respect of the orientation.

This method is called by the core layout algorithm with the integrated edge labeling for each edge label after the location of the label is determined.

Parameters:

graph - the graph to get the orientation information from

label - the information about the edge label whose location is determined

preProcessLabel

public void preProcessLabel(Graph graph,
                            LabelLayoutData label,
                            Direction segmentDirection)

Prepares the label for the core layout algorithm.

First, the preferred placement of the edge label is replaced by a non-ambiguous PreferredPlacementDescriptor that has only relative references. This descriptor is orientation independent and can be used in the core layout algorithm. Second, the method rotates the label box in respect of its PreferredPlacementDescriptor and the direction of the segment to which it belongs. After that call, the core layout algorithm can use the geometry (Width and Height) of the label to calculate its location.

This method is called by the core layout algorithm with the integrated edge labeling for each edge label before the layout algorithm uses the geometry of labels. It should be called as soon as the direction of the segment the label belongs to is determined.

Parameters:

graph - the graph to get the orientation information from

label - the information about the edge label whose segment direction is determined

segmentDirection - the direction of the segment the edge label belongs to

replaceAmbiguousLabelDescriptors

public void replaceAmbiguousLabelDescriptors(Graph graph)

Replaces the PreferredPlacementDescriptors of all edge labels in the given graph with non-ambiguous descriptors.

The non-ambiguous descriptors are retrieved from the original descriptors. They describe only one of the possible placements.

This method should be called by a layout algorithm at the beginning of the layout calculation to assure that the label's placement is handled consistently.

Parameters:

graph - the input graph

resetAmbiguousLabelDescriptors

public void resetAmbiguousLabelDescriptors(Graph graph)

Restores the PreferredPlacementDescriptors of all edge labels in the given graph with their original descriptors.

This method should be called by a layout algorithm at the end of the layout calculation to assure that the original state of the graph is not corrupted.

Parameters:

graph - the input graph

updateLabelOrientation

public static final void updateLabelOrientation(LabelLayoutData label,
                                                Direction segmentDirection)

Calculates and sets the up vector of an edge label considering the preferred placement of the label as well as the direction of the edge segment the label is attached to.

Parameters:

label - the data that describes the label orientation and is used for setting the new up vector

segmentDirection - the direction the edge segment is pointing to

See Also:

getEdgeLabelUpVector(PreferredPlacementDescriptor, Direction)