Documentation – Working with Tables in Java

Java: Table Overview

Mon, 01 Jan 0001 00:00:00 +0000

Aspose.Words is a class library designed for server-side processing of documents in various formats – PDF, HTML, different Microsoft Word formats and others – and supports tables in the following ways:

tables in a document are preserved during open/save and conversions
it is possible to edit table, content, and its formatting, and then export the changes to a file in a format that supports tables

In this article, we will learn more about table structure, cells, rows, and columns supported by Aspose.Words, and the details of working with such tables.

Table Structure

As already mentioned, the table consists of such elements as Cell, Row and Column. These are concepts that are common to all tables in general, regardless of the document format.

This is a common example of a table found in a Microsoft Word document:

Table Nodes

A table from any document loaded into Aspose.Words is imported as a Table node. The table can be found as a child of:

main text
an inline story such as a comment or a footnote
cells when a table is nested within another table

Note that tables can be nested inside other tables to any depth.

Table Content

The table node does not contain any real content – instead, it is a container for other such nodes that make up the content:

Table contains many Row nodes. The table provides all the usual node elements, allowing you to freely move, modify, and remove the table in the document.
Row represents a single table row and contains many Cell nodes. In addition, the Row provides elements that define how the row is displayed, such as height and alignment.
Cell is what contains the true content visible in the table and is made up of a Paragraph and other block level nodes. Additionally, cells can contain nested tables.

You can check the structure of table nodes in a document using the DocumentExplorer.

Empty Paragraph after Table

The picture above shows that the document contains a table of several rows, which in turn consists of two cells. Each of the two cells includes a paragraph, which is the container for the cell’s formatted text.

It is also worth noting that separating two consecutive tables in a document requires at least one empty paragraph after the table. Without such a paragraph, consecutive tables would be joined together into one. This behavior is identical in both Microsoft Word and Aspose.Words.

Aspose.Words has a number of classes related to tables – Tables, Rows, Cells, and others.

Java: How to Create a Table in Java

Mon, 01 Jan 0001 00:00:00 +0000

Aspose.Words allows users to create tables in a document from scratch and provides several different methods for doing so. This article presents details on how to add formatted tables to your document using each method, as well as a comparison of each method at the end of the article.

Default Table Styles

The newly created table is given default values similar to those used in Microsoft Word:

Table Property	Default in Aspose.Words
`Border Style`	`Single`
`Border Width`	`1/2 pt`
Border Color	`Black`
`Left and Right Padding`	`5.4 pts`
`AutoFit Mode`	`AutoFit to Window`
`Allow AutoFit`	`True`
A table can be inline if it is tightly positioned, or floating if it can be positioned anywhere on the page. By default, Aspose.Words always creates inline tables.

Create a Table with DocumentBuilder

In Aspose.Words, users can create a table in a document using the DocumentBuilder. The basic algorithm for creating a table is as follows:

Start the table with StartTable
Add a cell to the table using InsertCell – this automatically starts a new row
Optionally, use the CellFormat property to specify cell formatting
Insert the cell content using the appropriate DocumentBuilder methods such as Writeln, InsertImage, and others
Repeat steps 2-4 until the row is complete
Call EndRow to end the current row
Optionally, use the RowFormat property to specify row formatting
Repeat steps 2-7 until the table is complete
Call EndTable to finish building the table

Important details:

StartTable can also be called inside a cell, in which case it starts the creation of a nested table within the cell.
After calling InsertCell, a new cell is created, and any content you add using other methods of the DocumentBuilder class will be added to the current cell. To create a new cell on the same row, call InsertCell again.
If InsertCell is called immediately after EndRow and the end of a row, the table will continue on a new row.
The EndTable method to end the table should only be called once after calling EndRow. Calling EndTable moves the cursor from the current cell to the position immediately after the table.

The process of creating a table can be clearly seen in the following picture:

The following code example shows how to create a simple table using DocumentBuilder with default formatting:

The following code example shows how to create a formatted table using DocumentBuilder:

The following code example shows how to insert a nested table using DocumentBuilder:

Create a Table via DOM (Document Object Model)

You can insert tables directly into the DOM by adding a new Table node at a specific position.

Please note that immediately after the table node creation, the table itself will be completely empty, that is it does not yet contain rows and cells. To insert rows and cells into a table, add the appropriate Row and Cell child nodes to the DOM.

This method of creating a table uses the same table defaults as when using the DocumentBuilder.

