VS.Table()

A table subdivides a shape into rows and columns of cells.

VisualScript table

An instance of a VS.Table() is created by adding one to a VS.Shape() object. The number of rows and columns are required in the AddTable() method.

myTable=myShape.AddTable(3,2);

VS.Table() Methods

These methods return the objects they add or get:

The following methods modify the properties of a VS.Table() object and can be chained:

AddCell()

Example

myCell=myTable.AddCell(1,2);

Syntax

myCell=myTable.AddCell(Row,Column);

Usage

This method adds a VS.Cell() object to a table at the specified Row and Column location. Note that Row and Column coordinates are 1-based not 0-based. So the top left cell is 1,1 not 0,0.

Creating a table with 3 rows and 2 columns subdivides it into 6 cells visually, but to set properties of these cells you must first create a VS.Cell() object and set its properties.

If there is already a cell object created for the Row and Column you specify, the existing cell object is returned.

AddColumnProperties()

Example

myColumn=myTable.AddColumnProperties(1);

Syntax

myColumn=myTable.AddColumnProperties(Index);

Usage

This method adds a VS.ColumnProperties() object to a table at the column specified by the Index. Note that column indexes are 1-based not 0-based. So the left column has an Index of 1 not 0.

Creating a table with 2 column subdivides it into 2 columns visually, but to set properties of these columns you must first create a VS.ColumnProperties() object and set its properties.

If there is already a ColumnProperties object created for the column you specify, the existing ColumnProperties object is returned.

AddRowProperties()

Example

myRow=myTable.AddRowProperties(1);

Syntax

myRow=myTable.AddRowProperties(Index);

Usage

This method adds a VS.RowProperties() object to a table at the row specified by the Index. Note that row indexes are 1-based not 0-based. So the top row has an Index of 1, not 0.

Creating a table with 3 rows subdivides it into 3 rows visually, but to set properties of these rows you must first create a VS.RowProperties() object and set its properties.

If there is already a RowProperties object created for the rows you specify, the existing RowProperties object is returned.

GetCell()

Example

myCell=myTable.GetCell(1,2);

Syntax

myCell=myTable.GetCell(Row,Column);

Usage

This method gets a VS.Cell() object belonging to the table at the coordinates supplied Row and Column. Note that the Row and Column coordinates are 1-based not 0-based. So the top left cell is 1,1 not 0,0. If no cell has been created at these coordinates, this method returns null.

SetColumnWidth()

Example

myTable=myTable.SetColumnWidth(100);

Set column width

Syntax

myTable=myTable.SetColumnWidth(width);

Usage

This method overrides the minimum width of all the columns in a table and sets it to the value passed. The value is set in increments of 1/100 of an inch. This resizes the shape that contains the table. Text inside cells can grow a column wider than the value set depending on the TextGrow property of the parent shape.

SetRowHeight()

Example

myTable=myTable.SetRowHeight(50);

Set row height

Syntax

myTable=myTable.SetRowHeight(height);

Usage

This method overrides the minimum height of all the rows in a table and sets it to the value passed. The value is set in increments of 1/100". This resizes the shape that contains the table. Text inside cells can grow a row taller than the value set depending on the TextGrow property of the parent shape.

SetAlternateRows()

Example

myTable=myTable.SetAlternateRows("#FF8080","#80B8E0");

Set alternative rows

Syntax

myTable=myTable.SetAlternateRows(color1,color2);

Usage

This method alternates the background color of rows in a table. By default, this combination is gray and white, but you can specify any two colors.

SetAlternateColumns()

Example

myTable=myTable.SetAlternateColumns("#FF8080","#80B8E0",2,4,2,false);

Alternate columns

Syntax

myTable=myTable.SetAlternateRows(color1,color2,StartRow,EndRow,StartCol,UseFirstRow);

Usage

This method alternates the background color of columns in a table. By default, this combination is gray and white, but you can specify any two colors.

You can also specify the range of rows to alternate from StartRow to EndRow. If these parameters are undefined, all rows are included.

The StartCol parameter is also optional and starts the alternation at the specified column. If this is undefined all columns are alternated.

UseFirstRow is a boolean that alternates the columns based on the columns present for the first row. This only applies to Timelines (which are derived from Tables) since for normal tables alternating columns are applied before joins that change the number of columns in the top row.

JoinAcross()

Example

myTable=myTable.JoinAcross(1,1,1);

Join across

Syntax

myTable=myTable.JoinAcross(Row, Column,ntojoin);

Usage

This method joins cells in a the row specified by the Row index starting at the column specified by the Column index. The indexes are 1-based not 0-based. The ntojoin value determines the number of cells to the right of the target cell that will be joined.

JoinDown()

Example

myTable=myTable.JoinDown(1,1,2);

Join down

Syntax

myTable=myTable.JoinDown(Row, Column,ntojoin);

Usage

This method joins cells in a the column specified by Column index starting at the row specified by the Row index. The indexes 1-based not 0-based. The notojoin value determines the number of cells below the target cell that will be added to it.

VS.RowProperties()

An instance of a VS.RowProperties() is created by adding one to a VS.Table() object:

myRow=myTable.AddRowProperties(1);

The parameter it passes is the index of a row in the table. The first row has an index of 1 not 0. If the RowProperties object already exists for the given index, the AddRowProperties returns the object and does not create a new one.

VS.RowProperties() Methods

All of the methods return the RowProperties() object and so calls to them may be chained together:

  • FixedHeight() - This method sets a given row a fixed height that does not change as the shape containing the table grows
  • SetHeight() - Override the minimum height of for the row in 1/100"
  • SetLineColor() - Override the color of the line that separates this row from the row below it. This has no effect on the bottom row.
  • SetLinePattern() - Override the pattern of the line (dashed, dotted, or solid) that separates this row from the row below it. This has no effect on the bottom row.
  • SetLineThickness() - Override the thickness of the line that separates this row from the row below it. This has no effect on the bottom row.
  • All of the properties of a cell. Using Cell methods with RowProperties applies them to all the cells in the row.

FixedHeight()

Example

myRow=myRow.FixedHeight();

Syntax

myRow=myRow.FixedHeight();

Usage

This method causes the row to maintain a fixed height even as the shape that contains the table grows. This is often used to fix the height of a title row in a table.

SetHeight()

Example

myRow=myRow.SetHeight(50);

Set table height

Syntax

myRow=myRow.SetHeight(height);

Usage

This method sets the minimum height of a row in 1/100 of an inch increments. The height can increase if more text than can be accommodated is entered into a cell in the row.

SetLineColor()

Example

myRow=myRow.SetLineColor("#FF0000");

Set table line color

Syntax

myRow=myRow.SetLineColor(color);

Usage

This method overrides the color of the line that separates this row from the row below it. This has no effect on the bottom row.

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

SetLinePattern()

Example

myRow=myRow.SetLinePattern(VS.LinePatterns.Dotted);

Set line pattern on a grid

Syntax

myRow=myRow.SetLinePattern(pattern);

Usage

This method overrides the pattern of the line that separates this row from the row below it. The default is solid, but you can also choose dashed and dotted. This has no effect on the bottom row.

SetLineThickness()

Example

myRow=myRow.SetLineThickness(4);

Set line thickness on a grid

Syntax

myRow=myRow.SetLineThickness(thickness);

Usage

This method overrides the thickness of the line that separates this row from the row below it. This has no effect on the bottom row.

VS.ColumnProperties()

An instance of a VS.ColumnProperties() is created by adding one to a VS.Table() object:

myColumn=myTable.AddColumnProperties (1);

The parameter passes is the index of the row in the table. The first column has an index if 1 not 0. If the ColumnProperties object already exists for the specificed index, the AddColumnProperties returns the object and does not create a new one.

VS.ColumnProperties() Methods

All of the methods return the ColumnProperties object and so calls to them my be chained together.

  • FixedWidth() - This method sets a given column a fixed width that does not change as the shape containing the table grows
  • SetWidth() - Override the minimum width of for this column in 1/100"
  • SetLineColor() - Override the color of the line that separates this column from the column to the right of it. This has no effect on the rightmost column.
  • SetLinePattern() - Override the pattern of the line that separates this column from the column to the right of it. This has no effect on the rightmost column.
  • SetLineThickness() - Override the thickness of the line separates this column from the column to the right of it. This has no effect on the rightmost column.
  • All of the properties of a cell. Using Cell methods with ColumnProperties applies them to all the cells in the column.

FixedWidth()

Example

myColumn=myColumn.FixedWidth();

Syntax

myColumn=myColumn.FixedWidth();

Usage

This method causes the column to maintain a fixed width as the shape that contains the table grows. This is often used to fix the width of a row title column in a table. It only works for the left most column.

SetWidth()

Example

myColumn=myColumn.SetWidth(100);

Set column width

Syntax

myColumn=myColumn.SetWidth(width); //in 1/100"

Usage

This method sets the minimum width of a column. The width can increase if more text than can be accommodated is entered into a cell in the column.

SetLineColor()

Example

myColumn=myColumn.SetLineColor("#FF0000");

Set table line color

Syntax

myColumn=myColumn.SetLineColor(color);

Usage

This method overrides the color of the line that separates this column from the column to the right of it. This has no effect on the rightmost column.

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

SetLinePattern()

Example

myColumn=myColumn.SetLinePattern(VS.LinePatterns.Dotted);

Set table line patterns for columns

Syntax

