Apply Formatting

Each element of a table can be applied with different formatting. For example, table formatting will be applied to the entire table, row formatting to only particular rows, cell formatting to only certain cells.

Aspose.Words provides a rich API to retrieve and apply formatting to a table. You can use the Table, RowFormat, and CellFormat nodes to set the formatting.

In this article, we will talk about how to apply formatting to different table nodes and what table formatting settings Aspose.Words supports.

Apply Formatting to Different Nodes

In this section, we will look at applying formatting to various table nodes.

Table Level Formatting

To apply formatting to a table, you can use the properties available on the corresponding Table node using the Table, PreferredWidth, and TableCollection classes.

The pictures below show a representation of the Table formatting features in Microsoft Word and their corresponding properties in Aspose.Words.

formattin-features-table-level-aspose-words-cpp

formatting-table-options-aspose-words-cpp

The following code example shows how to apply an outline border to a table:

The following code example shows how to build a table with all borders enabled (grid):

Row Level Formatting

Row-level formatting can be controlled using the Row, RowFormat, and RowCollection classes.

The pictures below show a representation of the Row formatting features in Microsoft Word and their corresponding properties in Aspose.Words.

formatting-row-level-aspose-words-cpp

The following code example shows how to modify the table row formatting:

Cell Level Formatting

Cell-level formatting is controlled by the Cell, CellFormat, and CellCollection classes.

The pictures below show a representation of the Cell formatting features in Microsoft Word and their corresponding properties in Aspose.Words.

formatting-cell-level-aspose-words-cpp

auto-formatting-cell-level-aspose-words-cpp

The following code example shows how to modify the formatting of a table cell:

The following code example shows how to set the amount of space (in points) to add to the left/top/right/bottom of the contents of the cell:

Specify Row Heights

The simplest way to set the row height is to use the DocumentBuilder. Using the appropriate RowFormat properties, you can set the default height setting or apply a different height for each row in the table.

In Aspose.Words, table row height is controlled by:

  • the row height property – Height
  • the height rule property for the given row – HeightRule

At the same time, a different height can be set for each row – this allows you to widely control the table settings.

The following code example shows how to create a table that contains a single cell and apply row formatting:

Specifying Table and Cell Widths

A table in a Microsoft Word document provides several different ways to resize the table and individual cells. These properties allow considerable control over the appearance and behavior of the table, so that Aspose.Words supports the behavior of tables, as in Microsoft Word.

It is important to know that table elements present several different properties that can affect how the widths of the overall table, as well as individual cells, is calculated:

  • Preferred width on the table
  • Preferred width on individual cells
  • Allowing autofit on the table

This article details how the various table width calculation properties work and how to get full control over table width calculation. This is especially useful to know in such cases where the table layout does not appear as expected.

How to Use Preferred Width

The desired width of a table or individual cells is defined through the preferred width property, which is the size that an element strives to fit. That is, the preferred width can be specified for the entire table or for individual cells. In some situations it may not be possible to fit this width exactly, but the actual width will be close to this value in most cases.

The appropriate preferred width type and value are set using the methods of the PreferredWidth class:

  • the Auto method to specify auto or “no preferred width”
  • the FromPercent method to specify a percentage width
  • the FromPoints method to specify the width in points

The pictures below show a representation of the preferred width setting features in Microsoft Word and their corresponding properties in Aspose.Words.

formatting-table-properties-aspose-words-cpp

An example of how these options are applied to a real table in a document can be seen in the picture below.

todo:image_alt_text

Specify the Preferred Table or Cell Width

In Aspose.Words, table and cell widths are set using the Table.PreferredWidth property and the CellFormat.PreferredWidth property, with options available in the PreferredWidthType enumeration:

  • Auto, which is equivalent to no preferred width set
  • Percent, which fits the element relative to the available space in the window or container size, and recalculates the value when the available width changes
  • Points, which corresponds to an element of the specified width in points

Using the Table.PreferredWidth property will adjust its preferred width relative to its container: page, text column, or outer table cell if it is a nested table.

The following code example shows how to set the table to auto-fit to 50% of the page width:

Using the CellFormat.PreferredWidth property on a given cell will adjust its preferred width.

