TreeLayout

layout.TreeLayout is a class, which provides layout algorithm for tree-like graphs.

To learn more, check out the learn section.

constructor

constructor(options: TreeLayout.Options);

The layout.TreeLayout constructor options parameter has following properties:

attributeNames

[optional] An object that maps element attributes accepted by the layout to user defined attribute names. Useful for resolving conflicts when an attribute is already in use by the application logic. e.g Setting { siblingRank: 'index' } will make the layout look for the index attribute instead of siblingRank when trying to figure out the order of siblings.

direction

[optional] The default direction of the layout. It can be set to one of the following values: 'L', 'R', 'T', 'B' (for left-to-right, right-to-left, top-to-bottom and bottom-to-top layouts) or diagonal variants 'TL', 'TR','BL', 'BR' (for top-left, top-right, bottom-left and bottom-right). Defaults to 'R'.

filter()

(children: dia.Element[], parent: dia.Element | null, opt: { [key: string]: any }, treeLayout: layout.TreeLayout) => dia.Element[];

[optional] A callback which runs for every single parent element in the graph and returns an array of elements to be laid out.

Parameters:

• children is an array of siblings
• parent is the parent of the children or null, when children are roots
• opt is the option object passed to layout() method when calling the layout.
• treeLayout is the layout instance, for context.

firstChildGap

[optional] The distance between the first sibling and its parent. It's applicable only for diagonal layouts ('TL', 'TR','BL', 'BR'). Defaults to 20.

graph

The JointJS graph object on which you want to perform the layout.

parentGap

[optional] The distance between a parent element and its children. Defaults to 20.

siblingGap

[optional] The distance between siblings. Defaults to 20.

symmetrical

[optional] Enabling this layout option ensures that the distance between children is the same. This feature only works either in the horizontal or vertical direction.

updateAttributes()

(layoutArea: TreeLayout.LayoutArea, root: dia.Element, rootLink: dia.Link, opt: { [key: string]: any }, treeLayout: layout.TreeLayout) => void

[optional] A function responsible for updating attributes of the current root and the associated link.

updatePosition()

(element: dia.Element, position: dia.Point, opt?: { [key: string]: any }, treeLayout: layout.TreeLayout) => void

[optional] A function responsible for setting the resulting position on the elements. It calls element.set('position', position, opt); by default.

updateSiblingRank()

(element: dia.Element, siblingRank: number | undefined, opt?: { [key: string]: any }, treeLayout: layout.TreeLayout) => void

[optional] A function responsible for setting the resulting sibling rank on the elements. It calls element.set(this.getAttributeName('siblingRank'), siblingRank, opt); by default.

updateVertices()

(link: dia.Link, vertices: Array<dia.Point>, opt?: { [key: string]: any }, treeLayout: layout.TreeLayout) => void

[optional] A function responsible for setting the resulting vertices on the links. It calls link.set('vertices', vertices, opt); by default. If the option is defined as null no vertices will be set by the layout.

Methods

getLayoutBBox()

Returns the bounding box of all affected elements from the last layout run (i.e. elements, which have been filtered are not taken into account when calculating the bounding box).

treeLayout.getLayoutBBox(): g.Rect | null;

layout()

Layout the graph in a tree. It iterates over all graph sources (elements without a parent) and layout them as separate trees.

treeLayout.layout(opt?: { [key: string]: any }): this;

The option object opt, which will be passed down to all operations on the graph made by the layout call. e.g. treeLayout.layout({ myFlag: true }) will internally set an element position as element.position(x, y, { myFlag: true });

removeElement()

Removes element from graph and reconnects children to the parent of the removed element.

treeLayout.removeElement(el: dia.Element, opt?: { layout?: boolean, [key: string]: any }): void;

The option object opt, will be passed down to all operations on the graph made by the function. Additionally this method accepts opt.layout = false, this will omit calling layout function after removing the element.

Element attributes

The tree layout also reads some element attributes allowing for a fine control of the layout engine. These are:

direction	The direction of the layout for this specific node. Note, that the tree layout can handle even mixed layout directions on a per-node basis. See the direction property of constructor options.
siblingRank	The index of the element among its siblings.
offset	The additional distance from the parent (the real distance is a sum of parentGap and the offset).
margin	Extends the area occupied by the element on both sibling sides.
prevSiblingGap	The additional gap next to the element sub-tree on the side of the previous sibling. The previous sibling is defined as the sibling with the closest smaller siblingRank.
nextSiblingGap	The additional gap next to the element sub-tree on the side of the next sibling. The next sibling is defined as the sibling with the closest larger siblingRank.
firstChildGap	The distance between the element and the first child. It's applicable only for diagonal layouts ('TL', 'TR','BL', 'BR'). It overides the tree layout firstChildGap option.

Types

Options

Constructor options parameter type

interface Options {
    graph: dia.Graph;
    gap?: number;
    parentGap?: number;
    siblingGap?: number;
    firstChildGap?: number;
    direction?: Direction;
    directionRule?: DirectionRule;
    updatePosition?: null | ((element: dia.Element, position: dia.Point, opt?: { [key: string]: any }, layout: layout.TreeLayout) => void);
    updateVertices?: null | ((link: dia.Link, vertices: Array<dia.Point>, opt?: { [key: string]: any }, layout: layout.TreeLayout) => void);
    updateSiblingRank?: null | ((element: dia.Element, siblingRank: number | undefined, opt?: { [key: string]: any }, layout: layout.TreeLayout) => void);
    updateAttributes?: null | ((layoutArea: LayoutArea, root: dia.Element, rootLink: dia.Link, opt: { [key: string]: any }, layout: layout.TreeLayout) => void);
    filter?: null | ((children: dia.Element[], parent: dia.Element | null, opt: { [key: string]: any }, layout: layout.TreeLayout) => dia.Element[]);
    attributeNames?: AttributeNames;
    symmetrical?: boolean;
}