Search this API

y.layout.partial
Class PartialLayouter

java.lang.Object
  extended by y.layout.AbstractLayoutStage
      extended by y.layout.partial.PartialLayouter
All Implemented Interfaces:
Layouter, LayoutStage

public class PartialLayouter
extends AbstractLayoutStage

This class represents a partial layout algorithm which changes the coordinates for a given set of graph elements (called partial elements) only. The location and size of the remaining elements (called fixed elements) is not allowed to be changed.

Layout Style

This partial layout algorithm offers a kind of generic partial layout support for other existing layout algorithms. Hence, its layout style heavily depends on the selected core layout algorithm as well as the specified edge router or edge routing strategy.

The partial layout is suitable for applications where users may incrementally add new elements to an existing drawing. The added elements should be arranged so that they fit best possible into the given diagram without making any changes to the already existing layout. Hence, the so-called mental map of the existing drawing is preserved.


The input graph where marked nodes denote the partial elements that were incrementally added to the existing diagram.


The result of a partial layout run with component assignment strategy set to COMPONENT_ASSIGNMENT_STRATEGY_SINGLE and with node alignment enabled.

Features

Similar to the layout style, the supported feature set mainly depends on the features supported by the specified core layout algorithm as well as the specified edge router or edge routing strategy. The internal step that places the components can handle group nodes as well as minimum distance constraints. Furthermore, it is able to consider node labels.

Concept

The layout algorithm tries to place the partial elements such that the resulting drawing (including the fixed elements) has a good quality with respect to common graph drawing aesthetics.

The layout algorithm handles each selected graph element as partial element. For this, it looks up the DataProvider keys PARTIAL_NODES_DPKEY and PARTIAL_EDGES_DPKEY. Partial node elements can be assigned to the so-called subgraph components. During the layout process each subgraph induced by the nodes of a component is first laid out using the specified core layout algorithm. Then, the different components are placed one-by-one onto the drawing area such that the number of overlaps among graph elements is small. The user can specify different objectives for finding 'good' positions for subgraph components (see setPositioningStrategy(byte)), e.g., SUBGRAPH_POSITIONING_STRATEGY_BARYCENTER specifies that the component should be placed close to the barycenter of its graph neighbors and SUBGRAPH_POSITIONING_STRATEGY_FROM_SKETCH specifies that the component should be placed close to its original position.

Method setComponentAssignmentStrategy(byte) allows to specify the strategy that assigns partial nodes to subgraph components. Possible values are COMPONENT_ASSIGNMENT_STRATEGY_CLUSTERING, COMPONENT_ASSIGNMENT_STRATEGY_CONNECTED, COMPONENT_ASSIGNMENT_STRATEGY_SINGLE and COMPONENT_ASSIGNMENT_STRATEGY_CUSTOMIZED. The last value allows to use a customized component assignment. Note that nodes of a component cannot be assigned to different group nodes.

Furthermore, the user can specify the edge routing strategy (see setEdgeRoutingStrategy(byte)) that is used for routing partial edges and edges between different subgraph components (so-called inter-edges). Possible values are EDGE_ROUTING_STRATEGY_ORGANIC, EDGE_ROUTING_STRATEGY_ORTHOGONAL, EDGE_ROUTING_STRATEGY_STRAIGHTLINE, EDGE_ROUTING_STRATEGY_OCTILINEAR and EDGE_ROUTING_STRATEGY_AUTOMATIC.

 
When a partial node should be placed inside a fixed group node, it is important that there is enough free space inside the group. Otherwise, there may be overlapping node elements.
 

Nested Class Summary
static class PartialLayouter.StraightLineEdgeRouter
          Deprecated. Use class StraightLineEdgeRouter instead.
 
Field Summary
static java.lang.Object COMPONENT_ASSIGNMENT_DPKEY
          A DataProvider key for defining custom subgraph components.
static byte COMPONENT_ASSIGNMENT_STRATEGY_CLUSTERING
          A component assignment strategy where the subgraph components correspond to the clusters computed by a clustering algorithm based on edge betweenness centrality.
static byte COMPONENT_ASSIGNMENT_STRATEGY_CONNECTED
          A component assignment strategy where the subgraph components correspond to the connected components of the graph.
static byte COMPONENT_ASSIGNMENT_STRATEGY_CUSTOMIZED
          A component assignment strategy where the subgraph components are defined by the user.
static byte COMPONENT_ASSIGNMENT_STRATEGY_SINGLE
          A component assignment strategy that assigns each node to a separate subgraph component.
static java.lang.Object DIRECTED_EDGES_DPKEY
          A DataProvider key for specifying the edges that should be considered to be directed.
static byte EDGE_ROUTING_STRATEGY_AUTOMATIC
          Automatically chooses a suitable routing strategy by analyzing the existing edge routes.
static byte EDGE_ROUTING_STRATEGY_OCTILINEAR
          A routing strategy that produces octilinear routes.
static byte EDGE_ROUTING_STRATEGY_ORGANIC
          A routing strategy that produces organic routes for partial edges and inter-edges.
static byte EDGE_ROUTING_STRATEGY_ORTHOGONAL
          A routing strategy that produces orthogonal routes.
static byte EDGE_ROUTING_STRATEGY_STRAIGHTLINE
          A routing strategy that produces straight-line routes.
static byte ORIENTATION_AUTO_DETECTION
          Layout orientation specifier where the orientation is automatically detected.
static byte ORIENTATION_BOTTOM_TO_TOP
          Layout orientation specifier which defines that the main layout orientation is from bottom to top.
