Tables

  • 15 minutes to read

This topic describes how RichEditControl manages document tables in code and via User Interface.

XtraRichEdit_Tables_Result

Create a Table

In Code

Use members from the table below to create a table and add new rows and columns.

XtraRichEdit_Tables_CreatedAndExpanded

Member Description
TableCollection.Create Creates a new table at the specified position.
TableRowCollection.Append Appends a new row to the table.
TableRowCollection.InsertBefore Inserts a new row before the specified row.
TableRowCollection.InsertAfter Inserts a new row after the specified row.
TableCellCollection.Append Adds a new column at the table's end.
TableCellCollection.InsertBefore Inserts a new column before a specified column.
TableCellCollection.InsertAfter Inserts a new column after the specified column.
NOTE

A complete sample project is available at https://github.com/DevExpress-Examples/tables-simple-example-t472346.

using DevExpress.XtraRichEdit.API.Native;

Document document = richEditControl1.Document;

//Create a new table:
Table table = document.Tables.Create(document.Range.End, 2, 2);

//Add new rows to the table
TableRow newRowBefore = table.Rows.InsertBefore(0);
TableRow newRowAfter = table.Rows.InsertAfter(0);

//Add a new column to the table
TableCell newLastColumn = table.Rows[0].Cells.Append();

From the User Interface

Click the Table menu on the Insert Ribbon tab to insert a table. The invoked cell grid allows you to select the number of rows and columns.

XtraRichEdit_Tables_UI_Insert

Click the Table button to invoke the Insert Table dialog. This dialog allows users to enter the number of rows and columns. The maximum number of rows in the RichEditControl table is 32767, the maximum number of columns is 63. If a user enters the number of rows or columns that exceed the limit, an error icon appears.

XtraRichEdit_Table_RowLimitError

The Rows & Columns group on the Table Tools | Layout contextual tab allows you to insert new rows and columns. These items are also available in the context menu.

IMAGE

Resize the Table

In Code

Use members from the table below to change the table row/column width and height to a fixed value or make it automatically fit the content.

Member Description
Table.BeginUpdate() Initializes the update session.
TableRow.HeightType Specifies the height type (exact, automatic or minimum). If the property is set to HeightType.Auto, the TableRow.Height property is ignored.
TableRow.Height Specifies the row height.
TableCell.HeightType Specifies the height type (exact, automatic or minimum). If the property is set to HeightType.Auto, the TableCell.Height property is ignored.
TableCell.Height Specifies the cell height.
Table.SetPreferredWidth Specifies the table's width.
TableCell.PreferredWidth Sets the column's preferred width.
TableCell.PreferredWidthType Specifies the width type (exact, automatic, etc.). Set this property to WidthType.Auto to make table automatically fit the content.
Table.RightToLeft Specifies whether to change the table layout's direction to right-to-left.
Table.EndUpdate() Ends the table update.
NOTE

We do not recommend that you specify different sizes for cells in one column because it changes the column's layout.

The code snippet below resizes the table columns as in the following image:

XtraRichEdit_Tables_FixedWidthApplied

NOTE

A complete sample project is available at https://github.com/DevExpress-Examples/tables-simple-example-t472346.

using DevExpress.XtraRichEdit.API.Native;
using DevExpress.Office.Utils;

Document document = richEditControl.Document;
Table table = document.Tables[0];

//Set the width of the first column
table.Rows[0].FirstCell.PreferredWidthType = WidthType.Fixed;
table.Rows[0].FirstCell.PreferredWidth = Units.InchesToDocumentsF(0.8f);


//Set the second column width and cell height
table[0, 1].PreferredWidthType = WidthType.Fixed;
table[0, 1].PreferredWidth = Units.InchesToDocumentsF(5f);
table[0, 1].HeightType = HeightType.Exact;
table[0, 1].Height = Units.InchesToDocumentsF(0.5f);

