Rogue Wave Views 5.6
Rogue Wave Views
Graph Layout Package API Reference Guide
Rogue Wave Views
Documentation Home
Rogue Wave Views 5.6 |
Rogue Wave Views |
Rogue Wave Views Documentation Home |
The main class for the Tree Layout algorithm. More...
#include <ilviews/layout/tree.h>
Public Member Functions | |
| IlvTreeLayout () | |
| Creates a new instance of the Tree Layout algorithm. More... | |
| virtual | ~IlvTreeLayout () |
Destroys this instance of class IlvTreeLayout. More... | |
| virtual void | cleanObjectProperties (IlAny nodeOrLink) |
Overridden version of the method cleanObjectProperties. More... | |
| virtual void | detach () |
| Detaches the graph model from the layout instance. More... | |
| IlvLayoutAlignment | getAlignment (IlAny node) const |
| Returns the local alignment style of the node. More... | |
| IlDouble | getAspectRatio () const |
| Returns the aspect ratio specified for the layout. More... | |
| IlvPos | getBranchOffset () const |
| Returns the minimal offset between neighbored nodes that belong to different branches in the tree. More... | |
| const IlList * | getCalcBackwardTreeLinks () const |
| Returns the backward links that were used in reverse direction as part of the spanning tree during layout. More... | |
| const IlList * | getCalcForwardTreeLinks () const |
| Returns the forward links that were used as part of the spanning tree during layout. More... | |
| const IlList * | getCalcNonTreeLinks () const |
| Returns the links that were neither forward nor backward links in the spanning tree during layout. More... | |
| const IlList * | getCalcRoots () const |
| Returns the list of nodes that were used as roots during layout. More... | |
| IlAny | getEastNeighbor (IlAny node) const |
Returns the specified east neighbor node of the input node, or null if none was specified. More... | |
| IlvDirection | getFlowDirection () const |
| Returns the current direction of the flow. More... | |
| IlvLayoutAlignment | getGlobalAlignment () const |
| Returns the global alignment style. More... | |
| IlvLayoutLinkStyle | getGlobalLinkStyle () const |
| Returns the global style of the shapes of links. More... | |
| IlvTreeLayoutMode | getLayoutMode () const |
| Returns the current layout mode. More... | |
| IlvLayoutAlignment | getLevelJustification () const |
| Returns the current justification within the levels. More... | |
| IlvLayoutLinkStyle | getLinkStyle (IlAny link) const |
| Returns the style of the shape of an individual link. More... | |
| IlInt | getMaxChildrenAngle () const |
| Returns the maximal angle for children that are placed in radial mode. More... | |
| IlInt | getOrthForkPercentage () const |
| Returns the percentage of the parent child offset that determines the location where the orthogonal link routing places the bends in order to fork the routing towards the children. More... | |
| IlInt | getOverlapPercentage () const |
| Returns the percentage a node is considered smaller in the flow direction. More... | |
| IlvPos | getParentChildOffset () const |
| Returns the minimal offset between a parent and its children. More... | |
| const IlvPoint * | getPosition () const |
Returns the specified position of the layout, or null if there was never a position specified. More... | |
| IlInt | getRootPreference (IlAny node) const |
| Returns the specified preference of the node to become root node. More... | |
| IlvPos | getSiblingOffset () const |
| Returns the minimal offset between siblings. More... | |
| const IlList * | getSpecRoots () const |
| Returns the list of nodes that were specified as root. More... | |
| IlvPos | getTipOverBranchOffset () const |
| Returns the minimal offset in the flow direction between neighbored nodes that belong to different branches in the tree. More... | |
| IlAny | getWestNeighbor (IlAny node) const |
Returns the specified west neighbor node of the input node, or null if none was specified. More... | |
| IlBoolean | isCategorizingLinks () const |
Returns IlTrue if the layout algorithm stores the categorization of links into forward, backward, and non-tree links. More... | |
| IlBoolean | isRootPosition () const |
Returns IlTrue if the specified position means the position of the root node; otherwise it means the position of the top left border of the layout. More... | |
| void | setAlignment (IlAny node, IlvLayoutAlignment alignment) |
| Sets the alignment style of an individual node. More... | |
| void | setAspectRatio (IlDouble aspectRatio) |
| Sets the aspect ratio for the layout. More... | |
| void | setAspectRatio (const IlvRect &rect) |
| Sets the aspect ratio for the layout from a given rectangle. More... | |
| void | setAspectRatio (const IlvAbstractView *view) |
| Sets the aspect ratio for the layout from a given view. More... | |
| void | setBranchOffset (IlvPos offset) |
| Sets the minimal offset between neighbored nodes that belong to different branches in the tree. More... | |
| void | setCategorizingLinks (IlBoolean flag) |
| Sets whether the layout algorithm stores the categorization of links into forward, backward, and non-tree links. More... | |
| void | setEastWestNeighboring (IlAny eastNode, IlAny westNode) |
| Creates an east-west neighboring of two nodes. More... | |
| void | setFlowDirection (IlvDirection direction) |
| Sets the direction of the flow. More... | |
| void | setGlobalAlignment (IlvLayoutAlignment alignment) |
| Sets the global alignment style. More... | |
| void | setGlobalLinkStyle (IlvLayoutLinkStyle style) |
| Indicates that this layout class is able to determine the percentage of completion during the run of layout. More... | |
| void | setLayoutMode (IlvTreeLayoutMode mode) |
| Sets the layout mode. More... | |
| void | setLevelJustification (IlvLayoutAlignment justification) |
| Sets the justification within the levels. More... | |
| void | setLinkStyle (IlAny link, IlvLayoutLinkStyle style) |
| Sets the style of the shape of an individual link. More... | |
| void | setMaxChildrenAngle (IlInt angle) |
| Sets the maximal angle for children that are placed in radial mode. More... | |
| void | setOrthForkPercentage (IlInt percentage) |
| Sets the percentage of the parent child offset that determines the location where the orthogonal link routing places the bends in order to fork the routing towards the children. More... | |
| void | setOverlapPercentage (IlInt percentage) |
| Sets the percentage a node is considered smaller in the flow direction. More... | |
| void | setParentChildOffset (IlvPos offset) |
| Sets the minimal offset between a parent and its children. More... | |
| void | setPosition (const IlvPoint &point, IlBoolean isRootPosition) |
| Sets the position of the layout. More... | |
| void | setRoot (IlAny node) |
| Allows you to specify the root(s) of the tree. More... | |
| void | setRootPreference (IlAny node, IlInt preference) |
| Specifies the preference of the node to become root node. More... | |
| void | setSiblingOffset (IlvPos offset) |
| Sets the minimal offset between siblings, that is between nodes that have the same parent in the tree structure. More... | |
| void | setTipOverBranchOffset (IlvPos offset) |
| Sets the minimal offset in the flow direction between neighbored nodes that belong to different branches in the tree. More... | |
| void | setWestEastNeighboring (IlAny westNode, IlAny eastNode) |
| Creates an east-west neighboring of two nodes. More... | |
| IlBoolean | supportsAllowedTime () const |
| Indicates that this layout class can stop the layout computation in a proper manner when the user-defined allowed time is exceeded. More... | |
| IlBoolean | supportsPreserveFixedLinks () const |
| Indicates that this layout class allows the user to specify fixed links. More... | |
| IlBoolean | supportsPreserveFixedNodes () const |
| Indicates that this layout class allows the user to specify fixed nodes. More... | |
 Public Member Functions inherited from IlvGraphLayout | |
| IlvGraphLayout () | |
| Constructor. | |
| virtual void | attach (IlvGrapher *grapher) |
| Allows you to specify the grapher you want to lay out. More... | |
| virtual void | attach (IlvGraphModel *graphModel) |
| Allows you to specify the graph model you want to lay out. More... | |
| virtual IlvRunTimeType | getAllowedTime () const |
| Returns the currently allowed time for the layout algorithm in milliseconds. More... | |
| IlvMgrView * | getFirstManagerView () const |
Returns the first manager view attached to the graph model if any, and 0 otherwise. | |
| IlvGrapher * | getGrapher () const |
| Returns the grapher to lay out. More... | |
| IlvGraphModel * | getGraphModel () const |
| Returns the graph model to lay out if a graph model is attached. More... | |
| IlUInt | getInstanceId () const |
| A utility method that returns a unique integer value for each layout instance inside the same program. | |
| void | getLayoutRegion (IlvRect &rect) const |
| Updates the rectangle rect passed as argument with the region that the drawing of the graph model must fit (exactly or approximately). More... | |
| IlvGraphLayoutReport * | getLayoutReport () const |
| Returns the layout report, that is, an object containing information about the behavior of the layout algorithm for the previous run of layout. More... | |
| virtual IlUShort | getSeedValueForRandomGenerator () |
| Returns the user-defined seed value for the random generator. More... | |
| IlBoolean | isAnimate () const |
Returns IlTrue if the layout can perform a redraw of the graph model after each iteration or step of the layout algorithm. More... | |
| IlBoolean | isFitToView () const |
Returns IlTrue if the size of the graph drawing must fit (exactly or approximately) the size of a given manager view. More... | |
| IlBoolean | isFixed (IlAny nodeOrLink) const |
Returns IlTrue if the node or link nodeOrLink is specified as fixed. More... | |
| IlBoolean | isGeometryUpToDate () const |
Returns IlFalse if at least one node or link was moved or reshaped since the last time the layout was successfully performed on the same graph model or if the layout has never been performed successfully on the same graph model. More... | |
| IlBoolean | isIlvGrapherAttached () const |
| Convenience method. More... | |
| IlBoolean | isLayoutRunning () const |
| Specifies whether the layout algorithm is running. More... | |
| virtual IlBoolean | isLayoutTimeElapsed () const |
Returns IlTrue if, at the moment the method is called, the allowed layout time is exceeded; returns IlFalse otherwise. More... | |
| IlBoolean | isLinkConnectorReplacementAllowed () const |
Returns IlTrue if the replacement of the link connectors is allowed. More... | |
| virtual IlBoolean | isLinkReplacementAllowed () const |
Returns IlTrue if the replacement of the links is allowed. More... | |
| virtual IlBoolean | isMemorySavings () const |
| Returns the current setting specifying whether priority is given to speed or memory usage. | |
| virtual IlBoolean | isParametersUpToDate () const |
Returns IlFalse if at least one parameter was modified since the last time the layout was successfully performed on the same graph or if the layout has never been performed successfully on the same graph. More... | |
| virtual IlBoolean | isPreserveFixedLinks () const |
Returns IlTrue if the layout is not allowed to reshape the links indicated as fixed by the user. More... | |
| virtual IlBoolean | isPreserveFixedNodes () const |
Returns IlTrue if the layout is not allowed to move the nodes indicated as fixed by the user. More... | |
| IlBoolean | isStructureUpToDate () const |
| Indicates whether the graph model structure has been modified since the last layout was performed. More... | |
| virtual IlBoolean | isUseDefaultParameters () const |
| Returns the current options for the parameters. More... | |
| virtual IlBoolean | isUseSeedValueForRandomGenerator () |
Returns IlTrue if the user-defined seed value is used for the random generator and IlFalse otherwise. More... | |
| void | layoutRunning (IlBoolean) |
Updates the field _isLayoutRunning. | |
| virtual void | layoutStepPerformed () |
| This method can be called by the layout classes when a step (or iteration) of the layout algorithm has been performed. More... | |
| IlvGraphLayoutReport * | performLayout () |
| Starts the layout algorithm using the currently attached graph model and the current settings for the layout parameters. More... | |
| void | setAllowedTime (IlvRunTimeType time) |
| Allows you to specify an upper bound for the duration of the layout algorithm. More... | |
| void | setAnimate (IlBoolean arg) |
If arg is IlTrue, all manager views attached to the graph model are redrawn after each iteration or step of the layout algorithm. More... | |
| virtual void | setFixed (IlAny nodeOrLink, IlBoolean val) |
| Allows you to specify whether a node or a link is fixed. More... | |
| void | setGeometryUpToDate (IlBoolean) |
If the argument is IlFalse, notifies the layout instance that the geometry of the graph was changed since the last time the layout was successfully performed. More... | |
| void | setGrapher (IlvGrapher *grapher) |
| Allows you to specify the grapher you want to lay out. More... | |
| void | setLayoutRegion (IlvMgrView *view) |
| Allows you to specify that the size of the graph drawing must fit (exactly or approximately) the size of a given manager view. More... | |
| void | setLayoutRegion (IlvMgrView *view, const IlvRect &rect) |
| Allows you to specify a region (the rectangle rect) that the layout must fit (exactly or approximately) with the dimensions of the rectangle rect being given in the manager view coordinates. More... | |
| void | setLayoutRegion (const IlvRect &rect) |
| Allows you to specify a rectangle that the layout must fit (exactly or approximately). More... | |
| void | setLinkConnectorReplacementAllowed (IlBoolean allow) |
| Enables or disables the link connector replacement. More... | |
| virtual void | setLinkReplacementAllowed (IlBoolean) |
| Enables or disables the link replacement. More... | |
| virtual void | setMemorySavings (IlBoolean arg) |
If arg is IlTrue, the layout algorithm uses the implementation that consumes less memory. More... | |
| void | setParametersUpToDate (IlBoolean) |
If the argument is IlFalse, notifies the layout instance that a parameter value was changed. More... | |
| virtual void | setPreserveFixedLinks (IlBoolean arg) |
If arg is IlTrue, the layout is not allowed to reshape the links indicated as fixed by the user. More... | |
| virtual void | setPreserveFixedNodes (IlBoolean arg) |
If the argument is IlTrue, the layout is not allowed to move the nodes indicated as fixed by the user. More... | |
| virtual void | setSeedValueForRandomGenerator (IlUShort seedValue) |
| Allows you to specify a seed value for the random generator. More... | |
| void | setStructureUpToDate (IlBoolean) |
If the argument is IlFalse, notifies the layout instance that the structure of the graph was changed since the last time the layout was successfully performed. More... | |
| virtual void | setUseDefaultParameters (IlBoolean arg) |
If the argument is IlTrue, the layout uses the default values of all the parameters, that is, the "get..." and "is..." methods return the default values. More... | |
| virtual void | setUseSeedValueForRandomGenerator (IlBoolean) |
| Allows you to specify whether the user-defined seed value should be used for the random generator. More... | |
| virtual IlBoolean | supportsAnimation () const |
| Indicates whether the layout class performs a redraw of the graph model after each step or iteration. More... | |
| virtual IlBoolean | supportsLayoutRegion () const |
| Indicates whether the layout class can control the size of the graph drawing to fit (exactly or approximately) a user-defined region (a rectangle) or a user-defined manager view. More... | |
| virtual IlBoolean | supportsMemorySavings () const |
| Indicates whether the layout class can perform the layout using two partially different implementations. More... | |
| virtual IlBoolean | supportsRandomGenerator () const |
| Indicates whether the layout class uses randomly-generated numbers (or randomly-chosen parameters) for which it can accept a user-defined seed value. More... | |
| void | unfixAllLinks () |
| Removes the fixed attributes from all links in the graph model. More... | |
| void | unfixAllNodes () |
| Removes the fixed attribute from all nodes in the graph model. More... | |
Protected Member Functions | |
| virtual void | layout () |
| Computes the layout using the Tree Layout algorithm. More... | |
| Protected Member Functions inherited from IlvGraphLayout | |
| virtual IlvGraphLayoutReport * | createLayoutReport () |
| Returns a new instance of the layout report. More... | |
| virtual IlBoolean | isLayoutNeeded () const |
| Verifies that it is necessary to perform the layout. More... | |
The main class for the Tree Layout algorithm.
Library: ilvtree
The Tree Layout places the nodes of a tree starting from the root of the tree to the leaves. If the graph has parts that are disconnected, it arranges each connected component as an individual tree. The Tree Layout algorithm is primarily designed for a forest of pure trees. In a tree, each node except the root has a parent node. All the nodes that have the same parent are called children with respect to the parent and sibling among themselves. The Tree Layout algorithm can also be used for non-trees, for example cyclic graphs. In this case, the layout algorithm ignores those links that violate the tree structure and takes only the spanning tree of the graph into account.
The algorithm has several layout modes:
To simplify the explanations of the layout parameters, we use the compass directions north, south, east, and west. We consider the center of the root node of a tree to be the north pole. If the root node is placed at the top border, then north is always upwards, south towards the bottom, west towards the left, and east towards the right side of the layout. If the root node is placed at the left border, then north is left and south is right. In radial mode, the root is placed in the center, hence the notation of north and south depends on where a node is placed relative to the root: the north side of any node is the side that is closer to the root, and the south side is the side that is further away from the root.
Several alignment options are provided. In particular, the free layout mode allows the tip over alignment, which means that subtrees are arranged serial instead of parallel: if the subtrees starting at one node are normally arranged horizontally, then the tip over alignment arranges them vertically. The tree layout provides layout modes that automatically adapt the tip over alignment to fit the layout best to a given aspect ratio.
Two sample drawings produced by the Tree Layout algorithm. The left drawing uses the level layout mode. The flow direction of the links is towards the bottom, and the nodes are south justified (means here: at the bottom) within each level. The right drawing is the same tree in free layout mode (which uses always north justification):
Another sample drawing in free layout mode with tip over alignment at some leaf nodes:
Two sample drawings in the two radial layout modes. The normal radial mode in the left drawing places the nodes of the same level on a circle around the root node. The alternating radial mode in the right drawing places the nodes of the same level alternating on two circles around the root node. This results in a better space usage.
In non-radial layout modes, the Tree Layout algorithm supports different styles of links in the same drawing. The following sample drawing shows orthogonal and straight line links. It also shows nodes that are aligned at the center (see the red nodes), at the east (green), and at the west (blue) of their children. The drawing was created by the free layout mode with link flow direction to the right, hence north is to the left.
The Tree Layout algorithm also supports node neighboring in all modes. The following sample drawing shows a tree layout with flow direction towards the top. Some nodes are not placed as children but rather as neighbors at the same level as the corresponding parent node. The red links, which are perpendicular to the flow direction, are between nodes that were specified as neighbored.
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:
| IlvTreeLayout::IlvTreeLayout | ( | ) |
Creates a new instance of the Tree Layout algorithm.
To indicate the grapher you want to lay out, use the method attach(IlvGrapher).
To indicate the graph model you want to lay out, use the method attach(IlvGraphModel).
To perform the layout, use the method performLayout().
To modify the layout parameters, use the different methods provided in this class and its superclass.
|
virtual |
Destroys this instance of class IlvTreeLayout.
If necessary, it detaches this instance from the graph model or the grapher, respectively, before destroying this layout instance.
detach()
|
virtual |
Overridden version of the method cleanObjectProperties.
Reimplemented from IlvGraphLayout.
|
virtual |
Detaches the graph model from the layout instance.
When you attach a new graph model to the layout instance, it is not necessary to detach the old graph model because this is done automatically when you call attach. The detach() method performs cleaning operations on the graph model or the grapher. In addition to the cleaning operations in the base class, Tree Layout removes the alignment and root preference specifications of individual nodes, the node neighboring specifications, and the link style specifications of individual links.
IlvGraphLayout::attach(IlvGrapher*) IlvGraphLayout::attach(IlvGraphModel*) setAlignment(IlAny, IlvLayoutAlignment) setRootPreference(IlAny, IlInt) setLinkStyle(IlAny, IlvLayoutLinkStyle) setEastWestNeighboring(IlAny, IlAny) Reimplemented from IlvGraphLayout.
| IlvLayoutAlignment IlvTreeLayout::getAlignment | ( | IlAny | node | ) | const |
Returns the local alignment style of the node.
| node | A node of the attached grapher or graph model. |
| IlDouble IlvTreeLayout::getAspectRatio | ( | ) | const |
Returns the aspect ratio specified for the layout.
This is the ratio width / height of the desired layout region.
| IlvPos IlvTreeLayout::getBranchOffset | ( | ) | const |
Returns the minimal offset between neighbored nodes that belong to different branches in the tree.
This is the offset between neighbored nodes that are not siblings. The offset is in the opposite direction to the link flow.
| const IlList* IlvTreeLayout::getCalcBackwardTreeLinks | ( | ) | const |
Returns the backward links that were used in reverse direction as part of the spanning tree during layout.
This can be called after layout, if the link categorization option was set to IlTrue before layout by using the method setCategorizingLinks.
The backward tree links have the property that the "to" node is the parent of the "from" node in the tree layout. These links are reshaped by the layout algorithm.
If the graph was not a tree, some links will not be part of the spanning tree that forms the base structure for the layout. These links are not part of this list. Also, the links that do not need to be reversed but form the spanning tree are not part of this list.
null if the link categorization option was switched off during the last run of layout. | const IlList* IlvTreeLayout::getCalcForwardTreeLinks | ( | ) | const |
Returns the forward links that were used as part of the spanning tree during layout.
This can be called after layout, if the link categorization option was set to IlTrue before layout by using the method setCategorizingLinks.
The forward tree links have the property that the "from" node is the parent of the "to" node in the tree layout. These links are reshaped by the layout algorithm.
If the graph was not a tree, some links will not be part of the spanning tree that forms the base structure for the layout. If the graph was not a directed tree, some links need to be reversed to form the spanning tree. These links are not part of this list.
null if the link categorization option was switched off during the last run of layout. | const IlList* IlvTreeLayout::getCalcNonTreeLinks | ( | ) | const |
Returns the links that were neither forward nor backward links in the spanning tree during layout.
This can be called after layout, if the link categorization option was set to IlTrue before layout by using the method setCategorizingLinks.
The non-tree tree links have the property that neither the "from" node is the parent of the "to" node nor the "to" node is the parent of the "from" node in the tree layout. These links are not reshaped by the layout algorithm.
If the graph was not a tree, some links will not be part of the spanning tree that forms the base structure for the layout. Only these links are part of this list. If necessary, they can be treated by a link routing layout algorithm after the tree layout (for example, by IlvOrthogonalLinkLayout).
null if the link categorization option was switched off during the last run of layout. | const IlList* IlvTreeLayout::getCalcRoots | ( | ) | const |
Returns the list of nodes that were used as roots during layout.
This can be called after layout. If there are more than one connected components, each component has a root. If no root was specified, the layout algorithm automatically selects an appropriate node. If too many roots were specified, some specified roots will not become calculated roots during layout.
Returns the specified east neighbor node of the input node, or null if none was specified.
| node | A node of the attached grapher or graph model. |
| IlvDirection IlvTreeLayout::getFlowDirection | ( | ) | const |
Returns the current direction of the flow.
setFlowDirection(IlvDirection) | IlvLayoutAlignment IlvTreeLayout::getGlobalAlignment | ( | ) | const |
Returns the global alignment style.
| IlvLayoutLinkStyle IlvTreeLayout::getGlobalLinkStyle | ( | ) | const |
Returns the global style of the shapes of links.
| IlvTreeLayoutMode IlvTreeLayout::getLayoutMode | ( | ) | const |
| IlvLayoutAlignment IlvTreeLayout::getLevelJustification | ( | ) | const |
Returns the current justification within the levels.
| IlvLayoutLinkStyle IlvTreeLayout::getLinkStyle | ( | IlAny | link | ) | const |
Returns the style of the shape of an individual link.
| link | A link of the attached grapher or graph model. |
| IlInt IlvTreeLayout::getMaxChildrenAngle | ( | ) | const |
Returns the maximal angle for children that are placed in radial mode.
setMaxChildrenAngle(IlInt) | IlInt IlvTreeLayout::getOrthForkPercentage | ( | ) | const |
Returns the percentage of the parent child offset that determines the location where the orthogonal link routing places the bends in order to fork the routing towards the children.
setOrthForkPercentage | IlInt IlvTreeLayout::getOverlapPercentage | ( | ) | const |
Returns the percentage a node is considered smaller in the flow direction.
setOverlapPercentage(IlInt) | IlvPos IlvTreeLayout::getParentChildOffset | ( | ) | const |
Returns the minimal offset between a parent and its children.
setParentChildOffset(IlvPos) | const IlvPoint* IlvTreeLayout::getPosition | ( | ) | const |
Returns the specified position of the layout, or null if there was never a position specified.
null if there was never a position specified. Otherwise the specified position of the layout. setPosition(IlvPoint*, IlBoolean) isRootPosition() setRoot(IlAny) Returns the specified preference of the node to become root node.
The higher the preference, the more likely the node will be selected as root node. If no preference was specified for the node, it returns -1.
| node | A node of the attached grapher or graph model. |
| IlvPos IlvTreeLayout::getSiblingOffset | ( | ) | const |
Returns the minimal offset between siblings.
setSiblingOffset(IlvPos) | const IlList* IlvTreeLayout::getSpecRoots | ( | ) | const |
Returns the list of nodes that were specified as root.
Note that this does not necessarily mean that these nodes are selected as real roots, because the specification may have conflicts (for example, each connected component can only have one root, thus specifying two roots for the same connected component causes a conflict). In order to retrieve the nodes that were really used as roots during the layout, call the method getCalcRoots().
| IlvPos IlvTreeLayout::getTipOverBranchOffset | ( | ) | const |
Returns the minimal offset in the flow direction between neighbored nodes that belong to different branches in the tree.
This offset is used to separate the branches if their common parent node has tip over alignment.
Returns the specified west neighbor node of the input node, or null if none was specified.
| node | A node of the attached grapher or graph model. |
| IlBoolean IlvTreeLayout::isCategorizingLinks | ( | ) | const |
Returns IlTrue if the layout algorithm stores the categorization of links into forward, backward, and non-tree links.
Note that a run of layout is necessary to make the categorization available. Even if this method returns IlTrue, the methods getCalcForwardTreeLinks, getCalcBackwardTreeLinks, and getCalcNonTreeLinks return null if there was no run of layout.
IlTrue if link categorization should be done during the next run of layout. setCategorizingLinks(IlBoolean) | IlBoolean IlvTreeLayout::isRootPosition | ( | ) | const |
Returns IlTrue if the specified position means the position of the root node; otherwise it means the position of the top left border of the layout.
IlTrue if the specified position is the root node position.
|
protectedvirtual |
Computes the layout using the Tree Layout algorithm.
To start the layout, call the method performLayout().
IlvGraphLayout::performLayout() Implements IlvGraphLayout.
| void IlvTreeLayout::setAlignment | ( | IlAny | node, |
| IlvLayoutAlignment | alignment | ||
| ) |
Sets the alignment style of an individual node.
This alignment style is only used if the global alignment is set to IlvLayoutMixedAlignment. Otherwise all nodes have the alignment style that is specified as the global alignment style.
Valid values are:
IlvLayoutCenterAlignment - The node is centered with respect to the centers of its children. IlvLayoutBorderCenterAlignment - The node is centered with respect to the border of its children. IlvLayoutEastAlignment - The node is aligned with the border of its easternmost child. IlvLayoutWestAlignment - The node is aligned with the border of its westernmost child. IlvLayoutTipOverAlignment - A parent is outside the border of the children, while the children are placed sequential instead of parallel. The default value is IlvLayoutCenterAlignment.
| node | A node of the attached grapher or graph model. |
| alignment | The alignment style of this node. |
setGlobalAlignment(IlvLayoutAlignment) getAlignment(IlAny) | void IlvTreeLayout::setAspectRatio | ( | IlDouble | aspectRatio | ) |
Sets the aspect ratio for the layout.
This is the ratio width / height of the desired layout region.
The effect of the aspect ratio depends on the layout mode:
IlvTreeLayoutRadialMode and IlvTreeLayoutAlternatingRadialMode, the nodes are placed in circular layers if the aspect ratio is 1, otherwise in elliptic layers. IlvTreeLayoutTipOverMode, IlvTreeLayoutTipRootsOverMode, IlvTreeLayoutTipLeavesOverMode, and IlvTreeLayoutTipRootsAndLeavesOverMode, the nodes are placed as in in free mode, but local tip-over alignments are automatically added to fit the layout better to the aspect ratio. | aspectRatio | The desired aspect ratio. |
| void IlvTreeLayout::setAspectRatio | ( | const IlvRect & | rect | ) |
Sets the aspect ratio for the layout from a given rectangle.
This can be useful if the graph contains just one single tree and should be fit into the input rectangle.
| rect | The rectangle to fit the graph into. |
| void IlvTreeLayout::setAspectRatio | ( | const IlvAbstractView * | view | ) |
Sets the aspect ratio for the layout from a given view.
This can be useful if the graph contains just one single tree and should be fit into the visible area of the input view.
| view | The view to display the graph. |
| void IlvTreeLayout::setBranchOffset | ( | IlvPos | offset | ) |
Sets the minimal offset between neighbored nodes that belong to different branches in the tree.
This is the offset between neighbored nodes that are not siblings. The offset is in the opposite direction to the link flow.
If the flow direction is towards the top or bottom and the layout mode is not radial, this is a horizontal offset. If the flow direction is towards the left or right and the layout mode is not radial, this is a vertical offset. If the layout mode is radial, this is an offset tangential to the circles or ellipses.
The default value is 40.
| offset | The offset between tree branches. |
| void IlvTreeLayout::setCategorizingLinks | ( | IlBoolean | flag | ) |
Sets whether the layout algorithm stores the categorization of links into forward, backward, and non-tree links.
If passed IlTrue, the next run of the layout algorithm makes the link categorization available by the methods getCalcForwardTreeLinks, getCalcBackwardTreeLinks, and getCalcNonTreeLinks. If passed IlFalse, the link categorization is not made available, which saves memory and is faster. In this case, the methods getCalcForwardTreeLinks, getCalcBackwardTreeLinks, and getCalcNonTreeLinks will return null.
The default value is IlFalse.
| flag | Whether link categorization should be done during the next run of layout. |
isCategorizingLinks() Creates an east-west neighboring of two nodes.
The westNode is placed as first neighbor at the same level to the west of the eastNode. This implies conversely that the eastNode is the first neighbor at the same level to the east of the westNode.
For instance in free layout mode and flow direction towards the bottom, the east node is placed as immediate neighbor at the right side of the west node at approximately the same y coordinate. A link between both nodes is routed as a straight horizontal line between both nodes. In radial layout mode, the east node is placed as immediate neighbor in the same circle as the west node. A link between both nodes is routed tangential to the node circle as a straight line.
Note that each node can have at most one east neighbor and one west neighbor. Children of tip over alignments have for technical reasons special area requirements, therefore they can have a west neighbor but no east neighbor. This means that if the parent node of the westNode has tip over alignment, the east-west neighboring is ignored.
East west neighboring is possible even though there is no link between both nodes. The layout algorithm considers both nodes as if they were conceptually connected by a link.
| eastNode | The east neighbor of the westNode. |
| westNode | The west neighbor of the eastNode. |
getEastNeighbor() getWestNeighbor() | void IlvTreeLayout::setFlowDirection | ( | IlvDirection | direction | ) |
Sets the direction of the flow.
Valid values are:
IlvRight - The root is at the left and the links flow to the right. IlvLeft - The root is at the right and the links flow to the left. IlvBottom - The root is at the top and the links flow to the bottom. IlvTop - The root is at the bottom and the links flow to the top. IlvLayoutSouthAlignment) is identical to the flow direction.In the radial layout modes, all links flow radially from the center of the root outwards. In this case, the flow direction influences the placement of disconnected trees only.
The default value is IlvRight.
| flowDirection | The direction of the flow. |
| void IlvTreeLayout::setGlobalAlignment | ( | IlvLayoutAlignment | alignment | ) |
Sets the global alignment style.
Valid values are:
IlvLayoutCenterAlignment - A parent is centered over its children, taking the center of the children into account. IlvLayoutBorderCenterAlignment - A parent is centered over its children, taking the border of the children into account. IlvLayoutEastAlignment - A parent is aligned with the border of its easternmost child. IlvLayoutWestAlignment - A parent is aligned with the border of its westernmost child. IlvLayoutTipOverAlignment - A parent is outside the border of the children, while the children are placed sequential instead of parallel. This alignment style is not possible in the radial or level layout modes. IlvLayoutMixedAlignment - Each node can have a different alignment option. In this case, the alignment of each individual node can be set by the method setAlignment(IlAny, IlvLayoutAlignment), such that different alignments can occur in the same graph. The default value is IlvLayoutCenterAlignment.
| alignment | The global alignment style. |
| void IlvTreeLayout::setGlobalLinkStyle | ( | IlvLayoutLinkStyle | style | ) |
Indicates that this layout class is able to determine the percentage of completion during the run of layout.
IlTrue. increasePercentageComplete IlvGraphLayoutReport::getPercentageComplete Sets the global style of the shapes of links.Valid values are:
IlvLayoutOrthogonalLinkStyle - All links get an orthogonal shape, that is, a shape consisting of a sequence of orthogonal line segments. This option is not available for the radial layout modes. IlvLayoutStraightLineLinkStyle - All links get a straight-line shape. IlvLayoutNoReshapeLinkStyle - No reshape is performed on any link. IlvLayoutMixedLinkStyle - Each link can have a different link style. In this case, the style of each individual link can be set by the method setLinkStyle(IlAny, IlvLayoutLinkStyle), such that different link shapes can occur in the same graph. This feature can be useful if the graph contains links that can have intermediate points and are not straight-line links, for instance links of type IlvPolylineLinkImage. Unless the global link style is IlvLayoutMixedLinkStyle, all links have the same style of shape.
The default value is IlvLayoutStraightLineLinkStyle.
Note that, when the graph attached to the layout is of type IlvGrapher, the effect of the link reshaping depends on the type of link. For the following link types, the reshaping has no effect:
However, if the option isLinkReplacementAllowed returns IlTrue, the layout calls the method #ensureReshapeableLinks or #ensureStraightLineLinks to ensure that all the links can be reshaped as needed. Note that in this case, the links that cannot be reshaped can be replaced with new links of a different type.
| style | The global style of the shape of all links. |
| void IlvTreeLayout::setLayoutMode | ( | IlvTreeLayoutMode | mode | ) |
Sets the layout mode.
Valid values are:
IlvTreeLayoutFreeMode - All links flow roughly in the flow direction. Nodes of different tree branches (this is, nodes with different parent node) are not justified to each other, therefore the level justification parameter is ignored. Tip over alignment is possible, if specified as alignment. All link styles are possible. The aspect ratio is ignored. IlvTreeLayoutLevelMode - All links flow roughly in the flow direction. Nodes are organized in levels and are justified at their borders or center according to the level justification parameter. Tip over alignment is not possible, but all link styles are possible. The aspect ratio is ignored. IlvTreeLayoutTipOverMode - Similar to the mode IlvTreeLayoutFreeMode. However in mode IlvTreeLayoutTipOverMode, the algorithm tries to optimize the layout automatically to fit best the specified aspect ratio. By a fast heuristic, it chooses for some nodes the local alignment IlvLayoutTipOverAlignment, but keeps the alignment of all other nodes as specified. This heuristic is a fast compromise between the modes IlvTreeLayoutTipLeavesOverMode, IlvTreeLayoutTipRootsOverMode, and IlvTreeLayoutTipRootsAndLeavesOverMode. IlvTreeLayoutTipLeavesOverMode - Similar to the mode IlvTreeLayoutTipOverMode. The algorithm tries to optimize the layout automatically to fit best the specified aspect ratio. This slow heuristic tries to tip over starting from the leaves and chooses the best layout. It keeps the alignment of all nodes close to the root as specified. IlvTreeLayoutTipRootsOverMode - Similar to the mode IlvTreeLayoutTipOverMode. The algorithm tries to optimize the layout automatically to fit best the specified aspect ratio. This slow heuristic tries to tip over starting from the roots and chooses the best layout. It keeps the alignment of all nodes close to the leaves as specified. IlvTreeLayoutTipRootsAndLeavesOverMode - Similar to the mode IlvTreeLayoutTipOverMode. The algorithm tries to optimize the layout automatically to fit best the specified aspect ratio. This slow heuristic tries to tip over starting from the roots and from the leaves, and chooses the best layout. It keeps the alignment of all nodes in the middle between roots and leaves as specified. IlvTreeLayoutRadialMode - The root node is in the center, the links flow radial away from the center, and the nodes are placed in circular layers around the root node according to the level justification. Tip over alignment and orthogonal link style are not possible. If an aspect ratio is specified, the layers are ellipses around the center. IlvTreeLayoutAlternatingRadialMode - This is the same as mode IlvTreeLayoutRadialMode, with the exception that children of the same node are placed alternating in different circular layers, if this results in a smaller radius and better usage of the space. Tip over alignment and orthogonal link style are not possible. If an aspect ratio is specified, the layers are ellipses around the center. The default value is IlvTreeLayoutFreeMode.
| mode | The layout mode. |
| void IlvTreeLayout::setLevelJustification | ( | IlvLayoutAlignment | justification | ) |
Sets the justification within the levels.
Valid values are:
IlvLayoutCenterAlignment IlvLayoutNorthAlignment IlvLayoutSouthAlignment This feature sets the justification of the nodes within each level. It can be used in layout modes IlvTreeLayoutLevelMode, IlvTreeLayoutRadialMode, and IlvTreeLayoutAlternatingRadialMode.
If the nodes are center justified, all nodes of the same level are placed with their centers along a line. Otherwise, all nodes of the same level are placed with the specified border justified to a line. For instance if the link flow direction is to the right, the justification IlvLayoutNorthAlignment means that the nodes are justified to the left, and the justification IlvLayoutSouthAlignment means that the nodes are justified to the right.
In the radial layout modes, the justification IlvLayoutNorthAlignment means that the nodes are aligned along a circle with the border that is closer to the root, and justification IlvLayoutSouthAlignment means that the nodes are aligned along a circle with the border that is further away from the root.
The default value is IlvLayoutCenterAlignment.
| justification | The justification of the nodes within each level. |
| void IlvTreeLayout::setLinkStyle | ( | IlAny | link, |
| IlvLayoutLinkStyle | style | ||
| ) |
Sets the style of the shape of an individual link.
This link style is only used if the global link style is set to IlvLayoutMixedLinkStyle and the link is part of the spanning tree. If the global link style is not IlvLayoutMixedLinkStyle, all links of the spanning tree have the style that is specified as the global link style. Links that are not part of the spanning tree have the link style IlvLayoutNoReshapeLinkStyle.
Valid values are:
IlvLayoutOrthogonalLinkStyle - The link gets an orthogonal shape, that is, a shape consisting of a sequence of orthogonal line segments. This option is not available for the radial layout modes. IlvLayoutStraightLineLinkStyle - The link gets a straight-line shape. IlvLayoutNoReshapeLinkStyle - No reshape is performed on the link. This feature can be useful if the link can have intermediate points and is not a straight-line link, for instance, a link of type IlvPolylineLinkImage.
The default value is IlvLayoutStraightLineLinkStyle.
Note that, when the graph attached to the layout is of type IlvGrapher, the effect of link reshaping depends on the type of link. For the following link types, the reshaping has no effect:
However, if the option isLinkReplacementAllowed returns IlTrue, the layout calls the method #ensureReshapeableLinks or #ensureStraightLineLinks to ensure that all the links can be reshaped as needed. Note that in this case, the links that cannot be reshaped can be replaced with new links of a different type.
| link | A link of the attached grapher or graph model. |
| style | The style of the shape of this link. |
| void IlvTreeLayout::setMaxChildrenAngle | ( | IlInt | angle | ) |
Sets the maximal angle for children that are placed in radial mode.
This is the maximal angle between the two rays from the parent to its two outermost children. The angle must be between 0 and 360 degrees. The angle 0 means that the angle is unspecified.
The default value is 0.
In radial mode, children of one single node may nearly cover completely one circular layer. This sometimes looks unbalanced, in particular because the links from the node to its outermost children are likely to cross other nodes. In order to avoid this effect, a maximal angle can be specified such that the children are placed more in the same direction and are not spread too widely around the parent. This angular restriction is applied to all children except the children of the root node. As a side effect, specifying a small maximal children angle enlarges the radius of the circles.
It is recommended to choose a value between 30 and 180 degrees for good results. The algorithm uses a heuristic that has precision deviations below 30 degrees and above 180 degrees. If an aspect ratio is specified, the layout algorithm uses ellipses instead of circles. In this case, precision deviations may occur as well.
This is an expert option. It has no effect in layout modes other than radial.
| angle | The maximal children angle between, 0 and 360 degrees. |
| void IlvTreeLayout::setOrthForkPercentage | ( | IlInt | percentage | ) |
Sets the percentage of the parent child offset that determines the location where the orthogonal link routing places the bends in order to fork the routing towards the children.
This has only effect if the orthogonal link style is chosen.
The default value is 45%.
This is an expert option. In all normal cases, it is not necessary to change the option. It is recommended to choose the orthogonal fork percentage always larger than the overlap percentage to obtain a good layout.
| percentage | The orthogonal fork percentage, between 0 and 100. |
| void IlvTreeLayout::setOverlapPercentage | ( | IlInt | percentage | ) |
Sets the percentage a node is considered smaller in the flow direction.
This allows nodes to be placed closer together. However, in layout modes IlvTreeLayoutFreeMode, IlvTreeLayoutTipOverMode, IlvTreeLayoutTipRootsOverMode, IlvTreeLayoutTipLeavesOverMode, and IlvTreeLayoutTipRootsAndLeavesOverMode, outgoing links of a node may in seldom cases cross neighbored leaf nodes if the overlap percentage is high. In order to avoid this, set the parameter to 0%.
The default value is 30%, which is for many graphs a good compromise between wasting space and the risk of links crossing nodes.
This is an expert option. In all normal cases, it is not necessary to change the option. It is recommended to choose the orthogonal fork percentage always larger than the overlap percentage to obtain a good layout.
| percentage | The overlap percentage, between 0 and 100. |
| void IlvTreeLayout::setParentChildOffset | ( | IlvPos | offset | ) |
Sets the minimal offset between a parent and its children.
If the flow direction is towards the top or bottom and the layout mode is not radial, this is a vertical offset. If the flow direction is towards the left or right and the layout mode is not radial, this is a horizontal offset. If the layout mode is radial, this is an offset radial to the circle or ellipses.
The default value is 40.
| offset | The offset between a parent and its children. |
Sets the position of the layout.
If no position is specified, the layout algorithm keeps the position of the first root node unchanged.
| point | The position. |
| isRootPosition | If IlTrue, it specifies the position of the first root node. If IlFalse, it specifies the position of the top left border of the layout. |
getPosition() setRoot(IlAny) | void IlvTreeLayout::setRoot | ( | IlAny | node | ) |
Allows you to specify the root(s) of the tree.
If there are more than one connected components, it is possible to select a root for each component. If no root is specified, an appropriate node is automatically selected as root. For a directed tree, the canonical root node with indegree 0 is selected unless otherwise specified.
Setting the root node by this method is identical to setting the root preference of this node to 10000.
| node | A node of the attached grapher or graph model. |
Specifies the preference of the node to become root node.
The higher the preference, the more likely the node will be selected as root node.
If a negative value is passed as input, the preference of the node is unspecified, in which case the algorithm calculates a preference such that for directed trees the canonical root nodes with indegree 0 have the highest preference.
| node | A node of the attached grapher or graph model. |
| preference | The preference of this node to become root. |
getCalcRoots() getSpecRoots() getRootPreference(IlAny) setRoot(IlAny) | void IlvTreeLayout::setSiblingOffset | ( | IlvPos | offset | ) |
Sets the minimal offset between siblings, that is between nodes that have the same parent in the tree structure.
If the flow direction is towards the top or bottom and the layout mode is not radial, this is, a horizontal offset. If the flow direction is towards the left or right and the layout mode is not radial, this is a vertical offset. If the layout mode is radial, this is an offset tangential to the circles or ellipses.
The default value is 40.
| offset | The offset between siblings. |
| void IlvTreeLayout::setTipOverBranchOffset | ( | IlvPos | offset | ) |
Sets the minimal offset in the flow direction between neighbored nodes that belong to different branches in the tree.
This offset is used to separate the branches if their common parent node has tip over alignment. It has no effect if the layout mode is radial, or if no tip over alignment occurs.
If the flow direction is towards the top or bottom, this is a vertical offset. If the flow direction is towards the left or right, this is a horizontal offset.
The default value is 40.
| offset | The offset between tip over tree branches. |
Creates an east-west neighboring of two nodes.
The westNode is placed as first neighbor at the same level to the west of the eastNode. This implies conversely that the eastNode is the first neighbor at the same level to the east of the westNode.
This method is identical to setEastWestNeighboring(IlAny eastNode, IlAny westNode) with reversed argument order, and is available for convenience. Note that, for instance, in flow direction towards the bottom, east is right of west, therefore it resembles more the argument order of setWestEastNeighboring, while in flow direction towards the top, east is left of west, therefore this resembles more the argument order of setEastWestNeighboring.
| westNode | The west neighbor of the eastNode. |
| eastNode | The east neighbor of the westNode. |
|
virtual |
Indicates that this layout class can stop the layout computation in a proper manner when the user-defined allowed time is exceeded.
If the allowed time elapses before termination of the Tree Layout algorithm, the nodes and links are not moved and remain at the same position as before the start of the algorithm.
IlTrue. Reimplemented from IlvGraphLayout.
|
virtual |
Indicates that this layout class allows the user to specify fixed links.
Fixed links are not reshaped during the layout if the method setPreserveFixedLinks(IlBoolean) is called with an IlTrue argument. The effect is similar to if the link is filtered away during layout.
IlTrue. IlvGraphLayout::setPreserveFixedLinks(IlBoolean) IlvGraphLayout::isPreserveFixedLinks() setGlobalLinkStyle(IlvLayoutLinkStyle) setLinkStyle(IlAny, IlvLayoutLinkStyle) Reimplemented from IlvGraphLayout.
|
virtual |
Indicates that this layout class allows the user to specify fixed nodes.
Fixed nodes are not moved during the layout if the method setPreserveFixedNodes(IlBoolean) is called with an IlTrue argument. Links that are incident to fixed nodes are not reshaped during the layout. Fixed nodes are ignored by the Tree Layout algorithm, which may lead to node overlapping. The effect is similar to if the node is filtered away during layout.
IlTrue. Reimplemented from IlvGraphLayout.
© Copyright 2012, Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave is a registered trademark of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.