The following code example shows how to build a new table from scratch by adding the appropriate child nodes to the document tree:

Create a Table from HTML

Aspose.Words supports inserting content into a document from an HTML source using the InsertHtml method. The input can be a full HTML page or just a partial snippet.

Using this InsertHtml method, users can insert tables into the document via table tags like <table>, <tr>, <td>.

The following code example shows how to insert a table into a document from a string containing HTML tags:

Insert a Copy of an Existing Table

There are often times when you need to create a table based on an already existing table in a document. The easiest way to duplicate a table while retaining all formatting is to clone the Table node using the deepClone method.

The same technique can be used to add copies of an existing row or cell to a table.

The following code example shows how to duplicate a table using node constructors:

You can download the sample file of this example from Aspose.Words GitHub.

The following code example shows how to clone the last row of a table and append it to the table:

You can download the sample file of this example from Aspose.Words GitHub.

If you are looking at creating tables in a document that grow dynamically with each record from your data source, then the above method is not advised. Instead, the desired output is more easily achieved by using Mail merge with regions. You can learn more about this technique in the Mail Merge with Regions section.

Compare Ways to Create a Table

Aspose.Words provides several methods to create new tables in a document. Each method has its own advantages and disadvantages, so the choice of which to use often depends on the specific situation.

Let’s take a closer look at these ways of creating tables and compare their pros and cons:

Method	Advantages	Disadvantages
Via `DocumentBuilder`	The standard method for inserting tables and other document content	Sometimes difficult to create many varieties of tables at the same time with the same builder instance
Via DOM	Fits in better with surrounding code that creates and inserts nodes directly into the DOM without using a DocumentBuilder	The table is created “empty”: before performing most operations, you must call EnsureMinimum to create any missing child nodes
From HTML	Can create a new table from HTML source using tags like `<table>`, `<tr>`, `<td>`	Not all possible Microsoft Word table formats can be applied to HTML
Cloning an existing table	You can create a copy of an existing table while retaining all row and cell formatting	The appropriate child nodes must be removed before the table is ready for use

Java: Work with Columns and Rows in Java

Mon, 01 Jan 0001 00:00:00 +0000

For more control over how tables work, learn how to manipulate columns and rows.

Find the Table Element Index

Columns, rows and cells are managed by accessing the selected document node by its index. Finding the index of any node involves gathering all child nodes of the element type from the parent node, and then using the IndexOf method to find the index of the desired node in the collection.

Find the Index of a Table in a Document

Sometimes you may need to make changes to a particular table in a document. To do this, you can refer to a table by its index.

The following code example shows how to retrieve the index of a table in a document:

Finding the Index of a Row in a Table

Similarly, you may need to make changes to a specific row in a selected table. To do this, you can also refer to a row by its index.

The following code example shows how to retrieve the index of a row in a table:

Finding the Index of a Cell in a Row

Finally, you may need to make changes to a specific cell, and you can do this by cell index as well.

The following code example shows how to retrieve the index of a cell in a row:

Work with Columns

In the Aspose.Words Document Object Model (DOM), the Table node consists of Row nodes and then Cell nodes. Thus, in the Document Object Model of Aspose.Words, as in Word documents, there is no concept of a column.

By design, the table rows in Microsoft Word and Aspose.Words are completely independent, and the basic properties and operations are contained only in the rows and cells of the table. This gives tables the ability to have some interesting attributes:

Each table row can have a completely different number of cells
Vertically, the cells of each row can have different widths
It is possible to join tables with different row formats and number of cells

Any operations performed on columns are actually “shortcuts” that perform the operation by collectively changing row cells in such a way that it looks like they are being applied to columns. That is, you can perform operations on columns by simply iterating over the same table row cell index.

The following code example simplifies such operations by proving a facade class that collects the cells that make up a “column” of a table:

The following code example shows how to insert a blank column into a table:

The following code example shows how to remove a column from a table in a document:

Specify Rows as Header Rows

You can choose to repeat the first row in the table as the Header Row only on the first page or on each page if the table is split into several. In Aspose.Words, you can repeat the Header Row on every page using the HeadingFormat property.

You can also mark multiple header rows if such rows are located one after the other at the beginning of the table. To do this, you need to apply the HeadingFormat properties to these rows.

Note that Header Rows do not work in nested tables. That is, if you have a table inside another table, this setting will have no effect. It is a limitation of Microsoft Word that does not allow this, not Aspose.Words.

The following code example shows how to build a table which includes Header Rows that repeat on subsequent pages:

