Table Of Contents

Previous topic

QTextFrame.iterator

Next topic

QTextBlockGroup

QTextTable

Synopsis

Functions

Detailed Description

The PySide.QtGui.QTextTable class represents a table in a PySide.QtGui.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:

cursor = QTextCursor(editor.textCursor())

cursor.movePosition(QTextCursor.Start)

table = cursor.insertTable(rows, columns, tableFormat)

The table format is either defined when the table is created or changed later with PySide.QtGui.QTextTable.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 PySide.QtGui.QTextTable.resize() , or by using PySide.QtGui.QTextTable.insertRows() , PySide.QtGui.QTextTable.insertColumns() , PySide.QtGui.QTextTable.removeRows() , or PySide.QtGui.QTextTable.removeColumns() . Use PySide.QtGui.QTextTable.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 PySide.QtGui.QTextTable.rowStart() and PySide.QtGui.QTextTable.rowEnd() functions to obtain cursors at the start and end of each row.

Rows and columns within a PySide.QtGui.QTextTable can be merged and split using the PySide.QtGui.QTextTable.mergeCells() and PySide.QtGui.QTextTable.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.)

Note that if you have merged multiple columns and rows into one cell, you will not be able to split the merged cell into new cells spanning over more than one row or column. To be able to split cells spanning over several rows and columns you need to do this over several iterations.

../../_images/texttable-split.png

Suppose we have a 2x3 table of names and addresses. To merge both columns in the first row we invoke PySide.QtGui.QTextTable.mergeCells() with row = 0, column = 0, numRows = 1 and numColumns = 2.

table.mergeCells(0, 0, 1, 2)
../../_images/texttable-merge.png

This gives us the following table. To split the first row of the table back into two cells, we invoke the PySide.QtGui.QTextTable.splitCell() function with numRows and numCols = 1.

table.splitCell(0, 0, 1, 1)
../../_images/texttable-split.png This results in the original table.
class PySide.QtGui.QTextTable(doc)
Parameters:docPySide.QtGui.QTextDocument
PySide.QtGui.QTextTable.appendColumns(count)
Parameters:countPySide.QtCore.int

Appends count columns at the right side of the table.

PySide.QtGui.QTextTable.appendRows(count)
Parameters:countPySide.QtCore.int

Appends count rows at the bottom of the table.

PySide.QtGui.QTextTable.cellAt(row, col)
Parameters:
  • rowPySide.QtCore.int
  • colPySide.QtCore.int
Return type:

PySide.QtGui.QTextTableCell

Returns the table cell at the given row and column in the table.

PySide.QtGui.QTextTable.cellAt(position)
Parameters:positionPySide.QtCore.int
Return type:PySide.QtGui.QTextTableCell

This is an overloaded function.

Returns the table cell that contains the character at the given position in the document.

PySide.QtGui.QTextTable.cellAt(c)
Parameters:cPySide.QtGui.QTextCursor
Return type:PySide.QtGui.QTextTableCell

This is an overloaded function.

Returns the table cell containing the given cursor .

PySide.QtGui.QTextTable.columns()
Return type:PySide.QtCore.int

Returns the number of columns in the table.

PySide.QtGui.QTextTable.insertColumns(pos, num)
Parameters:
  • posPySide.QtCore.int
  • numPySide.QtCore.int

Inserts a number of columns before the column with the specified index .

PySide.QtGui.QTextTable.insertRows(pos, num)
Parameters:
  • posPySide.QtCore.int
  • numPySide.QtCore.int

Inserts a number of rows before the row with the specified index .

PySide.QtGui.QTextTable.mergeCells(row, col, numRows, numCols)
Parameters:
  • rowPySide.QtCore.int
  • colPySide.QtCore.int
  • numRowsPySide.QtCore.int
  • numColsPySide.QtCore.int

Merges the cell at the specified row and column with the adjacent cells into one cell. The new cell will span numRows rows and numCols columns. If numRows or numCols is less than the current number of rows or columns the cell spans then this method does nothing.

PySide.QtGui.QTextTable.mergeCells(cursor)
Parameters:cursorPySide.QtGui.QTextCursor

This is an overloaded function.

Merges the cells selected by the provided cursor .

PySide.QtGui.QTextTable.removeColumns(pos, num)
Parameters:
  • posPySide.QtCore.int
  • numPySide.QtCore.int

Removes a number of columns starting with the column at the specified index .

PySide.QtGui.QTextTable.removeRows(pos, num)
Parameters:
  • posPySide.QtCore.int
  • numPySide.QtCore.int

Removes a number of rows starting with the row at the specified index .

PySide.QtGui.QTextTable.resize(rows, cols)
Parameters:
  • rowsPySide.QtCore.int
  • colsPySide.QtCore.int

Resizes the table to contain the required number of rows and columns .

PySide.QtGui.QTextTable.rowEnd(c)
Parameters:cPySide.QtGui.QTextCursor
Return type:PySide.QtGui.QTextCursor

Returns a cursor pointing to the end of the row that contains the given cursor .

PySide.QtGui.QTextTable.rowStart(c)
Parameters:cPySide.QtGui.QTextCursor
Return type:PySide.QtGui.QTextCursor

Returns a cursor pointing to the start of the row that contains the given cursor .

PySide.QtGui.QTextTable.rows()
Return type:PySide.QtCore.int

Returns the number of rows in the table.

PySide.QtGui.QTextTable.setFormat(format)
Parameters:formatPySide.QtGui.QTextTableFormat

Sets the table’s format .

See also

PySide.QtGui.QTextTable.format()

PySide.QtGui.QTextTable.splitCell(row, col, numRows, numCols)
Parameters:
  • rowPySide.QtCore.int
  • colPySide.QtCore.int
  • numRowsPySide.QtCore.int
  • numColsPySide.QtCore.int

Splits the specified cell at row and column into an array of multiple cells with dimensions specified by numRows and numCols .

Note

It is only possible to split cells that span multiple rows or columns, such as rows that have been merged using PySide.QtGui.QTextTable.mergeCells() .