static byte ORIENTATION_LEFT_TO_RIGHT
          Layout orientation specifier which defines that the main layout orientation is from left to right.
static byte ORIENTATION_NONE
          Layout orientation specifier where the layout orientation is completely ignored.
static byte ORIENTATION_RIGHT_TO_LEFT
          Layout orientation specifier which defines that the main layout orientation is from right to left.
static byte ORIENTATION_TOP_TO_BOTTOM
          Layout orientation specifier which defines that the main layout orientation is from top to bottom.
static java.lang.Object PARTIAL_EDGES_DPKEY
          A DataProvider key for marking partial edges.
static java.lang.Object PARTIAL_NODES_DPKEY
          A DataProvider key for marking partial nodes.
static java.lang.String ROUTE_EDGE_DPKEY
          A DataProvider key for obtaining the edges that should be routed by the edge router.
static byte SUBGRAPH_POSITIONING_STRATEGY_BARYCENTER
          A positioning strategy which tries to place each subgraph component close to the barycenter of its graph neighbors.
static byte SUBGRAPH_POSITIONING_STRATEGY_FROM_SKETCH
          A positioning strategy which tries to place each subgraph component close to its original position.
 
Fields inherited from interface y.layout.Layouter
EDGE_ID_DPKEY, NODE_ID_DPKEY, SELECTED_EDGES, SELECTED_NODES
 
Constructor Summary
PartialLayouter()
          Creates a new instance of PartialLayouter.
PartialLayouter(Layouter subgraphLayouter)
          Creates a new instance of PartialLayouter which uses the specified Layouter instance as the core layout algorithm.
 
Method Summary
 boolean canLayout(LayoutGraph graph)
          Delegates the call to the specified core layout algorithm.
protected  void configureEdgeRouter(Layouter edgeRouter)
          This method is called each time when edges are routed with an edge router.
 void doLayout(LayoutGraph graph)
          This method calculates the partial layout.
 void doPartialLayout(LayoutGraph graph)
          This method calculates the partial layout.
 byte getComponentAssignmentStrategy()
          Returns the strategy that assigns partial nodes to subgraph components.
 Layouter getCoreLayouter()
          Returns the Layouter instance that is applied to each subgraph component.
 Layouter getEdgeRouter()
          Returns the custom edge router instance that is used for partial edges and edges between different subgraph components (so-called inter-edges).
 byte getEdgeRoutingStrategy()
          Returns the routing strategy that is used for partial edges and inter-edges.
 byte getLayoutOrientation()
          Returns the layout orientation that is considered during the placement of partial elements.
 long getMaximalDuration()
          Returns the preferred time limit (in milliseconds) for the layout algorithm.
 int getMinimalNodeDistance()
          Returns the minimum distance between two adjacent nodes.
 byte getPositioningStrategy()
          Returns the objective used for finding 'good' positions for subgraph components.
 boolean isConsiderNodeAlignment()
          Returns whether or not partial nodes should be aligned.
 boolean isFixedGroupResizingEnabled()
          Returns whether or not fixed (non-partial) group nodes may be resized.
 boolean isMirroringAllowed()
          Returns whether or not subgraph components are mirrored to improve the layout quality.
 boolean isOrientationOptimizationEnabled()
          Returns whether or not a postprocessing step should be applied to reduce the number of directed edges that do not comply with the specified layout orientation.
 boolean isPackComponentsEnabled()
          Returns whether or not a subgraph component may be placed within another subgraph component.
 boolean isRouteInterEdgesImmediatelyEnabled()
          Returns whether or not edges between different subgraph components should be routed immediately.
protected  void layoutSubgraph(LayoutGraph subGraph)
          This method is called during the layout process and calculates the layout for the given subgraph component using the specified core layout algorithm.
protected  void placeSubgraphs(LayoutGraph graph, NodeList[] subgraphComponents)
          This method is called during the layout process and places the subgraph components one-by-one onto the drawing area.
protected  void routeEdgesBetweenFixedElements(LayoutGraph graph, EdgeList partialEdges)
          This method is called during the layout process and routes all partial edges that connect two fixed elements.
protected  void routeInterEdges(LayoutGraph graph, EdgeList interEdges)
          This method is called during the layout process and routes all inter-edges.
 void setComponentAssignmentStrategy(byte strategy)
          Specifies the strategy that assigns partial nodes to subgraph components.
 void setConsiderNodeAlignment(boolean considerNodeAlignment)
          Specifies whether or not partial nodes should be aligned.
 void setCoreLayouter(Layouter layouter)
          Specifies the Layouter instance that is applied to each subgraph component.
 void setEdgeRouter(Layouter edgeRouter)
          Specifies the custom edge router instance that is used for partial edges and edges between different subgraph components (so-called inter-edges).
 void setEdgeRoutingStrategy(byte strategy)
          Specifies the routing strategy that is used for partial edges and inter-edges.
 void setFixedGroupResizingEnabled(boolean fixedGroupResizingEnabled)
          Specifies whether or not fixed (non-partial) group nodes may be resized.
 void setLayoutOrientation(byte layoutOrientation)
          Specifies the layout orientation that is considered during the placement of partial elements.
 void setMaximalDuration(long maximalDuration)
          Specifies the preferred time limit (in milliseconds) for the layout algorithm.
 void setMinimalNodeDistance(int minimalNodeDistance)
          Specifies the minimum distance between two adjacent nodes.
 void setMirroringAllowed(boolean mirroringAllowed)
          Specifies whether or not subgraph components are mirrored to improve the layout quality.
 void setOrientationOptimizationEnabled(boolean enabled)
          Specifies whether or not a postprocessing step should be applied to reduce the number of directed edges that do not comply with the specified layout orientation.
 void setPackComponentsEnabled(boolean packComponentsEnabled)
          Specifies whether or not a subgraph component may be placed within another subgraph component.
 void setPositioningStrategy(byte strategy)
          Specifies the objective used for finding 'good' positions for subgraph components.
 void setRouteInterEdgesImmediatelyEnabled(boolean enabled)
          Specifies whether or not edges between different subgraph components should be routed immediately.
 