Keep Tables and Rows from Breaking Across Pages

There are times where the contents of a table should not be split across pages. For instance, if a title is above a table, the title and table should always be kept together on the same page to preserve proper appearance.

There are two separate techniques that are useful to achieve this functionality:

Allow row break across pages, which is applied to table rows
Keep with next, which is applied to paragraphs in table cells

By default, the above properties are disabled.

Keep a Row from Breaking Across Pages

This involves restricting content inside the cells of a row from being split across a page. In Microsoft Word, this can found under Table Properties as the option “Allow row to break across pages”. In Aspose.Words this is found under the RowFormat object of a Row as the property RowFormat.AllowBreakAcrossPages.

The following code example shows how to disable breaking rows across pages for each row in a table:

Keep a Table from Breaking Across Pages

To stop the table from splitting across pages, we need to specify that we want the content contained within the table to stay together.

To do this, Aspose.Words uses a method, which allows users to select a table and enable the KeepWithNext parameter to true for each paragraph within the table cells. The exception is the last paragraph in the table, which should be set to false.

The following code example shows how to set a table to stay together on the same page:

FAQ

Q: How can I insert a new blank column into an existing table?
A: Use a helper class that gathers cells by column index, then iterate through each row and insert a new Cell at the desired position. After insertion, you may need to adjust column widths to maintain layout.
Q: What is the recommended way to remove a column from a table?
A: Iterate over all rows of the table and call Row.getCells().removeAt(columnIndex) for the column you want to delete. Ensure that any merged cells spanning the removed column are handled appropriately.
Q: How do I make the first row of a table repeat as a header on every page?
A: Set Row.getRowFormat().setHeadingFormat(true) on the first row (or on multiple consecutive rows) before saving the document. This marks the rows as header rows that Word repeats on each page.
Q: How can I prevent a table row from breaking across pages?
A: Set Row.getRowFormat().setAllowBreakAcrossPages(false) for the rows you want to keep together. This disables the “Allow row to break across pages” option.
Q: How do I keep an entire table on the same page without splitting?
A: For each paragraph inside the table cells, set Paragraph.getParagraphFormat().setKeepWithNext(true), except for the last paragraph in the table where it should be false. This forces Word to keep the table together when possible.

Java: Merge Table Cells in in Java

Mon, 01 Jan 0001 00:00:00 +0000

Sometimes certain rows in a table require a heading or large blocks of text that take up the full width of the table. For proper design of the table, the user can merge several table cells into one. Aspose.Words supports merged cells when working with all input formats, including importing HTML content.

How to Merge Table Cells

In Aspose.Words, merged cells are represented by the following properties of the CellFormat class:

HorizontalMerge which describes if the cell is a part of a horizontal merge of cells
VerticalMerge which describes if the cell is a part of a vertical merge of cells

The values of these properties determine the merge behavior of cells:

The first cell in a sequence of merged cells will have CellMerge.First
Any subsequently merged cells will have CellMerge.Previous
A cell that is not merged will have CellMerge.None

Sometimes, when loading existing document cells in a table, they will appear merged. However, it can actually be one long cell – sometimes Microsoft Word exports merged cells this way. This can be confusing when attempting to work with individual cells, but there doesn’t seem to be any particular pattern as to when this happens.

Checking if a Cell is Merged

To check if a cell is part of a sequence of merged cells, we simply check the HorizontalMerge and VerticalMerge properties.

The following code example shows how to print the horizontal and vertical cell merge type:

Merge Table Cells When Using DocumentBuilder

To merge cells in a table created with the DocumentBuilder, you need to set the appropriate merge type for each cell where the merge is expected – first CellMerge.First and then CellMerge.Previous.

Also, you must remember to clear the merge setting for those cells where no merge is required – this can be done by setting the first non-merge cell to CellMerge.None. If this is not done, all cells in the table will be merged.

The following code example shows how to create a table with two rows where the cells in the first row are merged horizontally:

The following code example shows how to create a two-column table where the cells in the first column are vertically merged:

Merge Table Cells in Other Cases

In other situations where the DocumentBuilder is not used, such as in an existing table, merging cells in the previous way may not be as easy. Instead, we can wrap the basic operations involved in applying merge properties to cells in a method that makes the task much easier. This method is similar to the Merge automation method, which is called to merge a range of cells in a table.

The code below will merge the table cells in the specified range, starting at the given cell and ending at the end cell. In this case, the range can span multiple rows or columns:

The following code example shows how to merge a range of cells between two specified cells:

Vertical and Horizontal Merged Cells in HTML Table

As we have said in previous articles, a table in Microsoft Word is a set of independent rows. Each row has a set of cells that are independent of the cells of other rows. Thus, in the Microsoft Word table there is no such object as a “column”, and “1st column” is something like “the set of the 1st cells of each row in the table”. This allows users to have a table in which, for example, the 1st row consists of two cells – 2cm and 1cm, and the 2nd row consists of two different cells – 1cm and 2cm wide. And Aspose.Words supports this concept of tables.

A table in HTML has a essentially different structure: each row has the same number of cells and (it is important for the task) each cell has the width of the corresponding column, the same for all cells in one column. So if HorizontalMerge and VerticalMerge return an incorrect value, use the following code example:

Convert to Horizontally Merged Cells

Sometimes it is not possible to detect which cells are merged because some newer versions of Microsoft Word no longer use the merge flags when cells are merged horizontally. But for situations where cells are merged into a cell horizontally by their width using merge flags, Aspose.Words provides the ConvertToHorizontallyMergedCells method to convert cells. This method simply transforms the table and adds new cells as needed.

The following code example shows the above method in operation:

FAQ

Q: How do I merge cells horizontally using DocumentBuilder?
A: Create the table with DocumentBuilder, then for the first cell in the merge set cell.getCellFormat().setHorizontalMerge(CellMerge.First). For each subsequent cell that should be merged, set CellMerge.Previous. After the merged range, set the next cell’s HorizontalMerge to CellMerge.None to stop the merge.
Q: How can I merge cells vertically?
A: The process is analogous to horizontal merging but uses the VerticalMerge property. Set CellMerge.First on the top‑most cell of the column, CellMerge.Previous on the cells below, and reset to CellMerge.None after the merged block.
Q: How can I determine whether a particular cell is part of a merged group?
A: Inspect the cell’s format: cell.getCellFormat().getHorizontalMerge() and cell.getCellFormat().getVerticalMerge(). If either returns CellMerge.First or CellMerge.Previous, the cell participates in a merge; CellMerge.None means it is not merged.
Q: Is there a way to merge a rectangular range of cells programmatically?
A: Yes. Loop through the cells in the desired range and set the appropriate HorizontalMerge and VerticalMerge values. Typically you set CellMerge.First on the top‑left cell, CellMerge.Previous on the remaining cells in the first row for horizontal merges, and similarly use VerticalMerge for rows. Aspose.Words also provides helper methods (e.g., a custom mergeRange method) that encapsulate this logic.
Q: My table appears to have merged cells, but the merge flags are missing. How can I fix this?
A: Use the Table.convertToHorizontallyMergedCells() method. It analyses the visual widths of cells, inserts missing cells where needed, and sets the correct HorizontalMerge flags so that the merged state is represented accurately in the document model. This resolves issues where Word exported a merged cell as a single wide cell without flags.

Java: Table Position in Java

Mon, 01 Jan 0001 00:00:00 +0000

There are floating tables and inline tables:

Inline tables are placed on the same layer as the text and are placed in a flow of text that only surrounds the table above and below. Inline tables will always appear between the paragraphs where you placed them.
Floating tables are layered over the text, and the position of the table relative to the paragraph is determined by the table anchor. Because of this, the position of the floating table in the document is affected by the vertical and horizontal positioning settings.

Sometimes you need to position a table in a document in a certain way. To do this, you need to use the alignment tools and set the indents between the table and the surrounding text.

In this article, we will discuss what options Aspose.Words provides for positioning.

Specify Inline Table Position

You can set the position of an inline table using the Aspose.Words API and the Alignment property. Thus, you can adjust the alignment of the table relative to the document page.

The following code example shows how to set the position of an inline table:

Get Floating Table Alignment

If the table text wrapping is set to Around, you can get the table’s horizontal and vertical alignment using the RelativeHorizontalAlignment and RelativeVerticalAlignment properties.

With other types of text wrapping, you can get inline table alignment using the Alignment property.

The following code example shows how to get the table’s alignment:

Get Floating Table Position

The position of a floating table is determined using the following properties:

HorizontalAnchor – an object for calculating the horizontal positioning of a floating table
VerticalAnchor – an object for calculating the vertical positioning of a floating table
AbsoluteHorizontalDistance – absolute horizontal floating table position
AbsoluteVerticalDistance – absolute vertical floating table position
AllowOverlap – option to enable/disable overlap with other floating objects
RelativeHorizontalAlignment – floating table relative horizontal alignment.
RelativeVerticalAlignment – floating table relative vertical alignment.

