rwlogo
Rogue Wave Views 5.5.1

Rogue Wave Views
Graph Layout Package API Reference Guide

Product Documentation:

Rogue Wave Views
Documentation Home

IlvTreeLayout Class Reference

The main class for the Tree Layout algorithm. More...

#include <ilviews/layout/tree.h>

Inheritance diagram for IlvTreeLayout:
IlvGraphLayout

List of all members.

Public Member Functions

 IlvTreeLayout ()
 Creates a new instance of the Tree Layout algorithm.
virtual ~IlvTreeLayout ()
 Destroys this instance of class IlvTreeLayout.
virtual void cleanObjectProperties (IlAny nodeOrLink)
 Overridden version of the method cleanObjectProperties.
virtual void detach ()
 Detaches the graph model from the layout instance.
IlvLayoutAlignment getAlignment (IlAny node) const
 Returns the local alignment style of the node.
IlDouble getAspectRatio () const
 Returns the aspect ratio specified for the layout.
IlvPos getBranchOffset () const
 Returns the minimal offset between neighbored nodes that belong to different branches in the tree.
const IlListgetCalcBackwardTreeLinks () const
 Returns the backward links that were used in reverse direction as part of the spanning tree during layout.
const IlListgetCalcForwardTreeLinks () const
 Returns the forward links that were used as part of the spanning tree during layout.
const IlListgetCalcNonTreeLinks () const
 Returns the links that were neither forward nor backward links in the spanning tree during layout.
const IlListgetCalcRoots () const
 Returns the list of nodes that were used as roots during layout.
IlAny getEastNeighbor (IlAny node) const
 Returns the specified east neighbor node of the input node, or null if none was specified.
IlvDirection getFlowDirection () const
 Returns the current direction of the flow.
IlvLayoutAlignment getGlobalAlignment () const
 Returns the global alignment style.
IlvLayoutLinkStyle getGlobalLinkStyle () const
 Returns the global style of the shapes of links.
IlvTreeLayoutMode getLayoutMode () const
 Returns the current layout mode.
IlvLayoutAlignment getLevelJustification () const
 Returns the current justification within the levels.
IlvLayoutLinkStyle getLinkStyle (IlAny link) const
 Returns the style of the shape of an individual link.
IlInt getMaxChildrenAngle () const
 Returns the maximal angle for children that are placed in radial mode.
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.
IlInt getOverlapPercentage () const
 Returns the percentage a node is considered smaller in the flow direction.
IlvPos getParentChildOffset () const
 Returns the minimal offset between a parent and its children.
const IlvPointgetPosition () const
 Returns the specified position of the layout, or null if there was never a position specified.
IlInt getRootPreference (IlAny node) const
 Returns the specified preference of the node to become root node.
IlvPos getSiblingOffset () const
 Returns the minimal offset between siblings.
const IlListgetSpecRoots () const
 Returns the list of nodes that were specified as root.
IlvPos getTipOverBranchOffset () const
 Returns the minimal offset in the flow direction between neighbored nodes that belong to different branches in the tree.
IlAny getWestNeighbor (IlAny node) const
 Returns the specified west neighbor node of the input node, or null if none was specified.
IlBoolean isCategorizingLinks () const
 Returns IlTrue if the layout algorithm stores the categorization of links into forward, backward, and non-tree links.
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.
void setAlignment (IlAny node, IlvLayoutAlignment alignment)
 Sets the alignment style of an individual node.
void setAspectRatio (const IlvAbstractView *view)
 Sets the aspect ratio for the layout from a given view.
void setAspectRatio (const IlvRect &rect)
 Sets the aspect ratio for the layout from a given rectangle.
void setAspectRatio (IlDouble aspectRatio)
 Sets the aspect ratio for the layout.
void setBranchOffset (IlvPos offset)
 Sets the minimal offset between neighbored nodes that belong to different branches in the tree.
void setCategorizingLinks (IlBoolean flag)
 Sets whether the layout algorithm stores the categorization of links into forward, backward, and non-tree links.
void setEastWestNeighboring (IlAny eastNode, IlAny westNode)
 Creates an east-west neighboring of two nodes.
void setFlowDirection (IlvDirection direction)
 Sets the direction of the flow.
void setGlobalAlignment (IlvLayoutAlignment alignment)
 Sets the global alignment style.
void setGlobalLinkStyle (IlvLayoutLinkStyle style)
 Indicates that this layout class is able to determine the percentage of completion during the run of layout.
void setLayoutMode (IlvTreeLayoutMode mode)
 Sets the layout mode.
void setLevelJustification (IlvLayoutAlignment justification)
 Sets the justification within the levels.
void setLinkStyle (IlAny link, IlvLayoutLinkStyle style)
 Sets the style of the shape of an individual link.
void setMaxChildrenAngle (IlInt angle)
 Sets the maximal angle for children that are placed in radial mode.
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.
void setOverlapPercentage (IlInt percentage)
 Sets the percentage a node is considered smaller in the flow direction.
void setParentChildOffset (IlvPos offset)
 Sets the minimal offset between a parent and its children.
void setPosition (const IlvPoint &point, IlBoolean isRootPosition)
 Sets the position of the layout.
void setRoot (IlAny node)
 Allows you to specify the root(s) of the tree.
void setRootPreference (IlAny node, IlInt preference)
 Specifies the preference of the node to become root node.
void setSiblingOffset (IlvPos offset)
 Sets the minimal offset between siblings, that is between nodes that have the same parent in the tree structure.
void setTipOverBranchOffset (IlvPos offset)
 Sets the minimal offset in the flow direction between neighbored nodes that belong to different branches in the tree.
void setWestEastNeighboring (IlAny westNode, IlAny eastNode)
 Creates an east-west neighboring of two nodes.
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.
IlBoolean supportsPreserveFixedLinks () const
 Indicates that this layout class allows the user to specify fixed links.
IlBoolean supportsPreserveFixedNodes () const
 Indicates that this layout class allows the user to specify fixed nodes.

Protected Member Functions

virtual void layout ()
 Computes the layout using the Tree Layout algorithm.

Detailed Description

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):

Tree-level-free.gif

Another sample drawing in free layout mode with tip over alignment at some leaf nodes:

Tree-tipover.gif

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.

Tree-radial.gif

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.

Tree-mixedlinks.gif

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.

Tree-attachments.gif

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:


Constructor & Destructor Documentation

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.

See also:
IlvGraphLayout::attach(IlvGrapher*)
IlvGraphLayout::attach(IlvGraphModel*)
IlvGraphLayout::performLayout()
virtual IlvTreeLayout::~IlvTreeLayout (  )  [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.

See also:
detach()

Member Function Documentation

virtual void IlvTreeLayout::cleanObjectProperties ( IlAny  nodeOrLink  )  [virtual]

Overridden version of the method cleanObjectProperties.

See also:
IlvGraphLayout::cleanObjectProperties

Reimplemented from IlvGraphLayout.

virtual void IlvTreeLayout::detach (  )  [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.

See also:
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.

Parameters:
node A node of the attached grapher or graph model.
Returns:
The alignment style of this node.
See also:
setGlobalAlignment(IlvLayoutAlignment)
setAlignment(IlAny, IlvLayoutAlignment)
IlDouble IlvTreeLayout::getAspectRatio (  )  const

Returns the aspect ratio specified for the layout.

This is the ratio width / height of the desired layout region.

Returns:
The desired aspect ratio.
See also:
setAspectRatio(IlDouble aspectRatio)
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.

Returns:
The offset between tree branches.
See also:
setFlowDirection(IlvDirection)
setBranchOffset(IlvPos)
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.

Returns:
The list of links that are part of the backward spanning tree, or null if the link categorization option was switched off during the last run of layout.
See also:
getCalcForwardTreeLinks()
getCalcNonTreeLinks()
setRoot(IlAny)
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.

Returns:
The list of links that are part of the forward spanning tree, or null if the link categorization option was switched off during the last run of layout.
See also:
getCalcBackwardTreeLinks()
getCalcNonTreeLinks()
setRoot(IlAny)
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).

Warning:
[note] Links that are specified as fixed links or that are adjacent to fixed nodes are not part of this list even though they are also not part of the spanning tree.
Returns:
The list of links that are not part of the spanning tree, or null if the link categorization option was switched off during the last run of layout.
See also:
getCalcForwardTreeLinks()
getCalcBackwardTreeLinks()
setRoot(IlAny)
IlvGraphLayout::setPreserveFixedLinks(IlBoolean)
IlvGraphLayout::isPreserveFixedLinks()
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 list of calculated root nodes.
See also:
getSpecRoots()
setRoot(IlAny)
setRootPreference(IlAny, IlInt)
IlAny IlvTreeLayout::getEastNeighbor ( IlAny  node  )  const

Returns the specified east neighbor node of the input node, or null if none was specified.

Parameters:
node A node of the attached grapher or graph model.
Returns:
The specified east neighbor of this node.
See also:
getWestNeighbor()
setEastWestNeighboring(IlAny, IlAny)
IlvDirection IlvTreeLayout::getFlowDirection (  )  const

Returns the current direction of the flow.

Returns:
The direction of the flow.
See also:
setFlowDirection(IlvDirection)
IlvLayoutAlignment IlvTreeLayout::getGlobalAlignment (  )  const

Returns the global alignment style.

Returns:
The global alignment style.
See also:
setGlobalAlignment(IlvLayoutAlignment)
IlvLayoutLinkStyle IlvTreeLayout::getGlobalLinkStyle (  )  const

Returns the global style of the shapes of links.

Returns:
The global style of the shape of all links.
See also:
setGlobalLinkStyle(IlvLayoutLinkStyle)
IlvTreeLayoutMode IlvTreeLayout::getLayoutMode (  )  const

Returns the current layout mode.

Returns:
The layout mode.
See also:
setLayoutMode(IlvTreeLayoutMode)
IlvLayoutAlignment IlvTreeLayout::getLevelJustification (  )  const

Returns the current justification within the levels.

Returns:
The justification of the nodes within each level.
See also:
setLevelJustification(IlvLayoutAlignment)
IlvLayoutLinkStyle IlvTreeLayout::getLinkStyle ( IlAny  link  )  const

Returns the style of the shape of an individual link.

Parameters:
link A link of the attached grapher or graph model.
Returns:
The style of the shape of this link
See also:
setGlobalLinkStyle(IlvLayoutLinkStyle)
setLinkStyle(IlAny, IlvLayoutLinkStyle)
IlInt IlvTreeLayout::getMaxChildrenAngle (  )  const

Returns the maximal angle for children that are placed in radial mode.

Returns:
The maximal children angle.
See also:
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.

Returns:
The orthogonal fork percentage.
See also:
setOrthForkPercentage
IlInt IlvTreeLayout::getOverlapPercentage (  )  const

Returns the percentage a node is considered smaller in the flow direction.

Returns:
The overlap percentage.
See also:
setOverlapPercentage(IlInt)
IlvPos IlvTreeLayout::getParentChildOffset (  )  const

Returns the minimal offset between a parent and its children.

Returns:
The offset between a parent and its children.
See also:
setParentChildOffset(IlvPos)
const IlvPoint* IlvTreeLayout::getPosition (  )  const

Returns the specified position of the layout, or null if there was never a position specified.

Returns:
null if there was never a position specified. Otherwise the specified position of the layout.
See also:
setPosition(IlvPoint*, IlBoolean)
isRootPosition()
setRoot(IlAny)
IlInt IlvTreeLayout::getRootPreference ( IlAny  node  )  const

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.

Parameters:
node A node of the attached grapher or graph model.
Returns:
The preference of this node to become root.
See also:
setRoot(IlAny)
setRootPreference(IlAny, IlInt)
IlvPos IlvTreeLayout::getSiblingOffset (  )  const

Returns the minimal offset between siblings.

Returns:
The offset between siblings.
See also:
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().

Returns:
The list of specified root nodes.
See also:
getCalcRoots()
setRoot(IlAny)
setRootPreference(IlAny, IlInt)
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 offset between tip over tree branches.
See also:
setFlowDirection(IlvDirection)
setTipOverBranchOffset(IlvPos)
IlAny IlvTreeLayout::getWestNeighbor ( IlAny  node  )  const

Returns the specified west neighbor node of the input node, or null if none was specified.

Parameters:
node A node of the attached grapher or graph model.
Returns:
The specified west neighbor of this node.
See also:
getEastNeighbor()
setEastWestNeighboring(IlAny, IlAny)
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.

Returns:
IlTrue if link categorization should be done during the next run of layout.
See also:
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.

Returns:
IlTrue if the specified position is the root node position.
See also:
getPosition()
setPosition(const IlvPoint&, IlBoolean)
setRoot(IlAny)
virtual void IlvTreeLayout::layout (  )  [protected, virtual]

Computes the layout using the Tree Layout algorithm.

To start the layout, call the method performLayout().

See also:
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.

Parameters:
node A node of the attached grapher or graph model.
alignment The alignment style of this node.
See also:
setGlobalAlignment(IlvLayoutAlignment)
getAlignment(IlAny)
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.

Parameters:
view The view to display the graph.
See also:
setAspectRatio(IlDouble aspectRatio)
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.

Parameters:
rect The rectangle to fit the graph into.
See also:
setAspectRatio(IlDouble aspectRatio)
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:

  • In layout modes IlvTreeLayoutRadialMode and IlvTreeLayoutAlternatingRadialMode, the nodes are placed in circular layers if the aspect ratio is 1, otherwise in elliptic layers.
  • In layout modes 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.
  • The aspect ratio has no effect in other layout modes.
Parameters:
aspectRatio The desired aspect ratio.
See also:
getAspectRatio()
setLayoutMode(IlvTreeLayoutMode)
setAlignment(IlAny, IlvLayoutAlignment)
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.

Parameters:
offset The offset between tree branches.
See also:
getBranchOffset()
setFlowDirection(IlvDirection)
setLayoutMode(IlvTreeLayoutMode)
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.

Parameters:
flag Whether link categorization should be done during the next run of layout.
See also:
isCategorizingLinks()
void IlvTreeLayout::setEastWestNeighboring ( IlAny  eastNode,
IlAny  westNode 
)

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.

Parameters:
eastNode The east neighbor of the westNode.
westNode The west neighbor of the eastNode.
See also:
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.
Warning:
[note] Except for the radial layout modes, the compass direction south (for instance in 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.

Parameters:
flowDirection The direction of the flow.
See also:
getFlowDirection()
setLayoutMode(IlvTreeLayoutMode)
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.

Parameters:
alignment The global alignment style.
See also:
getGlobalAlignment()
setLayoutMode(IlvTreeLayoutMode)
setAlignment(IlAny, IlvLayoutAlignment)
void IlvTreeLayout::setGlobalLinkStyle ( IlvLayoutLinkStyle  style  ) 

Indicates that this layout class is able to determine the percentage of completion during the run of layout.

Returns:
Always IlTrue.
See also:
increasePercentageComplete
IlvGraphLayoutReport::getPercentageComplete Sets the global style of the shapes of links. Valid values are: 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.

Parameters:
style The global style of the shape of all links.
See also:
getGlobalLinkStyle()
setLinkStyle(IlAny, IlvLayoutLinkStyle)
setLayoutMode(IlvTreeLayoutMode)
IlvGraphLayout::setLinkReplacementAllowed(IlBoolean)
IlvGraphModel::ensureReshapeableLinks(IlvGraphLayout*)
IlvGraphModel::ensureStraightLineLinks(IlvGraphLayout*)
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.

Parameters:
mode The layout mode.
See also:
getLayoutMode()
setFlowDirection(IlvDirection)
setLevelJustification(IlvLayoutAlignment)
setGlobalLinkStyle(IlvLayoutLinkStyle)
setLinkStyle(IlAny, IlvLayoutLinkStyle)
setGlobalAlignment(IlvLayoutAlignment)
setAlignment(IlAny, IlvLayoutAlignment)
setAspectRatio(IlDouble)
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.

Parameters:
justification The justification of the nodes within each level.
See also:
getLevelJustification()
setLayoutMode(IlvTreeLayoutMode)
setFlowDirection(IlvDirection)
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.

Parameters:
link A link of the attached grapher or graph model.
style The style of the shape of this link.
See also:
getLinkStyle(IlAny)
setLayoutMode(IlvTreeLayoutMode)
setGlobalLinkStyle(IlvLayoutLinkStyle)
IlvGraphLayout::setLinkReplacementAllowed(IlBoolean)
IlvGraphModel::ensureReshapeableLinks(IlvGraphLayout*)
IlvGraphModel::ensureStraightLineLinks(IlvGraphLayout*)
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.

Parameters:
angle The maximal children angle between, 0 and 360 degrees.
See also:
getMaxChildrenAngle()
setLayoutMode(IlvTreeLayoutMode)
setAspectRatio(IlDouble)
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.

Parameters:
percentage The orthogonal fork percentage, between 0 and 100.
See also:
setGlobalLinkStyle(IlvLayoutLinkStyle)
setLinkStyle(IlAny, IlvLayoutLinkStyle)
setParentChildOffset(IlvPos)
setOverlapPercentage(IlInt)
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.

Parameters:
percentage The overlap percentage, between 0 and 100.
See also:
setLayoutMode(IlvTreeLayoutMode)
setOrthForkPercentage(IlInt)
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.

Parameters:
offset The offset between a parent and its children.
See also:
getParentChildOffset()
setFlowDirection(IlvDirection)
setLayoutMode(IlvTreeLayoutMode)
void IlvTreeLayout::setPosition ( const IlvPoint point,
IlBoolean  isRootPosition 
)

Sets the position of the layout.

If no position is specified, the layout algorithm keeps the position of the first root node unchanged.

Parameters:
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.
See also:
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.

Parameters:
node A node of the attached grapher or graph model.
See also:
getCalcRoots()
getSpecRoots()
setRootPreference(IlAny, IlInt)
void IlvTreeLayout::setRootPreference ( IlAny  node,
IlInt  preference 
)

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.

Parameters:
node A node of the attached grapher or graph model.
preference The preference of this node to become root.
See also:
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.

Parameters:
offset The offset between siblings.
See also:
getSiblingOffset()
setFlowDirection(IlvDirection)
setLayoutMode(IlvTreeLayoutMode)
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.

Parameters:
offset The offset between tip over tree branches.
See also:
getTipOverBranchOffset()
setFlowDirection(IlvDirection)
setLayoutMode(IlvTreeLayoutMode)
void IlvTreeLayout::setWestEastNeighboring ( IlAny  westNode,
IlAny  eastNode 
)

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.

Parameters:
westNode The west neighbor of the eastNode.
eastNode The east neighbor of the westNode.
See also:
setEastWestNeighboring(IlAny, IlAny)
getEastNeighbor()
getWestNeighbor()
IlBoolean IlvTreeLayout::supportsAllowedTime (  )  const [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.

Returns:
Always IlTrue.
See also:
IlvGraphLayout::setAllowedTime(IlvRunTimeType)

Reimplemented from IlvGraphLayout.

IlBoolean IlvTreeLayout::supportsPreserveFixedLinks (  )  const [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.

Returns:
Always IlTrue.
See also:
IlvGraphLayout::setPreserveFixedLinks(IlBoolean)
IlvGraphLayout::isPreserveFixedLinks()
setGlobalLinkStyle(IlvLayoutLinkStyle)
setLinkStyle(IlAny, IlvLayoutLinkStyle)

Reimplemented from IlvGraphLayout.

IlBoolean IlvTreeLayout::supportsPreserveFixedNodes (  )  const [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.

Returns:
Always IlTrue.
See also:
IlvGraphLayout::setPreserveFixedNodes(IlBoolean)
IlvGraphLayout::isPreserveFixedNodes()

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.