Grid patterns

It is common to want to display a grid of lines drawn at regular intervals. You may also want to force dragged parts to be aligned on grid points, and to resize parts to be multiples of the grid cell size.

Grids are implemented using a type of Panel, Panel.Grid. Grid Panels, like most other types of Panels, can be used within Nodes or any other kind of Part. However when they are used as the Diagram.grid, they are effectively infinite in extent.

Unlike in other kinds of Panels, Grid Panel elements must be Shapes that are only used to control how the grid lines or grid bars are drawn.

See samples that make use of grids in the samples index.

Default grid

To display a grid pattern in the background of the diagram, you can just make the Diagram.grid visible:

Grid snapping

The DraggingTool and ResizingTool can change their behavior based on the background grid pattern, if you set the DraggingTool.isGridSnapEnabled and/or ResizingTool.isGridSnapEnabled properties to true.

Setting DraggingTool.isGridSnapEnabled to true will not affect disconnected Links, but these can snap if you define a custom Part.dragComputation to do so on the Link template.

Simple grid customization

You can change the size of the grid cell by setting Panel.gridCellSize:

The cell size used when snapping the locations of Parts during a drag does not need to be exactly the same as the background grid's cell size. The value of DraggingTool.gridSnapCellSize takes precedence over the Panel.gridCellSize. Note that if DraggingTool.gridSnapCellSize is set but ResizingTool.cellSize is not, Parts will use the DraggingTool.gridSnapCellSize value when resizing.

Custom grids

Grid patterns are implemented by the Panel class when its Panel.type is Panel.Grid. The elements of a Grid Panel must be Shapes whose Shape.figure is one of a small set of known kinds of figures. The only figures it can accept are: "LineH", "LineV", "BarH", and "BarV". The two "Line" figures result in stroked lines separating the grid cells; the two "Bar" figures result in filled rectangles in the grid cells. Thus, set the Shape.stroke property on "Line" figures and the Shape.fill property on "bar" figures to change colors.

Here is a simple grid consisting of blue horizontal lines and green vertical lines:

The Shape.interval property is also used by a Grid Panel to determine how frequently a line should be drawn. The value should be a positive integer specifying how many cells there are between drawings of this particular line. So if you wanted darker blue and darker green lines every five cells:

Note that the Shapes are drawn in the order in which they appear in the Panel, so you can see that the dark blue horizontal lines are drawn in front of the light green vertical lines, and that the dark green vertical line crosses in front of the dark blue horizontal lines.

Here is the definition of the predefined Diagram.grid:

You can get a green-bar pattern by using the "BarH" figure. Note the use of Shape.fill instead of Shape.stroke and explicitly setting the GraphObject.height:

This example also demonstrates how one can use the Part.dragComputation property to customize where the user can drag the node. In this case the Part.location.y is limited to be multiples of 100, corresponding to the rows of cells filled by the green bars.

To get a tablecloth effect, one can use both vertical and horizontal bars with a translucent color:

This example limits dragging of all nodes by setting DraggingTool.isGridSnapEnabled to true.

Another custom grid: dots

"Grid" Panels can also be used like any other Panel element as part of a Node. Here is a simple example using one as a regular data bound element. Try resizing the Nodes to see how they tile based on their grid properties:

Temporarily ignoring grid snap

The Part.dragComputation property passes both the Part's precise location and snapped location to its given function, and thus it can easily be used to allow the user to precision drag and ignore the grid. The following example contains a simple drag computation that allows users to precision drag when holding down Shift:

Other considerations

A Grid Panel should have a non-null background if it needs to be pickable. One cannot set or bind the Panel.itemArray of a Grid Panel.

Events on the Shapes will be ignored. Shapes in a Grid Panel must not be scaled or rotated.