The following code example shows how to get the position of a floating table:

Set Floating Table Position

Just like getting, you can set the position of a floating table using the same Aspose.Words API.

It is important to know that alignment and horizontal and vertical distance are combined properties and one can reset the other. For example, setting the RelativeHorizontalAlignment will reset the AbsoluteHorizontalDistance to its default value and vice versa. The same is true for the vertical arrangement.

The following code example shows how to set the position of a floating table:

Get Distance between Table and Surrounding Text

Aspose.Words also provides an opportunity to find out the distances between tables and surrounding texts:

DistanceTop – the value of the distance from above
DistanceBottom – the value of the distance of perception
DistanceRight – distance value on the right
DistanceLeft – distance value on the left

The following code example shows how to get the distance between a table and its surrounding text:

Java: Work with Text in a Table

Mon, 01 Jan 0001 00:00:00 +0000

As mentioned in previous articles, a table usually contains plain text, although other content such as images or even other tables can be placed in table cells.

Adding text or other content to the table is carried out using the appropriate methods of the DocumentBuilder class and is described in the “Create a Table” article. In this article, we will talk about how to work with text in an already existing table.

Replace Text in a Table

The table, like any other node in Aspose.Words, has access to the Range object. Using the table range object, you can replace text in a table.

The ability to use special characters when replacing is currently supported, so it is possible to replace existing text with multi-paragraph text. To do this, you need to use the special metacharacters described in the corresponding Replace method.

Typically, text replacement should be done at the cell level (per cell) or at the paragraph level.

The following code example shows how to replace all instances of a string of text in the cells of an entire table:

Extract Plain Text from a Table

Using the Range object, you can also call methods on the entire table range and extract the table as plain text. To do this, use the Text property.

The following code example shows how to print the text range of a table:

The same technique is used to extract content from individual table cells only.

The following code example shows how to print a text range of row and table elements:

The following code example shows how to print the text range of row and table elements.

Working with Alternative Table Text

Microsoft Word tables have a table title and table description that provide an alternative textual representation of the information contained in the table.

In Aspose.Words, you can also add a table title and description using the Title and Description properties. These properties are meaningful for DOCX documents conforming to the ISO/IEC 29500. When saving in formats earlier than ISO/IEC 29500, these properties are ignored.

The following code example shows how to set the title and description properties of a table:

Java: Table Formatting in Java

Mon, 01 Jan 0001 00:00:00 +0000

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 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.

Note that the table must have at least one row before the table properties can be applied. This means that when building a table with the DocumentBuilder, this formatting must be done after the first call to InsertCell, or after the first row is added to the table, or when nodes are inserted directly into the DOM.

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.

Note that a Row can only be a child node of a Table. At the same time, there must be at least one Cell in the Row so that formatting can be applied to it.

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:

Specifying 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.

Rule options for specifying the height of an object can be set using the HeightRule fields.

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

Specify 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.

All properties and methods described in this article are related to how tables work in Microsoft Word. So 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 into your application.

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 field 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.

Before you can use the preferred width in a table, you must ensure that the table contains at least one row. This is because such table formatting in a Microsoft Word document or in a document created in Aspose.Words is stored in the rows of the table.

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

By default, a 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.

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.

Additionally, the AllowAutoFit property can be used in conjunction with a preferred cell width to format a cell that automatically fits its content, but also has an initial width. If necessary, the cell width can then grow past this width.

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:

We will use the following table to apply the various auto fit settings as a demonstration.

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:

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

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:

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

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

Note that if no width is specified for CellFormat.Width, the default value of one inch (72 points) is used.

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

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

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)

Any changes to the width property are not updated in the preferred width and must instead be applied to the preferred width instead.

While creating a fixed table layout, specify the cell width. A cell without width cannot be saved to DOC format. Document formats other than DOC, such as DOCX, allow, in principle, saving cells without width in a fixed table layout.

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:

FAQ

Q: How can I set a fixed width for a specific table column?
A: Use the CellFormat.PreferredWidth property on the target cell and set it with PreferredWidth.fromPoints(double) or PreferredWidth.fromPercent(double). The column will adopt this width unless AutoFit overrides it.
Q: What is the difference between AllowAutoFit and PreferredWidth?
A: AllowAutoFit lets the table automatically resize columns based on content. PreferredWidth defines an explicit width that the table or cell tries to achieve. If AutoFit is enabled, explicit widths may be ignored.
Q: How do I add spacing between cells (cell spacing) programmatically?
A: Set Table.setAllowCellSpacing(true) and then assign a spacing value with Table.setCellSpacing(double) (the spacing is measured in points).
Q: How can I apply different border styles to the first row only?
A: Access the first Row object, retrieve its RowFormat, and use RowFormat.getBorders().setLineStyle(LineStyle.SINGLE) (or other styles) to customize the borders for that row alone.
Q: How do I control row height and ensure it is respected?
A: Use Row.getRowFormat().setHeight(double) to set the height in points and Row.getRowFormat().setHeightRule(HeightRule.EXACT) to enforce the exact height, preventing Word from adjusting it automatically.

Java: Working with Table Styles in Java

Mon, 01 Jan 0001 00:00:00 +0000

A table style defines a set of formatting that can be easily applied to a table. Formatting such as borders, shading, alignment, and font can be set in a table style and applied to many tables for a consistent appearance.

Aspose.Words supports applying a table style to a table and also reading properties of any table style. Table styles are preserved during loading and saving in the following ways:

Table styles in DOCX and WordML formats are preserved when loading and saving to these formats
Table styles are preserved when loading and saving in DOC format (but not to any other format)
When exporting to other formats, rendering or printing, table styles are expanded to direct formatting in the table, so all formatting is preserved

Create a Table Style

The user can create a new style and add it to style collection. The Add method is used to create a new table style.

The following code example shows how to create a new user defined table style:

Copy an Existing Table Style

If necessary, you can copy a table style that already exists in a certain document into your style collection using the AddCopy method.

It is important to know that with this copying, the linked styles are also copied.

The following code example shows how to import a style from one document to another document:

Apply an Existing Table Style

Aspose.Words provides a TableStyle inherited from the Style class. TableStyle facilitates the user to apply different style options like as shading, padding, indentation, CellSpacing and Font, etc.

In addition, Aspose.Words provides the StyleCollection class and a few properties of the Table class to specify which table style we will work with: Style, StyleIdentifier, StyleName, and StyleOptions.

Aspose.Words also provides ConditionalStyle class that represents special formatting applied to some area of a table with an assigned table style, and the ConditionalStyleCollection that represents a collection of ConditionalStyle objects. This collection contains a permanent set of items representing one item for each value of the ConditionalStyleType enumeration type. The ConditionalStyleType enumeration defines all possible table areas to which conditional formatting may be defined in a table style.

In this case, conditional formatting can be defined for all possible table area defined under the ConditionalStyleType enumeration type.

The following code example shows how to define conditional formatting for header row of the table:

You can also choose which table parts to apply styles to, such as first column, last column, banded rows. They are listed in the TableStyleOptions enumeration and are applied through the StyleOptions property. The TableStyleOptions enumeration allows a bitwise combination of these features.

The following code example shows how to create a new table with a table style applied:

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

Take Formatting from Table Style and Apply it as Direct Formatting

Aspose.Words also provides the ExpandTableStylesToDirectFormatting method to take formatting found on a table style and expands it onto the rows and cells of the table as direct formatting. Try combining formatting with table style and cell style.

This method will not override any other formatting already applied to the table through a row or cell format.

The following code example shows how to expand the formatting from styles onto table rows and cells as direct formatting:

FAQ

Q: How do I create a custom table style in Java?
A: Use the StyleCollection.add method on the document’s style collection, specifying a name and StyleType.TABLE. After creating the style, set its properties such as Font, Shading, Borders, and ParagraphFormat. Finally, add the style to the collection so it can be applied to tables.
Q: Can I copy a table style from another document?
A: Yes. Load the source document, retrieve the desired Style from its StyleCollection, and call StyleCollection.addCopy(sourceStyle) on the target document’s style collection. This copies the style together with any linked styles.
Q: What is the simplest way to apply an existing table style to a table?
A: Set the table’s StyleIdentifier, StyleName, or Style property. For example, table.setStyleIdentifier(StyleIdentifier.TABLE_GRID_LIGHT) or table.setStyleName("MyCustomStyle"). The table will immediately reflect the style’s formatting.
Q: How can I add conditional formatting (e.g., header row shading) to a table style?
A: Access the style’s ConditionalStyleCollection via TableStyle.getConditionalStyles(). Retrieve the ConditionalStyle for ConditionalStyleType.HEADER_ROW and modify its Shading, Font, or other properties. The conditional formatting is applied automatically to the matching table area.
Q: How do I convert a table style into direct formatting on a table’s rows and cells?
A: Call Document.expandTableStylesToDirectFormatting() after the table has the style applied. This method expands all style‑based formatting into explicit formatting on each row and cell, preserving the appearance while removing the style reference.

