VS.Table()
A table subdivides a shape into rows and columns of cells.
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);
These methods return the objects they add or get:
The following methods modify the properties of a VS.Table() object and can be chained:
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.
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.
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);
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.
Example
myTable=myTable.SetRowHeight(50);
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.
Example
myTable=myTable.SetAlternateRows("#FF8080","#80B8E0");
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);
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.
Example
myTable=myTable.SetShapeMarginH(50);
Syntax
myTable=myTable.SetShapeMarginH(margin);
Usage
This method overrides the default spacing between the right and left edges of a cell and a shape contained in that cell. This is 20/100" by default.
Example
myTable=myTable.SetShapeMarginV(50);
Syntax
myTable=myTable.SetShapeMarginV(margin);
Usage
This method overrides the default spacing between the top and bottomedges of a cell and a shape contained in that cell. This is 20/100" by default.
Example
myTable=myTable.JoinAcross(1,1,1);
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.
Example
myTable=myTable.JoinDown(1,1,2);
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.
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.
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.
Example
myRow=myRow.SetHeight(50);
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.
Example
myRow=myRow.SetLineColor("#FF0000");
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
Example
myRow=myRow.SetLinePattern(VS.LinePatterns.Dotted);
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.
Example
myRow=myRow.SetLineThickness(4);
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.
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.
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.
Example
myColumn=myColumn.SetWidth(100);
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.
Example
myColumn=myColumn.SetLineColor("#FF0000");
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
Example
myColumn=myColumn.SetLinePattern(VS.LinePatterns.Dotted);
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.
Example
myColumn=myColumn.SetLineThickness(4);
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.
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:
- AddExpandedView() - Add a child document that will display another VisualScript image in a pop-up or page.
- AddShape() - Add a shape to a table cell
All of the other methods return the VS.Cell() object and so calls to them my be chained together:
AddExpandedView()
Example
myDocument=myCell.AddExpandedView();
Syntax
myDocument=myCell.AddExpandedView();
Usage
This method returns a VS.Document() that can be used to create a full VisualScript
diagram that is displayed as a tooltip when the expanded view icon is clicked on the parent cell.
Large ExpandedViews become a second page of a VisualScript diagram.
Example
myCell=myTable.AddCell(2,2);
myShape=myCell.AddShape();
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.
In this one the shape is the parent of a ShapeConnector
You can add appear to add multiple shapes to a cell by making the added shape the parent of a ShapeContainer and hiding it:
Example
myCell.SetCellDisplayRectAsText(true);
SetCellDisplayRectAsText = false
SetCellDisplayRectAsText = true
Syntax
myCell=myCell.SetHyperlink(state);
Usage
This method causes any image displayed in the cell to be indented by the text margins instead of filling the cell to the edges of the cell (the default behavior).
Example
myCell.SetHyperlink("https://www.smartdraw.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.
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
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.
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.
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.
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.
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.
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.
Example
myCell.SetTextBold(true);
Syntax
myCell=myCell.SetTextBold(bold);
Usage
This method sets the text inside a cell to bold when true.
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
Example
myCell.SetTextFont("Copperplate");
Syntax
myCell=myCell.SetTextFont(fontname);
Usage
This method overrides the font setting of the text inside a cell.
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.smartdraw.com");
Syntax
myCell=myCell.SetTextHyperlink(url);
Usage
This method adds a hyperlink to the text inside a cell.
Example
myCell.SetTextItalic(true);
Syntax
myCell=myCell.SetTextItalic(italic);
Usage
Set this to true to make the text inside a cell italic.
Example
myCell.SetTextSize(18);
Syntax
myCell=myCell.SetTextBold(textsize);
Usage
This method overrides the default text size inside a cell using points.
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.
Example
myCell.SetTextUnderline(true);
Syntax
myCell=myCell.SetTextUnderline(underline);
Usage
This method underlines any text inside the cell when set to true.