Methods inherited from class y.layout.AbstractLayoutStage
canLayoutCore, doLayoutCore
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

PARTIAL_NODES_DPKEY

public static final java.lang.Object PARTIAL_NODES_DPKEY
A DataProvider key for marking partial nodes.

See Also:
PARTIAL_EDGES_DPKEY

DIRECTED_EDGES_DPKEY

public static final java.lang.Object DIRECTED_EDGES_DPKEY
A DataProvider key for specifying the edges that should be considered to be directed.

If a layout orientation is specified (i.e., getLayoutOrientation() is not ORIENTATION_NONE), the algorithm tries to route directed edges such that they adhere to that orientation.

 
If this DataProvider is not registered, all edges are considered to be directed.
See Also:
setLayoutOrientation(byte)

PARTIAL_EDGES_DPKEY

public static final java.lang.Object PARTIAL_EDGES_DPKEY
A DataProvider key for marking partial edges.

 
All edges with at least one partial endpoint are automatically considered to be partial.
See Also:
PARTIAL_NODES_DPKEY

ROUTE_EDGE_DPKEY

public static final java.lang.String ROUTE_EDGE_DPKEY
A DataProvider key for obtaining the edges that should be routed by the edge router.

 
The associated DataProvider must not be set by the user! The key is used by this algorithm to temporarily add a DataProvider that marks edges that should be routed by the specified edge router, see setEdgeRouter(y.layout.Layouter).
See Also:
setEdgeRouter(y.layout.Layouter), Constant Field Values

COMPONENT_ASSIGNMENT_DPKEY

public static final java.lang.Object COMPONENT_ASSIGNMENT_DPKEY
A DataProvider key for defining custom subgraph components.

 
The associated DataProvider is only considered if setComponentAssignmentStrategy(byte) is set to COMPONENT_ASSIGNMENT_STRATEGY_CUSTOMIZED.
 
Nodes of a subgraph component cannot be assigned to different group nodes or different partition cells.
See Also:
COMPONENT_ASSIGNMENT_STRATEGY_CUSTOMIZED, setComponentAssignmentStrategy(byte)
Sample Graphs:

The input graph where nodes 1 and 2 are fixed while the remaining nodes are partial.

The result of a partial layout run with core layout algorithm set to IncrementalHierarchicLayouter and the component assignment strategy set to COMPONENT_ASSIGNMENT_STRATEGY_CUSTOMIZED. Furthermore, in this example, the DataProvider associated with this key returns the same object for all partial nodes and, thus, all nodes are assigned to the same component.

EDGE_ROUTING_STRATEGY_ORTHOGONAL

public static final byte EDGE_ROUTING_STRATEGY_ORTHOGONAL
A routing strategy that produces orthogonal routes.

A route of an edge is called orthogonal if it only consists of vertical and horizontal segments.

See Also:
setEdgeRoutingStrategy(byte), ClearAreaLayouter.setEdgeRoutingStrategy(byte), Constant Field Values

EDGE_ROUTING_STRATEGY_STRAIGHTLINE

public static final byte EDGE_ROUTING_STRATEGY_STRAIGHTLINE
A routing strategy that produces straight-line routes.

See Also:
setEdgeRoutingStrategy(byte), ClearAreaLayouter.setEdgeRoutingStrategy(byte), Constant Field Values

EDGE_ROUTING_STRATEGY_AUTOMATIC

public static final byte EDGE_ROUTING_STRATEGY_AUTOMATIC
Automatically chooses a suitable routing strategy by analyzing the existing edge routes.

If, for example, all edges have orthogonal edge routes, edges that are rerouted are routed orthogonally, too.

See Also:
setEdgeRoutingStrategy(byte), ClearAreaLayouter.setEdgeRoutingStrategy(byte), Constant Field Values

EDGE_ROUTING_STRATEGY_ORGANIC

public static final byte EDGE_ROUTING_STRATEGY_ORGANIC
A routing strategy that produces organic routes for partial edges and inter-edges.

See Also:
setEdgeRoutingStrategy(byte), ClearAreaLayouter.setEdgeRoutingStrategy(byte), Constant Field Values

EDGE_ROUTING_STRATEGY_OCTILINEAR

public static final byte EDGE_ROUTING_STRATEGY_OCTILINEAR
A routing strategy that produces octilinear routes.

A route of an edge is called octilinear if the slope of each segment is a multiple of 45 degrees.

See Also:
setEdgeRoutingStrategy(byte), ClearAreaLayouter.setEdgeRoutingStrategy(byte), Constant Field Values

COMPONENT_ASSIGNMENT_STRATEGY_SINGLE

public static final byte COMPONENT_ASSIGNMENT_STRATEGY_SINGLE
A component assignment strategy that assigns each node to a separate subgraph component.

See Also:
setComponentAssignmentStrategy(byte), ClearAreaLayouter.setComponentAssignmentStrategy(byte), FillAreaLayouter.setComponentAssignmentStrategy(byte), Constant Field Values