//Set the third column width
table.Rows[0].LastCell.PreferredWidthType = WidthType.Fixed;
table.Rows[0].LastCell.PreferredWidth = Units.InchesToDocumentsF(0.8f);

From the User Interface

Use the Table Properties dialog to change the width and height of the row, cell or an entire column. You can invoke it from the Table Tools | Layout ribbon tab or from the context menu.

The AutoFit menu on the Table Tools | Layout contextual tab allows you to automatically resize table columns.

IMAGE

Merge and Split Table Cells

In Code

The following API allows you to split a cell into a number of new cells or merge multiple cells into a single cell.

Member Description
Table.BeginUpdate() Initializes the update session.
Table.MergeCells Merges the specified cell range. The merged cells content persists.
TableCell.Split Splits the table cell into the specified number of new cells.
Table.EndUpdate() Ends the table update.

The code snippet demonstrates how to modify cells so the table appears as in the following image.

XtraRichEdit_Tables_MergedAndSplit

NOTE

A complete sample project is available at https://github.com/DevExpress-Examples/tables-simple-example-t472346

using DevExpress.XtraRichEdit.API.Native;

Document document = richEditControl1.Document;
Table table = document.Tables[0];
table.BeginUpdate();

//Split cell into 8
table[3, 1].Split(4, 2);

//Merge cells
table.MergeCells(table[4, 1], table[4, 2]);
table.MergeCells(table[6, 1], table[6, 2]);
table.EndUpdate();

From the User Interface

Use Merge group buttons on the Table Tools | Layout contextual tab to merge and split table cells. These items are also available in the context menu.

IMAGE

Add Content to Table Cells

XtraRichEdit_Tables_DataInserted

The TableCell.Range property provides access to the cell content's range. You can insert text, shape or another table into the cell.

Member Description
Table.BeginUpdate() Initializes the update session.
SubDocument.InsertSingleLineText Inserts a text string into a cell.
SubDocument.InsertText Inserts text into a cell.
TableCollection.Create Inserts a table into a cell.
ShapeCollection.InsertPicture Inserts a picture into a cell.
Table.EndUpdate() Ends the table update.

The following code example inserts text and an image.

NOTE

A complete sample project is available at https://github.com/DevExpress-Examples/tables-simple-example-t472346

using DevExpress.XtraRichEdit.API.Native;

Document document = richEditControl1.Document;

Table table = document.Tables[0];
table.BeginUpdate();

//Insert the header data
document.InsertSingleLineText(table.Rows[0].Cells[1].Range.Start, "Active Customers");
document.InsertSingleLineText(table[2, 0].Range.Start, "Photo");
document.InsertSingleLineText(table[2, 1].Range.Start, "Customer Info");
document.InsertSingleLineText(table[2, 2].Range.Start, "Rentals");

//Insert the customer photo
document.Images.Insert(table[3, 0].Range.Start, DocumentImageSource.FromFile("photo.png"));

//Insert the customer info
document.InsertText(table[3, 1].Range.Start, "Ryan Anita W");
document.InsertText(table[3, 2].Range.Start, "Intermediate");
document.InsertText(table[4, 1].Range.Start, "3/28/1984");
document.InsertText(table[5, 1].Range.Start, "anita_ryan@dxvideorent.com");
document.InsertText(table[5, 2].Range.Start, "(555)421-0059");
document.InsertText(table[6, 1].Range.Start, "5119 Beryl Dr, San Antonio, TX 78212");

document.InsertSingleLineText(table[3, 3].Range.Start, "18");
table.EndUpdate();

Format Cell Content

You can Format table content as regular text. Refer to the Text Formatting topic for more information on how to format text.

In this example, the table data is formatted as in the following image.

XtraRichEdit_Tables_DataInsertedAndFormatted

Show Code Example
using System.Drawing;
using DevExpress.XtraRichEdit.API.Native;

Document document = richEditControl.Document;
Table table = document.Tables[0];

