y.layout
Class PreferredPlacementDescriptor

java.lang.Object
  y.layout.PreferredPlacementDescriptor

All Implemented Interfaces:

LabelLayoutConstants

public class PreferredPlacementDescriptor
extends java.lang.Object
implements LabelLayoutConstants

A PreferredPlacementDescriptor provides placement information for automatic edge labeling. It provides several options that influence the label placement in generic labeling algorithms and layout algorithms that support integrated label placement.

The preferred placement can describe multiple locations. For some options, like the placement along the edge, it is possible to have a combination of the valid values. These values can be connected with a logical or-operation.

The following options describe the preferred placement:

• the placement along the edge
• the side of the edge
• the reference of the side
• the rotation angle of the label
• the reference for the rotation angle
• the rotation behavior for label on the right side of the edge
• the angle offset for label on the right side of the edge
• the distance between the label and its edge segment

The PreferredPlacementDescriptor will be immutable after freeze() is called.

A PreferredPlacementDescriptor must be set for each label and will be retrieved by the layout algorithms calling EdgeLabelLayout.getPreferredPlacementDescriptor().

Field Summary

static byte	ANGLE_IS_ABSOLUTE Angle interpretation specifier for edge labels which expresses that the rotation angle should be interpreted absolute and not relative to the edge slope.
static byte	ANGLE_IS_RELATIVE_TO_EDGE_FLOW Angle interpretation specifier for edge labels which expresses that the rotation angle should be interpreted relative to the edge slope.
static byte	ANGLE_OFFSET_ON_RIGHT_SIDE_0 Angle offset specifier for edge labels which expresses that no additional offset should be added to the angle.
static byte	ANGLE_OFFSET_ON_RIGHT_SIDE_180 Angle offset specifier for edge labels which expresses that an additional offset of 180 degrees should be added to the angle.
static byte	ANGLE_ON_RIGHT_SIDE_CO_ROTATING Angle interpretation specifier which expresses that the rotation angle should be interpreted clockwise.
static byte	ANGLE_ON_RIGHT_SIDE_COUNTER_ROTATING Angle interpretation specifier which expresses that the rotation angle should be interpreted counter-clockwise.
static byte	SIDE_IS_ABSOLUTE_WITH_LEFT_IN_NORTH Side placement specifier for edge labels which defines that the preferred side for the label is interpreted independently of the edge direction placing left labels above horizontal segments.
static byte	SIDE_IS_ABSOLUTE_WITH_RIGHT_IN_NORTH Side placement specifier for edge labels which defines that the preferred side for the label is interpreted independently of the edge direction placing left labels above horizontal segments.
static byte	SIDE_IS_RELATIVE_TO_EDGE_FLOW Side placement specifier for edge labels which expresses that the preferred side of the edge is interpreted relative to the edge flow.

Fields inherited from interface y.layout.LabelLayoutConstants

PLACE_ANYWHERE, PLACE_AT_CENTER, PLACE_AT_SOURCE, PLACE_AT_SOURCE_PORT, PLACE_AT_TARGET, PLACE_AT_TARGET_PORT, PLACE_LEFT_OF_EDGE, PLACE_ON_EDGE, PLACE_RIGHT_OF_EDGE, PLACEMENT_ALONG_EDGE_MASK, PLACEMENT_ON_SIDE_OF_EDGE_MASK

Constructor Summary

PreferredPlacementDescriptor()
Creates a new PreferredPlacementDescriptor instance with default settings.

PreferredPlacementDescriptor(PreferredPlacementDescriptor descriptor)
Creates a new PreferredPlacementDescriptor instance that copies the given descriptor.

Method Summary

boolean	equals(java.lang.Object o)
void	freeze() Makes this PreferredPlacementDescriptor instance immutable.
double	getAngle() Returns the angle (in radians) for the label rotation.
byte	getAngleOffsetOnRightSide() Returns the angle offset for labels that are placed on the right side of the edge.
byte	getAngleReference() Returns the reference of the angle given by getAngle().
byte	getAngleRotationOnRightSide() Returns how the angle is applied to labels on the right side in respect of the labels of the left side of the edge.
double	getDistanceToEdge() Returns the preferred distance between a label and the corresponding edge segment.
byte	getPlaceAlongEdge() Returns the preferred placement along the edge.
byte	getSideOfEdge() Returns the preferred side of the edge.
byte	getSideReference() Returns how to interpret the preferred side as given by getSideOfEdge().
int	hashCode()
boolean	isAngleAbsolute() Returns whether or not one of the angle interpretations is absolute.
boolean	isAngleOffsetOnRightSide0() Returns whether or not one of the angle interpretations is to add no angle offset to labels that are right of the edge.
boolean	isAngleOffsetOnRightSide180() Returns whether or not one of the angle interpretations is to add an angle offset of 180 degrees to labels that are right of the edge.
boolean	isAngleOnRightSideCoRotating() Returns whether or not one of the angle interpretations is to rotate the angle of labels that are right of the edge co-rotating with the labels left of or centered on the edge, i.e., the angle of all labels is interpreted clockwise.
boolean	isAngleOnRightSideCounterRotating() Returns whether or not one of the angle interpretations is to rotate the angle of labels that are right of the edge counter-rotating with the labels left of or centered on the edge, i.e., the angle of labels left or centered on edge is interpreted clockwise while the angle of labels right of edge is interpreted counter-clockwise.
boolean	isAngleRelativeToEdgeFlow() Returns whether or not one of the angle interpretation is relative to the edge slope.
boolean	isAtCenter() Returns whether or not one of the preferred placement locations for this label is at center.
boolean	isAtSource() Returns whether or not one of the preferred placement locations for this label is at source.
boolean	isAtSourcePort() Returns whether or not one of the preferred placements for this label is at the source port.
boolean	isAtTarget() Returns whether or not one of the preferred placements for this label is at target.
boolean	isAtTargetPort() Returns whether or not one of the preferred placements for this label is at the target port.
boolean	isFrozen() Returns whether or not this is an immutable instance of PreferredPlacementDescriptor.
boolean	isLeftOfEdge() Returns whether or not one of the preferred sides for this label is left of the edge.
boolean	isOnEdge() Returns whether or not one of the preferred sides for this label is on the edge.
boolean	isRightOfEdge() Returns whether or not one of the preferred sides for this label is right of the edge.
boolean	isSideAbsoluteWithLeftInNorth() Returns whether or not the preferred side specified by getSideOfEdge() is interpreted absolute, and on horizontal segments, labels with preferred side LabelLayoutConstants.PLACE_LEFT_OF_EDGE are placed above the segment.
boolean	isSideAbsoluteWithRightInNorth() Returns whether or not the preferred side specified by getSideOfEdge() is interpreted absolute, and on horizontal segments, labels with preferred side LabelLayoutConstants.PLACE_RIGHT_OF_EDGE are placed above the segment.
boolean	isSideRelativeToEdgeFlow() Returns whether or not the preferred side specified by getSideOfEdge() is interpreted relative to the edge flow.
static PreferredPlacementDescriptor	newSharedInstance(byte placement) Returns an immutable descriptor instance for the specified placement.
void	setAngle(double angle) Specifies the angle (in radians) for the label rotation.
void	setAngleOffsetOnRightSide(byte angleOffset) Specifies the angle offset for labels that are placed on the right side of the edge.
void	setAngleReference(byte angleReference) Specifies the reference of the angle given by getAngle().
void	setAngleRotationOnRightSide(byte angleRotation) Specifies how the angle is applied to labels on the right side in respect of the labels of the left side of the edge.
void	setDistanceToEdge(double distance) Specifies the preferred distance between a label and the corresponding edge segment.
void	setPlaceAlongEdge(byte placeAlongEdge) Specifies the preferred placement along the edge.
void	setSideOfEdge(byte sideOfEdge) Specifies the preferred side of the edge.
void	setSideReference(byte sideReference) Specifies how to interpret the preferred side as given by getSideOfEdge().
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

SIDE_IS_RELATIVE_TO_EDGE_FLOW

public static final byte SIDE_IS_RELATIVE_TO_EDGE_FLOW

Side placement specifier for edge labels which expresses that the preferred side of the edge is interpreted relative to the edge flow.

See Also:

setSideReference(byte), setSideOfEdge(byte), Constant Field Values

Sample Graph:

SIDE_IS_ABSOLUTE_WITH_LEFT_IN_NORTH

