A table in a Microsoft word document provides several different ways to size a table and individual cells. These properties allow considerable control over the overall appearance and behavior of the table.
This article gives an in-depth look into how the different width calculation properties of tables work and provides information which will allow you gain full control of how table widths are calculated. This is useful to know in such cases where a table layout does not appear as expected.
Table elements present several different properties that can affect how the width of the overall table as well as individual cells are calculated. These are each explained in detail in this article.
· Preferred width on table.
· Preferred width on individual cells.
· Allowing autofit on the table.
· Regular cell width
All of the properties and techniques that are described in this article all link back to how tables work in Microsoft Word. Therefore in most cases, if you are building your table programmatically but are finding it hard to create the desired table you can instead try visually creating it in Microsoft Word first and then simply copy the formatting values to your application.
The desired width of a table or individual cells is defined through the preferred width property. That is a preferred width can be specified on individual cells or to the table as a whole. This is the size that the element strives to fit to. In some cases it may not be possible to fit to this exact width, but the real width will come close to this value on most occasions.
The preferred width property can be expressed in one of several different ways:
Width Type |
Behavior |
Absolute |
This fits the element to the given width in points. |
Percent |
Fits the element relative of the available space in the window or container size. If the available width changes then the table will automatically grow or shrink to reflect these changes. |
Auto |
This is the same as having no preferred width set. In this case size of the element is calculated using one of the other elements belonging to table which does have a size set. |
An example of how these are applied to a real table in a document can be seen in the diagram below.
The table can be described as being fitted to 100% of the available space on the page. In this case this means the table will try to take up the space between the left and right page margins.
The cells in the above table can be described as such:
· The width of the first cell is set at 40 points. This width shouldn’t vary even if the table is resized or other cells removed.
· The second cell is specified as taking up 20% of the available space in the table. This means if the table size was changed, the width of this cell should change as well to reflect this.
· The third cell is defined as auto or “width not defined”. This means the width of the cell is calculated using the other size information of the table. Normally such a cell will take up the remaining space in the table.
In Aspose.Words the sizing modes described above can be found under the PreferredWidthType enumeration and are set using the Table.PreferredWidth property and CellFormat.PreferredWidth property.
The appropriate preferred width type and value is set by using the methods of the PreferredWidth class. For instance, to specify a width from points you would use the PreferredWidth.FromPoints method. To specify a percentage width you would use PreferredWidth.FromPercent. Finally to specify auto or “no preferred width” you would use PreferredWidth.Auto.
Using the Table.PreferredWidth property will adjust its preferred width relative to the container (i.e the page, text column or outer table cell).
Example
Shows how to set a table to auto fit to 50% of the page width.
[Java]
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a table with a width that takes up half the page width.
Table table = builder.startTable();
// Insert a few cells
builder.insertCell();
table.setPreferredWidth(PreferredWidth.fromPercent(50));
builder.writeln("Cell #1");
builder.insertCell();
builder.writeln("Cell #2");
builder.insertCell();
builder.writeln("Cell #3");
doc.save(getMyDir() + "Table.PreferredWidth Out.doc");
Before you can use preferred widths on a table you must make sure that the table contains at least one row. This is because such table formatting in a Microsoft Word document is stored in the rows of a table.
Using the CellFormat.PreferredWidth property on a given cell will adjust its preferred width.
Example
Shows how to set the different preferred width settings.
[Java]
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a table row made up of three cells which have different preferred widths.
Table table = builder.startTable();
// Insert an absolute sized cell.
builder.insertCell();
builder.getCellFormat().setPreferredWidth(PreferredWidth.fromPoints(40));
builder.getCellFormat().getShading().setBackgroundPatternColor(Color.RED);
builder.writeln("Cell at 40 points width");
// Insert a relative (percent) sized cell.
builder.insertCell();
builder.getCellFormat().setPreferredWidth(PreferredWidth.fromPercent(20));
builder.getCellFormat().getShading().setBackgroundPatternColor(Color.BLUE);
builder.writeln("Cell at 20% width");
// Insert a auto sized cell.
builder.insertCell();
builder.getCellFormat().setPreferredWidth(PreferredWidth.AUTO);
builder.getCellFormat().getShading().setBackgroundPatternColor(Color.GREEN);
builder.writeln("Cell automatically sized. The size of this cell is calculated from the table preferred width.");
builder.writeln("In this case the cell will fill up the rest of the available space.");
doc.save(getMyDir() + "Table.PreferredWidths Out.doc");
You can use the PreferredWidth.Type and PreferredWidth.Value properties to find the preferred width details of the desired table or cell.
Example
Retrieves the preferred width type of a table cell.
[Java]
Cell firstCell = table.getFirstRow().getFirstCell();
int type = firstCell.getCellFormat().getPreferredWidth().getType();
double value = firstCell.getCellFormat().getPreferredWidth().getValue();
The Table.AllowAutoFit property enables cells in the table to grow and shrink to accommodate their contents. This property can be used in conjunction with a preferred cell width to format a cell which auto fits its content but which also has an initial width. The cell width can then grow past this width if needed. Therefore if you are using a table as layout or placeholder for content then you should disable this property on your table.
Example
Shows how to set a table to shrink or grow each cell to accommodate its contents.
[Java]
table.setAllowAutoFit(true);
In Aspose.Words the CellFormat object also provides a width property. This property is mainly left over from previous versions, however it is still useful as a way to simplify setting a cell’s width. This property now acts differently depending on which of the other width properties already exist on the table:
· If a cell has a preferred width of PreferredWidthType.Auto type (no preferred width set) then the value from the CellFormat.Width is copied over and becomes the preferred width of the cell (in points).
· If a cell has a cell preferred width of PreferredWidthType.Percent then any changes to CellFormat.Width is ignored.
· If a cell already has a preferred width of type PreferredWidthType.Points then any changes to CellFormat.Width is ignored. That is, any changes to the width property are not updated in preferred width and should be applied to the preferred width instead.
· If the table has Table.AllowAutoFit enabled then any change in CellFormat.Width value is ignored and the cell is fitted to its contents instead.
Aspose.Words uses the following order when calculating cell widths.
Order |
Property |
Description |
1 |
CellFormat.PreferredWidth |
Ideally the preferred widths are used to calculate the cell sizes. |
2 |
Table.AllowAutoFit |
If auto fit is allowed then the table may grow past the preferred width to accommodate contents. Normally it will not shrink below the preferred width. |
3 |
CellFormat.Width |
If neither of the settings above are present then the width defined under CellFormat.Width is used. |
4 |
(Default value) |
If no other property is present (i.e if the first two properties are not set and the cell width is left as 0) then a hardcoded value of one inch (72 points) is used instead. |