The following code example shows how to set the different preferred width settings:

Find Preferred Width Type and Value

You can use the Type and Value properties to find the preferred width details of the desired table or cell.

The following code example shows how to retrieve the preferred width type of a table cell:

How to Set Autofit

The AllowAutoFit property allows cells in a table to grow and shrink according to a selected criterion. For example, you can use the AutoFit to Window option to fit the table to the width of the page, and the AutoFit to Content option to allow each cell to grow or shrink according to its content.

By default, Aspose.Words inserts a new table using AutoFit to Window. The table will be sized according to the available page width. To resize a table, you can call the AutoFit method. This method accepts an AutoFitBehavior enumeration that specifies what type of autofit is applied to the table.

It is important to know that the autofit method is actually a shortcut that applies different properties to the table at the same time. These are properties that actually give the table the observed behavior. We will discuss these properties for each autofit option.

The following code example shows how to set a table to shrink or grow each cell according to its contents:

AutoFit Table to Window

When autofitting to a window is applied to a table, the following operations are actually performed behind the scenes:

  1. The Table.AllowAutoFit property is enabled to automatically resize columns to fit the available content, using a Table.PreferredWidth value of 100%
  2. CellFormat.PreferredWidth is removed from all table cells
  3. Column widths are recalculated for the current table content – the end result is a table that occupies the entire available width
  4. The width of the columns in the table changes automatically as the user edits the text

The following code example shows how to autofit a table to the page width:

AutoFit Table to Content

When the table is autofitted the content, the following steps are actually performed behind the scenes:

  1. The Table.AllowAutoFit property is enabled to automatically resize each cell according to its content

  2. The preferred table width is removed from Table.PreferredWidth, CellFormat.PreferredWidth is removed for each table cell

  3. Column widths are recalculated for the current table content – the end result is a table where the column widths and the width of the entire table are automatically resized to best fit the content as the user edits the text

The following code example shows how to autofit a table to its content:

Disable AutoFit in Table and Use Fixed Column Widths

If a table has autofit disabled and fixed column widths are used instead, the following steps are performed:

  1. Table.AllowAutoFit property is disabled so columns do not grow or shrink to their content
  2. The preferred width of the entire table is removed from Table.PreferredWidth, CellFormat.PreferredWidth is removed from all table cells
  3. The end result is a table whose column widths are determined by the CellFormat.Width property, and whose columns are not automatically resized when the user enters text or when the page is resized

The following code example shows how to disable autofit and enable fixed width for the specified table:

Order of Precedence when Calculating Cell Width

Aspose.Words allows users to define the width of a table or cell through multiple objects, including CellFormat – its Width property is mostly left over from previous versions, however, it is still useful for simplifying setting the cell width.

It is important to know that the CellFormat.Width property works differently depending on which of the other width properties already exist in the table.

Aspose.Words uses the following order for calculating cell widths:

Order Property Description
1 AllowAutoFit is determined If AutoFit is enabled:
- the table may grow past the preferred width to accommodate the content – it usually does not shrink below the preferred width
- any change to the CellFormat.Width value is ignored and the cell will fit to its contents instead
2 PreferredWidthType with a value of Points or Percent CellFormat.Width is ignored
3 PreferredWidthType with a value of Auto The value from CellFormat.Width is copied and becomes the cell’s preferred width (in points)

Allow Spacing Between Cells

You can get or set any additional space between table cells similar to the “Сell spacing” option in Microsoft Word. This can be done using the AllowCellSpacing property.

An example of how these options are applied to a real table in a document can be seen in the picture below.

formatting-spacing-between-cells-aspose-words-cpp

The following code example shows how to set the spacing between cells:

Apply Borders and Shading

Borders and shading can be applied either to the entire table using Table.SetBorder, Table.SetBorders and Table.SetShading, or only to specific cells using CellFormat.Borders and CellFormat.Shading. Additionally, row borders can be set using RowFormat.Borders, however shading cannot be applied in this way.

The pictures below show the border and shadow settings in Microsoft Word and their corresponding properties in Aspose.Words.

formatting-border-line-aspose-words-cpp

formatting-cell-color-aspose-words-cpp

The following code example shows how to format a table and cell with different borders and shadings: