The VisualScript Cookbook

13/18 Page

Arranging Shapes in Rows and Columns

You can use a ShapeContainer object to arrange a collection of shapes in a row across the page.

For example, if you have a list of tables from a database, you may want to represent them as a list of shapes. You could show this list as a row of shapes across the page using a ShapeContainer.

You add a ShapeContainer to the root shape and then add as many shapes as you need to the ShapeContainer.

{
var myDocument=new VS.Document();
var rootShape=myDocument.GetTheShape();
var myContainer=rootShape.AddShapeContainer(VS.ShapeContainerArrangement.Row);
myContainer.AddShape().SetLabel("Table 1");
myContainer.AddShape().SetLabel("Table 2");
myContainer.AddShape().SetLabel("Table 3");
myContainer.AddShape().SetLabel("Table 4");
myContainer.AddShape().SetLabel("Table 5");
myContainer.AddShape().SetLabel("Table 6");
myContainer.AddShape().SetLabel("Table 7");

var vsJSON = myDocument.toJSON(); //turn the VisualScript object constructed using the API into a JSON string
vsCompleteCallback(vsJSON); //pass the JSON string into the callback to trigger the creation of a document.
}

VisualScript shape row

Note that the ShapeContainer has an Arrangement property which is set to "Row". By default the ShapeContainer Arrangement is "Square" which attempts to make a square matrix arrangement. Omitting the "Arrangement" property, or replacing it with "Square" gives:

VisualScript shape set to square arrangement

You can control the maximum number of shapes in each row using a "Wrap" property combined with the Row Arrangement. Here we set the rows to wrap at every fourth shape:

{
var myDocument=new VS.Document();
var rootShape=myDocument.GetTheShape();
var myContainer=rootShape.AddShapeContainer(VS.ShapeContainerArrangement.Row);
myContainer.SetWrap(4);
myContainer.AddShape().SetLabel("Table 1");
myContainer.AddShape().SetLabel("Table 2");
myContainer.AddShape().SetLabel("Table 3");
myContainer.AddShape().SetLabel("Table 4");
myContainer.AddShape().SetLabel("Table 5");
myContainer.AddShape().SetLabel("Table 6");
myContainer.AddShape().SetLabel("Table 7");

var vsJSON = myDocument.toJSON(); //turn the VisualScript object constructed using the API into a JSON string
vsCompleteCallback(vsJSON); //pass the JSON string into the callback to trigger the creation of a document.
}
VisualScript shape with wrapping set

Setting the Arrangement to "Column" shows all the shapes arranged vertically:

VisualScript shape column

The Wrap property can also be used to control the maximum number of shapes in a column.

Hiding the Parent Shape

In our example of showing a shape for each table in a database you probably don't want to actually display the parent shape as a border around the seven shapes. You can remove the parent shape using the "Hide" property:

{
var myDocument=new VS.Document();
var rootShape=myDocument.GetTheShape();
rootShape.Hide();
var myContainer=rootShape.AddShapeContainer(VS.ShapeContainerArrangement.Row);
myContainer.AddShape().SetLabel("Table 1");
myContainer.AddShape().SetLabel("Table 2");
myContainer.AddShape().SetLabel("Table 3");
myContainer.AddShape().SetLabel("Table 4");
myContainer.AddShape().SetLabel("Table 5");
myContainer.AddShape().SetLabel("Table 6");
myContainer.AddShape().SetLabel("Table 7");

var vsJSON = myDocument.toJSON(); //turn the VisualScript object constructed using the API into a JSON string
vsCompleteCallback(vsJSON); //pass the JSON string into the callback to trigger the creation of a document.
}

VisualScript row with hidden parent

Controlling the Spacing Between Shapes

By default the space between each shape in a ShapeContainer, and the space between the shapes and their container is 0,5 inches (50/100). The ShapeContainer properties HorizontalSpacing and VerticalSpacing are used to override the default of 50/100.

{
var myDocument=new VS.Document();
var rootShape=myDocument.GetTheShape();
rootShape.Hide();
var myContainer=rootShape.AddShapeContainer(VS.ShapeContainerArrangement.Matrix);
myContainer.SetHorizontalSpacing(25);
myContainer.SetVerticalSpacing(75);
myContainer.AddShape().SetLabel("Table 1");
myContainer.AddShape().SetLabel("Table 2");
myContainer.AddShape().SetLabel("Table 3");
myContainer.AddShape().SetLabel("Table 4");
myContainer.AddShape().SetLabel("Table 5");
myContainer.AddShape().SetLabel("Table 6");
myContainer.AddShape().SetLabel("Table 7");

var vsJSON = myDocument.toJSON(); //turn the VisualScript object constructed using the API into a JSON string
vsCompleteCallback(vsJSON); //pass the JSON string into the callback to trigger the creation of a document.
}
VisualScript row spacing