//Apply formatting to the "Active Customers" cell
CharacterProperties properties =
document.BeginUpdateCharacters(table[0, 1].ContentRange);
properties.FontName = "Segoe UI";
properties.FontSize = 16;
document.EndUpdateCharacters(properties);
ParagraphProperties alignment =
document.BeginUpdateParagraphs(table[0, 1].ContentRange);
alignment.Alignment = ParagraphAlignment.Center;
document.EndUpdateParagraphs(alignment);
table[0, 1].VerticalAlignment = TableCellVerticalAlignment.Center;

//Apply formatting to the header cells
CharacterProperties headerRowProperties =
document.BeginUpdateCharacters(table.Rows[2].Range);
headerRowProperties.FontName = "Segoe UI";
headerRowProperties.FontSize = 11;
headerRowProperties.ForeColor = Color.FromArgb(212, 236, 183);
document.EndUpdateCharacters(headerRowProperties);

ParagraphProperties headerRowParagraphProperties =
document.BeginUpdateParagraphs(table.Rows[2].Range);
headerRowParagraphProperties.Alignment = ParagraphAlignment.Center;
document.EndUpdateParagraphs(headerRowParagraphProperties);

//Apply formatting to the customer info cells
DocumentRange targetRange =
document.CreateRange(table[3, 1].Range.Start, table[6, 2].Range.Start.ToInt() - table[3, 1].Range.Start.ToInt());
CharacterProperties infoProperties =
document.BeginUpdateCharacters(targetRange);
infoProperties.FontSize = 8;
infoProperties.FontName = "Segoe UI";
infoProperties.ForeColor = Color.FromArgb(111, 116, 106);
document.EndUpdateCharacters(infoProperties);

//Format "Rentals" cells
CharacterProperties rentalFormat =
document.BeginUpdateCharacters(table[3, 3].Range);
rentalFormat.FontSize = 28;
rentalFormat.Bold = true;
document.EndUpdateCharacters(rentalFormat);

ParagraphProperties rentalAlignment =
document.BeginUpdateParagraphs(table[3, 3].Range);
rentalAlignment.Alignment = ParagraphAlignment.Center;
document.EndUpdateParagraphs(rentalAlignment);
table[3, 3].VerticalAlignment = TableCellVerticalAlignment.Center;

Change the Table Appearance

Change the Appearance of Table Elements

In Code

XtraRichEdit_Tables_MainHeaderCustomized

Change the cell's background and border color to customize the table appearance as on the image above.

Member Description
Table.BeginUpdate() Initializes the update session.
TableCell.BackgroundColor Sets the background color of the cell.
TableCellBorder.LineColor Sets the color of the cell border.
Table.TableBackgroundColor Sets the color of the empty space between cells.
Table.ForEachCell Helps you to perform the specific actions for each table cell.
Document.DefaultTableProperties Provides access to the default table properties.
Table.EndUpdate() Ends the table update.

The code snippet below changes the third row's background color and hides the border of the first two rows.

NOTE

A complete sample project is available at https://github.com/DevExpress-Examples/tables-simple-example-t472346.

using DevExpress.XtraRichEdit.API.Native;
using System.Drawing;

Document document = richEditControl.Document;
Table table = document.Tables[0];
table.BeginUpdate();

//Call the ChangeCellBorderColor method for every cell in the first two rows
for (int i = 0; i < 2; i++)
{
    for (int j = 0; j < table.Rows[i].Cells.Count; j++)
    {
        ChangeCellBorderColor(table[i, j]);
    }
}

//Specify the background color for the third row
TableRow targetRow = table.Rows[2];
targetRow.Cells[0].BackgroundColor = Color.FromArgb(99, 122, 110);
targetRow.Cells[1].BackgroundColor = Color.FromArgb(99, 122, 110);
targetRow.Cells[2].BackgroundColor = Color.FromArgb(99, 122, 110);
table.EndUpdate();

