In a table several cells can be merged together into a single cell. This is useful when certain rows require a title or large blocks of text which span across the width of the table. This can only be achieved by merging some of the cells in the table into a single cell. Aspose.Words supports merged cells when working with all input formats including when importing HTML content.
In Aspose.Words, merged cells are represented by CellFormat.HorizontalMerge and CellFormat.VerticalMerge. The CellFormat.HorizontalMerge property describes if the cell is part of a horizontal merge of cells. Likewise the CellFormat.VerticalMerge property describes if the cell is a part of a vertical merge of cells.
The values of these properties are what define the merge behavior of cells.
· The first cell in a sequence of merged cells will have CellMerge.First.
· Any subsequent merged cells will have CellMerge.Previous.
· A cell which is not merged will have CellMerge.None.
Sometimes when you load an existing document cells in a table will appear merged. However these can be in fact one long cell. Microsoft Word at times is known to export merged cells in this way. This can cause confusion when attempting to work with individual cells. There appears to be no particular pattern as to when this happens.
To check if a cell is part of a sequence of merged cells, we simply check the CellFormat.HorizontalMerge and CellFormat.VerticalMerge properties.
Example
Prints the horizontal and vertical merge type of a cell.
[Java]
public void checkCellsMerged() throws Exception
{
Document doc = new Document(getMyDir() + "Table.MergedCells.doc");
// Retrieve the first table in the document.
Table table = (Table)doc.getChild(NodeType.TABLE, 0, true);
for (Row row : table.getRows())
{
for (Cell cell : row.getCells())
{
System.out.println(printCellMergeType(cell));
}
}
}
public String printCellMergeType(Cell cell)
{
boolean isHorizontallyMerged = cell.getCellFormat().getHorizontalMerge() != CellMerge.NONE;
boolean isVerticallyMerged = cell.getCellFormat().getVerticalMerge() != CellMerge.NONE;
String cellLocation = MessageFormat.format("R{0}, C{1}", cell.getParentRow().getParentTable().indexOf(cell.getParentRow()) + 1, cell.getParentRow().indexOf(cell) + 1);
if (isHorizontallyMerged && isVerticallyMerged)
return MessageFormat.format("The cell at {0} is both horizontally and vertically merged", cellLocation);
else if (isHorizontallyMerged)
return MessageFormat.format("The cell at {0} is horizontally merged.", cellLocation);
else if (isVerticallyMerged)
return MessageFormat.format("The cell at {0} is vertically merged", cellLocation);
else
return MessageFormat.format("The cell at {0} is not merged", cellLocation);
}
The same technique is used to set the merge behavior on the cells in a table. When building a table with merge cells with DocumentBuilder you need to set the appropriate merge type for each cell. Also you must remember to clear the merge setting or otherwise all cells in the table will become merged. This can be done by setting the value of the appropriate merge property to CellMerge.None.
Example
Creates a table with two rows with cells in the first row horizontally merged.
[Java]
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.insertCell();
builder.getCellFormat().setHorizontalMerge(CellMerge.FIRST);
builder.write("Text in merged cells.");
builder.insertCell();
// This cell is merged to the previous and should be empty.
builder.getCellFormat().setHorizontalMerge(CellMerge.PREVIOUS);
builder.endRow();
builder.insertCell();
builder.getCellFormat().setHorizontalMerge(CellMerge.NONE);
builder.write("Text in one cell.");
builder.insertCell();
builder.write("Text in another cell.");
builder.endRow();
builder.endTable();
Example
Creates a table with two columns with cells merged vertically in the first column.
[Java]
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.insertCell();
builder.getCellFormat().setVerticalMerge(CellMerge.FIRST);
builder.write("Text in merged cells.");
builder.insertCell();
builder.getCellFormat().setVerticalMerge(CellMerge.NONE);
builder.write("Text in one cell");
builder.endRow();
builder.insertCell();
// This cell is vertically merged to the cell above and should be empty.
builder.getCellFormat().setVerticalMerge(CellMerge.PREVIOUS);
builder.insertCell();
builder.getCellFormat().setVerticalMerge(CellMerge.NONE);
builder.write("Text in another cell");
builder.endRow();
builder.endTable();
In other situations where a builder is not used, such as in an existing table, merging cells in this way may not be as simple.
Instead we can wrap the base operations which are involved in apply merge properties to cells into a method which makes the task much easier. This method is similar to the automation Merge method which is called to merge a range of cells in a table.
The code below will merge the range of cells in table starting from the given cell, to the end cell. This range can span over many rows or columns.
Example
A method which merges all cells of a table in the specified range of cells.
[Java]
/**
* Merges the range of cells found between the two specified cells both horizontally and vertically. Can span over multiple rows.
*/
public static void mergeCells(Cell startCell, Cell endCell)
{
Table parentTable = startCell.getParentRow().getParentTable();
// Find the row and cell indices for the start and end cell.
Point startCellPos = new Point(startCell.getParentRow().indexOf(startCell), parentTable.indexOf(startCell.getParentRow()));
Point endCellPos = new Point(endCell.getParentRow().indexOf(endCell), parentTable.indexOf(endCell.getParentRow()));
// Create the range of cells to be merged based off these indices. Inverse each index if the end cell if before the start cell.
Rectangle mergeRange = new Rectangle(Math.min(startCellPos.x, endCellPos.x), Math.min(startCellPos.y, endCellPos.y),
Math.abs(endCellPos.x - startCellPos.x) + 1, Math.abs(endCellPos.y - startCellPos.y) + 1);
for (Row row : parentTable.getRows())
{
for(Cell cell : row.getCells())
{
Point currentPos = new Point(row.indexOf(cell), parentTable.indexOf(row));
// Check if the current cell is inside our merge range then merge it.
if (mergeRange.contains(currentPos))
{
if (currentPos.x == mergeRange.x)
cell.getCellFormat().setHorizontalMerge(CellMerge.FIRST);
else
cell.getCellFormat().setHorizontalMerge(CellMerge.PREVIOUS);
if (currentPos.y == mergeRange.y)
cell.getCellFormat().setVerticalMerge(CellMerge.FIRST);
else
cell.getCellFormat().setVerticalMerge(CellMerge.PREVIOUS);
}
}
}
}
Example
Merges the range of cells between the two specified cells.
[Java]
// We want to merge the range of cells found inbetween these two cells.
Cell cellStartRange = table.getRows().get(2).getCells().get(2);
Cell cellEndRange = table.getRows().get(3).getCells().get(3);
// Merge all the cells between the two specified cells into one.
mergeCells(cellStartRange, cellEndRange);