y.layout.hierarchic.incremental
Class SubcomponentDescriptor

java.lang.Object
  y.layout.hierarchic.incremental.SubcomponentDescriptor

public class SubcomponentDescriptor
extends java.lang.Object

A SubcomponentDescriptor defines settings for subcomponents that are arranged by a different layout algorithm than their containing graph for IncrementalHierarchicLayouter.

Property getLayoutAlgorithm() defines the algorithm that is responsible for arranging the subcomponent. The placement policy specifies the integration into the main hierarchic layout.

Nodes mapped to the same SubcomponentDescriptor instance form a component that is arranged as an independent sub-graph, induced by the component nodes. The mapping is retrieved from a DataProvider registered with the input graph with key IncrementalHierarchicLayouter.SUBCOMPONENT_DESCRIPTOR_DPKEY. Components may not be nested, that is, a subcomponent is not allowed to contain nodes that belong to yet another subcomponent. Nesting of subcomponents results in an exception.

A graph in hierarchic layout with subcomponents in 3 layout styles. Blue: Organic, Green: Hierarchic, Orange: Tree

See Also:

IncrementalHierarchicLayouter.SUBCOMPONENT_DESCRIPTOR_DPKEY

Field Summary

static byte	SUB_COMPONENT_PLACEMENT_POLICY_ALWAYS_INTEGRATED A placement policy that integrates subcomponents at a connector node if such a node exists.
static byte	SUB_COMPONENT_PLACEMENT_POLICY_AUTOMATIC A placement policy that integrates subcomponents at a connector node if such an integration is possible without causing overlaps or violating constraints of the main layout algorithm.
static byte	SUB_COMPONENT_PLACEMENT_POLICY_ISOLATED A placement policy that treats the component as a single node in the containing graph so that it is placed as such by the main layout algorithm.

Constructor Summary

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

SubcomponentDescriptor(byte placementPolicy, Layouter layoutAlgorithm)
Creates a new SubcomponentDescriptor instance with the specified settings.

SubcomponentDescriptor(Layouter layoutAlgorithm)
Creates a new SubcomponentDescriptor instance with the specified layout algorithm.

Method Summary

Node	getConnectorNode(LayoutGraph graph) Determines if there is a unique node outside the subcomponent whose removal would disconnect the component from the remaining graph and returns the node if it exists.
Layouter	getLayoutAlgorithm() Returns the Layouter for the subgraph that is induced by the nodes associated with this descriptor.
byte	getPlacementPolicy() Returns the policy defining how the subcomponent is placed within the layout context of the remaining graph.
void	setLayoutAlgorithm(Layouter layoutAlgorithm) Specifies the Layouter for the subgraph that is induced by the nodes associated with this descriptor.
void	setPlacementPolicy(byte placementPolicy) Specifies the policy defining how the subcomponent is placed within the layout context of the remaining graph.

Methods inherited from class java.lang.Object

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

Field Detail

SUB_COMPONENT_PLACEMENT_POLICY_ISOLATED

public static final byte SUB_COMPONENT_PLACEMENT_POLICY_ISOLATED

A placement policy that treats the component as a single node in the containing graph so that it is placed as such by the main layout algorithm.

The hierarchic layout chooses a layer for the whole component like it does for normal nodes. All inter-edges are at that point re-directed to a component representative node.

An isolated component does not have a specific connector node but it can have many non-component nodes it is connected to.

See Also:

setPlacementPolicy(byte), Constant Field Values

Sample Graph:

The two components are placed isolated on a respective hierarchic layer

SUB_COMPONENT_PLACEMENT_POLICY_ALWAYS_INTEGRATED

public static final byte SUB_COMPONENT_PLACEMENT_POLICY_ALWAYS_INTEGRATED

A placement policy that integrates subcomponents at a connector node if such a node exists.

A component has a valid connector node if all edges to non-component nodes are adjacent to the connector node.

The connector node and its edges to the component are included and handled by the layout algorithm arranging the component. If there is no unique connecting node, the subcomponent is instead treated in an isolated way.

This policy forces an integrated layout for subcomponents, regardless of potential overlaps or other constraints of the main layout algorithm, such as sequence constraints, layer constraints, incremental layouts, partition grids, PortCandidates or PortConstraints.

See Also:

setPlacementPolicy(byte), Constant Field Values

Sample Graph:

Both components are integrated at the bottom side of the connector node, disregarding overlaps between them

SUB_COMPONENT_PLACEMENT_POLICY_AUTOMATIC

public static final byte SUB_COMPONENT_PLACEMENT_POLICY_AUTOMATIC