Arranging Shapes that are Different Sizes

In all of our examples so far the shapes in the ShapeContainer were all the same size, but in most applications this will not true.

Rows of shapes with different heights can be arranged so their tops, middles or bottoms align. You control this with the SetAlignV method of the ShapeContainer. This is "Top" by default.

Columns of shapes with different widths can be arranged so the lefts, centers or rights align. You control this with the SetAlignH method of the ShapeContainer. This is "Center" by default.

The following script shows the default behavior.

{
var myDocument=new VS.Document();
var rootShape=myDocument.GetTheShape();
var myContainer=rootShape.AddShapeContainer(VS.ShapeContainerArrangement.Matrix);
myContainer.AddShape().SetLabel("Table 1").SetMinHeight(150);
myContainer.AddShape().SetLabel("Table 2");
myContainer.AddShape().SetLabel("Table 3");
myContainer.AddShape().SetLabel("Table 4");
myContainer.AddShape().SetLabel("Table 5").SetMinWidth(300);
myContainer.AddShape().SetLabel("Table 6");
myContainer.AddShape().SetLabel("Table 7");
var vsJSON = myDocument.toJSON(); //turn the VisualScript object constructed using the API into a JSON string
vsCompleteCallback(vsJSON); //pass the JSON string into the callback to trigger the creation of a document.
}
VisualScript default alignment

Setting SetAlignV to "Middle" and SetAlignH to "Left" gives this:

{
var myDocument=new VS.Document();
var rootShape=myDocument.GetTheShape();
var myContainer=rootShape.AddShapeContainer(VS.ShapeContainerArrangement.Matrix);
myContainer.SetAlignH(VS.TextAlignH.Left);
myContainer.SetAlignV(VS.TextAlignV.Middle);
myContainer.AddShape().SetLabel("Table 1").SetMinHeight(150);
myContainer.AddShape().SetLabel("Table 2");
myContainer.AddShape().SetLabel("Table 3");
myContainer.AddShape().SetLabel("Table 4");
myContainer.AddShape().SetLabel("Table 5").SetMinWidth(300);
myContainer.AddShape().SetLabel("Table 6");
myContainer.AddShape().SetLabel("Table 7");
var vsJSON = myDocument.toJSON(); //turn the VisualScript object constructed using the API into a JSON string
vsCompleteCallback(vsJSON); //pass the JSON string into the callback to trigger the creation of a document.
}
Setting alignment

Drawing Lines Between Shapes in a Container

Extending our example of shapes representing tables in a database, we might want to connect shapes with a line showing relationships between tables. For example suppose there is a one to many relationship between Table 1 and Tables 5 and 7.

You create these lines by adding Returns to the Document using the AddReturn method and supplying the IDs of the shapes you want to connect.

{
var myDocument=new VS.Document();
var rootShape=myDocument.GetTheShape();
var myContainer=rootShape.AddShapeContainer(VS.ShapeContainerArrangement.Row);
myContainer.SetWrap(4);
myContainer.AddShape().SetLabel("Table 1").SetID(1);
myContainer.AddShape().SetLabel("Table 2");
myContainer.AddShape().SetLabel("Table 3");
myContainer.AddShape().SetLabel("Table 4");
myContainer.AddShape().SetLabel("Table 5").SetID(5);
myContainer.AddShape().SetLabel("Table 6");
myContainer.AddShape().SetLabel("Table 7").SetID(7);
var myReturn=myDocument.AddReturn(1,5);
myReturn.SetEndDirection(VS.Directions.Top).SetEndArrow(VS.Arrowheads.CrowsFoot);
myReturn=myDocument.AddReturn(1,7);
myReturn.SetEndDirection(VS.Directions.Top).SetEndArrow(VS.Arrowheads.CrowsFoot);
var vsJSON = myDocument.toJSON(); //turn the VisualScript object constructed using the API into a JSON string
vsCompleteCallback(vsJSON); //pass the JSON string into the callback to trigger the creation of a document.
}
VisualScript shape row with connectors

Note that the "EndArrow" is one of the custom arrowheads called CrowsFoot. For a detailed list of arrowhead styles available, read the VSON markup reference guide.

13/18 Page