mergeCells

Type: Integer

Availability: Read or write at run time only

The mergeCells property of the JadeTableCell class contains a value that specifies the type of cell merging that can be performed, if any. You can set the mergeCells property to one of the Table class constants listed in the following table.

Table Class Constant	Value	Description
MergeCells_Available	0	Cell available for merging if empty (the default value)
MergeCells_Merge	1	Merge all following empty cells
MergeCells_MergeSelectable	2	Merge all following empty cells (cells still selectable)
MergeCells_NotAvailable	3	Current cell not available for merging

The mergeCells property enables you to extend a cell over adjacent cells, as shown in the following image.

In this example, the table holds entries divided into months, with the month heading centered across three cells and an extended fixed-column cell further dividing each month.

Setting the mergeCells property of a cell to MergeCells_MergeSelectable (2) or MergeCells_Merge (1) causes that cell to be drawn across adjacent cells of the same row. The drawing stops prior to a cell in which one of the following applies.

The mergeCells property of the cell is not set to MergeCells_Available (0).
The cell has a non-null text value.
The cell has a non-null picture value.
The cell is the current cell.

The mergeCells property can be set to a value represented by a Table control class constant, as follows.

MergeCells_Available (0)

If the cell has no text or picture, it can be merged into a preceding cell. (This is the default value for all cells.)
MergeCells_Merge (1)

The cells following the cell will be merged into this cell up to the end of the row or up to (but not including):
- A cell that contains a text or picture
- The mergeCells property of the cell is not MergeCells_Available (0)
- The cell is the current cell
Clicking anywhere in the expanded cell is treated as a click event in that cell and the hidden cell or cells cannot be accessed. Similarly, the left and right arrow keys ignore the covered cells.

The getCellFromPosition method also returns the merged cell for any position within the whole of the drawn cell.
MergeCells_MergeSelectable (2)

Cells are merged in exactly the same way as they are when the property is set to the MergeCells_Merge value, but the covered cells can be ‘brought back to life’ by clicking on the expanded cell in the position corresponding to the hidden cell. Similarly, the left and right arrow keys step into the previously hidden cells rather than skipping to the start or end of the merged cell.

The getCellFromPosition method also returns the cell that corresponds to the position, ignoring any merged cell size.
MergeCells_NotAvailable (3)

This setting has no effect on that cell except to specifically terminate any merging process; that is, this cell cannot be merged.

This value is required only to terminate the merging process prior to an empty cell.

If the cells are automatically resized (by using the Table class autoSize property) and the cell contents do not fit within the whole of the merged columns, the first column of the merged columns is enlarged. (This size is calculated by determining the size of the merged columns using the above rules, except that the current cell does not terminate the merging of the cells.)

The following example shows the use of the mergeCells property.

table1.accessCell(2, 2).mergeCells := Table.MergeCells_Merge;
    // column 2 merges following cells
table1.accessedCell.text           := "Heading 1";
table1.accessedCell.alignment      := Table.Alignment_Center_Middle;
    // center
table1.accessCell(2, 7).mergeCells := Table.MergeCells_NotAvailable;
    // ensure merging ended

Merged cells do not affect the values of the Table control class columnWidth property.

A merged cell uses the total displayed width for data entry when used with a cell that has the inputType property set or that has a JadeTableElement class cellControl property.

If the horizontal alignment of the cell is not left aligned, the alignment is performed based on the total width of the merged cell.

You can also merge cells belonging to a fixed row and column to allow, for example, headings that span more than one column. If you merge fixed cells, the moving and resizing processes of columns and rows are also affected by whether the MergeCells_MergeSelectable (2) or MergeCells_Merge (1) value applies. For the MergeCells_Merge value, the hidden cells cannot be moved or resized, while they can be for the MergeCells_MergeSelectable value.

See also the JadeTableCell class getCellWidth method.