A placement policy that integrates subcomponents at a connector node if such an integration is possible without causing overlaps or violating constraints of the main layout algorithm.

A component has a valid connector node if all edges to non-component nodes are adjacent to the connector node.

If there is a connector node and if the integration is possible, the connector node and its edges to the component are handled by the layout algorithm arranging the component. If an integration is not possible, the subcomponent is instead treated in an isolated way.

An important condition for the integration to be possible is that the orientation of the inner layout must be orthogonal with respect to the main layout, e.g., one top-to-bottom orientation and one left-to-right orientation. In other words, the component layout generated by the sub-layout must be completely on a side of the connector node which is orthogonal to the flow of the main hierarchic layout. If the sub-layout arranges the connector node somewhere in the middle of the component, then an integration of the connector into the main layout may lead to overlaps. This can be forced when using placement policy SUB_COMPONENT_PLACEMENT_POLICY_ALWAYS_INTEGRATED.

For components that are connected to a single node in the remaining graph, this policy supersedes layer and sequence constraints unless they directly constrain the placement of the connecting node in relation to the subcomponent.

See Also:

setPlacementPolicy(byte), Constant Field Values

Sample Graph:

One component can be placed integrated at the connector node but not both, since they have the same orientation (one above and one below would work)

Constructor Detail

SubcomponentDescriptor

public SubcomponentDescriptor()

Creates a new SubcomponentDescriptor instance with default settings.

SubcomponentDescriptor

public SubcomponentDescriptor(Layouter layoutAlgorithm)

Creates a new SubcomponentDescriptor instance with the specified layout algorithm.

Parameters:

layoutAlgorithm - The layout algorithm handling the layout of the graph induced by the subcomponent.

SubcomponentDescriptor

public SubcomponentDescriptor(byte placementPolicy,
                              Layouter layoutAlgorithm)

Creates a new SubcomponentDescriptor instance with the specified settings.

Parameters:

placementPolicy - The policy for placing the component into the layout context of the remaining graph.

layoutAlgorithm - The layout algorithm handling the layout of the graph induced by the subcomponent.

Method Detail

getLayoutAlgorithm

public Layouter getLayoutAlgorithm()

Returns the Layouter for the subgraph that is induced by the nodes associated with this descriptor.

Returns:

the Layouter handling the subgraph that is induced by the nodes associated with this descriptor.

See Also:

setLayoutAlgorithm(Layouter)

setLayoutAlgorithm

public void setLayoutAlgorithm(Layouter layoutAlgorithm)

Specifies the Layouter for the subgraph that is induced by the nodes associated with this descriptor.

It is possible to define another IncrementalHierarchicLayouter instance as layout algorithm responsible for the component. This way, different hierarchical layout styles can be conveniently combined into one layout (e.g. layouts with different orientations). The best layout results are achieved if a is connected to only a single other connector node. In that case this connector can be embedded in both the main layout and the inner layout. A condition for this is that the orientations of the two layouts are orthogonal with respect to each other, e.g., one top-to-bottom orientation and one left-to-right orientation.

Default Value:

The default value is null.

Parameters:

layoutAlgorithm - the Layouter handling the subgraph that is induced by the nodes associated with this descriptor.

Sample Graphs:

Subcomponent in tree layout

Subcomponent in hierarchic layout

Subcomponent in organic layout using a star substructure

getPlacementPolicy

public byte getPlacementPolicy()

Returns the policy defining how the subcomponent is placed within the layout context of the remaining graph.

Returns:

the policy defining how the subcomponent is placed within the layout context of the remaining graph.

See Also:

setPlacementPolicy(byte)

setPlacementPolicy

public void setPlacementPolicy(byte placementPolicy)

Specifies the policy defining how the subcomponent is placed within the layout context of the remaining graph.

Default Value:

The default value is SUB_COMPONENT_PLACEMENT_POLICY_AUTOMATIC. It is automatically determined how the subcomponent is placed.

Parameters:

placementPolicy - one of the predefined placement policies.

Throws:

java.lang.IllegalArgumentException - if an unknown placement policy is given.

getConnectorNode

public Node getConnectorNode(LayoutGraph graph)

Determines if there is a unique node outside the subcomponent whose removal would disconnect the component from the remaining graph and returns the node if it exists.

This convenience method can be used to determine if a subcomponent is a possible candidate for integrated placement when using the policies SUB_COMPONENT_PLACEMENT_POLICY_ALWAYS_INTEGRATED or SUB_COMPONENT_PLACEMENT_POLICY_AUTOMATIC.

Parameters:

graph - the graph containing the subcomponent.

Returns:

the only node outside the subcomponent with edges connecting to nodes within the subcomponent if such a node exists, null otherwise.