com.yworks.yfiles.layout

Class OrientationLayout

java.lang.Object

com.yworks.yfiles.layout.AbstractLayoutStage

com.yworks.yfiles.layout.OrientationLayout

All Implemented Interfaces:

ILayoutAlgorithm, ILayoutStage

public class OrientationLayout
extends AbstractLayoutStage

OrientationLayout is a ILayoutStage that changes the orientation of the layout.

Layout Style

There are four orientations that can be used for a layout. These orientations can exist with or without mirroring at the x-axis or y-axis.

Changing the layout orientation is useful for layout styles that show a main direction.

LayoutOrientation.TOP_TO_BOTTOM layout

LayoutOrientation.BOTTOM_TO_TOP layout with mirroring

LayoutOrientation.LEFT_TO_RIGHT layout

LayoutOrientation.RIGHT_TO_LEFT layout

Concept

OrientationLayout performs three basic steps.

1. Preparation: The sizes and locations of nodes and edge bends as well as labels and PortConstraints are transformed to the LayoutOrientation.TOP_TO_BOTTOM orientation.
2. Delegation: The core layout algorithm is invoked and calculates the layout for orientation LayoutOrientation.TOP_TO_BOTTOM.
3. Completion: The result of the core layout algorithm is rotated and mirrored to fit the desired layout orientation.

Features

OrientationLayout can either be used as a ILayoutStage wrapping a layout algorithm. Then it will change the orientation of the result of the core layout algorithm.
If no core layout algorithm is specified, OrientationLayout can work alone. It will just change the orientation of the layout without arranging nodes and edges.

For subclasses of MultiStageLayouts it is highly recommended to use OrientationLayout for layout orientation changes and not to wrap MultiStageLayout with an OrientationLayout instance. That may cause unwanted artifacts.

Constructor Summary

Constructors

Constructor and Description
OrientationLayout() Creates a new OrientationLayout instance with default settings.
OrientationLayout(ILayoutAlgorithm coreLayouter) Creates a new OrientationLayout instance using the given core layout algorithm.
OrientationLayout(LayoutOrientation orientation) Creates a new OrientationLayout instance using the given orientation.

Method Summary

Modifier and Type	Method and Description
void	applyLayout(LayoutGraph graph) Prepares the graph for orientation change before calling the core layout algorithm and finishes the orientation change afterwards.
protected void	completeOrientationChange(LayoutGraph graph) Applies the desired orientation to the graph.
protected YPoint	completeTransform(YPoint point) Transforms the given point during completion.
YInsets	createOrientedInsets(YInsets insets) Creates YInsets that are a geometric transformation of the given YInsets.
NodeHalo	createOrientedNodeHalo(NodeHalo halo) Creates a NodeHalo that is a geometric transformation of the given NodeHalo.
YDimension	createOrientedNodeSize(YDimension nodeSize) Creates a YDimension that is a geometric transformation of the given size.
MirrorModes	getMirrorMode() Gets the mirror mask that defines which orientations this OrientationLayout shall mirror.
LayoutOrientation	getOrientation() Gets the main direction of the layout.
boolean	isEdgeLabelConsiderationEnabled() Gets whether or not the position of the edge labels should be changed during orientation change.
boolean	isHorizontalOrientation() Gets whether or not the current orientation is horizontal.
boolean	isOrientationMirrored(LayoutOrientation orientation) Returns whether or not this OrientationLayout instance will mirror the graph for a given layout orientation.
protected void	prepareOrientationChange(LayoutGraph graph) Prepares the layout for the desired orientation.
protected YPoint	prepareTransform(YPoint point) Transforms the given point during preparation.
void	setEdgeLabelConsiderationEnabled(boolean value) Sets whether or not the position of the edge labels should be changed during orientation change.
void	setMirrorMode(MirrorModes value) Sets the mirror mask that defines which orientations this OrientationLayout shall mirror.
void	setOrientation(LayoutOrientation value) Sets the main direction of the layout.
protected YPoint	transform(YPoint point, boolean prepare) Transforms the given point during the preparation or completion step.

Methods inherited from class com.yworks.yfiles.layout.AbstractLayoutStage

applyLayoutCore, getCoreLayout, setCoreLayout

Methods inherited from class java.lang.Object

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

Constructor Detail

OrientationLayout

public OrientationLayout()

Creates a new OrientationLayout instance with default settings.

OrientationLayout

public OrientationLayout(ILayoutAlgorithm coreLayouter)

Creates a new OrientationLayout instance using the given core layout algorithm.

Parameters:

coreLayouter - the core layout routine

OrientationLayout

public OrientationLayout(LayoutOrientation orientation)

Creates a new OrientationLayout instance using the given orientation.

Throws:

IllegalArgumentException - if the specified orientation is unknown

Parameters:

orientation - the orientation specifier

See Also:

setOrientation(LayoutOrientation)

Method Detail

applyLayout

public void applyLayout(LayoutGraph graph)

Prepares the graph for orientation change before calling the core layout algorithm and finishes the orientation change afterwards.

Specified by:

applyLayout in interface ILayoutAlgorithm

Specified by:

applyLayout in class AbstractLayoutStage

Parameters:

graph - the input graph

completeOrientationChange

protected void completeOrientationChange(LayoutGraph graph)

Applies the desired orientation to the graph.

It performs the inverse coordinate transformation that has been applied to the layout by method prepareOrientationChange(LayoutGraph).

This method is called by applyLayout(LayoutGraph) after invoking the core layout algorithm. It may be overridden to extend the orientation change to custom layout features.

Parameters:

graph - the input graph

See Also:

prepareOrientationChange(LayoutGraph)

completeTransform

protected YPoint completeTransform(YPoint point)

Transforms the given point during completion.

The point is transformed from LayoutOrientation.TOP_TO_BOTTOM orientation to the desired orientation.

Parameters:

point - the calculated point

Returns:

the transformed point

See Also:

completeOrientationChange(LayoutGraph)

createOrientedInsets

public YInsets createOrientedInsets(YInsets insets)

Creates YInsets that are a geometric transformation of the given YInsets.

The transform will correspond to the currently set orientation.

Parameters:

insets - the original insets

Returns:

the oriented insets

See Also:

setOrientation(LayoutOrientation)

createOrientedNodeHalo

public NodeHalo createOrientedNodeHalo(NodeHalo halo)

Creates a NodeHalo that is a geometric transformation of the given NodeHalo.

The transform will correspond to the currently set orientation.

Parameters:

halo - the original NodeHalo

Returns:

the oriented NodeHalo

See Also:

setOrientation(LayoutOrientation)

createOrientedNodeSize

public YDimension createOrientedNodeSize(YDimension nodeSize)

Creates a YDimension that is a geometric transformation of the given size.

The transform will correspond to the currently set orientation.

Parameters:

nodeSize - the original node size

Returns:

the oriented node size

See Also:

setOrientation(LayoutOrientation)

getMirrorMode

public MirrorModes getMirrorMode()

Gets the mirror mask that defines which orientations this OrientationLayout shall mirror.

Setting a layout orientation can be seen as rotating the graph by 90, 180 or 270 degrees. Afterwards the graph can be mirrored at the x-axis (for horizontal layout orientations) or y-axis (for vertical layout orientations).

Which directions are mirrored can be defined by the given mask. It can combine several mirrored directions with a logical or-operation.

Throws:

IllegalArgumentException - if an unknown mask is specified

Default Value:

The default value is MirrorModes.BOTTOM_TO_TOP

Returns:

the mask that determines which layout orientations are mirrored

See Also:

setMirrorMode(MirrorModes)

getOrientation

public LayoutOrientation getOrientation()

Gets the main direction of the layout.

Throws:

IllegalArgumentException - if the specified orientation is unknown

Default Value:

The default value is LayoutOrientation.TOP_TO_BOTTOM

Returns:

of the valid orientation specifiers

See Also:

setOrientation(LayoutOrientation)

isEdgeLabelConsiderationEnabled

public boolean isEdgeLabelConsiderationEnabled()

Gets whether or not the position of the edge labels should be changed during orientation change.

