Aspose.Words

Specifying Table and Cell Widths

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.

Using Preferred Widths

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.

Specifying a Preferred Width on a Table in Aspose.Words

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 TablePreferredWidth

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.

Specifying Preferred Width on a Cell

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

Example CellPreferredWidths

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");

 

 

Finding Preferred Width Type and Value of a Table or Cell

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

Example GetPreferredWidthTypeAndValue

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();

 

 

Allowing AutoFit

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 AllowAutoFit

Shows how to set a table to shrink or grow each cell to accommodate its contents.

[Java]

 

table.setAllowAutoFit(true);

 

 

Using Cell Width

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.

The Order of Precedence during Cell Width Calculations

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.