y.layout
Class OrientationLayouter

java.lang.Object
  y.layout.AbstractLayoutStage
      y.layout.OrientationLayouter

All Implemented Interfaces:

Layouter, LayoutOrientation, LayoutStage

public class OrientationLayouter
extends AbstractLayoutStage
implements LayoutOrientation

OrientationLayouter is a LayoutStage 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

OrientationLayouter 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

OrientationLayouter can either be used as a LayoutStage 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, OrientationLayouter can work alone. It will just change the orientation of the layout without arranging nodes and edges.

For subclasses of CanonicMultiStageLayouters it is highly recommended to use CanonicMultiStageLayouter.getOrientationLayouter() for layout orientation changes and not to wrap CanonicMultiStageLayouter with an OrientationLayouter instance. That may cause unwanted artifacts.

Nested Class Summary

class

OrientationLayouter.Transformer This class provides methods for transferring a point to its final position.

Field Summary

static int	MIRROR_BOTTOM_TO_TOP Mirroring specifier that defines that layout orientation LayoutOrientation.BOTTOM_TO_TOP will be mirrored.
static int	MIRROR_LEFT_TO_RIGHT Mirroring specifier that defines that layout orientation LayoutOrientation.LEFT_TO_RIGHT will be mirrored.
static int	MIRROR_NONE Mirroring specifier that can be used for preventing any mirroring of layout orientations.
static int	MIRROR_RIGHT_TO_LEFT Mirroring specifier that defines that layout orientation LayoutOrientation.RIGHT_TO_LEFT will be mirrored.
static int	MIRROR_TOP_TO_BOTTOM Mirroring specifier that defines that layout orientation LayoutOrientation.TOP_TO_BOTTOM will be mirrored.

Fields inherited from interface y.layout.LayoutOrientation

BOTTOM_TO_TOP, LEFT_TO_RIGHT, RIGHT_TO_LEFT, TOP_TO_BOTTOM

Fields inherited from interface y.layout.Layouter

EDGE_ID_DPKEY, NODE_ID_DPKEY, NODE_TYPE_DPKEY, SELECTED_EDGES, SELECTED_NODES

Constructor Summary

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

OrientationLayouter(byte orientation)
Creates a new OrientationLayouter instance using the given orientation.

OrientationLayouter(Layouter coreLayouter)
Creates a new OrientationLayouter instance using the given core layout algorithm.

Method Summary

boolean	canLayout(LayoutGraph graph) Accepts all graphs that can be handled by the core layout algorithm.
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(java.awt.Insets insets) Deprecated. Use createOrientedInsets(YInsets) instead.
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.
void	doLayout(LayoutGraph graph) Prepares the graph for orientation change before calling the core layout algorithm and finishes the orientation change afterwards.
int	getMirrorMask() Returns the mirror mask that defines which orientations this OrientationLayouter shall mirror.
byte	getOrientation() Returns the main direction of the layout.
boolean	isConsiderEdgeLabelsEnabled() Returns whether or not the position of the edge labels should be changed during orientation change.
boolean	isHorizontalOrientation() Returns whether or not the current orientation is horizontal.
boolean	isOrientationMirrored(byte orientation) Returns whether or not this OrientationLayouter 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	setConsiderEdgeLabelsEnabled(boolean enabled) Specifies whether or not the position of the edge labels should be changed during orientation change.
void	setMirrorMask(int mirrorMask) Specifies the mirror mask that defines which orientations this OrientationLayouter shall mirror.
void	setOrientation(byte orientation) Specifies 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 y.layout.AbstractLayoutStage

canLayoutCore, doLayoutCore, getCoreLayouter, setCoreLayouter

Methods inherited from class java.lang.Object

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

Field Detail

MIRROR_NONE

public static final int MIRROR_NONE

Mirroring specifier that can be used for preventing any mirroring of layout orientations.

See Also:

setMirrorMask(int), setOrientation(byte), Constant Field Values

MIRROR_TOP_TO_BOTTOM

public static final int MIRROR_TOP_TO_BOTTOM

Mirroring specifier that defines that layout orientation LayoutOrientation.TOP_TO_BOTTOM will be mirrored.

This specifier can be used for creating a mirror mask that defines which layout orientations shall be mirrored at their corresponding axis. It can be combined with the other mirroring specifiers to mirror several orientations.

See Also:

setMirrorMask(int), setOrientation(byte), Constant Field Values

Sample Graph:

LayoutOrientation.TOP_TO_BOTTOM for the left graph and the mirrored graph on the right

MIRROR_RIGHT_TO_LEFT

public static final int MIRROR_RIGHT_TO_LEFT

Mirroring specifier that defines that layout orientation LayoutOrientation.RIGHT_TO_LEFT will be mirrored.