The core layout algorithm should switch this off if it performs integrated edge labeling.

Default Value:

The default value is true. The orientation of labels is handled by this OrientationLayout.

Returns:

true if the position of the edge labels are changed, false otherwise

See Also:

setEdgeLabelConsiderationEnabled(boolean)

isHorizontalOrientation

public boolean isHorizontalOrientation()

Gets whether or not the current orientation is horizontal.

The orientation is horizontal if it is LayoutOrientation.LEFT_TO_RIGHT or LayoutOrientation.RIGHT_TO_LEFT.

Returns:

true if a horizontal orientation is currently used, false otherwise

See Also:

setOrientation(LayoutOrientation)

isOrientationMirrored

public boolean isOrientationMirrored(LayoutOrientation orientation)

Returns whether or not this OrientationLayout instance will mirror the graph for a given layout orientation.

Horizontal orientations get mirrored at the x-axis while vertical orientations are mirrored at the y-axis.

Parameters:

orientation - the layout orientation for which to check the mirror state

Returns:

true if the layout algorithm will mirror the graph at the corresponding axis for the given layout orientation, false otherwise

See Also:

setOrientation(LayoutOrientation), setMirrorMode(MirrorModes)

prepareOrientationChange

protected void prepareOrientationChange(LayoutGraph graph)

Prepares the layout for the desired orientation.

It will rotate and mirror the coordinates and bounds of the graph layout such that the core layout algorithm can perform its calculations assuming the canonical LayoutOrientation.TOP_TO_BOTTOM orientation.

This method is called by applyLayout(LayoutGraph) before invoking the core layout algorithm. It might be overridden to extend the preparations to custom layout features.

Parameters:

graph - the input graph

See Also:

completeOrientationChange(LayoutGraph)

prepareTransform

protected YPoint prepareTransform(YPoint point)

Transforms the given point during preparation.

The point is transformed so it matches the LayoutOrientation.TOP_TO_BOTTOM orientation.

Parameters:

point - the original point

Returns:

the transformed point

See Also:

prepareOrientationChange(LayoutGraph)

setEdgeLabelConsiderationEnabled

public void setEdgeLabelConsiderationEnabled(boolean value)

Sets whether or not the position of the edge labels should be changed during orientation change.

The core layout algorithm should switch this off if it performs integrated edge labeling.

Default Value:

The default value is true. The orientation of labels is handled by this OrientationLayout.

Parameters:

value - true if the position of the edge labels are changed, false otherwise

See Also:

isEdgeLabelConsiderationEnabled()

setMirrorMode

public void setMirrorMode(MirrorModes value)

Sets the mirror mask that defines which orientations this OrientationLayout shall mirror.

Setting a layout orientation can be seen as rotating the graph by 90, 180 or 270 degrees. Afterwards the graph can be mirrored at the x-axis (for horizontal layout orientations) or y-axis (for vertical layout orientations).

Which directions are mirrored can be defined by the given mask. It can combine several mirrored directions with a logical or-operation.

Throws:

IllegalArgumentException - if an unknown mask is specified

Default Value:

The default value is MirrorModes.BOTTOM_TO_TOP

Parameters:

value - the mask that determines which layout orientations are mirrored

See Also:

getMirrorMode()

setOrientation

public void setOrientation(LayoutOrientation value)

Sets the main direction of the layout.

Throws:

IllegalArgumentException - if the specified orientation is unknown

Default Value:

The default value is LayoutOrientation.TOP_TO_BOTTOM

Parameters:

value - of the valid orientation specifiers

See Also:

getOrientation()

transform

protected YPoint transform(YPoint point,
                           boolean prepare)

Transforms the given point during the preparation or completion step.

This method is called by prepareOrientationChange(LayoutGraph) and completeOrientationChange(LayoutGraph) to get the according point location.

Parameters:

point - the original/calculated point

prepare - true if this method is called during preparation, false if it is called during completion

Returns:

the transformed point

See Also:

prepareOrientationChange(LayoutGraph), completeOrientationChange(LayoutGraph), prepareTransform(YPoint), completeTransform(YPoint)