public static final byte SIDE_IS_ABSOLUTE_WITH_LEFT_IN_NORTH

Side placement specifier for edge labels which defines that the preferred side for the label is interpreted independently of the edge direction placing left labels above horizontal segments.

For vertical segments the label is placed left or right of the edge. In case the segment is horizontal, the label is placed above the segment if it should be left of the edge, otherwise below the segment.

See Also:

setSideReference(byte), setSideOfEdge(byte), Constant Field Values

Sample Graph:

SIDE_IS_ABSOLUTE_WITH_RIGHT_IN_NORTH

public static final byte SIDE_IS_ABSOLUTE_WITH_RIGHT_IN_NORTH

Side placement specifier for edge labels which defines that the preferred side for the label is interpreted independently of the edge direction placing left labels above horizontal segments.

For vertical segments the label is placed left or right of the edge. In case the segment is horizontal, the label is placed above the segment if it should be right of the edge, otherwise below the segment.

See Also:

setSideReference(byte), setSideOfEdge(byte), Constant Field Values

Sample Graph:

ANGLE_IS_ABSOLUTE

public static final byte ANGLE_IS_ABSOLUTE

Angle interpretation specifier for edge labels which expresses that the rotation angle should be interpreted absolute and not relative to the edge slope.

See Also:

setAngleReference(byte), setAngle(double), Constant Field Values

Sample Graph:

Absolute angle, both labels are rotated 0 radians (0 degrees)

ANGLE_IS_RELATIVE_TO_EDGE_FLOW

public static final byte ANGLE_IS_RELATIVE_TO_EDGE_FLOW

Angle interpretation specifier for edge labels which expresses that the rotation angle should be interpreted relative to the edge slope.

See Also:

setAngleReference(byte), setAngle(double), Constant Field Values

Sample Graph:

Relative angle, both labels are rotated 0 radians (0 degrees)

ANGLE_ON_RIGHT_SIDE_CO_ROTATING

public static final byte ANGLE_ON_RIGHT_SIDE_CO_ROTATING

Angle interpretation specifier which expresses that the rotation angle should be interpreted clockwise.

Therefore, edge labels whose descriptor isRightOfEdge() will be co-rotating with the angle of labels that are placed left of or centered on the edge.

See Also:

setAngleRotationOnRightSide(byte), setAngle(double), setSideOfEdge(byte), Constant Field Values

Sample Graph:

ANGLE_ON_RIGHT_SIDE_COUNTER_ROTATING

public static final byte ANGLE_ON_RIGHT_SIDE_COUNTER_ROTATING

Angle interpretation specifier which expresses that the rotation angle should be interpreted counter-clockwise.

Therefore, edge labels whose descriptor isRightOfEdge() will be counter-rotating with the angle of labels that are placed left of or centered on the edge.

See Also:

setAngleRotationOnRightSide(byte), setAngle(double), setSideOfEdge(byte), Constant Field Values

Sample Graph:

ANGLE_OFFSET_ON_RIGHT_SIDE_0

public static final byte ANGLE_OFFSET_ON_RIGHT_SIDE_0

Angle offset specifier for edge labels which expresses that no additional offset should be added to the angle.

See Also:

setAngleOffsetOnRightSide(byte), setAngle(double), setSideOfEdge(byte), Constant Field Values

Sample Graph:

ANGLE_OFFSET_ON_RIGHT_SIDE_180

public static final byte ANGLE_OFFSET_ON_RIGHT_SIDE_180

Angle offset specifier for edge labels which expresses that an additional offset of 180 degrees should be added to the angle. That way, point-symmetric label placements left and right of the edge can be attained.

See Also:

setAngleOffsetOnRightSide(byte), setAngle(double), setSideOfEdge(byte), Constant Field Values

Sample Graph:

Constructor Detail

PreferredPlacementDescriptor

public PreferredPlacementDescriptor()

Creates a new PreferredPlacementDescriptor instance with default settings.

PreferredPlacementDescriptor

public PreferredPlacementDescriptor(PreferredPlacementDescriptor descriptor)

Creates a new PreferredPlacementDescriptor instance that copies the given descriptor.

Parameters:

descriptor - the PreferredPlacementDescriptor that is copied

