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.
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.
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.
Note that a Cell can only be a child node of a Row. At the same time, there must be at least one Paragraph in the Cell so that formatting can be applied to it.
In addition to the Paragraph, you can also insert a Table into a Cell.
The pictures below show a representation of the Cell formatting features in Microsoft Word and their corresponding properties in Aspose.Words.
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.
In most cases, the preferred cell is recommended than the table width. The preferred cell width is more in line with the DOCX format specification as well as the Aspose.Words model.
The cell width is actually a calculated value for the DOCX format. The actual cell width can depend on many things. For example, changing the page margins or the preferred table width can affect the actual cell width.
The preferred cell width is a cell property that is stored in the document. It does not depend on anything and does not change when you change the table or other properties of the cell.
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.
An example of how these options are applied to a real table in a document can be seen in the picture below.
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:
- The Table.AllowAutoFit property is enabled to automatically resize columns to fit the available content, using a Table.PreferredWidth value of 100%
- CellFormat.PreferredWidth is removed from all table cells
Note that this is slightly different from the Microsoft Word behavior, where each cell’s preferred width is set to appropriate values based on their current size and content. Aspose.Words does not update the preferred width so they just get cleared instead.
- Column widths are recalculated for the current table content – the end result is a table that occupies the entire available width
- 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:
-
The Table.AllowAutoFit property is enabled to automatically resize each cell according to its content
-
The preferred table width is removed from Table.PreferredWidth, CellFormat.PreferredWidth is removed for each table cell
Note that this autofit option removes the preferred width from cells, just like in Microsoft Word. If you want to keep the column sizes and increase or decrease the columns to fit the content, you should set the Table.AllowAutoFit property to True on its own rather than using the autofit shortcut. -
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:
- Table.AllowAutoFit property is disabled so columns do not grow or shrink to their content
- The preferred width of the entire table is removed from Table.PreferredWidth, CellFormat.PreferredWidth is removed from all table cells
- 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.
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.
The following code example shows how to format a table and cell with different borders and shadings: