GFX layout

The Dojo Diagrammer GFX layout API extends the dojox.gfx API. It provides the GFX Group class (and therefore, the Node class) with the ability to automatically arrange its children according to location and size constraints.
With this extended API, the position and size of the Node subcomponents do not have to be hardcoded. The node automatically adapts its size to the content as soon as a change occurs that affects the size. For example, if the Node label gets longer, the node size fits to the new label size dynamically.
By default, the gfxlayout API is not enabled, although it is used in most of the samples. To enable it, set the useGfxLayout property of djConfig to true as shown in the following code:
<script type="text/javascript">
	    var djConfig = {
	        parseOnLoad:true,
               useGfxLayout:true
	    }
</scrip>
	

Arranging the children of a node

When the children of a Node instance are arranged, the direct child of the Node is typically a Group instance that acts as the top panel for child shapes. This panel handles the size and position of the child objects in association with the layout algorithm of your choice.
The following example shows how to write a template to build a basic Node composed of a background shape and a text label. This template is a simplified version of the default node template. Its layout constraints are set so that the node size always fits to the label size:
{
layout: { type:'ibm_ilog.diagram.gfxlayout.GridLayout' },
children: [
    { 
        dojoAttachPoint: 'baseShape',
        minimumSize:{width:80, height:40},
        shape: { width:1, height:1, r: 5, type:'rect'}, 
        fill: '{{backgroundColor}}', 
        stroke: {'color': '{{borderColor}}', 
        'width': 2 }
    },
    {
        dojoAttachPoint: 'textShape', 
        margins:[5,5,5,-2],
        shape: {type:'text', text:'{{label}}', align:'middle'}, 
        fill:'{{textColor}}', 
        font:{type:'font', size:'10pt', family:'sans-serif'}
    }
]
}
The template first defines a Group as the unique direct child. An instance of the GridLayout class is set to this group. The group is composed of two children:
  • A rectangle shape that has its size parameters set to 1 to fit the label size. However, a minimum size is also specified so that, if the label size is smaller, the Node keeps its default size. The layout engine uses the minimumSize property to control the size of a shape.
  • A text shape that is bound to the label property of the node. The margins property is set on the text to define the space between the label and the panel border.
The following figure illustrates the result and shows a node size adjusted to fit the label length:
Figure
showing two rectangular nodes, one at the upper left and the other
at the lower right of the figure. Both nodes have a blue background.
The upper left node has the label Node 1 and the lower right node
has the label New node added 1. The size of each shape is adjusted
to the length of its label.
The example specifies two properties that add some constraints to the layout: minimumSize and margins. These are part of a set of properties that can be defined on any shape and are supported by all layout algorithms:
  • halign and valign: the horizontal and vertical alignments.
    These properties are used to compute the horizontal and vertical positions of the shape within the slot of the panel.
    halign values are: left, center, right, stretch.
    valign values are: top, center, bottom, stretch.
    If the value is ‘stretch’, the shape fills the entire slot.
  • margins: the margins of the shape within the slot.
    It is the space between the slot bounds and the shape itself. The value is either a number to set the left, top, right, and bottom margins to the same value, or an array of four numbers arranged in order by the left, top, right, and bottom margins.
  • minimumSize: the minimum size of the shape.
  • maximumSize: the maximum size of the shape.

StackLayout

The ibm_ilog.diagram.gfxlayout.StackLayout class arranges the children of a container in a horizontal or a vertical stack. The orientation is given at construction time through the horizontal property.
The following figure shows two Group instances with a StackLayout whose horizontal property is set to false in the first instance and to true in the second instance:
Figure
showing a group of four rectangular shapes of the same length but
of different heights. The shapes are aligned vertically with a gap
between each of them. (Stack layout with property horizontal set to
false.)
Figure
showing a group of four rectangular shapes of the same height but
of different lengths. The shapes are aligned horizontally with a gap
between each of them. (Stack layout with property horizontal set to
true.)
The StackLayout class defines the paddingLeft, paddingRight, paddingTop, and paddingBottom properties to specify the internal margins of the panel relative to which the children are positioned. A global padding property defines the same padding in all directions. The space between the children can be adjusted using the gap property. The following figure illustrates these properties:
Figure
showing three rectangular shapes stacked up vertically. The figure
illustrates the gap between the shapes as well as the padding on the
left, the right, the top, and the bottom relative to the panel that
contains this group of shapes.
A horizontal stack layout aligns the child objects vertically in the computed layout slot according to the value of their valign property and their margins property. A vertical stack layout aligns the child objects horizontally in the computed layout slot according to the value of their halign property and their margins property.
The following image shows how the horizontal and vertical alignment values are used by the layout to position the shapes in the container:
Figure
showing a vertical stack layout and a horizontal stack layout. The
vertical stack layout has four piled up rectangular shapes of different
sizes. Each shape has a label in it: center (the shape is centered
horizontally within the container panel), stretch (the shape is aligned
horizontally to the right and left margins of the container panel),
left (the shape is aligned horizontally to the left of container panel),
center (the shape is centered horizontally within the container panel).
At the top of this vertical stack layout, the caption ‘halign
property’ is indicated. The horizontal stack layout shows four
rectangular shapes of different sizes next to each other. Each shape
has a label in it: center (the shape is centered vertically within
the container panel), stretch (the shape is aligned vertically to
the top and to the bottom margins of the container panel), bottom
(the shape is aligned vertically to the bottom of the container panel),
top (the shape is aligned vertically to the top of the container shape).
At the top of this horizontal stack layout, the caption ‘valign
property’ is indicated.
The following template code creates the horizontal stack illustrated in the figure:
{
layout:{
horizontal:true,
gap:10,
padding:[5,5,5,5]},
children:[
{
valign:'center',
shape:{x:0, y:0, width:60, height:40, r:5, type:'rect'}, 
fill: '{{backgroundColor}}', 
stroke: {'color': '{{borderColor}}', 'width': 2 }},

{
valign:'stretch',
shape:{x:0, y:0, width:110, height:65, r:5, type:'rect'}, 
fill: '{{backgroundColor}}', 
stroke: {'color': '{{borderColor}}', 'width': 2 }},

{
valign:'bottom',
shape:{x:0, y:0, width:40, height:40, r:5, type:'rect'}, 
fill: '{{backgroundColor}}', 
stroke: {'color': '{{borderColor}}', 'width': 2 }},

{
valign:'top', 
shape:{x:0, y:0, width:80, height:20, r:5, type:'rect'}, 
fill: '{{backgroundColor}}', 
stroke: {'color': '{{borderColor}}', 'width': 2 }},
]}

GridLayout

The ibm_ilog.diagram.gfxlayout.GridLayout class arranges the children of a container as grid elements.
The grid layout structure is defined by a collection of column and row descriptor objects that specify how the metric of each row or column is computed. These descriptor objects support the following properties:
  • width and height: if the container width or height is not fixed, then the column width or row height depends on the value of this property. A value of -1 adjusts the dimensions to the maximum child dimensions.
  • weight: if the container width or height is fixed, this property defines how the space that remains after all the fixed widths or heights have been subtracted from the container width or height is distributed across the columns or rows. For example, a column with a weight of 2 has twice the space of a column with a weight of 1 and the same fixed width. A row with a weight of 2 has twice the space of a row with a weight of 1 and the same fixed height.
Consider the following grid structure:
cols:[{ width:250}, {weight:2}, {weight:1}, {weight:2} ],  
rows:[{ height:90}, {height:-1}]
The whole panel has a fixed width of 600. The first column is set to 250 pixels wide and the other columns share the remaining space with the following constraint: the width of the second and fourth columns is set to be twice the width of the third column.
If the height panel is set to -1, the panel adapts to the size of its children. In this example, the first row has a fixed height of 90 and the second row fits the maximum height of the shape in this row. The following figure illustrates this grid structure:
Illustration
of the grid structure described above.
The GridLayout class defines the paddingLeft, paddingRight, paddingTop, and paddingBottom properties to specify the internal margins of the panel relative to which the children are positioned. A global padding property defines the same padding in all directions. This padding adds to the specific margins that are defined for each shape. The following figure shows the relationships between these properties:
Padding
illustration on a grid layout that contains four square shapes of
different sizes. There is some padding at the top, at the bottom,
on the left, and on the right of the grid container. There are margins
between the shapes in the grid container.
The children in the grid are placed in the grid cells according to the column and row properties of the children. When these properties are not specified for a shape, the shape is automatically placed in the grid according to its order in the children list of the container. The direction of the placement is defined through the property horizontalFlow that is true by default.
If the horizontalFlow property is true, and the children do not define any specific row or column index, the first child is placed at the (0,0) cell, the second one at the (1,0) cell, and so on.
A child can span over multiple rows or columns depending on its colspan or rowspan properties. These properties indicate the number of columns or rows the child must overlap.
A value of -1 for the colspan or rowspan properties means that the child must span over all the remaining columns or rows. In the following figure, a shape in the cell (0,0) is configured to span two columns (its colspan property is set to 2). Another shape in the cell (2,0) is configured to span vertically across all the remaining rows (its rowspan property is set to -1).
Illustration
of the grid spanning described above