VS.Shape()

This class defines a shape in a VisualScript document. An instance of VS.Shape() is the basic building block of a visual with a border, a fill color, and text inside.

Visualscript Shape

A Shape is also the parent of all the objects that arrange other shapes on a page like ShapeConnectors and ShapeContainers.

Shape parent

One of the key concepts of VisualScript is the recursive nature of Shapes and ShapeConnectors, ShapeContainers. Shapes added to ShapeConnectors and ShapeContainers can themselves be the parent of other ShapeConnectors and ShapeContainers allowing you to create virtually any arrangement of hierarchical shapes on a page. For more examples, see the VisualScript Cookbook.

The VS.Document() automatically contains one VS.Shape() object (the root shape). This Shape object may be obtained with the call:

var rootShape=myDocument.GetTheShape();

You can add additional shapes to the document by calling the AddShape() method of either a ShapeContainer or ShapeConnector, objects that control shape positions in the document.

Below is an example of the syntax for adding a shape to a ShapeContainer.

var myContainer=rootShape.AddShapeContainer();

myShape=myContainer.AddShape();

using myShape= new VS.Shape() will return a shape, but it will not be part of your VisualScript document. Other than the root shape, the only way to add a shape to your document is to create one with an AddShape() method.

VS.Shape() Methods

The following methods return the object added:

The following methods return the Shape object and can be chained together (myShape.SetID().SetTextColor().SetLabel() etc).

  • Hide() - Hide the parent shape of a ShapeContainer
  • SetHyperlink() - Add a hyperlink to a shape
  • SetFillColor() - Override the fill color of a shape
  • SetID() - Set the ID used by VS.Return() to a shape
  • SetImage() - Fill a shape with an image
  • SetLabel() - Set the text inside a shape
  • SetLineColor() - Override the border color of a shape
  • SetLineLabel() - Set the text that appears on a ShapeConnector entering a shape
  • SetLinePattern() - Override the pattern (dotted, dashed, etc) of the border of a shape
  • SetLineThickness() - Override the thickness of the border of a shape
  • SetMinHeight() - Override the height of a shape before any text is added
  • SetMinWidth() - Override the width of a shape before any text is added
  • SetNote() - Add a note to a shape
  • SetNoteIcon() - Set the icon for the note on a shape
  • SetShapeDataRow() - Assign a row in a DataTable to a shape
  • SetShapeType() - Override the default type of a shape. By default, shapes are rectangles, but you can use ovals, circles, rounded rectangles, squares, and diamonds
  • SetTextAlignH() - Override the horizontal justification of text inside the shape
  • SetTextAlignV() - Override the vertical justification of text inside the shape
  • SetTextBold() - Overrides the bold state of the text inside a shape
  • SetTextColor() - Override the default color of the text inside a shape
  • SetTextFont() -Override the default font setting for the text inside a shape
  • SetTextGrow() - Override the way text makes a shape grow
  • SetTextHyperlink() - Add a hyperlink to the text inside a shape
  • SetTextItalic() - Overrides the italic state of the text inside a shape
  • SetTextMargin() - Override the spacing between the inside edge of the shape and the text inside it
  • SetTextSize() - Override the text size for the text inside a shape
  • SetTextTruncate() - Limit the number of characters that can show inside a shape and add a note to contain any truncated text
  • SetTextUnderline() - Overrides the underlined state of the text inside a shape

AddShapeConnector()

Example

myShapeConnector=myShape.AddShapeConnector(VS.ShapeConnectorTypes,Decisiontree);

Syntax

myShapeConnector=myShape.AddShapeConnector(ShapeConnectorType);

Usage

This method adds an instance of a VS.ShapeConnector() object to the shape. The ShapeConnectorType specified determines the layout of the shapes that will be added to the ShapeConnector. If no value is passed, the default used is hierarchy.

AddShapeContainer()

Example

myShapeContainer=myShape.AddShapeContainer(VS.ShapeContainerArrangement.Matrix);

Syntax

myShapeContainer=myShape.AddShapeContainer(arrangement);

Usage

This method adds instance of a VS.ShapeContainer() object to the shape. The arrangement passed to method determines the layout of the shapes that will be added to the ShapeContainer. If no value is passed, the default used will be row.

AddShapeDataRow()

Example

myDataRow=myShape.AddShapeDataRow(myDocument,1);

Syntax

myDataRow=myShape.AddShapeDataRow(Document,TableID);

Usage

This method adds a new row to a previously defined VS.DataTable() object. The row is assigned to the shape.

A DataTable object is created by adding one to the VisualScript document with its AddDataTable() method. The row added and returned by AddShapeDataRow() has empty values for all of the columns. Values are set using the VS.DataRow().SetValues() method.

AddTable()

Example

myTable=myShape.AddTable(3,2);

VisualScript table

Syntax

myTable=myShape.AddTable(NRows,NColumns);

Usage

This method adds a VS.Table() object to a shape subdividing it into rows and columns of cells. The table attempts to fit inside the shape without changing its size, however each cell has a minimum height and width determined by the text size which may cause the shape to grow to accommodate it. The default text settings for each cell are inherited from the shape.

AddTimeline()

Example

myTimeline=myShape.AddTimeline(VS.Timeline_Arrangements.Row1);

VisualScript timeline

Syntax

myTimeline=myShape.AddTimeline(arrangement);

Usage

This method adds a VS.Timeline() object to a shape. A timeline is 12 inches long by default and starts "today". Events are added to the timeline using the AddEvent() method of the Timeline. By default, timelines automatically adjust their start date, end date and scale to accommodate all of the events added. They also adjust the position or size of event shapes so that they don't overlap.

Hide()

Example

myShape.Hide();

Hide a shape

Syntax

myShape=myShape.Hide();

Usage

The Hide() method hides a shape if it is a parent of a ShapeContainer otherwise it is ignored. This allows you to organize shapes within a container without requiring that the container appear in the final visual.

Example

myShape.SetHyperlink("https://www.visualscript.com");

Set hyperlink

Syntax

myShape=myShape.SetHyperlink(urlstring);

Usage

This method applies a hyperlink to a shape. This appears as a link icon in the bottom right. Clicking on the icon opens the hyperlink.

SetFillColor()

Example

myShape.SetFillColor("#80FF0000");

Override fill color

Syntax

myShape=myShape.SetFillColor(color);

Usage

This method overrides the fill color of a shape.

A color can be:

  • A string specifying an RGB literal in HTML format - "#FF00FF"
  • A string specifying an RGBA literal in HTML format - "#FF00FF80" - where the last byte is an opacity
  • A string specifying the name of a standard color defined by the VS.Document() SetColors() method

SetID()

Example

myShape.SetID(19);

Syntax

myShape=myShape.SetID(ID);

Usage

This assigns a shape an arbitrary numeric ID for later use in defining the shape as the start or the end of a VS.Return() object. The ID assigned to each shape should be unique.

SetImage()

Example

myShape.SetImage("https://wcs.smartdraw.com/working-smarter/img/how-to-write-a-desktop-quality-cloud-app.png");

Put an image inside a shape

Syntax

myShape=myShape.SetImage(url);

Usage

This places an image inside a shape that is loaded from the URL passed. The image is scaled to completely fill the shape while maintaining its aspect ratio.

SetLabel()

Example

myShape.SetLabel("Hello World");

Add a label inside a shape

Syntax

myShape=myShape.SetLabel(label);

Usage

SetLabel() assigns a text label to shape. The text automatically wraps inside the shape and may make the shape grow to accommodate it all. You can use the VS.Shape.Truncate() method to restrict the length of text that will display and add a tooltip that shows all of the text.

SetLineColor()

Example

myShape.SetLineColor("#00FF00");

Override line color

Syntax

myShape=myShape.SetLineColor(color);

Usage

This method overrides the border color of a shape.

A color can be:

  • A string specifying an RGB literal in HTML format - "#FF00FF"
  • A string specifying an RGBA literal in HTML format - "#FF00FF80" - where the last byte is an opacity
  • A string specifying the name of a standard color defined by the VS.Document() SetColors() method

SetLineLabel()

Example

myShape.SetLineLabel("label A");

Add text to a line

Syntax

myShape=myShape.SetLineLabel(textlabel);

Usage

This method assigns a text label to the ShapeConnector line segment that connects to the shape from the parent shape. It is used to assign labels to lines when using flowcharts.

SetLinePattern()

Example

myShape.SetLinePattern(VS.LinePatterns.Dotted);

Change the line style around a shape

Syntax

myShape=myShape.SetLinePattern(linepattern);

Usage

This method overrides the pattern of the border of the shape which is solid by default. You can use dash, dotted, or solid.

SetLineThickness()

Example

myShape.SetLineThickness(4);

Change the line thickness around a shape

Syntax

myShape=myShape.SetLineThickness(thickness);

Usage

This method overrides the thickness of the border of the shape which is 1/100" by default. The thickness parameter is in units of 1/100 inch.

SetMinHeight()

Example

myShape.SetMinHeight(100);

VisualScript set min height

Syntax

myShape=myShape.SetMinHeight(height);

Usage

This method overrides the minimum height for a shape which is 75/100" by default. The height parameter is in units of 1/100 inch. Adding text to shape may grow it height or width (or both) to accommodate all of the text. The Minimum height is the smallest height the shape can have even with no text.

SetMinWidth()

Example

myShape.SetMinWidth(100);

VisualScript set min width

Syntax

myShape=myShape.SetMinWidth(width);

Usage

This method overrides the minimum width for a shape, which is 150/100" by default. The width parameter is in units of 1/100 inch. Adding text to shape may grow the shape's height or width (or both) to accommodate all of the text. The minimum width is the smallest height the shape can have even with no text.

SetNote()

Example

myShape.SetNote("This is a note");

VisualScript set note

Syntax

myShape=myShape.SetNote(label);

Usage

This method adds a note to a shape. A note is a tool tip accessed by hovering or clicking on the note icon.

SetNoteIcon()

Example

myShape.SetNoteIcon(VS.NoteIcons.Info);

VisualScript set note icon

Syntax

myShape=myShape.SetNoteIcon(noteicon);

Usage

This method allows you to change the default icon for a note from the yellow note icon to a blue info icon.

SetShapeDataRow()

Example

myShape.SetShapeDataRow(1,12);

Syntax

myShape=myShape.SetShapeDataRow(TableID,RowID);

Usage

A Shape may be assigned a row of column values from a VS.DataTable() object. A VS.DataTable() object is added to a document using the VS.Document.AddDataTable() method. DataTables have an array of rows of values for each column in the table. Each row has a unique ID that is assigned as the row is added to the table. SetShapeDataRow() assigns a row in the table to a shape using the ID of the row and the table.

SetShapeType()

Example

myShape.SetShapeType(VS.ShapeTypes.Oval);

VisualScript set shape type

Syntax

myShape=myShape.SetShapeType(shapetype);

Usage

This method overrides the default shape type for a shape (a rectangle). The supported shape types are:

VS.ShapeTypes =
{
RoundedRectangle: "RRect",
Oval: "Oval",
Circle: "Circle",
Square: "Square",
Diamond: "Diamond",
};

plus any new shape types defined in the VS.Document.SetSymbols() command.

SetTextAlignH()

Example

myShape.SetTextAlignH(VS.TextAlignH.Left);

VisualScript set text align

Syntax

myShape=myShape.SetTextAlignH(textalignh);

Usage

This method sets the horizontal text alignment inside a shape: left, center, right.

SetTextAlignV()

Example

myShape.SetTextAlignV(VS.TextAlignV.Top);

VisualScript set text align vertical

Syntax

myShape=myShape.SetTextAlignV(textalignv);

Usage

This method sets the vertical text alignment inside a shape: top, middle, bottom.

SetTextBold()

Example

myShape.SetTextBold(true);

VisualScript set bold text

Syntax

myShape=myShape.SetTextBold(bold);

Usage

This method sets the text inside a shape to bold when true.

SetTextColor()

Example

myShape.SetTextColor("#0000FF");

VisualScript set text color

Syntax

myShape=myShape.SetTextColor(color);

Usage

This method overrides the color of the text inside a shape.

A color can be:

  • A string specifying an RGB literal in HTML format - "#FF00FF"
  • A string specifying an RGBA literal in HTML format - "#FF00FF80" - where the last byte is an opacity
  • A string specifying the name of a standard color defined by the VS.Document() SetColors() method

SetTextFont()

Example

myShape.SetTextFont("Copperplate");

VisualScript set text font

Syntax

myShape=myShape.SetTextFont(fontname);

Usage

This method overrides the font setting of the text inside a shape.

SetTextGrow()

Example

myShape.SetTextGrow(VS.TextGrow.Horizontal);

Syntax

myShape=myShape.SetTextGrow(grow);

Usage

This method sets the way a shape grows as text is added. There are three values possible:

VS.TextGrow = {
Proportional:"Proportional",
Horizontal: "Horizontal",
Vertical: "Vertical",
};

VisualScript shape growing

Example

myShape.SetTextHyperlink("https://www.visualscript.com");

VisualScript text hyperlink

Syntax

myShape=myShape.SetTextHyperlink(url);

Usage

This method adds a hyperlink to the text inside a shape.

SetTextItalic()

Example

myShape.SetTextItalic(true);

VisualScript text italic

Syntax

myShape=myShape.SetTextItalic(italic);

Usage

This makes the text inside a shape italic when set to true.

SetTextMargin()

Example

myShape.SetTextMargin(10);

VisualScript set text margin

Syntax

myShape=myShape.SetTextMargin(margin);

Usage

This method overrides the spacing between the edge of the shape and the text inside.

SetTextSize()

Example

myShape.SetTextSize(18);

VisualScript set text size

Syntax

myShape=myShape.SetTextBold(textsize);

Usage

This method overrides the default text size inside a shape using points.

SetTextTruncate()

Example

myShape.SetTextTruncate(30);

VisualScript set text truncate

Syntax

myShape=myShape.SetTextTruncate(nchar);

Usage

This method restricts the number of characters that can appear inside a shape to the value passed. If this is less than the actual number of characters, a note with the full text is automatically added to the shape.

SetTextUnderline()

Example

myShape.SetTextUnderline(true);

VisualScript set text underline

Syntax

myShape=myShape.SetTextUnderline(underline);

Usage

This method underlines any text inside a shape when set to true.