COMPONENT_ASSIGNMENT_STRATEGY_CONNECTED

public static final byte COMPONENT_ASSIGNMENT_STRATEGY_CONNECTED
A component assignment strategy where the subgraph components correspond to the connected components of the graph.

See Also:
setComponentAssignmentStrategy(byte), ClearAreaLayouter.setComponentAssignmentStrategy(byte), FillAreaLayouter.setComponentAssignmentStrategy(byte), Constant Field Values

COMPONENT_ASSIGNMENT_STRATEGY_CLUSTERING

public static final byte COMPONENT_ASSIGNMENT_STRATEGY_CLUSTERING
A component assignment strategy where the subgraph components correspond to the clusters computed by a clustering algorithm based on edge betweenness centrality.

See Also:
setComponentAssignmentStrategy(byte), ClearAreaLayouter.setComponentAssignmentStrategy(byte), FillAreaLayouter.setComponentAssignmentStrategy(byte), Constant Field Values

COMPONENT_ASSIGNMENT_STRATEGY_CUSTOMIZED

public static final byte COMPONENT_ASSIGNMENT_STRATEGY_CUSTOMIZED
A component assignment strategy where the subgraph components are defined by the user.

See Also:
setComponentAssignmentStrategy(byte), ClearAreaLayouter.setComponentAssignmentStrategy(byte), FillAreaLayouter.setComponentAssignmentStrategy(byte), Constant Field Values

SUBGRAPH_POSITIONING_STRATEGY_BARYCENTER

public static final byte SUBGRAPH_POSITIONING_STRATEGY_BARYCENTER
A positioning strategy which tries to place each subgraph component close to the barycenter of its graph neighbors.

See Also:
setPositioningStrategy(byte), Constant Field Values
Sample Graphs:

Initial graph where node 3 is a partial node.

After applying the layout algorithm the partial node 3 is placed near the barycenter of its neighbor.

SUBGRAPH_POSITIONING_STRATEGY_FROM_SKETCH

public static final byte SUBGRAPH_POSITIONING_STRATEGY_FROM_SKETCH
A positioning strategy which tries to place each subgraph component close to its original position.

 
The algorithm still tries to prevent overlaps.
See Also:
setPositioningStrategy(byte), Constant Field Values
Sample Graphs:

Initial graph where node 3 is a partial node.

After applying the layout algorithm the partial node 3 is located near its original position.

ORIENTATION_TOP_TO_BOTTOM

public static final byte ORIENTATION_TOP_TO_BOTTOM
Layout orientation specifier which defines that the main layout orientation is from top to bottom.

See Also:
setLayoutOrientation(byte), ClearAreaLayouter.setLayoutOrientation(byte), FillAreaLayouter.setLayoutOrientation(byte), Constant Field Values

ORIENTATION_BOTTOM_TO_TOP

public static final byte ORIENTATION_BOTTOM_TO_TOP
Layout orientation specifier which defines that the main layout orientation is from bottom to top.

See Also:
setLayoutOrientation(byte), ClearAreaLayouter.setLayoutOrientation(byte), FillAreaLayouter.setLayoutOrientation(byte), Constant Field Values

ORIENTATION_LEFT_TO_RIGHT

public static final byte ORIENTATION_LEFT_TO_RIGHT
Layout orientation specifier which defines that the main layout orientation is from left to right.

See Also:
setLayoutOrientation(byte), ClearAreaLayouter.setLayoutOrientation(byte), FillAreaLayouter.setLayoutOrientation(byte), Constant Field Values

ORIENTATION_RIGHT_TO_LEFT

public static final byte ORIENTATION_RIGHT_TO_LEFT
Layout orientation specifier which defines that the main layout orientation is from right to left.

See Also:
setLayoutOrientation(byte), ClearAreaLayouter.setLayoutOrientation(byte), FillAreaLayouter.setLayoutOrientation(byte), Constant Field Values

ORIENTATION_AUTO_DETECTION

public static final byte ORIENTATION_AUTO_DETECTION
Layout orientation specifier where the orientation is automatically detected.

See Also:
setLayoutOrientation(byte), ClearAreaLayouter.setLayoutOrientation(byte), FillAreaLayouter.setLayoutOrientation(byte), Constant Field Values

ORIENTATION_NONE

public static final byte ORIENTATION_NONE
Layout orientation specifier where the layout orientation is completely ignored.

See Also:
setLayoutOrientation(byte), ClearAreaLayouter.setLayoutOrientation(byte), FillAreaLayouter.setLayoutOrientation(byte), Constant Field Values
Constructor Detail

PartialLayouter

public PartialLayouter()
Creates a new instance of PartialLayouter.


PartialLayouter

public PartialLayouter(Layouter subgraphLayouter)
Creates a new instance of PartialLayouter which uses the specified Layouter instance as the core layout algorithm. This instance is applied to each subgraph component, see setComponentAssignmentStrategy(byte).

Parameters:
subgraphLayouter - the layout algorithm that is applied to the subgraph components
See Also:
setComponentAssignmentStrategy(byte)
Method Detail

setCoreLayouter

public void setCoreLayouter(Layouter layouter)
Specifies the Layouter instance that is applied to each subgraph component.

More precisely, during the layout process each subgraph induced by the (partial) nodes of a component (see setComponentAssignmentStrategy(byte)) is first laid out using this instance.

Specified by:
setCoreLayouter in interface LayoutStage
Overrides:
setCoreLayouter in class AbstractLayoutStage
Parameters:
layouter - the Layouter instance that is applied to each subgraph component
Sample Graphs:

The input graph where nodes 1 and 2 are fixed while the remaining nodes are partial.

The result of a partial layout run with core layout algorithm set to IncrementalHierarchicLayouter and the component assignment strategy set to COMPONENT_ASSIGNMENT_STRATEGY_CONNECTED.

getCoreLayouter

public Layouter getCoreLayouter()
Returns the Layouter instance that is applied to each subgraph component.

More precisely, during the layout process each subgraph induced by the (partial) nodes of a component (see setComponentAssignmentStrategy(byte)) is first laid out using this instance.

Specified by:
getCoreLayouter in interface LayoutStage
Overrides:
getCoreLayouter in class AbstractLayoutStage
Returns:
the Layouter instance that is applied to each subgraph component
See Also:
setCoreLayouter(Layouter)

getMaximalDuration

public long getMaximalDuration()
Returns the preferred time limit (in milliseconds) for the layout algorithm.

The specified value has to be greater than or equal to 0. If the value is Integer.MAX_VALUE, the time is not limited.

 
Restricting the maximum duration may result in a worse layout quality. Furthermore, the real runtime may exceed the maximum duration since the layout algorithm still has to find a valid solution.
Returns:
the preferred time limit
See Also:
setMaximalDuration(long)

setMaximalDuration

public void setMaximalDuration(long maximalDuration)
Specifies the preferred time limit (in milliseconds) for the layout algorithm.

The specified value has to be greater than or equal to 0. If the value is Integer.MAX_VALUE, the time is not limited.

 
Restricting the maximum duration may result in a worse layout quality. Furthermore, the real runtime may exceed the maximum duration since the layout algorithm still has to find a valid solution.
Default Value:
The default value is Integer.MAX_VALUE. The time is not limited.
Parameters:
maximalDuration - the preferred time limit
Throws:
java.lang.IllegalArgumentException - if the maximum duration is negative

isRouteInterEdgesImmediatelyEnabled

public boolean isRouteInterEdgesImmediatelyEnabled()
Returns whether or not edges between different subgraph components should be routed immediately. If this option is enabled, edges are routed during the placement of the subgraph components, i.e., immediately after a component is placed, its edges to other already placed components are routed. Otherwise, these edges are routed in a separate step after placing all subgraph components. Hence, while enabling this option usually leads to shorter edge routes, the placement of subgraph components is less compact.

Returns:
true if edges between different subgraph components are routed immediately, false otherwise.
See Also:
setRouteInterEdgesImmediatelyEnabled(boolean)

setRouteInterEdgesImmediatelyEnabled

public void setRouteInterEdgesImmediatelyEnabled(boolean enabled)
Specifies whether or not edges between different subgraph components should be routed immediately. If this option is enabled, edges are routed during the placement of the subgraph components, i.e., immediately after a component is placed, its edges to other already placed components are routed. Otherwise, these edges are routed in a separate step after placing all subgraph components. Hence, while enabling this option usually leads to shorter edge routes, the placement of subgraph components is less compact.

Default Value:
The default value is false. Edges are not routed immediately.
Parameters:
enabled - true if edges between different subgraph components should be routed immediately, false otherwise
See Also:
routeInterEdges(y.layout.LayoutGraph, y.base.EdgeList), placeSubgraphs(y.layout.LayoutGraph, y.base.NodeList[])

isPackComponentsEnabled

public boolean isPackComponentsEnabled()
Returns whether or not a subgraph component may be placed within another subgraph component. Enabling this option leads to more compact layout results but requires more runtime.

Returns:
true if a subgraph component may be placed within another subgraph component, false otherwise
See Also:
setPackComponentsEnabled(boolean)

setPackComponentsEnabled

public void setPackComponentsEnabled(boolean packComponentsEnabled)
Specifies whether or not a subgraph component may be placed within another subgraph component. Enabling this option leads to more compact layout results but requires more runtime.

Default Value:
The default value is true. Subgraph component may be placed within another subgraph component.
Parameters:
packComponentsEnabled - true if a subgraph component may be placed within another subgraph component, false otherwise

isFixedGroupResizingEnabled

public boolean isFixedGroupResizingEnabled()
Returns whether or not fixed (non-partial) group nodes may be resized. Enabling this option may lead to better results if there are fixed group nodes, since there is more space for the partial elements.

Returns:
true if fixed group nodes may be resized, false otherwise
See Also:
setFixedGroupResizingEnabled(boolean)

setFixedGroupResizingEnabled

public void setFixedGroupResizingEnabled(boolean fixedGroupResizingEnabled)
Specifies whether or not fixed (non-partial) group nodes may be resized. Enabling this option may lead to better results if there are fixed group nodes since there is more space for the partial elements.

Default Value:
The default value is false. Fixed group nodes may not be resized.
Parameters:
fixedGroupResizingEnabled - true if fixed group nodes may be resized, false otherwise

getPositioningStrategy

public byte getPositioningStrategy()
Returns the objective used for finding 'good' positions for subgraph components.

Returns:
one of the predefined positioning strategies
See Also:
setPositioningStrategy(byte)

setPositioningStrategy

public void setPositioningStrategy(byte strategy)
Specifies the objective used for finding 'good' positions for subgraph components.

Default Value:
The default value is SUBGRAPH_POSITIONING_STRATEGY_BARYCENTER. Each subgraph component is placed close to the barycenter of its graph neighbors.
Parameters:
strategy - one of the predefined positioning strategies
Throws:
java.lang.IllegalArgumentException - if the specified strategy does not match one of the predefined positioning strategies