public static void ChangeCellBorderColor(TableCell cell)
{
  //Specify the border style and the background color for the header cells
  cell.Borders.Bottom.LineStyle = TableBorderLineStyle.None;
  cell.Borders.Left.LineStyle = TableBorderLineStyle.None;
  cell.Borders.Right.LineStyle = TableBorderLineStyle.None;
  cell.Borders.Top.LineStyle = TableBorderLineStyle.None;
  cell.BackgroundColor = Color.Transparent;
}

From the User Interface

Use Borders and Shadings group items on the Table Tools | Design contextual tab to change cell's border and background settings. The dialog launcher invokes the Borders and Shading dialog, which contains additional border and shading options.

IMAGE

Create and Apply a Table Style

In Code

Use the table style to format all table elements simultaneously. You can use the following members to create a style:

Member Description
SubDocument.BeginUpdate() Initializes the document update.
Document.TableStyles Provides access to the collection of table styles.
TableStyleCollection.CreateNew Creates a new TableStyle instance.
TableStyle.TableBorders Provides access to the table borders options.
TableStyle.CellBackgroundColor Specifies the table cells' background color.
TableStyleCollection.Add Adds a new style to the collection. You cannot apply styles that are not in the collection.
TableStyle.ConditionalStyleProperties Provides access to the options for specific table elements (the first table cell, row, etc. )
TableConditionalStyleProperties.CreateConditionalStyle Creates a new style for a specific table element. Use the Table.TableLook property to determine the element to which the style should be applied.
SubDocument.EndUpdate() Finalizes the document update.
Table.Style Gets or sets the table style.
TableStyleCollection.DefaultStyle Specifies the default table style.

The following code creates a new table style, sets the desired style options, including settings for specific table elements (odd rows and the bottom right cell), and applies the style to the table.

XtraRichEdit_Tables_Result

NOTE

A complete sample project is available at https://github.com/DevExpress-Examples/tables-simple-example-t472346

using XtraRichEdit.API.Native;
using System.Drawing;

Document document = richEditControl.Document;
document.BeginUpdate();
//Create a new table style
TableStyle tStyleMain = document.TableStyles.CreateNew();

//Specify style options
TableBorder insideHorizontalBorder = tStyleMain.TableBorders.InsideHorizontalBorder;
insideHorizontalBorder.LineStyle = TableBorderLineStyle.Single;
insideHorizontalBorder.LineColor = Color.White;

TableBorder insideVerticalBorder = tStyleMain.TableBorders.InsideVerticalBorder;
insideVerticalBorder.LineStyle = TableBorderLineStyle.Single;
insideVerticalBorder.LineColor = Color.White;
tStyleMain.CellBackgroundColor = Color.FromArgb(227, 238, 220);
tStyleMain.Name = "MyTableStyle";

//Add the style to the document collection
document.TableStyles.Add(tStyleMain);

//Create conditional styles (styles for specific table elements)
TableConditionalStyle myNewStyleForOddRows = tStyleMain.ConditionalStyleProperties.CreateConditionalStyle(ConditionalTableStyleFormattingTypes.OddRowBanding);
myNewStyleForOddRows.CellBackgroundColor = Color.FromArgb(196, 220, 182);

TableConditionalStyle myNewStyleForBottomRightCell = tStyleMain.ConditionalStyleProperties.CreateConditionalStyle(ConditionalTableStyleFormattingTypes.BottomRightCell);
myNewStyleForBottomRightCell.CellBackgroundColor = Color.FromArgb(188, 214, 201);
document.EndUpdate();


// Apply a previously defined style to the table
document.Tables[0].Style = tStyleMain;

From the User Interface

The Table Styles gallery on the Table Tools | Design contextual tab shows all available table styles. Right-click the target table style in the gallery and select New Style... or Modify Style... to open the Table Style dialog.

Wrap Text Around a Table

In Code

You can wrap text around a table and specify the table's position.

Use properties from the table below to position the table as shown on the image (the table AutoFit type is changed to AutoFit Contents):