Method Detail

getPlaceAlongEdge

public byte getPlaceAlongEdge()

Returns the preferred placement along the edge.

Returns:

one of the valid positions along the edge

See Also:

setPlaceAlongEdge(byte)

setPlaceAlongEdge

public void setPlaceAlongEdge(byte placeAlongEdge)

Specifies the preferred placement along the edge.

Placements LabelLayoutConstants.PLACE_AT_SOURCE_PORT and LabelLayoutConstants.PLACE_AT_TARGET_PORT that indicate a placement directly at the edge port are currently only supported by IncrementalHierarchicLayouter.

Default Value:

The default value is LabelLayoutConstants.PLACE_AT_CENTER

Parameters:

placeAlongEdge - any combination of the valid positions along the edge

Throws:

java.lang.IllegalStateException - if this instance is immutable

getSideOfEdge

public byte getSideOfEdge()

Returns the preferred side of the edge.

Returns:

one of the valid sides of the edge

See Also:

setSideOfEdge(byte)

setSideOfEdge

public void setSideOfEdge(byte sideOfEdge)

Specifies the preferred side of the edge.

Default Value:

The default value is LabelLayoutConstants.PLACE_ON_EDGE

Parameters:

sideOfEdge - any combination of the valid sides of the edge

Throws:

java.lang.IllegalStateException - if this instance is immutable

getSideReference

public byte getSideReference()

Returns how to interpret the preferred side as given by getSideOfEdge().

Returns:

any combination of the valid side references

See Also:

setSideReference(byte)

setSideReference

public void setSideReference(byte sideReference)

Specifies how to interpret the preferred side as given by getSideOfEdge().

Default Value:

The default value is SIDE_IS_RELATIVE_TO_EDGE_FLOW

Parameters:

sideReference - any combination of the valid side references

Throws:

java.lang.IllegalStateException - if this instance is immutable

java.lang.IllegalArgumentException - if the specified side reference is invalid

getAngle

public double getAngle()

Returns the angle (in radians) for the label rotation.

How this angle is applied depends on the angle reference, the rotation and the offset for labels on the right side of the edge.

Returns:

the angle in radians

See Also:

setAngle(double), setAngleReference(byte), setAngleRotationOnRightSide(byte), setAngleOffsetOnRightSide(byte)

setAngle

public void setAngle(double angle)

Specifies the angle (in radians) for the label rotation.

How this angle is applied depends on the angle reference, the rotation and the offset for labels on the right side of the edge.

Default Value:

The default value is 0.

Parameters:

angle - the angle in radians

Throws:

java.lang.IllegalStateException - if this instance is immutable

See Also:

setAngleReference(byte), setAngleRotationOnRightSide(byte), setAngleOffsetOnRightSide(byte)

Sample Graphs:

0 radians (0 degree) with an absolute angle reference

0.78 radians (45 degree) with an absolute angle reference

getAngleReference

public byte getAngleReference()

Returns the reference of the angle given by getAngle().

Returns:

any combination of valid angle references

See Also:

setAngleReference(byte)

setAngleReference

public void setAngleReference(byte angleReference)

Specifies the reference of the angle given by getAngle().

Default Value:

The default value is ANGLE_IS_ABSOLUTE

Parameters:

angleReference - any combination of valid angle references

Throws:

java.lang.IllegalStateException - if this instance is immutable

java.lang.IllegalArgumentException - if the specified value is not a valid angle reference

getAngleRotationOnRightSide

public byte getAngleRotationOnRightSide()

Returns how the angle is applied to labels on the right side in respect of the labels of the left side of the edge.

Returns:

any combination of valid rotation directions

See Also:

setAngleRotationOnRightSide(byte)

setAngleRotationOnRightSide

public void setAngleRotationOnRightSide(byte angleRotation)

Specifies how the angle is applied to labels on the right side in respect of the labels of the left side of the edge.

Default Value:

The default value is ANGLE_ON_RIGHT_SIDE_CO_ROTATING

Parameters:

angleRotation - any combination of valid rotation directions

Throws:

java.lang.IllegalStateException - if this instance is immutable

java.lang.IllegalArgumentException - if the specified value is not a valid angle rotation

getAngleOffsetOnRightSide

