Loading document parsing libraries...
# TableNode
Class Inherits Node
## About
`TableNode` is a row-and-column container whose cells support editable rich text and embedded nodes. It provides optional header and footer rows, per-cell alignment and appearance, row and column operations, merged cells, and drag insertion into cells.
## Methods
| Name | Parameters | Return Type | Description |
| --- | :---: | :---: | --- |
| ActionItem | index As Integer | ToolbarItem | Returns the contextual toolbar item at the specified index. |
| ActiveSuggestionProvider | (None) | GraffitiProEditor.Suggestions.Provider | Returns the provider that supplies suggestions for this editable content. |
| AddChildAtPoint | node As Node <br> x As Double <br> y As Double | Boolean | Embeds a child node at the specified document coordinates and returns whether it was accepted. |
| AddColumn | (None) | (None) | Adds column to this table node. |
| AddNode | row As Integer <br> column As Integer <br> node As Node | (None) | Adds node to this table node. |
| AddRow | (None) | (None) | Adds row to this table node. |
| ApplyHTMLTextAlignment | element As GraffitiProEditor.HTMLSupport.HTMLElement | (None) | Sets TextAlignment from the supplied HTML element's text-align style, or Automatic when it has none. |
| CanAcceptChildAtPoint | node As Node <br> x As Double <br> y As Double | Boolean | Returns whether the supplied node can be embedded at the specified document coordinates. |
| CanMergeSelectedCells | (None) | Boolean | Returns True when the selected cells form a rectangle of two or more cells that can be merged. |
| CanUnmergeSelectedCells | (None) | Boolean | Returns True when a selected cell is merged. |
| Cell | row As Integer <br> column As Integer | TextSnapshot | Returns the content snapshot for the specified table row and column. |
| CellHTMLStyle | state As TextSnapshot | String | (None) |
| CellText | row As Integer <br> column As Integer | String | Returns the plain text stored in the specified table cell. |
| CellText | row As Integer <br> column As Integer <br> Assigns value As String | (None) | Sets the plain text stored in the specified table cell. |
| ChildAt | index As Integer | Node | Returns the embedded child node at the specified index. |
| ClearFormatting | (None) | (None) | Removes supported formatting and restores this content's formatting defaults. |
| ColumnOffset | column As Integer <br> totalWidth As Double | Double | Returns the horizontal offset of the specified column within the supplied total width. |
| ColumnsRightToLeft | (None) | Boolean | Returns True when the table's columns run right to left: when its direction is RightToLeft, or Automatic in an editor whose interface reads right to left. |
| ColumnWidth | column As Integer <br> totalWidth As Double | Double | Returns the rendered width of the specified column within the supplied total width. |
| Constructor | rowCount As Integer = 3 <br> columnCount As Integer = 3 | (None) | Creates a new table node instance initialized from the supplied values. |
| ContainsNode | node As Node | Boolean | Returns whether this node contains the supplied node, directly or recursively. |
| ContextMenuCaption | index As Integer | String | Returns the caption for the contextual menu item at the specified index. |
| ContextMenuEnabled | index As Integer | Boolean | Returns whether the contextual menu item at the specified index is enabled. |
| CopyTablePropertiesTo | target As TableNode | (None) | Copies this table's rows, columns, header and footer settings, and cells to the supplied table. |
| Destructor | (None) | (None) | Releases background-image event handlers owned by this table. |
| Duplicate | (None) | Node | Returns an independent copy of this node and its configurable state. |
| EditingApplyStyle | start As Integer <br> length As Integer <br> style As TextStyle <br> fieldName As String | (None) | Applies the specified style field to a range in the active editable content. |
| EditingCaretFrame | position As Integer | Rect | Returns the document bounds of the caret at the specified text position. |
| EditingClearFormatting | start As Integer <br> length As Integer | (None) | Clears character formatting from the specified editable range. |
| EditingDrawOverlay | g As Graphics <br> selectionStart As Integer <br> selectionLength As Integer <br> caretPosition As Integer <br> caretVisible As Boolean | (None) | Draws the selection and caret overlay for the active editable content. |
| EditingHandleKey | key As String <br> shiftKey As Boolean <br> menuShortcutKey As Boolean <br> ByRef selectionStart As Integer <br> ByRef selectionLength As Integer <br> ByRef caretPosition As Integer <br> style As TextStyle | (None) | Handles a key press and updates the supplied selection and caret positions. |
| EditingHandleReturn | (None) | Boolean | Handles a Return key press and returns whether the content consumed it. |
| EditingHandlesKey | key As String <br> shiftKey As Boolean <br> menuShortcutKey As Boolean | Boolean | Returns whether the editable content handles the specified key combination. |
| EditingHitIndex | x As Double <br> y As Double | Integer | Returns the nearest text insertion index for the specified document coordinates. |
| EditingInsertText | position As Integer <br> value As String <br> style As TextStyle | (None) | Inserts styled text at the specified position. |
| EditingLength | (None) | Integer | Returns the number of editable characters in the active content. |
| EditingRemoveText | start As Integer <br> length As Integer | (None) | Removes the specified range from the active editable content. |
| EditingRestoreState | state As Variant | (None) | Restores a previously captured editing state. |
| EditingSelectedHTML | start As Integer <br> length As Integer | String | Returns the selected range as an HTML fragment. |
| EditingSelectedText | start As Integer <br> length As Integer | String | Returns the selected range as plain text. |
| EditingState | (None) | Variant | Returns a snapshot that can restore the current editing state. |
| EditingStyleAt | index As Integer | TextStyle | Returns the character style at the specified editable index. |
| EditingSupportsStyles | (None) | Boolean | Returns whether the editable content supports character-level styling. |
| ExportStyles | stylesheet As GraffitiProEditor.Stylesheet | (None) | Adds the stylesheet rules this node type's HTML output uses. |
| FindChildPlacement | node As Node <br> ByRef parent As Node <br> ByRef slot As Integer <br> ByRef index As Integer | Boolean | Finds an embedded node and returns its parent, slot, and index. |
| FromHTML | element As GraffitiProEditor.HTMLSupport.HTMLElement | Boolean | Imports supported content and formatting from an HTML element and returns whether it succeeded. |
| FromJSON | data As JSONItem | Boolean | Restores state from JSON data and returns whether it succeeded. |
| HandleKey | key As String | Boolean | Handles a key press for this node and returns whether it was consumed. |
| HitTest | x As Double <br> y As Double | Node | Returns the deepest selectable node at the specified document coordinates. |
| HTMLTags | (None) | String | Returns the HTML tag names supported by this node type. |
| HTMLTextAlignmentCSS | (None) | String | Returns the CSS text-align declaration for this node's resolved text alignment. |
| InsertChild | slot As Integer <br> index As Integer <br> node As Node | (None) | Inserts a child node into the specified container slot and index. |
| InsertHTMLNode | node As Node | Boolean | Inserts an imported node into this container and returns whether it was accepted. |
| InsertionIndicatorAtPoint | node As Node <br> x As Double <br> y As Double | Rect | Returns the document bounds of the insertion indicator for a child dropped at the supplied coordinates. |
| InspectorSections | (None) | InspectorSection | Returns the user-editable table and active cell properties exposed by the inspector. |
| IsCellSelected | row As Integer <br> column As Integer | Boolean | Returns whether the cell at the supplied row and column is selected. |
| LastActionIndex | (None) | Integer | Returns the last zero-based action index supplied by this node, or -1 when there are no actions. |
| LastChildIndex | (None) | Integer | Returns the last zero-based child index, or -1 when there are no children. |
| LastContextMenuIndex | (None) | Integer | Returns the last zero-based contextual-menu item index, or -1 when there are no contextual-menu items. |
| LastSearchSegmentIndex | (None) | Integer | Returns the last zero-based searchable segment index, or -1 when there are no searchable segments. |
| LastSelectedCellIndex | (None) | Integer | Returns the last zero-based selected-cell index, or -1 when there are no selected cells. |
| LinkAtPoint | x As Double <br> y As Double <br> ByRef linkNode As GraffitiProEditor.Node <br> ByRef url As String <br> ByRef linkText As String <br> ByRef title As String | Boolean | Finds the hyperlink at the specified document coordinates and returns whether one was found, with the node that holds it, its URL, its complete link text, and its title. |
| LocalizeToolbarItem | strings As GraffitiProEditor.Editor | (None) | Sets this node type's toolbar item text from the supplied editor's localization properties. The editor calls it when the type is registered, when the editor opens, and when a locale pack is applied to the editor. A custom node type can override it to localize its own toolbar item. |
| MergeCells | row As Integer <br> column As Integer <br> rowCount As Integer <br> columnCount As Integer | Boolean | Merges the cells in the supplied rectangle into its top-left cell and returns whether they were merged. |
| MergeSelectedCells | (None) | (None) | Merges the selected cells into the top-left cell of their rectangle. The other cells' content follows the top-left cell's in reading order. |
| MoveActiveCell | rowOffset As Integer <br> columnOffset As Integer <br> extendSelection As Boolean = False | Boolean | Moves the active cell by the supplied number of rows and columns, optionally extending the cell selection, and returns False when the target is outside the table. |
| PerformAction | index As Integer <br> selectedItem As DesktopMenuItem | (None) | Handles the contextual toolbar action at the specified index. |
| PerformContextMenuAction | index As Integer | (None) | Handles the contextual menu action at the specified index. |
| PerformToolbarAction | editor As Editor <br> selectedItem As DesktopMenuItem | (None) | Handles activation of this node type's main-toolbar item. |
| PickCell | x As Double <br> y As Double <br> extendSelection As Boolean = False <br> toggleSelection As Boolean = False <br> preserveSelection As Boolean = False | (None) | Selects the cell at the supplied document coordinates, optionally extending, toggling, or preserving the current cell selection. |
| PlainText | (None) | String | Returns the node's readable content as plain text. |
| PreferredHeight | g As Graphics <br> availableWidth As Double | Double | Returns the preferred node height for the available width. |
| RemoveChild | node As Node | Boolean | Removes the supplied embedded node and returns whether it was found. |
| RemoveColumn | (None) | (None) | Removes column from this table node. |
| RemoveRow | (None) | (None) | Removes row from this table node. |
| Render | g As Graphics <br> bounds As Rect <br> selected As Boolean | (None) | Draws the node within the supplied document bounds. |
| RenderSelectionOverlay | g As Graphics | (None) | Draws the node-specific selection overlay. |
| ReplaceSearchText | segment As Integer <br> start As Integer <br> length As Integer <br> value As String | Boolean | Replaces a range in the specified searchable segment and returns whether it succeeded. |
| ResolvedTextAlignment | (None) | GraffitiProEditor.Alignments | Returns the alignment used by cell text whose own text alignment is Automatic. |
| RestoreHTMLCellChildren | element As GraffitiProEditor.HTMLSupport.HTMLElement <br> slot As Integer <br> ByRef embeddedIndex As Integer | (None) | Restores the child nodes of an imported HTML cell into the cell at the supplied index. |
| RestoreHTMLChildren | element As GraffitiProEditor.HTMLSupport.HTMLElement | (None) | Restores table cell children from HTML using the editor's registered node prototypes. |
| RestoreJSONChildren | data As JSONItem | (None) | Restores table cell children from JSON using the editor's registered node prototypes. |
| SearchSegmentName | index As Integer | String | Returns the display name of the searchable segment at the specified index. |
| SearchSegmentText | index As Integer | String | Returns the text of the searchable segment at the specified index. |
| SelectAllCells | (None) | (None) | Selects all cells in the table. |
| SelectCell | row As Integer <br> column As Integer <br> extendSelection As Boolean = False <br> toggleSelection As Boolean = False | (None) | Selects the cell at the supplied row and column, optionally extending or toggling the current selection. |
| ShowCellBackgroundColorPicker | title As String <br> onlyActiveCell As Boolean | (None) | Opens the system color panel for the selected cells' background, or only the active cell's when onlyActiveCell is True. The panel is a non-modal DesktopColorPicker; each color it reports is applied at once to the cells selected when it opened. |
| SupportsTextAlignment | (None) | Boolean | Returns whether the node draws text that follows its TextAlignment. |
| TextAlignmentInspectorItem | identifier As String <br> propertyName As String | InspectorItem | Returns a Text Alignment inspector item for the supplied property, with Automatic, Start, Center, and End choices. |
| ToHTML | (None) | String | Returns an HTML representation of this content. |
| ToJSON | (None) | JSONItem | Returns a JSON representation of this object's persistent state. |
| ToMarkdown | (None) | String | Returns a Markdown representation of this content. |
| TranslateLayout | offsetX As Double <br> offsetY As Double | (None) | Offsets this node and its cached descendant layout by the supplied distances. |
| TypeName | (None) | String | Returns the display name for this node type. |
| UnmergeCell | row As Integer <br> column As Integer | Boolean | Unmerges the merged cell at the supplied row and column, or the merged cell that covers it, and returns whether it was merged. |
| UnmergeSelectedCells | (None) | (None) | Splits each selected merged cell back into separate cells and selects them. The merged content stays in the top-left cell. |
## Properties
| Name | Type | Default Value | Description |
| --- | :---: | :---: | --- |
| ActiveCell | Integer | (None) | Gets or sets the zero-based index of the active table cell. |
| ActiveCellBackgroundColor | Color | (None) | Gets or sets the background color of the active cell. |
| ActiveCellBorderBottomColor | Color | (None) | Gets or sets the bottom border color for the selected cells. |
| ActiveCellBorderBottomSize | Double | (None) | Gets or sets the bottom border width for the selected cells. |
| ActiveCellBorderBottomVisible | Boolean | (None) | Gets or sets whether the bottom border is drawn for the selected cells. |
| ActiveCellBorderLeftColor | Color | (None) | Gets or sets the left border color for the selected cells. |
| ActiveCellBorderLeftSize | Double | (None) | Gets or sets the left border width for the selected cells. |
| ActiveCellBorderLeftVisible | Boolean | (None) | Gets or sets whether the left border is drawn for the selected cells. |
| ActiveCellBorderRightColor | Color | (None) | Gets or sets the right border color for the selected cells. |
| ActiveCellBorderRightSize | Double | (None) | Gets or sets the right border width for the selected cells. |
| ActiveCellBorderRightVisible | Boolean | (None) | Gets or sets whether the right border is drawn for the selected cells. |
| ActiveCellBorderTopColor | Color | (None) | Gets or sets the top border color for the selected cells. |
| ActiveCellBorderTopSize | Double | (None) | Gets or sets the top border width for the selected cells. |
| ActiveCellBorderTopVisible | Boolean | (None) | Gets or sets whether the top border is drawn for the selected cells. |
| ActiveCellHasBackgroundColor | Boolean | (None) | Gets or sets whether the active cell uses an explicit background color. |
| ActiveCellTextAlignment | GraffitiProEditor.Alignments | (None) | Gets or sets the text alignment of the selected cells. Automatic uses the table's text alignment. |
| ActiveCellVerticalAlignment | Integer | (None) | Gets or sets the vertical alignment of the active cell. |
| Columns | Integer | (None) | Gets or sets the columns collection. |
| HasFooter | Boolean | (None) | Gets or sets whether footer is enabled. |
| HasHeader | Boolean | (None) | Gets or sets whether header is enabled. |
| Rows | Integer | (None) | Gets or sets the rows collection. |
| TextAlignment | GraffitiProEditor.Alignments | (None) | Gets or sets the alignment of cell text whose own text alignment is Automatic. Automatic uses the editor's TextAlignment. |
## Notes
Table behavior is organized around row-and-column cell coordinates.
### Cell Appearance
Cells support background color, text alignment, vertical alignment, and the complete `BackgroundImage` source, fill, repeat, and removal model. These settings survive JSON and HTML round trips.
### Cells and Children
Address cells by row and column through `Cell`. The active cell supplies the current text-editing and inspector target. Normal clicks select one cell, dragging across cells or Shift-click selects a rectangular range, and platform-shortcut-click toggles individual cells. Cell-level toolbar formatting applies to the selected cells while character-level editing remains scoped to the active cell.
Each cell can contain direct text without first adding a text node, or it can contain registered child nodes including nested tables and columns.
Columns run right to left when `ColumnsRightToLeft` is True: when the table's direction is RightToLeft, or Automatic in an editor whose interface reads right to left. `ColumnLeft` returns a column's position in screen order. A cell's text follows the table's direction, or each paragraph's first letter when it is Automatic, Text alignment is logical and inherited. A cell's `TextSnapshot.TextAlignment` (Text Alignment in the Active Cell inspector section and the popover toolbar) is Automatic by default, which uses the table's `TextAlignment`; Automatic there uses `Editor.TextAlignment`. `ResolvedTextAlignment` returns the table's result. Start (`Leading`) begins at the leading edge and End (`Trailing`) at the other edge, so right-to-left text starts on the right and ends on the left. HTML export writes the table's resolved alignment on the `table` element and each explicit cell alignment on its cell, as `text-align:start`, `center`, or `end`; Automatic cells write none and inherit it. Import reads `start` as Automatic, and CSS `left` and `right` as Start or End for the text's direction. Forms keep drawing their text with the form's block `Alignment` and have no Text Alignment item.
Cell content is clipped to cell bounds. Row measurement expands for wrapped text and embedded content. Drag indicators identify the exact child insertion position.
### JSON Format
`rows` and `columns` are integers. `cells` is a row-major array of `TextSnapshot` objects with `rows * columns` entries; cell `(row, column)` is stored at index `(row * columns) + column`. `activeCell` uses the same flat index. `hasHeader` and `hasFooter` are Boolean. A merged cell's snapshot stores `rowSpan` and `columnSpan` when they are greater than 1; covered cells are stored like any other cell. Suggestion providers are runtime application objects and are not stored in document JSON.
`textAlignment` stores the table's `TextAlignment` as a `GraffitiProEditor.Alignments` value and is omitted when it is Automatic. Each cell snapshot stores its own `textAlignment` the same way, and vertical alignment as `0` Top, `1` Middle, or `2` Bottom; cells saved earlier with `horizontalAlignment` are read as described for `TextSnapshot`. Cell colors, background images, text styles, and embedded nodes use their respective nested JSON objects. Cell borders are disabled by default and use the snapshot's independent `CellBorderTop*`, `CellBorderRight*`, `CellBorderBottom*`, and `CellBorderLeft*` properties. Tables and columns therefore export without grid lines unless the user explicitly enables cell or node borders.
`rows`, `columns`, and `cells` are always written. `hasHeader` and `hasFooter` are omitted when `False`, `activeCell` when it is `0`, and `textAlignment` when it is Automatic; missing names restore those defaults. Each cell snapshot omits its own default values as described for `TextSnapshot`.
### Merged Cells
Select two or more cells that fill a rectangle and choose Merge Cells in the table's popover toolbar or contextual menu, or call `MergeCells` or `MergeSelectedCells`. The top-left cell becomes the merged cell and covers the whole rectangle. The other cells' text follows its text in reading order, separated by spaces, and their child nodes move into it. Header and footer rows merge only with cells in the same row.
Unmerge Cells, `UnmergeSelectedCells`, or `UnmergeCell` splits a selected merged cell back into separate cells and selects them, so they can be merged again. The merged content stays in the top-left cell, and the other cells are empty.
A merged cell's `TextSnapshot.RowSpan` and `ColumnSpan` give the rows and columns it covers. The cells it covers stay in `Cell` and the row-major cell list, so a cell's index does not change, but they are not drawn, selected, or exported. Clicking one selects the merged cell; the arrow keys and Tab move past it. A merged cell taller than its rows makes the last of them taller. Removing a row or column inside a merged cell makes it smaller; removing its first row or column moves it, with its content, to the next one. A row added above the footer inside a merged cell's rows makes it cover the new row too.
HTML export writes `colspan` and `rowspan` and leaves out covered cells, and HTML import reads them. Markdown tables cannot merge cells, so a merged cell's content appears in its first cell and the cells it covers are empty.
### Rows and Columns
The main toolbar's Table button opens a grid picker for the new table's size, from 1 x 1 up to 8 rows and 10 columns; the insertion chooser inserts a 3 x 3 table. In code, pass the size to the constructor. The chosen size reaches `PerformToolbarAction` as a rows : columns `Pair`.
`AddRow` inserts a row above the footer row when there is one, so the footer stays last, and otherwise at the end. The new row is formatted like the body row above it: its text style, alignment, fill, and borders. When the only row above it is the header, it gets plain body formatting. Footer cells that were selected stay selected as the footer moves down. `AddColumn` adds a column at the end; each new cell is formatted like the cell before it in its row, so header and footer cells match their row, and a new header cell is titled like the others. Links and suggestion tags are not copied.
`RemoveRow` and `RemoveColumn` remove the active cell's row or column and select a single cell; a table keeps at least one of each. See Merged Cells for how adding and removing rows and columns changes merged cells.
## Examples
Register a table prototype before inserting, importing, or restoring tables.
### Create a Table
```xojo
Var table As New GraffitiProEditor.TableNode(3, 2)
table.HasHeader = True
Editor.AddNode(table)
```
### Merge Cells
```xojo
Var table As New GraffitiProEditor.TableNode(4, 3)
table.HasHeader = True
'// Merge the first two body rows of the first column.
If table.MergeCells(1, 0, 2, 1) Then table.CellText(1, 0) = "Spans two rows"
Editor.AddNode(table)
'// Split it again later.
Call table.UnmergeCell(1, 0)
```