ibm_ilog.graphlayout.hierarchical
Method Summary
- HierarchicalConstraint(priority) The abstract class 'HierarchicalConstraint' is the base class for constraints of the Hierarchical Layout.
- HierarchicalExtremityConstraint(a0, a1) The class 'ExtremityConstraint' is a constraint that forces the node to be placed at an extremal level, or at one of the extremal sides of a level.
- HierarchicalGroupSpreadConstraint(a0, a1) The class 'GroupSpreadConstraint' is a constraint that forces a group of nodes to be placed no more than a specified number of levels apart.
- HierarchicalLayout(a0) The main class for the Hierarchical Layout algorithm.
- HierarchicalLevelRangeConstraint(a0, a1, a2) The class 'LevelRangeConstraint' is a constraint that forces the node to be placed at a level with index within the specified range.
- HierarchicalNodeGroup(a0) The class 'NodeGroup' allows to create a group of nodes that is subject to a constraint.
- HierarchicalRelativeConstraint(a0, a1, a2) 'RelativeConstraint' is the base class of 'RelativeLevelConstraint' and 'RelativePositionConstraint'.
- HierarchicalRelativeLevelConstraint(a0, a1, a2) The class 'RelativeLevelConstraint' is a constraint to place a node relative to another node.
- HierarchicalRelativePositionConstraint(a0, a1, a2) The class 'RelativePositionConstraint' is a constraint to place a node relative to another node that belongs to the same level.
- HierarchicalSameLevelConstraint(a0, a1) The class 'SameLevelConstraint' is a constraint that forces two nodes to be placed at the same level.
- HierarchicalSideBySideConstraint(a0, a1) The class 'SideBySideConstraint' is a constraint that forces a group of nodes that belong to the same level to be placed side by side.
- HierarchicalSwimLaneConstraint(a0, a1, a2, a3, a4) The class 'SwimLaneConstraint' is a constraint that forces a group of nodes to be placed in the same column or row.
Attached Objects
Methods
The abstract class HierarchicalConstraint
is the base
class for constraints of the Hierarchical Layout.
Constraints can be used to influence the way the layout algorithms
partition the nodes into levels and order the nodes within the
levels.
Parameter | Type | Description |
---|---|---|
priority |
The class ExtremityConstraint
is a constraint that
forces the node to be placed at an extremal level, or at one of the
extremal sides of a level.
Nodes are organized in horizontal or vertical levels numbered from 0 to "n". The first level is the north pole level, and the last level is the south pole level. If the link flow direction is from top to bottom, the nodes with level index 0 are placed in the topmost level, and the nodes with higher level indexes are placed in the levels below. North is at the top and south is at the bottom of the drawing in this case. If the link flow direction is from left to right, the nodes with level index 0 are placed in the leftmost level, and the nodes with higher level indexes are placed in the levels farther to the right. North is at the left side and south is at the right side of the drawing in this case.
A north extremity constraint causes a node to be placed at level 0 (that is, at the top if the flow direction is top to bottom, or at the left if the flow direction is left to right), and all other nodes to be placed at a level with higher index. A south extremity constraint causes a node to be placed at the level with highest index (that is, at the bottom if the flow direction is top to bottom, or at the right if the flow direction is left to right), and all other nodes to be placed at a level with lower index. If for instance a south extremity constraint is specified for several nodes, these nodes are all placed at the same level with highest index.
Within each level, the nodes are placed sequentially from west to east at relative positions numbered from 0 to "m". If the link flow direction is from top to bottom, the node with position index 0 is placed leftmost within its level, and the nodes with higher position indexes are placed farther to the right. West is at the left side and east is at the right side of the drawing in this case. If the link flow direction is from left to right, the node with position index 0 is placed bottommost within its level, and the nodes with higher position indexes are placed above. West is at the bottom side and east is at the top side of the drawing in this case.
A west extremity constraint causes a node to be placed at position index 0, and an east extremity constraint causes a node to be placed at the highest position index of its level. Note that the east and west extremity constraint are local to each level: an node with east extremity constraint is not placed at the eastmost corner of the entire drawing, but only eastmost relative to its own level.
Of course, you should not specify level indexes for nodes additional to north or south extremity constraints, and you should not specify position indexes for nodes additional to east or west extremity constraints.
The constraint is evaluated, if the incremental mode is disabled. If the incremental mode is enabled, the constraint is only evaluated if the constraint node is marked for incremental recalculation, because otherwise, the incremental positions of the nodes are dominant.
In recursive layout mode (see
HierarchicalLayout.setRecursiveLayoutMode()
), the constraint
must be installed at the layout instance that is attached to the
subgraph the constrained node belongs to.
Parameter | Type | Description |
---|---|---|
a0 | ||
a1 |
The class GroupSpreadConstraint
is a constraint that
forces a group of nodes to be placed no more than a specified number
of levels apart.
Nodes are organized in horizontal or vertical levels numbered from 0 to "n". If the link flow direction is from top to bottom, the nodes with level index 0 are placed in the topmost level, and the nodes with higher level indexes are placed in the levels below. If the link flow direction is from left to right, the nodes with level index 0 are placed in the leftmost level, and the nodes with higher level indexes are placed in the levels farther to the right.
For instance, a constraint with spread size 2 forces the group to be placed such that the group node with smallest level index is no more than 2 levels apart from the group node with largest level index. All remaining nodes are placed in between. Assume that the group consists of the nodes A, B, and C. The group spread constraint is satisfied if the levels of A, B and C are 1, 2, 3. It is also satisfied if the levels of A, B and C are 10, 9, 8, or 10, 10, 12 or 10, 11, 11, or 10, 10, 10. But it is not satisfied if the levels of A, B and C are 10, 13, 12, because the highest node B is in this case more than 2 levels apart from the lowest node A.
The constraint is evaluated, if the incremental mode is disabled. If the incremental mode is enabled, the constraint is only evaluated if the nodes of the group are marked for incremental recalculation, because otherwise, the incremental positions of the nodes are dominant.
Among the constraints, this kind has the highest priority. If several conflicting constraints are specified (such as two nodes must be placed no more than 2 number of levels apart, but in level 1 and 10), the constraints with lower priority are ignored during layout.
The automatic conflict resolution can handle conflicting constraints. However, to speedup the layout, it is recommended to specify constraints in a way such that there are no conflicts.
The group spread constraint has the same priority as the same level constraint, because both cannot be conflicting. In fact, there are two ways of forcing two nodes to the same level: use the same level constraint, or use a group spread constraint of a group of two nodes with spread size 0.
In recursive layout mode (see
HierarchicalLayout.setRecursiveLayoutMode()
), all nodes of a
group spread constraint must belong to the same subgraph, and the
constraint must be installed at the layout instance that is attached
to this subgraph. It is not possible to have a group spread
constraint containing nodes of different subgraphs.
Parameter | Type | Description |
---|---|---|
a0 | ||
a1 |
The main class for the Hierarchical Layout algorithm.
The Hierarchical Layout arranges the nodes in horizontal or vertical levels such that the majority of the links point in the same direction and the number of link crossings is small.
Here is a sample drawing produced by the Hierarchical Layout algorithm with two levels of nodes that are top-justified within each level:
Another sample drawing with eight levels follows. This graph contains a cycle and a self-loop. The direction of the flow is from top to bottom. The nodes are organized in horizontal levels.
The Hierarchical Layout algorithm supports different styles of links in the same drawing. The following sample drawing shows orthogonal, straight, and polyline links. The direction of the flow is to the right and the node levels are vertical.
The Hierarchical Layout algorithm supports port specifications. The side and index of the port where a link connects to a node can be specified. The following sample drawing shows a drawing with port specifications and orthogonal link style. The direction of the flow is from top to bottom.
To simplify the explanations of the layout parameters, we use the compass directions north, south, east, and west. The first level of the layout is the north pole. If the flow direction is top to bottom, north is always upwards, south towards the bottom, west towards the left, and east towards the right side of the layout. If the flow direction is left to right, north is left and south is right.
See the corresponding chapter of the User's Manual for details on the algorithm, the types of graphs for which this algorithm can be used, the features and limitations, code samples, and so on.
Note the following points:
- The layout algorithm always takes into account the direction of links.
- The initial position of the nodes (at the moment you start the layout) does not affect the resulting layout.
- The algorithm supports self-links, cycles, and multiple links between the same pair of nodes.
Parameter | Type | Description |
---|---|---|
a0 |
The class LevelRangeConstraint
is a constraint that
forces the node to be placed at a level with index within the
specified range.
Nodes are organized in horizontal or vertical levels numbered from 0 to "n". If the link flow direction is from top to bottom, the nodes with level index 0 are placed in the topmost level, and the nodes with higher level indexes are placed in the levels below. If the link flow direction is from left to right, the nodes with level index 0 are placed in the leftmost level, and the nodes with higher level indexes are placed in the levels farther to the right.
For instance, a level range constraint with minimum index 5 and
maximum index 7 causes the node to be placed at level with index 5,
6, or 7. A level range with minimum index 6 and maximum index 6
causes the node to be placed exactly at level 6. This has the same
effect as specifying the node level index 6 by
HierarchicalLayout.setSpecNodeLevelIndex()
.
The constraint is evaluated, if the incremental mode is disabled. If the incremental mode is enabled, the constraint is only evaluated if the constraint node is marked for incremental recalculation, because otherwise, the incremental positions of the nodes are dominant.
This kind of constraint is dominated by same level constraints and group spread constraints, that is, two nodes cannot have different level ranges while being forced to the same level. The constraint has higher priority than any relative level constraints.
The automatic conflict resolution can handle conflicting constraints. However, to speedup the layout, it is recommended to specify constraints in a way such that there are no conflicts.
Note that empty levels are invisible after layout. For instance a node with level range constraint to be placed at level 2 may appear to be placed in the topmost level, if level 0 and 1 don't contain any other nodes.
In recursive layout mode (see HierarchicalLayout.setRecursiveLayoutMode()
), all nodes of the group of a level spread constraint must belong to the same subgraph, and the constraint must be installed at the layout instance that is attached to this subgraph. It is not possible to have a level spread constraint containing a group of nodes of different subgraphs.
Parameter | Type | Description |
---|---|---|
a0 | ||
a1 | ||
a2 |
The class NodeGroup
allows to create a group of nodes
that is subject to a constraint.
A node group itself is not a constraint. But some constraints allow node groups as input rather than single nodes. For instance, it is possible to force a group of nodes to be placed in a higher level than another group of nodes. Or it is possible to force all nodes of the group to be placed no more than a certain number of levels apart.
Parameter | Type | Description |
---|---|---|
a0 |
RelativeConstraint
is the base class of
RelativeLevelConstraint
and
RelativePositionConstraint
.
Both classes have common internal functionality.
Parameter | Type | Description |
---|---|---|
a0 | ||
a1 | ||
a2 |
The class RelativeLevelConstraint
is a constraint to
place a node relative to another node.
It forces a node to be placed at a level with higher index than
another node. The constraint can also be applied to groups of nodes.
Nodes are organized in horizontal or vertical levels numbered from 0 to "n". If the link flow direction is from top to bottom, the nodes with level index 0 are placed in the topmost level, and the nodes with higher level indexes are placed in the levels below. If the link flow direction is from left to right, the nodes with level index 0 are placed in the leftmost level, and the nodes with higher level indexes are placed in the levels farther to the right.
The constraint is evaluated, if the incremental mode is disabled. If the incremental mode is enabled, the constraint is only evaluated for those nodes that are marked for incremental recalculation, because otherwise, the incremental positions of the nodes are dominant.
Among the constraints, this kind is dominated by level range constraints, that is, if the level range for node A is below the level range of node B, then A cannot be forced to be placed in a higher level than B. This kind of constraint is also dominated by the same level constraints, that is, if both nodes A and B are forced to be at the same level, then A cannot be forced to be placed in a higher level than B.
The relative constraints have priorities. Conflicting relative level constraints are resolved by removing the constraint with the smallest priority. Relative level constraints also compete with the links of the graph. Each link acts like a constraint (with the same priority as the link) that forces that the target node is placed in a higher level than the source node.
The automatic conflict resolution can handle conflicting constraints. However, to speedup the layout, it is recommended to specify constraints in a way such that there are no conflicts.
In recursive layout mode (see
HierarchicalLayout.setRecursiveLayoutMode()
), both nodes of
the relative level constraint must belong to the same subgraph, and
the constraint must be installed at the layout instance that is
attached to this subgraph. It is not possible to have a relative
level constraint containing nodes of different subgraphs.
Parameter | Type | Description |
---|---|---|
a0 | ||
a1 | ||
a2 |
The class RelativePositionConstraint
is a constraint to
place a node relative to another node that belongs to the same level.
It does not affect the order of nodes that belong to different levels. It forces a node to be placed after another node within the same level. The constraint can also be applied to groups of nodes.
Nodes are organized in horizontal or vertical levels. Within each level, the nodes are placed sequentially at relative positions numbered from 0 to "n". If the link flow direction is from top to bottom, the node with position index 0 is placed leftmost within its level, and the nodes with higher position indexes are placed farther to the right. If the link flow direction is from right to left, the node with position index 0 is placed topmost within its level, and the nodes with higher position indexes are placed below. The constraint specifies that a node is placed at a higher position index than another node. The constraint is ignored, if both nodes do not belong to the same level.
The constraint is evaluated, if the incremental mode is disabled. If the incremental mode is enabled, the constraint is only evaluated for those nodes that are marked for incremental recalculation, because otherwise, the incremental positions of the nodes are dominant.
Among the constraints, this kind is dominated by side by side constraints, that is, if a node A and B must be placed side by side, then a node C cannot be forced to be at a higher position than A but at a lower position than B at the same time. The node C cannot be forced to be placed in between A and B. The constraint is also dominated by specified position indexes, i.e. it does not change the order of nodes that have specified position indexes, and by swim lane constraints, that is, it is not able to break swim lanes apart.
The relative constraints have priorities. Conflicting relative position constraints are resolved by removing the constraint with the smallest priority.
The automatic conflict resolution can handle conflicting constraints. However, to speed up the layout, it is recommended to specify constraints in a way such that there are no conflicts.
In recursive layout mode (see
HierarchicalLayout.setRecursiveLayoutMode()
), both nodes of
the relative position constraint must belong to the same subgraph,
and the constraint must be installed at the layout instance that is
attached to this subgraph. It is not possible to have a relative
position constraint containing nodes of different subgraphs.
Parameter | Type | Description |
---|---|---|
a0 | ||
a1 | ||
a2 |
The class SameLevelConstraint
is a constraint that
forces two nodes to be placed at the same level.
The constraint is evaluated, if the incremental mode is disabled. If the incremental mode is enabled, the constraint is only evaluated if at least one of the nodes is marked for incremental recalculation, because otherwise, the incremental positions of the nodes are dominant.
Among the constraints, this kind has the highest priority. If several conflicting constraints are specified (such as the node must be placed in a lower level than another node and at the same level as this other node), the constraints with lower priority are ignored during layout.
The automatic conflict resolution can handle conflicting constraints. However, to speedup the layout, it is recommended to specify constraints in a way such that there are no conflicts.
The same level constraint has the same priority as the group spread constraint, because both cannot be conflicting. In fact, there are two ways of forcing two nodes to the same level: use the same level constraint, or use a group spread constraint of a group of two nodes with spread size 0.
In recursive layout mode (see
HierarchicalLayout.setRecursiveLayoutMode()
), both nodes of
the same level constraint must belong to the same subgraph, and the
constraint must be installed at the layout instance that is attached
to this subgraph. It is not possible to have a same level constraint
containing nodes of different subgraphs.
Parameter | Type | Description |
---|---|---|
a0 | ||
a1 |
The class SideBySideConstraint
is a constraint that
forces a group of nodes that belong to the same level to be placed
side by side.
It prohibits that other nodes of the same level are placed in the
middle of the group. By this, the relative positions of the nodes of
the group are close together. It does not affect the order of nodes
that belong to different levels.
Nodes are organized in horizontal or vertical levels. Within each level, the nodes are placed sequentially at relative positions numbered from 0 to "n". The constraint specifies that those nodes of the group that belong to the same level are placed in subsequent positions within the level. The constraint is ignored, if all nodes of the group belong to different levels.
For instance, assume the group consists of nodes A, B, C, D, E. If A, B and C belong to one level and D and E to another level, then the side by side constraint forces the nodes A, B, C to be placed side by side, and D and E to be placed side by side. The constraint is satisfied if the positions of A, B, C are 5, 6, 7 and the positions of D and E are 1 and 2. The constraint affects only the nodes that belong to the same level, therefore the constraint affects the subgroup ( A, B, C ) and the subgroup ( D, E ) individually, not the entire group ( A, B, C, D, E ) as a unit. The constraint is not satisfied if the positions of A, B and C are 5, 7 and 8, because in this case, there must be a node between A and B that does not belong to the same group. The node between A and B cannot be D or E, because D and E belong to a different level.
The constraint is evaluated, if the incremental mode is disabled. If the incremental mode is enabled, the constraint is only evaluated if the nodes of the group are marked for incremental recalculation, because otherwise, the incremental positions of the nodes are dominant.
This kind of constraint dominates the relative position constraints. The constraints have priorities. If several conflicting constraints are specified (such as a node must be side by side to three different groups), the constraints with lower priority are ignored during layout. The constraint is dominated by specified position indexes, i.e. it does not change the order of nodes that have specified position indexes, and by swim lane constraints, that is, it is not able to break swim lanes apart.
The automatic conflict resolution can handle conflicting constraints. However, to speed up the layout, it is recommended to specify constraints in a way such that there are no conflicts.
In recursive layout mode (see
HierarchicalLayout.setRecursiveLayoutMode()
), all nodes of the
group of a side by side constraint must belong to the same subgraph,
and the constraint must be installed at the layout instance that is
attached to this subgraph. It is not possible to have a side by side
constraint containing a group of nodes of different subgraphs.
Parameter | Type | Description |
---|---|---|
a0 | ||
a1 |
The class SwimLaneConstraint
is a constraint that
forces a group of nodes to be placed in the same column or row.
Swim lanes are orthogonal to the levels. If the link flow direction
is towards bottom or top, the levels are horizontal rows and the swim
lanes are vertical columns. If the flow direction is towards left or
right, the levels are vertical columns and the swim lanes are
horizontal rows.
The nodes of the same swim lane are placed so that it is possible to draw a surrounding rectangle around them. Swim lanes allow to organize the graph in a table-like manner. For instance, you may have a workflow diagram where nodes represent actions, then the swim lanes could represent the departments that perform these actions. Each node can only belong to one swim lane.
A swim lane constraint is always evaluated, even if the incremental mode is enabled. The constraint has a higher priority than the relative position constraint and the side by side constraint. You can specify side by side constraints for a group of nodes that belong to the same swim lane, but side by side constraints of nodes of different swim lanes are ignored. You can specify relative position constraints between nodes of the same swim lane. You can also specify relative position constraints between one entire swimlane group and another swimlane group, which effectively orders the swimlanes. But relative position constraints are ignored if they would require to break the swimlanes apart. The swim lane constraint dominates the specified position indexes and the extremity constraints, i.e., if a swim lane constraint is used, you cannot specify position indexes or east/west extremity constraints for any node.
The automatic conflict resolution can handle conflicting constraints. However, to speedup the layout, it is recommended to specify constraints in a way such that there are no conflicts.
Swim lane constraints work in flat graphs. It is not possible to
spread a subgraph among multiple swim lanes. Swim lane constraints do
not work in recursive layout mode
HierarchicalLayout.setRecursiveLayoutMode()
.
Parameter | Type | Description |
---|---|---|
a0 | ||
a1 | ||
a2 | ||
a3 | ||
a4 |