getMinimalNodeDistance

public int getMinimalNodeDistance()
Returns the minimum distance between two adjacent nodes.

The specified value has to be non-negative.

Returns:
the non-negative minimum distance
See Also:
setMinimalNodeDistance(int)

setMinimalNodeDistance

public void setMinimalNodeDistance(int minimalNodeDistance)
Specifies the minimum distance between two adjacent nodes.

The specified value has to be non-negative.

Default Value:
The default value is 10.
Parameters:
minimalNodeDistance - the non-negative minimum distance
Throws:
java.lang.IllegalArgumentException - if the distance is negative
Sample Graphs:

10 - the partial nodes (node 2 and 3) are placed such that the minimum distance between adjacent nodes is at least 10

60 - the partial nodes (node 2 and 3) are placed such that the minimum distance between adjacent nodes is at least 60

isConsiderNodeAlignment

public boolean isConsiderNodeAlignment()
Returns whether or not partial nodes should be aligned. If this option is enabled, the algorithm tries to align the center of partial nodes with other nodes.

 
Since the specified core layout algorithm doesn't consider this option, the alignment works best if the component assignment is set to COMPONENT_ASSIGNMENT_STRATEGY_SINGLE.
Returns:
true if nodes are aligned, false otherwise
See Also:
setConsiderNodeAlignment(boolean)

setConsiderNodeAlignment

public void setConsiderNodeAlignment(boolean considerNodeAlignment)
Specifies whether or not partial nodes should be aligned. If this option is enabled, the algorithm tries to align the center of partial nodes with other nodes.

 
Since the specified core layout algorithm doesn't consider this option, the alignment works best if the component assignment is set to COMPONENT_ASSIGNMENT_STRATEGY_SINGLE.
Default Value:
The default value is false. Nodes are not aligned.
Parameters:
considerNodeAlignment - true if nodes should be aligned, false otherwise
Sample Graphs:

false - partial node 3 is not aligned with the other nodes.

true - partial node 3 is horizontally aligned with node 1.

canLayout

public boolean canLayout(LayoutGraph graph)
Delegates the call to the specified core layout algorithm. If no core layout algorithm is specified, this method always returns true.

Parameters:
graph - the input graph
Returns:
true if the partial layout algorithm can be applied to the specified graph, false otherwise
See Also:
Layouter.doLayout(LayoutGraph)

getComponentAssignmentStrategy

public byte getComponentAssignmentStrategy()
Returns the strategy that assigns partial nodes to subgraph components.

The specified core layout algorithm independently calculates the layout for each subgraph component.

 
Borders of groups and partition cells always split up the components, i.e., two nodes assigned to different groups or partition cells are always assigned to different subgraph components.
Returns:
one of the predefined assignment strategies
See Also:
setComponentAssignmentStrategy(byte), COMPONENT_ASSIGNMENT_DPKEY, setCoreLayouter(Layouter)

setComponentAssignmentStrategy

public void setComponentAssignmentStrategy(byte strategy)
Specifies the strategy that assigns partial nodes to subgraph components.

The specified core layout algorithm independently calculates the layout for each subgraph component.

 
Borders of groups and partition cells always split up the components, i.e., two nodes assigned to different groups or partition cells are always assigned to different subgraph components.
Default Value:
The default value is COMPONENT_ASSIGNMENT_STRATEGY_SINGLE. Each partial node is assigned to a separate subgraph component.
Parameters:
strategy - one of the predefined assignment strategies
Throws:
java.lang.IllegalArgumentException - if the specified strategy does not match one of the predefined strategies
See Also:
COMPONENT_ASSIGNMENT_DPKEY, setCoreLayouter(Layouter)
Sample Graphs:

The input graph where nodes 1 and 2 are fixed while the remaining nodes are partial.

The result of a partial layout run with IncrementalHierarchicLayouter as core layout and component assignment strategy COMPONENT_ASSIGNMENT_STRATEGY_SINGLE.

The result of a partial layout run with IncrementalHierarchicLayouter as core layout and component assignment strategy COMPONENT_ASSIGNMENT_STRATEGY_CONNECTED.

The result of a partial layout run with IncrementalHierarchicLayouter as core layout and component assignment strategy COMPONENT_ASSIGNMENT_STRATEGY_CLUSTERING.

The result of a partial layout run with IncrementalHierarchicLayouter as core layout and component assignment strategy COMPONENT_ASSIGNMENT_STRATEGY_CUSTOMIZED. In this example, all nodes are manually assigned to the same component (i.e. the DataProvider associated with key COMPONENT_ASSIGNMENT_DPKEY returns the same object for all partial nodes).

isOrientationOptimizationEnabled

public boolean isOrientationOptimizationEnabled()
Returns whether or not a postprocessing step should be applied to reduce the number of directed edges that do not comply with the specified layout orientation.

Returns:
true if this postprocessing step is applied, false otherwise
See Also:
setOrientationOptimizationEnabled(boolean)

setOrientationOptimizationEnabled

public void setOrientationOptimizationEnabled(boolean enabled)
Specifies whether or not a postprocessing step should be applied to reduce the number of directed edges that do not comply with the specified layout orientation.

Default Value:
The default value is true. This postprocessing step is enabled.
Parameters:
enabled - true if this postprocessing step should be applied, false otherwise
See Also:
setLayoutOrientation(byte), DIRECTED_EDGES_DPKEY

getEdgeRouter

public Layouter getEdgeRouter()
Returns the custom edge router instance that is used for partial edges and edges between different subgraph components (so-called inter-edges).

 
Calling method setEdgeRoutingStrategy(byte) automatically sets a new edge router instance according to the specified routing strategy.
 
Edges that have to be routed with the specified router will be marked using DataProvider key ROUTE_EDGE_DPKEY. Hence, the specified router has to be configured such that it observes this key and only routes marked edges!
Returns:
the custom edge router instance that is used for partial edges and edges between different subgraph components
See Also:
setEdgeRouter(y.layout.Layouter), ROUTE_EDGE_DPKEY, setEdgeRoutingStrategy(byte)

setEdgeRouter

public void setEdgeRouter(Layouter edgeRouter)
Specifies the custom edge router instance that is used for partial edges and edges between different subgraph components (so-called inter-edges).

 
Calling method setEdgeRoutingStrategy(byte) automatically sets a new edge router instance according to the specified routing strategy.
 
Edges that have to be routed with the specified router will be marked using DataProvider key ROUTE_EDGE_DPKEY. Hence, the specified router has to be configured such that it observes this key and only routes marked edges!
Default Value:
The default value is PartialLayouter.StraightLineEdgeRouter
Parameters:
edgeRouter - the custom edge router instance that is used for partial edges and edges between different subgraph components
See Also:
ROUTE_EDGE_DPKEY, setEdgeRoutingStrategy(byte)

getEdgeRoutingStrategy

public byte getEdgeRoutingStrategy()
Returns the routing strategy that is used for partial edges and inter-edges.

Inter-edges are edges between fixed and partial nodes as well as edges between different subgraph components. The available strategies are listed in the following.

 
Calling this method disables a previously set customized edge router, see setEdgeRouter(Layouter).
Returns:
one of the predefined edge routing strategies
See Also:
setEdgeRoutingStrategy(byte), setEdgeRouter(Layouter)

setEdgeRoutingStrategy

public void setEdgeRoutingStrategy(byte strategy)
Specifies the routing strategy that is used for partial edges and inter-edges.

Inter-edges are edges between fixed and partial nodes as well as edges between different subgraph components. The available strategies are listed in the following.

 
Calling this method disables a previously set customized edge router, see setEdgeRouter(Layouter).
Default Value:
The default value is EDGE_ROUTING_STRATEGY_STRAIGHTLINE
Parameters:
strategy - one of the predefined edge routing strategies
Throws:
java.lang.IllegalArgumentException - if the specified strategy does not match one of the predefined routing strategies
See Also:
setEdgeRouter(Layouter)
Sample Graphs:

The input graph where node 2 is a partial node.

The result of a partial layout run with strategy EDGE_ROUTING_STRATEGY_STRAIGHTLINE.

The result of a partial layout run with strategy EDGE_ROUTING_STRATEGY_ORTHOGONAL.

The result of a partial layout run with strategy EDGE_ROUTING_STRATEGY_OCTILINEAR.

The result of a partial layout run with strategy EDGE_ROUTING_STRATEGY_ORGANIC.

The result of a partial layout run with strategy EDGE_ROUTING_STRATEGY_AUTOMATIC. The algorithm detects that the fixed edge between node 1 and 3 is routed straight-line and, thus, routes the inter-edge straight-line, too.

getLayoutOrientation

public byte getLayoutOrientation()
Returns the layout orientation that is considered during the placement of partial elements.

More precisely, the algorithm tries to place each subgraph component such that each predecessor of a component's node v is placed before v and each successor after v with respect to the layout orientation.

 
This only affects the placement of nodes of different subgraph components that are connected by directed edges. For nodes of the same subgraph component the layout orientation depends on the chosen core layout algorithm.
Returns:
one of the predefined layout orientations
See Also:
setLayoutOrientation(byte), DIRECTED_EDGES_DPKEY

setLayoutOrientation

public void setLayoutOrientation(byte layoutOrientation)
Specifies the layout orientation that is considered during the placement of partial elements.

More precisely, the algorithm tries to place each subgraph component such that each predecessor of a component's node v is placed before v and each successor after v with respect to the layout orientation.

 
This only affects the placement of nodes of different subgraph components that are connected by directed edges. For nodes of the same subgraph component the layout orientation depends on the chosen core layout algorithm.
Default Value:
The default value is ORIENTATION_NONE. The layout orientation is completely ignored.
Parameters:
layoutOrientation - one of the predefined layout orientations
Throws:
java.lang.IllegalArgumentException - if the specified orientation does not match one of the predefined orientations
See Also:
DIRECTED_EDGES_DPKEY
Sample Graphs:

ORIENTATION_NONE: the partial node 3 is placed without considering the layout orientation.

ORIENTATION_AUTO_DETECTION: the layout algorithm detects that the placement of the fixed nodes (node 1 and 2) corresponds to ORIENTATION_TOP_TO_BOTTOM placement and, thus, uses this orientation during the placement of the partial node (node 3).

ORIENTATION_TOP_TO_BOTTOM: the fixed node 1 is a predecessor of the partial node 3 and, thus, according to the ORIENTATION_TOP_TO_BOTTOM placement rule, node 3 is placed below node 1.

ORIENTATION_BOTTOM_TO_TOP: the fixed node 1 is a predecessor of the partial node 3 and, thus, according to the ORIENTATION_BOTTOM_TO_TOP placement rule, node 3 is placed above node 1. Note that the location of the fixed nodes (node 1 and 2) is not changed.

ORIENTATION_LEFT_TO_RIGHT: the fixed node 1 is a predecessor of the partial node 3 and, thus, according to the ORIENTATION_LEFT_TO_RIGHT placement rule, node 3 is placed to the right of node 1. Note that the location of the fixed nodes (node 1 and 2) is not changed.

ORIENTATION_RIGHT_TO_LEFT: the fixed node 1 is a predecessor of the partial node 3 and, thus, according to the ORIENTATION_RIGHT_TO_LEFT placement rule, node 3 is placed to the left of node 1. Note that the location of the fixed nodes (node 1 and 2) is not changed.

isMirroringAllowed

public boolean isMirroringAllowed()
Returns whether or not subgraph components are mirrored to improve the layout quality. If enabled, the algorithm checks for each component which of the four possible mirrorings minimizes the edge length.

Returns:
true if subgraph components are mirrored, false otherwise
See Also:
setMirroringAllowed(boolean)

setMirroringAllowed

public void setMirroringAllowed(boolean mirroringAllowed)
Specifies whether or not subgraph components are mirrored to improve the layout quality. If enabled, the algorithm checks for each component which of the four possible mirrorings minimizes the edge length.

Default Value:
The default value is false. Mirroring is disabled.
Parameters:
mirroringAllowed - true if subgraph components should be mirrored, false otherwise
Sample Graphs:

The input graph where node 1 and 2 are fixed while the remaining nodes are partial. The partial layout is applied to this graph with core layout algorithm set to SingleCycleLayouter and the component assignment strategy set to COMPONENT_ASSIGNMENT_STRATEGY_CONNECTED.

false

true

doLayout

public void doLayout(LayoutGraph graph)
This method calculates the partial layout. It calls the following methods:
  1. routeEdgesBetweenFixedElements(y.layout.LayoutGraph, y.base.EdgeList)
  2. layoutSubgraph(y.layout.LayoutGraph) for each subgraph component
  3. placeSubgraphs(y.layout.LayoutGraph, y.base.NodeList[])
  4. routeInterEdges(y.layout.LayoutGraph, y.base.EdgeList)

 
The above methods are called after applying the OrientationLayouter. Hence, they always assume that the graph is drawn from top to bottom.
Parameters:
graph - the input graph
See Also:
Layouter.canLayout(LayoutGraph)

doPartialLayout

public void doPartialLayout(LayoutGraph graph)
This method calculates the partial layout.

 
For internal use only. Users should start the layout by calling doLayout(LayoutGraph).
Parameters:
graph - the input graph

layoutSubgraph

protected void layoutSubgraph(LayoutGraph subGraph)
This method is called during the layout process and calculates the layout for the given subgraph component using the specified core layout algorithm. It is called once for each subgraph component.

Subclasses may implement a custom layout strategy or add some additional data.

Parameters:
subGraph - the subgraph component

placeSubgraphs

protected void placeSubgraphs(LayoutGraph graph,
                              NodeList[] subgraphComponents)
This method is called during the layout process and places the subgraph components one-by-one onto the drawing area. Therefore, it considers the specified objective for finding a suitable position.

Subclasses may implement a custom placement strategy or add some additional data. However, they must not modify the given subgraph component lists.

Parameters:
graph - the input graph
subgraphComponents - each entry contains a NodeList that induces a subgraph component

routeInterEdges

protected void routeInterEdges(LayoutGraph graph,
                               EdgeList interEdges)
This method is called during the layout process and routes all inter-edges. Inter-edges are edges between different subgraph components including edges between fixed and partial elements. For the routing, this method uses the edge router instance set with method setEdgeRouter(y.layout.Layouter). If no edge router was specified by the user, it uses an internal edge router with routing strategy getEdgeRoutingStrategy().

Subclasses may implement a custom routing strategy or add some additional data.

Parameters:
graph - the relevant subgraph
interEdges - the list of inter-edges to be routed

routeEdgesBetweenFixedElements

protected void routeEdgesBetweenFixedElements(LayoutGraph graph,
                                              EdgeList partialEdges)
This method is called during the layout process and routes all partial edges that connect two fixed elements. It either uses a custom edge router or an internal edge router that produces routes according to the specified routing strategy.

Subclasses may implement a custom routing strategy or add some additional data.

Parameters:
graph - the subgraph of the input graph induced by the fixed nodes
partialEdges - the list of partial edges to be routed

configureEdgeRouter

protected void configureEdgeRouter(Layouter edgeRouter)
This method is called each time when edges are routed with an edge router.

Subclasses may modify the configuration of the given edge router instance.

The type of the given instance depends on the edge routing strategy, i.e., if the routing strategy is set to EDGE_ROUTING_STRATEGY_OCTILINEAR or EDGE_ROUTING_STRATEGY_ORTHOGONAL it's an instance of EdgeRouter, if the routing strategy is set to EDGE_ROUTING_STRATEGY_ORGANIC it's an instance of OrganicEdgeRouter, and, if the routing strategy is set to EDGE_ROUTING_STRATEGY_STRAIGHTLINE it's an instance of PartialLayouter.StraightLineEdgeRouter. If the edge routing strategy is set to EDGE_ROUTING_STRATEGY_AUTOMATIC, the layout algorithm chooses one of the above strategies that best fits the routing style of the fixed edges.

 
If a custom edge router is set (see setEdgeRouter(y.layout.Layouter)), its instance corresponds to that of the parameter.
Parameters:
edgeRouter - the instance used for routing the edges
See Also:
setEdgeRouter(y.layout.Layouter), setEdgeRoutingStrategy(byte)

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