Search this API

y.layout
Class OrientationLayouter

java.lang.Object
  extended by y.layout.AbstractLayoutStage
      extended by 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, 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)

© Copyright 2000-2021,
yWorks GmbH.
All rights reserved.