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:

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

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

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

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