public byte getAngleOffsetOnRightSide()

Returns the angle offset for labels that are placed on the right side of the edge.

Returns:

any combination of valid offsets (0 or 180 degrees)

See Also:

setAngleOffsetOnRightSide(byte)

setAngleOffsetOnRightSide

public void setAngleOffsetOnRightSide(byte angleOffset)

Specifies the angle offset for labels that are placed on the right side of the edge.

Default Value:

The default value is ANGLE_OFFSET_ON_RIGHT_SIDE_0

Parameters:

angleOffset - any combination of valid offsets (0 or 180 degrees)

Throws:

java.lang.IllegalStateException - if this instance is immutable

java.lang.IllegalArgumentException - if the specified value is not valid angle offset

getDistanceToEdge

public double getDistanceToEdge()

Returns the preferred distance between a label and the corresponding edge segment.

If the given distance is < 0, the distance is not fixed, i.e., it is chosen by the automatic labeling algorithm.

Returns:

preferred distance between a label and the corresponding edge segment

See Also:

setDistanceToEdge(double)

setDistanceToEdge

public void setDistanceToEdge(double distance)

Specifies the preferred distance between a label and the corresponding edge segment.

If the given distance is < 0, the distance is not fixed, i.e., it is chosen by the automatic labeling algorithm.

Default Value:

The default value is -1.

Parameters:

distance - preferred distance between a label and the corresponding edge segment

Throws:

java.lang.IllegalStateException - if this instance is immutable

java.lang.IllegalArgumentException - if the specified value is infinite or NaN

Sample Graphs:

0

20

isAtSource

public boolean isAtSource()

Returns whether or not one of the preferred placement locations for this label is at source.

Returns:

true if at source is a possible placement for this label, false otherwise

See Also:

LabelLayoutConstants.PLACE_AT_SOURCE

isAtCenter

public boolean isAtCenter()

Returns whether or not one of the preferred placement locations for this label is at center.

Returns:

true if at center is a possible placement for this label, false otherwise

See Also:

LabelLayoutConstants.PLACE_AT_CENTER

isAtTarget

public boolean isAtTarget()

Returns whether or not one of the preferred placements for this label is at target.

Returns:

true if at target is a possible placement for this label, false otherwise

See Also:

LabelLayoutConstants.PLACE_AT_TARGET

isAtSourcePort

public boolean isAtSourcePort()

Returns whether or not one of the preferred placements for this label is at the source port.

Returns:

true if at source port is a possible placement for this label, false otherwise

See Also:

LabelLayoutConstants.PLACE_AT_SOURCE_PORT

isAtTargetPort

public boolean isAtTargetPort()

Returns whether or not one of the preferred placements for this label is at the target port.

Returns:

true if at target port is a possible placement for this label, false otherwise

See Also:

LabelLayoutConstants.PLACE_AT_TARGET_PORT

isLeftOfEdge

public boolean isLeftOfEdge()

Returns whether or not one of the preferred sides for this label is left of the edge.

Returns:

true if left of the edge is a possible side for this label, false otherwise

See Also:

LabelLayoutConstants.PLACE_LEFT_OF_EDGE

isOnEdge

public boolean isOnEdge()

Returns whether or not one of the preferred sides for this label is on the edge.

Returns:

true if on the edge is a possible side for this label, false otherwise

See Also:

LabelLayoutConstants.PLACE_ON_EDGE

isRightOfEdge

public boolean isRightOfEdge()

Returns whether or not one of the preferred sides for this label is right of the edge.

Returns:

true if right of the edge is a possible side for this label, false otherwise

See Also:

LabelLayoutConstants.PLACE_RIGHT_OF_EDGE

isAngleAbsolute

public boolean isAngleAbsolute()

Returns whether or not one of the angle interpretations is absolute.

Returns:

true if absolute angle interpretation is a possible angle interpretation for this label, false otherwise

See Also:

ANGLE_IS_ABSOLUTE

isAngleRelativeToEdgeFlow

public boolean isAngleRelativeToEdgeFlow()

Returns whether or not one of the angle interpretation is relative to the edge slope.

Returns:

true if angle interpretation relative to the edge slope is a possible angle interpretation for this label, false otherwise

See Also:

ANGLE_IS_RELATIVE_TO_EDGE_FLOW

isAngleOnRightSideCoRotating

public boolean isAngleOnRightSideCoRotating()

Returns whether or not one of the angle interpretations is to rotate the angle of labels that are right of the edge co-rotating with the labels left of or centered on the edge, i.e., the angle of all labels is interpreted clockwise.

Returns:

true if co-rotating angle interpretation for right-side edges is a possible angle interpretation for this label, false otherwise

See Also:

isRightOfEdge(), ANGLE_ON_RIGHT_SIDE_CO_ROTATING

isAngleOnRightSideCounterRotating

public boolean isAngleOnRightSideCounterRotating()

Returns whether or not one of the angle interpretations is to rotate the angle of labels that are right of the edge counter-rotating with the labels left of or centered on the edge, i.e., the angle of labels left or centered on edge is interpreted clockwise while the angle of labels right of edge is interpreted counter-clockwise.

Returns:

true if counter-rotating angle interpretation for right-side edges is a possible angle interpretation for this label, false otherwise

See Also:

isRightOfEdge(), ANGLE_ON_RIGHT_SIDE_COUNTER_ROTATING

isAngleOffsetOnRightSide0

public boolean isAngleOffsetOnRightSide0()

Returns whether or not one of the angle interpretations is to add no angle offset to labels that are right of the edge.

Returns:

true if adding no angle offset for right-side edges is a possible angle interpretation for this label, false otherwise

See Also:

isRightOfEdge(), ANGLE_OFFSET_ON_RIGHT_SIDE_0

isAngleOffsetOnRightSide180

public boolean isAngleOffsetOnRightSide180()

Returns whether or not one of the angle interpretations is to add an angle offset of 180 degrees to labels that are right of the edge.

Returns:

true if adding an angle offset of 180 degrees for right-side edges is a possible angle interpretation for this label, false otherwise.

See Also:

isRightOfEdge(), ANGLE_OFFSET_ON_RIGHT_SIDE_180

isSideRelativeToEdgeFlow

public boolean isSideRelativeToEdgeFlow()

Returns whether or not the preferred side specified by getSideOfEdge() is interpreted relative to the edge flow.

Returns:

true if the preferred side is interpreted relative to the edge flow, false otherwise

See Also:

SIDE_IS_RELATIVE_TO_EDGE_FLOW

isSideAbsoluteWithLeftInNorth

public boolean isSideAbsoluteWithLeftInNorth()

Returns whether or not the preferred side specified by getSideOfEdge() is interpreted absolute, and on horizontal segments, labels with preferred side LabelLayoutConstants.PLACE_LEFT_OF_EDGE are placed above the segment.

Returns:

true if the preferred side is interpreted absolute, false otherwise

See Also:

SIDE_IS_ABSOLUTE_WITH_LEFT_IN_NORTH

isSideAbsoluteWithRightInNorth

public boolean isSideAbsoluteWithRightInNorth()

Returns whether or not the preferred side specified by getSideOfEdge() is interpreted absolute, and on horizontal segments, labels with preferred side LabelLayoutConstants.PLACE_RIGHT_OF_EDGE are placed above the segment.

Returns:

true if the preferred side is interpreted absolute, false otherwise

See Also:

SIDE_IS_ABSOLUTE_WITH_RIGHT_IN_NORTH

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

isFrozen

public boolean isFrozen()

Returns whether or not this is an immutable instance of PreferredPlacementDescriptor.

If this instance is immutable, all setter methods will throw an IllegalStateException when invoked.

Returns:

true if this instance is immutable, false otherwise

See Also:

freeze()

freeze

public void freeze()

Makes this PreferredPlacementDescriptor instance immutable.

If this instance is immutable, all setter methods will throw an IllegalStateException when invoked.

See Also:

isFrozen()

newSharedInstance

public static PreferredPlacementDescriptor newSharedInstance(byte placement)

Returns an immutable descriptor instance for the specified placement.

Descriptor instances returned by this method will use default values for all properties but placement along edge and side of edge.

Parameters:

placement - a combination of valid placements along the edge and valid sides of the edge

Returns:

an immutable descriptor instance for the specified placement

See Also:

isFrozen(), getPlaceAlongEdge(), getSideOfEdge()