IMAGE

Member Description
Table.BeginUpdate() Initializes the update session.
Table.TextWrappingType Wraps text around a table. Set this property to TableTextWrappingType.Around.
Table.RelativeHorizontalPosition
Table.HorizontalAlignment
Table.OffsetXRelative
Specify the table's horizontal alignment. The RelativeHorizontalPosition defines the element to which the table's horizontal position is relative. Set the HorizontalAlignment to None to use the OffsetXRelative property.
Table.RelativeVerticalPosition
Table.VerticalAlignment
Table.OffsetXRelative
Specify the table's vertical alignment. The RelativeVerticalPosition defines the element to which the table alignment is relative. Set the VerticalAlignment to None to use the OffsetYRelative property.
Table.MarginTop
Table.MarginRight
Table.MarginBottom
Table.MarginLeft
Specify the distance between the table and surrounding text.
Table.EndUpdate() Ends the table update.
using DevExpress.XtraRichEdit.API.Native;
using DevExpress.Office.Utils;

Document document = richEditControl.Document;
Table table = document.Tables[0];
table.BeginUpdate();
//Wrap text around the table
table.TextWrappingType = TableTextWrappingType.Around;

//Specify vertical alignment:
table.RelativeVerticalPosition = TableRelativeVerticalPosition.Paragraph;
table.VerticalAlignment = TableVerticalAlignment.None;
table.OffsetYRelative = Units.InchesToDocumentsF(2f);

//Specify horizontal alignment:
table.RelativeHorizontalPosition = TableRelativeHorizontalPosition.Margin;
table.HorizontalAlignment = TableHorizontalAlignment.Center;

//Set distance between the text and the table:
table.MarginBottom = Units.InchesToDocumentsF(0.3f);
table.MarginLeft = Units.InchesToDocumentsF(0.3f);
table.MarginTop = Units.InchesToDocumentsF(0.3f);
table.MarginRight = Units.InchesToDocumentsF(0.3f);
table.EndUpdate();

From the User Interface

Use the Table Properties Dialog to wrap text around a table. Click the Positioning... button to invoke the Table Positioning dialog. It allows users to specify table position options: horizontal and vertical position, and distance from surrounding text.

Delete a Table

In Code

Delete a cell, row or the entire table

Member Description
Table.BeginUpdate() Initializes the update session.
TableCell.Delete Deletes the cell. The cell that is next to the deleted cell is moved to the left.
TableRow.Delete Deletes the row .
TableCollection.Remove Deletes the entire table.
Table.EndUpdate() Ends the table update.

The following code snippet deletes the first row and the second cell from the second row.

NOTE

A complete sample project is available at https://github.com/DevExpress-Examples/tables-simple-example-t472346.

using XtraRichEdit.API.Native;

Document document = richEditControl.Document;
Table tbl = document.Tables[0];
tbl.BeginUpdate();

//Delete a cell
tbl.Cell(1, 1).Delete();

//Delete a row
tbl.Rows[0].Delete();
tbl.EndUpdate();

//Delete the entire table
//document.Tables.Remove(tbl);

Delete a column

You cannot delete table columns directly. Delete cells with the corresponding index from every table row using the Table.ForEachRow method to remove the column.

The code sample below shows how to remove the second column.

NOTE

A complete sample project is available at https://github.com/DevExpress-Examples/tables-simple-example-t472346.

using XtraRichEdit.API.Native;

//Declare a method that deletes the second cell in every table row
public static void DeleteCells(TableRow row, int i)
{
    row.Cells[1].Delete();
}

//Call the declared method using ForEachRow method and the corresponding delegate
Table table = richEditControl.Document.Tables[0];
table.ForEachRow(new TableRowProcessorDelegate(DeleteCells));

From the User Interface

Use the Delete menu on the Table Tools | Layout contextual tab to delete cell, row, column or an entire table. You can also select the element to delete and click Delete... in the context menu.

IMAGE