Java: Join Tables in Java

Mon, 01 Jan 0001 00:00:00 +0000

A table, represented in the Aspose.Words Document Object Model, is made up of independent rows and cells, making it easy to join tables.

To manipulate a table to join with another table, we just need to move the rows from the second table to the end of the first one and remove the second table’s container.

The following code example shows how to merge rows from two tables into one:

FAQ

Q: How can I join two tables in a Word document using Aspose.Words for Java?
A: Locate the two Table objects in the document, then move each Row from the second table into the first using firstTable.appendChild(row.deepClone(true)). After all rows are transferred, remove the now‑empty second table with secondTable.remove(). Finally, call doc.updatePageLayout() to refresh the layout.
Q: How do I split a joined table back into separate tables?
A: Create a new Table instance, move the rows you want to separate from the original table into the new one, and insert the new table at the desired position using firstTable.getParentNode().insertAfter(newTable, firstTable). Adjust any required formatting on the new table’s rows and cells.
Q: The joined table loses its original formatting after moving rows. What should I do?
A: Preserve formatting by cloning the row with row.deepClone(true), which copies both content and formatting. After the join, call firstTable.ensureMinimum() and doc.updatePageLayout() to make sure the table layout is recalculated and the formatting is applied correctly.

Java: Split Table in Java

Mon, 01 Jan 0001 00:00:00 +0000

A table, represented in the Aspose.Words Document Object Model, is made up of independent rows and cells, making it easy to split a table.

To manipulate a table to split it into two tables, we just need to move some of the rows from the original table to the new one. To do this, we need to pick the row by which we want to split the table.

We can create two tables from the original table by following these simple steps:

Create a clone of the table without cloning the children to keep the moved rows and insert them after the original table
Starting at the specified row, move all subsequent rows to this second table

The following code example shows how to split a table into two tables on a specific row:

FAQ

Q: How can I split a table at a specific row using Aspose.Words for Java?
A: Load the document, locate the target Table node, clone the table without its child nodes (Table clonedTable = (Table) originalTable.deepClone(false);), insert the cloned table after the original, then move each Row starting from the split row to the cloned table using clonedTable.appendChild(row);. This creates two independent tables.
Q: Does cloning a table also clone its rows and cells?
A: By default deepClone(true) copies the table together with all its rows and cells. To split a table you should use deepClone(false) so only the table structure is cloned; the rows are then moved manually to the new table.
Q: After splitting, how do I preserve the original table’s formatting in the new table?
A: The cloned table inherits the original table’s formatting (borders, shading, width, etc.) because the clone copies the table’s properties. Since you move existing Row objects, their individual formatting is retained as well. If you need to adjust spacing, modify Table.setAllowAutoFit(false) or set Table.getRowFormat().setHeight(...) on the new table.
Q: Can I split a table without affecting the surrounding document layout (e.g., page breaks or spacing)?
A: Yes. Insert the cloned table immediately after the original with originalTable.getParentNode().insertAfter(clonedTable, originalTable);. This keeps the flow of paragraphs unchanged. If a page break is required, insert a Paragraph with a page break (Paragraph pageBreak = new Paragraph(doc); pageBreak.appendChild(new Break(BreakType.PAGE_BREAK));) between the two tables.

Java: How to Build a Table from a DataTable in Java

Mon, 01 Jan 0001 00:00:00 +0000

Often your application will pull data from a database and store it in the form of a DataTable. You may wish to easily insert this data into your document as a new table and quickly apply formatting to the whole table.

Note that the preferred way of inserting data from a DataTable into a document table is by using Mail Merge with Regions. The technique presented in this article is only suggested if you are unable to create a suitable template beforehand to merge data with, in other words, if you require everything to happen programmatically.

Using Aspose.Words, you can easily retrieve data from a database and store it as a table:

Create a new DocumentBuilder object on your Document.
Start a new table using DocumentBuilder.
If we want to insert the names of each of the columns from our DataTable as a header row then iterate through each data column and write the column names into a row in the table.
Iterate through each DataRow in the DataTable:
1. Iterate through each object in the DataRow.
2. Insert the object into the document using DocumentBuilder. The method used depends on the type of the object being inserted e.g DocumentBuilder.writeln() for text and DocumentBuilder.insertImage() for a byte array which represents an image.
3. At the end of processing of the data row also end the row being created by the DocumentBuilder by using DocumentBuilder.endRow().
Once all rows from the DataTable have been processed finish the table by calling DocumentBuilder.endTable().
Finally, we can set the desired table style using one of the appropriate table properties such as Table.getStyleIdentifier() to automatically apply formatting to the entire table. The following data in our DataTable is used in this example:

The following code example shows how to execute the above algorithm in Aspose.Words:

The method can then be easily called using your DocumentBuilder and data.

The following code example shows how to import the data from a DataTable and insert it into a new table in the document:

The table shown in the picture below is produced by running the above code.

FAQ

Q: How can I insert an image stored as a byte array into a table cell?
A: Use DocumentBuilder.insertImage(byte[] imageBytes) while the builder’s cursor is positioned inside the desired cell. After inserting the image you may call DocumentBuilder.endRow() to continue with the next cell.
Q: What is the easiest way to apply a predefined table style after the table is built?
A: Retrieve the Table node (the first child of the builder’s current paragraph) and call table.setStyleIdentifier(StyleIdentifier.LIGHT_LIST) (or any other StyleIdentifier). The style is applied to the whole table instantly.
Q: Is there a more automatic approach than writing code for each column when populating a table from a DataTable?
A: Yes. Aspose.Words’ Mail Merge with Regions can map a DataTable directly to a table in a template. Create a region in the template (<<TableStart:Data>> … <<TableEnd:Data>>) and call document.getMailMerge().executeWithRegions(dataTable). This eliminates manual iteration.
Q: How should I handle null values in the DataTable while building the table?
A: Check each cell value before writing. If the value is null, write an empty string or a placeholder, e.g. builder.writeln(""). This prevents NullPointerException and keeps the table layout consistent.
Q: Can I merge cells or set column widths after the table has been created?
A: Yes. After endTable(), locate the Table node, then use Cell.merge(Cell other) to merge cells horizontally or vertically. Column widths can be set via Table.getFirstRow().getCells().get(i).getCellFormat().setWidth(width). Adjust widths before saving the document.

Documentation – Working with Tables in Java

Java: Table Overview

Table Structure

Table Nodes

Table Content

Empty Paragraph after Table

See Also

Java: How to Create a Table in Java

Default Table Styles

Create a Table with DocumentBuilder

Create a Table via DOM (Document Object Model)

Create a Table from HTML

Insert a Copy of an Existing Table

Compare Ways to Create a Table

Java: Work with Columns and Rows in Java

Find the Table Element Index

Find the Index of a Table in a Document

Finding the Index of a Row in a Table

Finding the Index of a Cell in a Row

Work with Columns

Specify Rows as Header Rows

Keep Tables and Rows from Breaking Across Pages

Keep a Row from Breaking Across Pages

Keep a Table from Breaking Across Pages

FAQ

Java: Merge Table Cells in in Java

How to Merge Table Cells

Checking if a Cell is Merged

Merge Table Cells When Using DocumentBuilder

Merge Table Cells in Other Cases

Vertical and Horizontal Merged Cells in HTML Table

Convert to Horizontally Merged Cells

FAQ

Java: Table Position in Java

Specify Inline Table Position

Get Floating Table Alignment

Get Floating Table Position

Set Floating Table Position

Get Distance between Table and Surrounding Text

Java: Work with Text in a Table

Replace Text in a Table

Extract Plain Text from a Table

Working with Alternative Table Text

Java: Table Formatting in Java

Apply Formatting to Different Nodes

Table Level Formatting

Row Level Formatting

Cell Level Formatting

Specifying Row Heights

Specify Table and Cell Widths

How to Use Preferred Width

Specify the Preferred Table or Cell Width

Find Preferred Width Type and Value

How to Set Autofit

AutoFit Table to Window

AutoFit Table to Content

Disable AutoFit in Table and Use Fixed Column Widths

Order of Precedence when Calculating Cell Width

Allow Spacing Between Cells

Apply Borders and Shading

FAQ

Java: Working with Table Styles in Java

Create a Table Style

Copy an Existing Table Style

Apply an Existing Table Style

Take Formatting from Table Style and Apply it as Direct Formatting

FAQ

Java: Join Tables in Java

FAQ

Java: Split Table in Java

FAQ

Java: How to Build a Table from a DataTable in Java

FAQ