Tables
- 8 minutes to read
Overview
A table is an abstract type of block-level content in a document. A table is a set of paragraphs arranged in rows and columns. In a sub-document, the information about existing tables is stored within a specific table list. A table’s textual contents (paragraphs) are maintained within the sub-document’s text buffer.
Definition
A table is a logical unit that contains child elements (rows and cells), defines element-specific formatting settings and specifies the text buffer intervals to which these settings should be applied. Programmatically, a table is implemented as the Table client object. A list of table objects in the active sub-document can be accessed through the tablesInfo client property (SubDocument.tablesInfo) in the following notation:
clientRichEditName.document.activeSubDocument.tablesInfo
A table maintains a list of table rows. Each row, in its turn, maintains a list of its cells. A table and all its child elements (rows and cells) have their own positions within the text buffer of a sub-document. A table’s start position equals the start position of the first cell within the table’s first row.
A table can be defined using the following characteristics.
- Start position (Table.start)
- A position in a sub-document text buffer where the table’s first cell starts.
- Length (Table.length)
- The number of characters in a table within the text buffer.
- List of rows (Table.rows)
- A list of child table rows (TableRow objects).
- List of cells (TableRow.cells)
- A list of a table row’s child cells (TableCell objects). Table properties (TableFormattingSettings, TableCellFormattingSettings) : Table and cell-specific formatting settings.
- Table style name (Table.styleName)
- The name of a separate style object containing uniform table formatting settings.
Note
The RichEdit processes all tables as tables of a fixed width. A fixed width table is not dynamically resized based on its contents. The final width of cells in a fixed width table depends only on the table preferred width and the cell preferred width, and does not depend on the cell content. As a result, the display of tables in the RichEdit can differ between tables of the XtraRichEdit and Microsoft Word.
ClientAPI
Tables
The following client commands are available for manipulating tables and their settings. Call the commands in the notation given below:
clientRichEditName.commands.commandName.execute(parameter_if_any)
| Command Name | Link | Description |
|---|---|---|
| changeTableBorderRepositoryItem | RichEditCommands.changeTableBorderRepositoryItem | Gets a command to apply borders’ drawing settings. |
| changeTableBordersAndShading | RichEditCommands.changeTableBordersAndShading | Gets a command to change the selected table’s borders and shading. |
| changeTableFormatting | RichEditCommands.changeTableFormatting | Gets a command to change the selected table’s formatting. |
| changeTableLook | RichEditCommands.changeTableLook | Gets a command to change the selected table’s style options. |
| changeTableStyle | RichEditCommands.changeTableStyle | Gets a command to change the selected table’s style. |
| deleteTable | RichEditCommands.deleteTable | Gets a command to delete the selected table. |
| insertTable | RichEditCommands.insertTable | Gets a command to insert a rectangular table of the specified size. |
| showTableGridLines | RichEditCommands.showTableGridLines | Gets a command to toggle the display of grid lines for a table with no borders applied - on/off. |
| toggleTableCellInsideHorizontalBorders | RichEditCommands.toggleTableCellInsideHorizontalBorders | Gets a command to apply (or cancel) border settings of the inside horizontal borders for the selected cells. |
| toggleTableCellInsideVerticalBorders | RichEditCommands.toggleTableCellInsideVerticalBorders | Gets a command to apply (or cancel) border settings of the inside vertical borders for the selected cells. |
| toggleTableCellOutsideBorders | RichEditCommands.toggleTableCellOutsideBorders | Gets a command to apply (or cancel) border settings of the outside borders for the selected cells. |
Rows
The following client commands are available for manipulating table rows. Call the commands in the notation given below:
clientRichEditName.commands.commandName.execute(parameter_if_any)
| Command Name | Link | Description |
|---|---|---|
| changeTableRowPreferredHeight | RichEditCommands.changeTableRowPreferredHeight | Gets a command to change the selected table rows’ preferred height. |
| deleteTableRows | RichEditCommands.deleteTableRows | Gets a command to delete the selected rows in the table. |
| insertTableRowAbove | RichEditCommands.insertTableRowAbove | Gets a command to insert a row in the table above the selected row. |
| insertTableRowBelow | RichEditCommands.insertTableRowBelow | Gets a command to insert a row in the table below the selected row. |
Cells
The following client commands are available for manipulating table cells and their settings. Call the commands in the notation given below:
clientRichEditName.commands.commandName.execute(parameter_if_any)
Insert
| Command Name | Link | Description |
|---|---|---|
| insertTableCellsWithShiftToTheVertically | RichEditCommands.insertTableCellsWithShiftToTheVertically | Gets a command to insert table cells with a vertical shift into the selected table. |
| insertTableCellWithShiftToTheLeft | RichEditCommands.insertTableCellWithShiftToTheLeft | Gets a command to insert table cells with a horizontal shift into the selected table. |
| insertTableColumnToTheLeft | RichEditCommands.insertTableColumnToTheLeft | Gets a command to insert a table column to the left of the current position in the table. |
| insertTableColumnToTheRight | RichEditCommands.insertTableColumnToTheRight | Gets a command to insert a table column to the right of the current position in the table. |
Delete
| Command Name | Link | Description |
|---|---|---|
| deleteTableCellsWithShiftHorizontally | RichEditCommands.deleteTableCellsWithShiftHorizontally | Gets a command to delete the selected table cells with a horizontal shift. |
| deleteTableCellsWithShiftVertically | RichEditCommands.deleteTableCellsWithShiftVertically | Gets a command to delete the selected table cells with a vertical shift. |
| deleteTableColumns | RichEditCommands.deleteTableColumns | Gets a command to delete the selected columns in the table. |
Formatting Properties
| Command Name | Link | Description |
|---|---|---|
| changeTableCellFormatting | RichEditCommands.changeTableCellFormatting | Gets a command to change the cell formatting of the selected table elements. |
| changeTableCellPreferredWidth | RichEditCommands.changeTableCellPreferredWidth | Gets a command to change the preferred cell width of the selected table rows. |
| changeTableCellShading | RichEditCommands.changeTableCellShading | Gets a command to change cell shading in selected table cells. |
| changeTableColumnPreferredWidth | RichEditCommands.changeTableColumnPreferredWidth | Gets a command to change the selected table columns’ preferred width. |
| mergeTableCells | RichEditCommands.mergeTableCells | Gets a command to merge the selected cells. |
| splitTableCells | RichEditCommands.splitTableCells | Gets a command to split the selected table cells. |
Alignment
| Command Name | Link | Description |
|---|---|---|
| toggleTableCellAlignBottomCenter | RichEditCommands.toggleTableCellAlignBottomCenter | Gets a command to apply bottom-center alignment for the selected cells. |
| toggleTableCellAlignBottomLeft | RichEditCommands.toggleTableCellAlignBottomLeft | Gets a command to apply bottom-left alignment for the selected cells. |
| toggleTableCellAlignBottomRight | RichEditCommands.toggleTableCellAlignBottomRight | Gets a command to apply bottom-right alignment for the selected cells. |
| toggleTableCellAlignMiddleCenter | RichEditCommands.toggleTableCellAlignMiddleCenter | Gets a command to apply middle-center alignment for the selected cells. |
| toggleTableCellAlignMiddleLeft | RichEditCommands.toggleTableCellAlignMiddleLeft | Gets a command to apply middle-left alignment for the selected cells. |
| toggleTableCellAlignMiddleRight | RichEditCommands.toggleTableCellAlignMiddleRight | Gets a command to apply middle-right alignment for the selected cells. |
| toggleTableCellAlignTopCenter | RichEditCommands.toggleTableCellAlignTopCenter | Gets a command to apply top-center alignment for the selected cells. |
| toggleTableCellAlignTopLeft | RichEditCommands.toggleTableCellAlignTopLeft | Gets a command to apply top-left alignment for the selected cells. |
| toggleTableCellAlignTopRight | RichEditCommands.toggleTableCellAlignTopRight | Gets a command to apply top-right alignment for the selected cells. |
Borders
| Command Name | Link | Description |
|---|---|---|
| removeTableCellBorders | RichEditCommands.removeTableCellBorders | Gets a command to remove the borders of the selected table cells. |
| toggleTableCellAllBorders | RichEditCommands.toggleTableCellAllBorders | Gets a command to apply (or cancel) border settings to all borders of the selected cells. |
| toggleTableCellBottomBorder | RichEditCommands.toggleTableCellBottomBorder | Gets a command to apply (or cancel) border settings of the bottom border for the selected cells. |
| toggleTableCellInsideBorders | RichEditCommands.toggleTableCellInsideBorders | Gets a command to apply (or cancel) border settings of the inside borders for the selected cells. |
| toggleTableCellLeftBorder | RichEditCommands.toggleTableCellLeftBorder | Gets a command to apply (or cancel) border settings of the left border for the selected cells. |
| toggleTableCellRightBorder | RichEditCommands.toggleTableCellRightBorder | Gets a command to apply (or cancel) border settings of the right border for the selected cells. |
| toggleTableCellTopBorder | RichEditCommands.toggleTableCellTopBorder | Gets a command to apply (or cancel) border settings of the top border for the selected cells. |
Dialogs
The following client commands are available for opening table-specific dialogs. Call the commands in the notation given below:
clientRichEditName.commands.commandName.execute(parameter_if_any)
| Command Name | Link | Description |
|---|---|---|
| deleteTableCellsDialog | RichEditCommands.deleteTableCellsDialog | Gets a command to invoke the Delete Cells dialog window. |
| insertTableCellsDialog | RichEditCommands.insertTableCellsDialog | Gets a command to invoke the Insert Cells dialog window. |
| openInsertTableDialog | RichEditCommands.openInsertTableDialog | Gets a command to invoke the Insert Table dialog window. |
| openTableBordersAndShadingDialog | RichEditCommands.openTableBordersAndShadingDialog | Gets a command to invoke the Borders tab of the Borders and Shading dialog window. |
| openTableFormattingDialog | RichEditCommands.openTableFormattingDialog | Gets a command to invoke the Table tab of the Table Properties dialog window. |
| splitTableCellsDialog | RichEditCommands.splitTableCellsDialog | Gets a command to invoke the Split Cells dialog window. |
Table Styles
Using a table style allows setting common formatting properties of multiple tables at once. A table style contains settings that affect character properties, paragraph properties, cell properties, row properties and table properties.
A list of table styles can be accessed using the following tableStylesInfo property in the notation given below:
clientRichEditName.document.tableStylesInfo
| Property Name | Link | Description |
|---|---|---|
| tableStylesInfo | RichEditDocument.tableStylesInfo | Returns information about table styles in the document. |
To apply a table style (TableStyle) to the text, use the following changeTableStyle client command in the notation given below:
clientRichEditName.commands.changeTableStyle(parameter_if_any)
| Command Name | Link | Description |
|---|---|---|
| changeTableStyle | RichEditCommands.changeTableStyle | Gets a command to change the selected table’s style. |
To apply a table look (TableLookSettings) to a table, use the following changeTableLook client command in the notation given below:
clientRichEditName.commands.changeTableLook(parameter_if_any)
| Command Name | Link | Description |
|---|---|---|
| changeTableLook | RichEditCommands.changeTableLook | Gets a command to change the selected table’s style options. |
UI Interactions
The ASPxRichEdit control provides support for complex tables, as well as nested ones. A user can insert tables, edit a table layout by splitting and merging cells, and insert rows and columns. Borders and shading can be applied individually for each cell in a table.
A user can easily insert a table using the dropdown window of the Table ribbon button located in the ribbon’s Insert tab in the Tables group.
The RichEdit provides a set of ribbon commands to work with tables. These commands are available through two specific ribbon context tabs (Design and Layout).
The Design tab allows users with the ability to set borders, border color and cell shading.
The Layout tab allows you to perform complex table element operations, such as merging cells, inserting and deleting rows and columns, and defining the properties of all main table elements.
Users can change table settings and table layout using Table Dialogs.
Limitations
- ASPxRichEdit does not support floating tables.