The VisualScript Cookbook

4/18 Page

Drawing Lines with VisualScript

VisualScript relies on some simple, rule-based mechanisms to connect shapes so you can generate even complex diagrams with just a few lines of code. There are two basic ways you can connect shapes. One uses the ShapeConnector to connect shapes in a hierarchical diagram like an org chart, decision tree, or mind map. The other is a single line called a "return" that can connect any two shapes in a free-form way. This is useful for flowcharts, but can be used for any type of diagram.

Using ShapeConnectors

Lines connecting shapes in tree or flow arrangements are drawn automatically by ShapeConnectors. The thickness, pattern and color of these lines are the default for the template or can be defined explicitly for the ShapeConnector.

At a basic level, a simple hierarchy is very easy to create.

{
  var myDocument=new VS.Document();
  var rootShape=myDocument.GetTheShape();
  var myConnector=rootShape.AddShapeConnector(VS.ShapeConnectorTypes.OrgChart);
  myConnector.AddShape();
  myConnector.AddShape();
}
Simple org chart built with a ShapeConnector

You can now specify additional styling if you want.

{
   var myDocument=new VS.Document();
   var rootShape=myDocument.GetTheShape();
   var myConnector=rootShape.AddShapeConnector(VS.ShapeConnectorTypes.OrgChart);
   myConnector.SetLineThickness(3).SetLineColor("#FF0000");
   myConnector.AddShape();
   myConnector.AddShape();
}
Change connector line color to red

The properties of a ShapeConnector are passed down to ShapeConnectors of its child shapes.

{
  var myDocument=new VS.Document();
  var rootShape=myDocument.GetTheShape();
  var myConnector=rootShape.AddShapeConnector(VS.ShapeConnectorTypes.OrgChart);
  myConnector.SetLineThickness(3).SetLineColor("#FF0000");
  var myShape=myConnector.AddShape();
  myConnector.AddShape();
  var myChildConnector=myShape.AddShapeConnector();
  myChildConnector.AddShape();
  myChildConnector.AddShape();
}
VisualScript simple org chart with red lines with children

Using Returns

A return can be used to connect any two shapes in any type of diagram. The most common use for a return line is to connect back to a previous shape in a flowchart.

{
  var myDocument=new VS.Document();
  var rootShape=myDocument.GetTheShape();
  var myConnector=rootShape.AddShapeConnector(VS.ShapeConnectorTypes.Flowchart);
  myConnector.AddShape().SetID(1);
  myConnector.AddShape().SetID(21);
  myDocument.AddReturn(21,1);    
}
Return line

The returns array is defined at the root level of the VisualScript Object. Each return object in the array must have a "StartID" and an "EndID" defined for the line to appear. These ID's are the ID's of the shapes that the line connects. The "ID" is an optional property of any shape:

myShape.SetID(1);

The ID's are arbitrary but should be unique. If they are not unique, the first shape encountered with a particular ID will be the one that is used.

By default, returns connect to the bottom center of any shape they are attached to. You can control this with the optional parameters StartDirection and EndDirection. Four values are possible: "Top", "Bottom", "Left" and "Right". The default is "Bottom".

{
  var myDocument=new VS.Document();
  var rootShape=myDocument.GetTheShape();
  var myConnector=rootShape.AddShapeConnector(VS.ShapeConnectorTypes.Flowchart);
  myConnector.AddShape().SetID(1);
  myConnector.AddShape().SetID(21);
  var myReturn=myDocument.AddReturn(21,1);
  myReturn.SetStartDirection(VS.Directions.Right).SetEndDirection(VS.Directions.Top);
}
Show the return live above the shape

Returns also share the normal line appearance parameters with ShapeConnectors such as thickness, color, and pattern.

Curved Returns

Using the Curved() method changes the shape of the return to a curved line.

{
  var myDocument=new VS.Document();
  var rootShape=myDocument.GetTheShape();
  var myContainer=rootShape.AddShapeContainer(VS.ShapeContainerArrangement.Matrix);
  myContainer.AddShape().SetID(1);
  myContainer.AddShape();
  myContainer.AddShape();
  myContainer.AddShape().SetID(2);
  var myReturn=myDocument.AddReturn(1,2);
  myReturn.SetStartDirection(VS.Directions.Right).SetEndDirection(VS.Directions.Left).Curved();
}
Curved line

Using Arrowheads

By default, returns have a simple arrowhead at the end of the line. ShapeConnectors have arrowheads by default if the template used specifies this. You can use the methods SetEndArrow() and SetStartArrow() to specifically enforce the type of arrowhead used on a ShapeConnector or Return.

Setting an arrow to "0" turns off the arrowhead at the end of a line.

{
  var myDocument=new VS.Document();
  var rootShape=myDocument.GetTheShape();
  var myContainer=rootShape.AddShapeContainer(VS.ShapeContainerArrangement.Row);
  myContainer.AddShape().SetID(1);
  myContainer.AddShape().SetID(2);
  var myReturn=myDocument.AddReturn(1,2);
  myReturn.SetStartDirection(VS.Directions.Right).SetEndDirection(VS.Directions.Left).SetEndArrow(0);
}
Two boxes connected with a line inside a ShapeContainer

The arrowhead styles are determined by an array of arrowheads referenced by ID or name as shown below. The arrow "4" draws the line with the fifth arrowhead from the left in the top row of the standard selection of arrowheads:

VisualScript arrowheads

The "6" arrow picks the first arrowhead in the second row and so on.

We've also named the arrows with more descriptive terms. VS.Arrowheads.FilledSquare will also get you the 6th arrow. For a detailed list of arrowhead styles available, read the VSON markup reference guide.

{   
  var myDocument=new VS.Document();
  var rootShape=myDocument.GetTheShape();
  var myContainer=rootShape.AddShapeContainer(VS.ShapeContainerArrangement.Row);
  myContainer.AddShape().SetID(1);
  myContainer.AddShape().SetID(2);
  var myReturn=myDocument.AddReturn(1,2);
  myReturn.SetStartDirection(VS.Directions.Right).SetEndDirection(VS.Directions.Left).SetEndArrow(VS.Arrowheads.FilledSquare);
}
Two shapes connected with arrowheads

Adding Text to a Line

Both ShapeConnector lines and Return lines can show text labels.

The label for a ShapeConnector connector line that connects to a shape is specified in the definition of the Shape using the SetLineLabel() method.

{
  var myDocument=new VS.Document();
  var rootShape=myDocument.GetTheShape();
  var myConnector=rootShape.AddShapeConnector(VS.ShapeConnectorTypes.Flowchart);
  var myShapeA=myConnector.AddShape();
  myShapeA.SetLabel("Shape A").SetLineLabel("label A");
  var myShapeB=myConnector.AddShape();
  myShapeB.SetLabel("Shape B").SetLineLabel("label B");
}
VisualScript lines with text

Note that the label appears on the line going into the shape.

For Returns, text is added by including using a SetLabel() method on the return object.

{  
  var myDocument=new VS.Document();
  var rootShape=myDocument.GetTheShape();
  var myConnector=rootShape.AddShapeConnector(VS.ShapeConnectorTypes.Flowchart);
  myConnector.AddShape().SetID(1);
  myConnector.AddShape().SetID(21);
  var myReturn=myDocument.AddReturn(21,1);
  myReturn.SetLabel("Repeat");
}
VisualScript return line with text

You can specify the font, size, color and style of the text on a line (ShapeConnector or Return).

{   
  var myDocument=new VS.Document();
  var rootShape=myDocument.GetTheShape();
  var myConnector=rootShape.AddShapeConnector(VS.ShapeConnectorTypes.Flowchart);
  var myShapeA=myConnector.AddShape();
  myShapeA.SetLabel("Shape A").SetLineLabel("label A");
  var myShapeB=myConnector.AddShape();
  myShapeB.SetLabel("Shape B").SetLineLabel("label B");
  myConnector.SetTextSize(18).SetTextColor("#D60000");
}
VisualScript line with color text
4/18 Page