|  | Home · Overviews · Examples

# QTextTable Class Reference
[com.trolltech.qt.gui module]

The `QTextTable` class represents a table in a `QTextDocument`. More...

Inherits `QTextFrame`.

## Detailed Description

The `QTextTable` class represents a table in a `QTextDocument`.

A table is a group of cells ordered into rows and columns. Each table contains at least one row and one column. Each cell contains a block, and is surrounded by a frame.

Tables are usually created and inserted into a document with the QTextCursor::insertTable() function. For example, we can insert a table with three rows and two columns at the current cursor position in an editor using the following lines of code:

            QTextCursor cursor(editor->textCursor());
            cursor.movePosition(QTextCursor::Start);

            QTextTable *table = cursor.insertTable(rows, columns, tableFormat);

The table format is either defined when the table is created or changed later with `setFormat`.

The table currently being edited by the cursor is found with QTextCursor::currentTable(). This allows its format or dimensions to be changed after it has been inserted into a document.

A table's size can be changed with `resize`, or by using `insertRows`, `insertColumns`, `removeRows`, or `removeColumns`. Use `cellAt` to retrieve table cells.

The starting and ending positions of table rows can be found by moving a cursor within a table, and using the `rowStart` and `rowEnd` functions to obtain cursors at the start and end of each row.

Rows and columns within a `QTextTable` can be merged and split using the `mergeCells` and `splitCell` functions. However, only cells that span multiple rows or columns can be split. (Merging or splitting does not increase or decrease the number of rows and columns.)

| Suppose we have a 2x6 table of names and addresses. To merge both columns in the first row we invoke `mergeCells` with row = 0, column = 0, numRows = 1 and numColumns = 2.
            table->mergeCells(0, 0, 1, 2);
| This gives us the following table. To split the first row of the table back into two cells, we invoke the `splitCell` function with numRows and numCols = 1.
            table->splitCell(0, 0, 1, 1);
| This results in the original table.

See also `QTextTableFormat`.