myColumn=myColumn.SetLinePattern(pattern);

Usage

This method overrides the pattern of the line that separates this column from the column to the right of it. This has no effect on the rightmost column. The default is Solid and you can also choose Dashed and Dotted.

SetLineThickness()

Example

myColumn=myColumn.SetLineThickness(4);

Set line thickness for a column

Syntax

myColumn=myColumn.SetLineThickness(thickness);

Usage

This method overrides the thickness of the line that separates this column from the column to the right of it. This has no effect on the rightmost column.

VS.Cell()

An instance of a VS.Cell() is created by adding one to a VS.Table() object:

myColumn=myTable.AddCell (1,2);

When adding a new cell, pass the method the index of the row and column that will define the position of the cell. The first row and column in the table have an index 1, not 0. If a Cell object already exists for the specified row and column, AddCell() returns the existing cell object and does not create a new one.

VS.Cell() Methods

The following method returns a shape:

All of the other methods return the VS.Cell() object and so calls to them my be chained together:

AddShape()

Example

myCell=myTable.AddCell(2,2);

myShape=myCell.AddShape();

Add table shape

Syntax

myShape=myCell.AddShape();

Usage

This method sets adds a shape to a cell in a table.The cell (and the parent shape of the table) grow to accommodate the shape's size with a margin of 20/100" between the edge of the shape and the cell border.

The shape added can itself be the parent shape of a ShapeConnector, a ShapeContainer or a another Table. In which case the cell grows to accommodate the full arrangement of shapes owned by the added shape.

In this example the shape added has its own table with a shape added.

Table with shape

In this one the shape is the parent of a ShapeConnector

VisualScript table with shape connector parent

You can add appear to add multiple shapes to a cell by making the added shape the parent of a ShapeContainer and hiding it:

VisualScript tablecell with multiple shapes

Example

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

Syntax

myCell=myCell.SetHyperlink(urlstring);

Usage

This method applies a hyperlink to a cell. This appears as a link icon in the bottom right of the table cell. You can set a hyperlink for the whole cell or just the text inside the cell using two different methods. When the hyperlink is set to the cell, you will have to click on the icon to open the hyperlink.

SetFillColor()

Example

myCell.SetFillColor("#80FF0000");

Syntax

myCell=myCell.SetFillColor(color);

Usage

This method overrides the fill color of a cell.

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

SetImage()

Example

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

Syntax

myCell=myCell.SetImage(url);

Usage

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

SetLabel()

Example

myCell.SetLabel("Hello World");

Syntax

myCell=myCell.SetLabel(label);

Usage

This method lets you put text inside a cell. The text automatically wraps inside the cell and may make the cell grow to accommodate it all. You can use the VS.Cell.Truncate() method to restrict the length of text that will display and add a tool tip that shows all of the text.

SetNote()

Example

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

Syntax

myCell=myCell.SetNote(label);

Usage

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

SetNoteIcon()

Example

myCell.SetNoteIcon(VS.NoteIcons.Info);

Syntax

myCell=myCell.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.

SetTextAlignH()

Example

myCell.SetTextAlignH(VS.TextAlignH.Left);

Syntax

myCell=myCell.SetTextAlignH(textalignh);

Usage

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

SetTextAlignV()

Example

myShape.SetTextAlignV(VS.TextAlignV.Top);

Syntax

myCell=myCell.SetTextAlignV(textalignv);

Usage

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

SetTextBold()

Example

myCell.SetTextBold(true);

Syntax

myCell=myCell.SetTextBold(bold);

Usage

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

SetTextColor()

Example

myCell.SetTextColor("#0000FF");

Syntax

myCell=myCell.SetTextColor(color);

Usage

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

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

myCell.SetTextFont("Copperplate");

Syntax

myCell=myCell.SetTextFont(fontname);

Usage

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

SetTextGrow()

Example

myCell.SetTextGrow(VS.TextGrow.Horizontal);

Syntax

myCell=myCell.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",
};

Example

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

Syntax

myCell=myCell.SetTextHyperlink(url);

Usage

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

SetTextItalic()

Example

myCell.SetTextItalic(true);

Syntax

myCell=myCell.SetTextItalic(italic);

Usage

Set this to true to make the text inside a cell italic.

SetTextSize()

Example

myCell.SetTextSize(18);

Syntax

myCell=myCell.SetTextBold(textsize);

Usage

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

SetTextTruncate()

Example

myCell.SetTextTruncate(30);

Syntax

myCell=myCell.SetTextTruncate(nchar);

Usage

This method restricts the number of characters that can appear inside a cell 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 cell.

SetTextUnderline()

Example

myCell.SetTextUnderline(true);

Syntax

myCell=myCell.SetTextUnderline(underline);

Usage

This method underlines any text inside the cell when set to true.