This specifier can be used for creating a mirror mask that defines which layout orientations shall be mirrored at their corresponding axis. It can be combined with the other mirroring specifiers to mirror several orientations.

See Also:

setMirrorMask(int), setOrientation(byte), Constant Field Values

Sample Graph:

LayoutOrientation.RIGHT_TO_LEFT for the left graph and the mirrored graph on the right

MIRROR_BOTTOM_TO_TOP

public static final int MIRROR_BOTTOM_TO_TOP

Mirroring specifier that defines that layout orientation LayoutOrientation.BOTTOM_TO_TOP will be mirrored.

This specifier can be used for creating a mirror mask that defines which layout orientations shall be mirrored at their corresponding axis. It can be combined with the other mirroring specifiers to mirror several orientations.

See Also:

setMirrorMask(int), setOrientation(byte), Constant Field Values

Sample Graph:

LayoutOrientation.BOTTOM_TO_TOP for the left graph and the mirrored graph on the right

MIRROR_LEFT_TO_RIGHT

public static final int MIRROR_LEFT_TO_RIGHT

Mirroring specifier that defines that layout orientation LayoutOrientation.LEFT_TO_RIGHT will be mirrored.

This specifier can be used to create a mirror mask that defines which layout orientations shall be mirrored at their corresponding axis. It can be combined with the other mirroring specifiers to mirror several orientations.

See Also:

setMirrorMask(int), setOrientation(byte), Constant Field Values

Sample Graph:

LayoutOrientation.LEFT_TO_RIGHT for the left graph and the mirrored graph on the right

Constructor Detail

OrientationLayouter

public OrientationLayouter(Layouter coreLayouter)

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

Parameters:

coreLayouter - the core layout routine

OrientationLayouter

public OrientationLayouter()

Creates a new OrientationLayouter instance with default settings.

OrientationLayouter

public OrientationLayouter(byte orientation)

Creates a new OrientationLayouter instance using the given orientation.

Parameters:

orientation - the orientation specifier

Throws:

java.lang.IllegalArgumentException - if the specified orientation is unknown

See Also:

setOrientation(byte)

Method Detail

setOrientation

public void setOrientation(byte orientation)

Specifies the main direction of the layout.

Default Value:

The default value is LayoutOrientation.TOP_TO_BOTTOM

Parameters:

orientation - one of the valid orientation specifiers

Throws:

java.lang.IllegalArgumentException - if the specified orientation is unknown

getOrientation

public byte getOrientation()

Returns the main direction of the layout.

Returns:

of the valid orientation specifiers

See Also:

setOrientation(byte)

getMirrorMask

public int getMirrorMask()

Returns the mirror mask that defines which orientations this OrientationLayouter 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.

Returns:

the mask that determines which layout orientations are mirrored

See Also:

setMirrorMask(int)

setMirrorMask

public void setMirrorMask(int mirrorMask)

Specifies the mirror mask that defines which orientations this OrientationLayouter 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.

Default Value:

The default value is MIRROR_BOTTOM_TO_TOP

Parameters:

mirrorMask - the mask that determines which layout orientations should be mirrored

Throws:

java.lang.IllegalArgumentException - if an unknown mask is specified

isHorizontalOrientation

public boolean isHorizontalOrientation()

Returns 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(byte)

isConsiderEdgeLabelsEnabled

public boolean isConsiderEdgeLabelsEnabled()

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

Returns:

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

See Also:

setConsiderEdgeLabelsEnabled(boolean)

setConsiderEdgeLabelsEnabled

public void setConsiderEdgeLabelsEnabled(boolean enabled)

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

Parameters:

enabled - true if the position of the edge labels should be changed, false otherwise

canLayout

public boolean canLayout(LayoutGraph graph)

Accepts all graphs that can be handled by the core layout algorithm.

Specified by:

canLayout in interface Layouter

Parameters:

graph - the input graph

Returns:

true if there is no core layout algorithm or it can handle the given graph, false otherwise

See Also:

Layouter.doLayout(LayoutGraph)

doLayout

public void doLayout(LayoutGraph graph)

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

Specified by:

doLayout in interface Layouter

Parameters:

graph - the input graph

See Also:

Layouter.canLayout(LayoutGraph)

isOrientationMirrored

public boolean isOrientationMirrored(byte orientation)

Returns whether or not this OrientationLayouter 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(byte), setMirrorMask(int)

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 doLayout(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)

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 doLayout(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)

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)

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)

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(java.awt.Insets insets)

Deprecated. Use createOrientedInsets(YInsets) instead.

Creates YInsets that are a geometric transformation of the given Insets. The transform will correspond to the currently set orientation.

Parameters:

insets - the original insets

Returns:

the oriented insets

See Also:

setOrientation(byte)

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(byte)

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(byte)

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(byte)