y.layout.hierarchic.incremental
Interface IncrementalHintsFactory

public interface IncrementalHintsFactory

This interface provides factory methods for creating incremental hints for the hierarchic layout.

Incremental hints can be used for specifying that a subset of nodes (called incremental nodes) should be added to an existing graph layout. A layer hint specifies that both, a node's layer and its position within the layer should be freely determined by the algorithm. A sequence hint specifies that the algorithm should consider the current layer of a node while its position within the layer should be freely determined by the algorithm. A node without any hint is called a fixed node.

Sequence hints can also be specified for edges. These incremental edges are inserted in a suitable position within the layers crossed by the edges. For fixed edges the given input route is considered to calculate the position with the layers.

Information about incremental hints is provided by a DataProvider registered with the graph with key IncrementalHierarchicLayouter.INCREMENTAL_HINTS_DPKEY.

An instance of a class implementing this interface can be obtained through method IncrementalHierarchicLayouter.createIncrementalHintsFactory().

Method Summary

java.lang.Object	createIncrementalGroupHint(java.lang.Object forItemId) Creates a hint Object for a group Node that should be inserted incrementally during the layering phase.
java.lang.Object	createLayerIncrementallyHint(java.lang.Object forNodeId) Creates a hint Object for a Node that should be inserted incrementally during the layering phase.
java.lang.Object	createSequenceIncrementallyHint(java.lang.Object forItemId) Creates a hint Object for a Node or Edge that should be inserted incrementally during the sequencing phase.
java.lang.Object	createUseExactCoordinatesHint(java.lang.Object forNodeId) Creates a hint Object for a Node that should be inserted incrementally into the graph on its exact current position.
java.lang.Object	createUseExactLayerCoordinatesHint(java.lang.Object forNodeId) Creates a hint Object for a Node that should be inserted incrementally into the graph on its exact current layer position.
java.lang.Object	createUseExactSequenceCoordinatesHint(java.lang.Object forNodeId) Creates a hint Object for a Node that should be inserted incrementally into the graph on its exact current sequence position.

Method Detail

createLayerIncrementallyHint

java.lang.Object createLayerIncrementallyHint(java.lang.Object forNodeId)

Creates a hint Object for a Node that should be inserted incrementally during the layering phase.

This will place the node in a suitable layer, possibly creating new layers.

Neighbors of this node may be also marked such that they are laid out incrementally. This makes it possible to incrementally add whole subgraphs to the current layout.

Parameters:

forNodeId - the node to be layered and sequenced incrementally

Returns:

an Object that can be interpreted as a hint by HierarchicLayouter

createSequenceIncrementallyHint

java.lang.Object createSequenceIncrementallyHint(java.lang.Object forItemId)

Creates a hint Object for a Node or Edge that should be inserted incrementally during the sequencing phase.

All nodes that are not incrementally inserted during the layering phase (see createLayerIncrementallyHint(Object)) stay in their current layer. More precisely, the default IncrementalHierarchicLayouter.getFixedElementsLayerer() implementation is an instance of AsIsLayerer that determines the layer of the "fixed" nodes by analyzing the current node coordinates. Note that for the other nodes, the layout algorithm may insert new layers in between the existing layers.

For edges associated with this hint (or which are incident to an incremental node), the algorithm automatically calculates a suitable sequencing (position within the layer). For edges between two non-incremental nodes that do not have a hint, the sequencing phase considers the current route.

Parameters:

forItemId - the node or edge to be sequenced/inserted incrementally

Returns:

an Object that can be interpreted as a hint by HierarchicLayouter

createIncrementalGroupHint

java.lang.Object createIncrementalGroupHint(java.lang.Object forItemId)

Creates a hint Object for a group Node that should be inserted incrementally during the layering phase.

The group will be placed on a suitable position. The descendants of the group may be associated with hints created by methods createLayerIncrementallyHint(Object), createSequenceIncrementallyHint(Object) or this method (if the descendant is an inner group).

All hints of the descendants of a group are interpreted relative to the group node. Descendants without hints maintain their relative order within the group node (but not with elements outside the group).

The positions of groups without incremental hints depend on the position of their descendants (i.e., the group is not interpreted as fixed - it is simply ignored).

If groups are incrementally inserted (especially larger ones), it can be a good idea to mark all edges in the graph as incremental too (including edges between fixed nodes). Otherwise, it can happen that the incremental group affects the layers through which a fixed edge is routed such that it is not clear where the edge should be with respect to the newly inserted incremental group and this can is some cases lead to routing artifacts.

Descendants of incremental groups must not be associated with exact coordinate hints (see method createUseExactCoordinatesHint(Object), createUseExactSequenceCoordinatesHint(Object) and createUseExactLayerCoordinatesHint(Object)).

Parameters:

forItemId - the group node to be inserted incrementally

Returns:

an Object that can be interpreted as a hint by HierarchicLayouter

createUseExactCoordinatesHint

java.lang.Object createUseExactCoordinatesHint(java.lang.Object forNodeId)

Creates a hint Object for a Node that should be inserted incrementally into the graph on its exact current position.

As for nodes without hints, the algorithm uses the IncrementalHierarchicLayouter.getFixedElementsLayerer() instance to determine the layer of such nodes and the IncrementalHierarchicLayouter.getFixedElementsSequencer() instance to determine the position within the layer. By default, both implementations use the current coordinates of the nodes to derive the layer/position. However, for nodes marked with this hint, the algorithm should also preserve the exact coordinates while for nodes without hints the coordinates may be changed (these nodes only keep their relative positions).

Using exact coordinate hints may lead to drawing artifacts like node overlaps and node-edge intersections.

Parameters:

forNodeId - the node to be placed on its exact current position

Returns:

an Object that can be interpreted as a hint by HierarchicLayouter

See Also:

createUseExactSequenceCoordinatesHint(Object), createUseExactLayerCoordinatesHint(Object), SimplexNodePlacer.setExactPlacementEnforced(boolean)

createUseExactLayerCoordinatesHint

java.lang.Object createUseExactLayerCoordinatesHint(java.lang.Object forNodeId)

Creates a hint Object for a Node that should be inserted incrementally into the graph on its exact current layer position.

The algorithm uses the IncrementalHierarchicLayouter.getFixedElementsLayerer() instance to determine the layer of such nodes and the IncrementalHierarchicLayouter.getFromScratchSequencer() instance to determine the sequencing.

Using exact coordinate hints may lead to drawing artifacts like node overlaps and node-edge intersections.

Parameters:

forNodeId - the node to be placed on its exact current layer position

Returns:

an Object that can be interpreted as a hint by HierarchicLayouter

See Also:

createUseExactCoordinatesHint(Object), createUseExactSequenceCoordinatesHint(Object), SimplexNodePlacer.setExactPlacementEnforced(boolean)

createUseExactSequenceCoordinatesHint

java.lang.Object createUseExactSequenceCoordinatesHint(java.lang.Object forNodeId)

Creates a hint Object for a Node that should be inserted incrementally into the graph on its exact current sequence position.

The algorithm uses the IncrementalHierarchicLayouter.getFromScratchLayerer() instance to determine the layer of such nodes and the IncrementalHierarchicLayouter.getFixedElementsSequencer() instance to determine the sequencing.

Using exact coordinate hints may lead to drawing artifacts like node overlaps and node-edge intersections.

Parameters:

forNodeId - the node to be placed on its exact current sequence position

Returns:

an Object that can be interpreted as a hint by HierarchicLayouter

See Also:

createUseExactCoordinatesHint(Object), createUseExactLayerCoordinatesHint(Object), SimplexNodePlacer.setExactPlacementEnforced(boolean)