Class: QgsLayoutTable

class qgis.core.QgsLayoutTable

Bases: QgsLayoutMultiFrame

A class to display a table in the print layout, and allow the table to span over multiple frames

New in version 3.0.

QgsLayoutTable(layout: QgsLayout) Constructor for QgsLayoutTable, belonging to the specified layout.

Methods

backgroundColor

Returns the color used for the background of the table.

calculateMaxColumnWidths

Calculates the maximum width of text shown in columns.

calculateMaxRowHeights

Calculates the maximum height of text shown in rows.

cellMargin

Returns the margin distance between cell borders and their contents in mm.

cellStyle

Returns the cell style for a cell group.

childEvent

columns

Returns a reference to the list of QgsLayoutTableColumns shown in the table

conditionalCellStyle

Returns the conditional style to use for the cell at row, column.

connectNotify

contentFont

Returns the font used to draw text in table body cells.

contentFontColor

Returns the color used to draw text in table body cells.

contentTextFormat

Returns the format used to draw content text in the table.

contents

Returns the current contents of the table.

contentsContainsRow

Checks whether a table contents contains a given row

customEvent

disconnectNotify

drawHorizontalGridLines

Draws the horizontal grid lines for the table.

emptyTableBehavior

Returns the behavior mode for empty tables.

emptyTableMessage

Returns the message for empty tables with no content rows.

fixedFrameSize

param frameIndex:

getTableContents

Fetches the contents used for the cells in the table.

gridColor

Returns the color used for grid lines in the table.

gridStrokeWidth

Returns the width of grid lines in the table in mm.

headerFont

Returns the font used to draw header text in the table.

headerFontColor

Returns the color used to draw header text in the table.

headerHAlignment

Returns the horizontal alignment for table headers.

headerMode

Returns the display mode for headers in the table.

headerTextFormat

Returns the format used to draw header text in the table.

horizontalAlignmentForCell

Returns the horizontal alignment to use for the cell at the specified row and column.

horizontalGrid

Returns whether the grid's horizontal lines are drawn in the table.

isSignalConnected

minFrameSize

param frameIndex:

readObjectPropertiesFromElement

Sets object properties from a DOM element

readPropertiesFromElement

param itemElem:

recalculateFrameSizes

recalculateTableSize

Recalculates and updates the size of the table and all table frames.

receivers

refresh

refreshAttributes

Refreshes the contents shown in the table by querying for new data.

render

param context:

rowRange

Calculates a range of rows which should be visible in a given frame.

rowsVisible

Calculates how many content rows would be visible within a frame of the specified height.

scopeForCell

Creates a new QgsExpressionContextScope for the cell at row, column.

sender

senderSignalIndex

setBackgroundColor

Sets the color used for background of table.

setCellMargin

Sets the margin distance in mm between cell borders and their contents.

setCellStyle

Sets the cell style for a cell group.

setColumns

Replaces the columns in the table with a specified list of QgsLayoutTableColumns.

setContentFont

Sets the font used to draw text in table body cells.

setContentFontColor

Sets the color used to draw text in table body cells.

setContentTextFormat

Sets the format used to draw content text in the table.

setEmptyTableBehavior

Sets the behavior mode for empty tables with no content rows.

setEmptyTableMessage

Sets the message for empty tables with no content rows.

setGridColor

Sets the color used for grid lines in the table.

setGridStrokeWidth

Sets the width in mm for grid lines in the table.

setHeaderFont

Sets the font used to draw header text in the table.

setHeaderFontColor

Sets the color used to draw header text in the table.

setHeaderHAlignment

Sets the horizontal alignment for table headers.

setHeaderMode

Sets the display mode for headers in the table.

setHeaderTextFormat

Sets the format used to draw header text in the table.

setHorizontalGrid

Sets whether the grid's horizontal lines should be drawn in the table

setShowEmptyRows

Sets whether empty rows should be drawn.

setShowGrid

Sets whether grid lines should be drawn in the table

setSortColumns

Replaces the sorting columns in the table with a specified list of QgsLayoutTableSortColumns.

setVerticalGrid

Sets whether the grid's vertical lines should be drawn in the table

setWrapBehavior

Sets the wrap behavior for the table, which controls how text within cells is automatically wrapped.

showEmptyRows

Returns whether empty rows are drawn in the table.

showGrid

Returns whether grid lines are drawn in the table

sortColumns

Returns a reference to the list of QgsLayoutTableSortColumns shown in the table.

textFormatForCell

Returns the text format to use for the cell at the specified row and column.

textFormatForHeader

Returns the text format to use for the header cell at the specified column.

timerEvent

totalHeight

rtype:

float

totalSize

rtype:

QSizeF

totalWidth

rtype:

float

verticalAlignmentForCell

Returns the vertical alignment to use for the cell at the specified row and column.

verticalGrid

Returns whether the grid's vertical lines are drawn in the table.

wrapBehavior

Returns the wrap behavior for the table, which controls how text within cells is automatically wrapped.

writeObjectPropertiesToElement

Stores object properties within an XML DOM element.

writePropertiesToElement

param elem:

Attributes

AllFrames

EvenColumns

EvenRows

FirstColumn

FirstFrame

FirstRow

FollowColumn

HeaderCenter

HeaderLeft

HeaderRight

HeaderRow

HeadersOnly

HideTable

LastColumn

LastRow

NoHeaders

OddColumns

OddRows

ShowMessage

TruncateText

WrapText

AllFrames = 1
class CellStyleGroup

Bases: int

class EmptyTableMode

Bases: int

EvenColumns = 1
EvenRows = 3
FirstColumn = 4
FirstFrame = 0
FirstRow = 7
FollowColumn = 0
HeaderCenter = 2
class HeaderHAlignment

Bases: int

HeaderLeft = 1
class HeaderMode

Bases: int

HeaderRight = 3
HeaderRow = 6
HeadersOnly = 0
HideTable = 1
LastColumn = 5
LastRow = 8
NoHeaders = 2
OddColumns = 0
OddRows = 2
ShowMessage = 2
TruncateText = 0
class WrapBehavior

Bases: int

WrapText = 1
backgroundColor(self) QColor

Returns the color used for the background of the table.

See also

gridColor()

Return type:

QColor

calculateMaxColumnWidths(self) bool

Calculates the maximum width of text shown in columns.

Return type:

bool

calculateMaxRowHeights(self) bool

Calculates the maximum height of text shown in rows.

Return type:

bool

cellMargin(self) float

Returns the margin distance between cell borders and their contents in mm.

See also

setCellMargin()

Return type:

float

cellStyle(self, group: QgsLayoutTable.CellStyleGroup) QgsLayoutTableStyle

Returns the cell style for a cell group.

See also

setCellStyle()

Parameters:

group (QgsLayoutTable.CellStyleGroup) –

Return type:

QgsLayoutTableStyle

childEvent(self, QChildEvent)
columns(self) List[QgsLayoutTableColumn]

Returns a reference to the list of QgsLayoutTableColumns shown in the table

See also

setColumns()

Return type:

List[QgsLayoutTableColumn]

conditionalCellStyle(self, row: int, column: int) QgsConditionalStyle

Returns the conditional style to use for the cell at row, column.

New in version 3.12.

Parameters:
  • row (int) –

  • column (int) –

Return type:

QgsConditionalStyle

connectNotify(self, QMetaMethod)
contentFont(self) QFont

Returns the font used to draw text in table body cells.

See also

setContentFont()

See also

headerFont()

Deprecated since version use: contextTextFormat() instead

Return type:

QFont

contentFontColor(self) QColor

Returns the color used to draw text in table body cells.

See also

contentFont()

Deprecated since version use: contextTextFormat() instead

Return type:

QColor

contentTextFormat(self) QgsTextFormat

Returns the format used to draw content text in the table.

New in version 3.16.

Return type:

QgsTextFormat

contents(self) object

Returns the current contents of the table. Excludes header cells.

Return type:

object

contentsContainsRow(self, contents: object, row: Iterable[Any]) bool

Checks whether a table contents contains a given row

Parameters:
  • contents (object) – table contents to check

  • row (Iterable[Any]) – row to check for

Return type:

bool

Returns:

True if contents contains rows

customEvent(self, QEvent)
disconnectNotify(self, QMetaMethod)
drawHorizontalGridLines(self, context: QgsLayoutItemRenderContext, firstRow: int, lastRow: int, drawHeaderLines: bool)

Draws the horizontal grid lines for the table.

Parameters:
  • context (QgsLayoutItemRenderContext) – destination render context

  • firstRow (int) – index corresponding to first row shown in frame

  • lastRow (int) – index corresponding to last row shown in frame. If greater than the number of content rows in the table, then the default row height will be used for the remaining rows.

  • drawHeaderLines (bool) – set to True to include for the table header

See also

drawVerticalGridLines()

emptyTableBehavior(self) QgsLayoutTable.EmptyTableMode

Returns the behavior mode for empty tables. This property controls how the table is drawn if it contains no content rows.

Return type:

QgsLayoutTable.EmptyTableMode

emptyTableMessage(self) str

Returns the message for empty tables with no content rows. This message is displayed in the table body if the empty table behavior is set to ShowMessage.

Return type:

str

fixedFrameSize(self, frameIndex: int = -1) QSizeF
Parameters:

frameIndex (int = -1) –

Return type:

QSizeF

getTableContents(self, contents: object) bool

Fetches the contents used for the cells in the table.

Return type:

bool

Returns:

True if table contents were successfully retrieved.

Parameters:

contents (object) – QgsLayoutTableContents to store retrieved row data in

gridColor(self) QColor

Returns the color used for grid lines in the table.

See also

setGridColor()

See also

showGrid()

Return type:

QColor

gridStrokeWidth(self) float

Returns the width of grid lines in the table in mm.

See also

showGrid()

See also

gridColor()

Return type:

float

headerFont(self) QFont

Returns the font used to draw header text in the table.

See also

setHeaderFont()

See also

contentFont()

Deprecated since version use: headerTextFormat() instead

Return type:

QFont

headerFontColor(self) QColor

Returns the color used to draw header text in the table.

See also

headerFont()

Deprecated since version use: headerTextFormat() instead

Return type:

QColor

headerHAlignment(self) QgsLayoutTable.HeaderHAlignment

Returns the horizontal alignment for table headers.

Return type:

QgsLayoutTable.HeaderHAlignment

headerMode(self) QgsLayoutTable.HeaderMode

Returns the display mode for headers in the table. This property controls if and where headers are shown in the table.

See also

setHeaderMode()

Return type:

QgsLayoutTable.HeaderMode

headerTextFormat(self) QgsTextFormat

Returns the format used to draw header text in the table.

New in version 3.16.

Return type:

QgsTextFormat

horizontalAlignmentForCell(self, row: int, column: int) Qt.Alignment

Returns the horizontal alignment to use for the cell at the specified row and column.

New in version 3.16.

Parameters:
  • row (int) –

  • column (int) –

Return type:

Qt.Alignment

horizontalGrid(self) bool

Returns whether the grid’s horizontal lines are drawn in the table.

See also

setShowGrid()

See also

setGridColor()

Return type:

bool

isSignalConnected(self, QMetaMethod) bool
minFrameSize(self, frameIndex: int = -1) QSizeF
Parameters:

frameIndex (int = -1) –

Return type:

QSizeF

readObjectPropertiesFromElement(self, parentElement: QDomElement, document: QDomDocument, context: QgsReadWriteContext) bool

Sets object properties from a DOM element

Parameters:
  • parentElement – is the parent DOM element for the object

  • document – DOM document

  • context – read write context

Returns:

True if read was successful

readPropertiesFromElement(self, itemElem: QDomElement, doc: QDomDocument, context: QgsReadWriteContext) bool
Parameters:
Return type:

bool

recalculateFrameSizes(self)
recalculateTableSize(self)

Recalculates and updates the size of the table and all table frames.

receivers(self, PYQT_SIGNAL) int
refresh(self)
refreshAttributes(self)

Refreshes the contents shown in the table by querying for new data. This also causes the column widths and size of the table to change to accommodate the new data.

render(self, context: QgsLayoutItemRenderContext, renderExtent: QRectF, frameIndex: int)
Parameters:
rowRange(self, context: QgsRenderContext, frameIndex: int) Tuple[int, int]

Calculates a range of rows which should be visible in a given frame.

Parameters:
  • context (QgsRenderContext) – render context

  • frameIndex (int) – index number for frame

Return type:

Tuple[int, int]

Returns:

row range

rowsVisible(self, context: QgsRenderContext, frameHeight: float, firstRow: int, includeHeader: bool, includeEmptyRows: bool) int

Calculates how many content rows would be visible within a frame of the specified height.

Parameters:
  • context (QgsRenderContext) – render context

  • frameHeight (float) – height of frame

  • firstRow (int) – index of first row visible in frame (where 0 = first row in table)

  • includeHeader (bool) – set to True if frame would include a header row

  • includeEmptyRows (bool) – set to True to also include rows which would be empty in the returned count. For instance, if the frame would include all table content rows and have space left for extra rows then setting this parameter to True would also include a count of these extra blank rows.

Returns:

number of visible content rows (excluding header row)

rowsVisible(self, context: QgsRenderContext, frameIndex: int, firstRow: int, includeEmptyRows: bool) -> int Calculates how many content rows are visible within a given frame.

Parameters:
  • context – render context

  • frameIndex – index number for frame

  • firstRow – index of first row visible in frame (where 0 = first row in table)

  • includeEmptyRows – set to True to also include rows which would be empty in the returned count. For instance, if the frame would include all table content rows and have space left for extra rows then setting this parameter to True would also include a count of these extra blank rows.

Return type:

int

Returns:

number of visible content rows (excludes header rows)

scopeForCell(self, row: int, column: int) QgsExpressionContextScope

Creates a new QgsExpressionContextScope for the cell at row, column.

New in version 3.16.

Parameters:
  • row (int) –

  • column (int) –

Return type:

QgsExpressionContextScope

sender(self) QObject
senderSignalIndex(self) int
setBackgroundColor(self, color: QColor | Qt.GlobalColor | QGradient)

Sets the color used for background of table.

See also

setGridColor()

Parameters:

color (Union[QColor) –

setCellMargin(self, margin: float)

Sets the margin distance in mm between cell borders and their contents.

See also

cellMargin()

Parameters:

margin (float) –

setCellStyle(self, group: QgsLayoutTable.CellStyleGroup, style: QgsLayoutTableStyle)

Sets the cell style for a cell group.

See also

cellStyle()

Parameters:
setColumns(self, columns: Iterable[QgsLayoutTableColumn])

Replaces the columns in the table with a specified list of QgsLayoutTableColumns.

Parameters:

columns (Iterable[QgsLayoutTableColumn]) – list of QgsLayoutTableColumns to show in table.

See also

columns()

setContentFont(self, font: QFont)

Sets the font used to draw text in table body cells.

See also

contentFont()

See also

setHeaderFont()

Deprecated since version use: setContentTextFormat() instead

Parameters:

font (QFont) –

setContentFontColor(self, color: QColor | Qt.GlobalColor | QGradient)

Sets the color used to draw text in table body cells.

See also

setContentFont()

Deprecated since version use: setContentTextFormat() instead

Parameters:

color (Union[QColor) –

setContentTextFormat(self, format: QgsTextFormat)

Sets the format used to draw content text in the table.

New in version 3.16.

Parameters:

format (QgsTextFormat) –

setEmptyTableBehavior(self, mode: QgsLayoutTable.EmptyTableMode)

Sets the behavior mode for empty tables with no content rows.

Parameters:

mode (QgsLayoutTable.EmptyTableMode) –

setEmptyTableMessage(self, message: str)

Sets the message for empty tables with no content rows. This message is displayed in the table body if the empty table behavior is set to ShowMessage.

Parameters:

message (str) –

setGridColor(self, color: QColor | Qt.GlobalColor | QGradient)

Sets the color used for grid lines in the table.

See also

gridColor()

See also

setShowGrid()

Parameters:

color (Union[QColor) –

setGridStrokeWidth(self, width: float)

Sets the width in mm for grid lines in the table.

See also

setShowGrid()

See also

setGridColor()

Parameters:

width (float) –

setHeaderFont(self, font: QFont)

Sets the font used to draw header text in the table.

See also

headerFont()

See also

setContentFont()

Deprecated since version use: setHeaderTextFormat() instead

Parameters:

font (QFont) –

setHeaderFontColor(self, color: QColor | Qt.GlobalColor | QGradient)

Sets the color used to draw header text in the table.

See also

setHeaderFont()

Deprecated since version use: setHeaderTextFormat() instead

Parameters:

color (Union[QColor) –

setHeaderHAlignment(self, alignment: QgsLayoutTable.HeaderHAlignment)

Sets the horizontal alignment for table headers.

Parameters:

alignment (QgsLayoutTable.HeaderHAlignment) –

setHeaderMode(self, mode: QgsLayoutTable.HeaderMode)

Sets the display mode for headers in the table. This property controls if and where headers are shown in the table.

See also

headerMode()

Parameters:

mode (QgsLayoutTable.HeaderMode) –

setHeaderTextFormat(self, format: QgsTextFormat)

Sets the format used to draw header text in the table.

New in version 3.16.

Parameters:

format (QgsTextFormat) –

setHorizontalGrid(self, horizontalGrid: bool)

Sets whether the grid’s horizontal lines should be drawn in the table

Parameters:

horizontalGrid (bool) – set to True to draw grid’s horizontal lines

See also

setShowGrid()

See also

setGridColor()

setShowEmptyRows(self, showEmpty: bool)

Sets whether empty rows should be drawn. Tables default to hiding empty rows.

Parameters:

showEmpty (bool) – set to True to show empty rows in the table

See also

showEmptyRows()

setShowGrid(self, showGrid: bool)

Sets whether grid lines should be drawn in the table

Parameters:

showGrid (bool) – set to True to show grid lines

See also

showGrid()

See also

setGridColor()

setSortColumns(self, sortColumns: Iterable[QgsLayoutTableColumn])

Replaces the sorting columns in the table with a specified list of QgsLayoutTableSortColumns.

Parameters:

sortColumns (Iterable[QgsLayoutTableColumn]) – list of QgsLayoutTableColumns used to sort the table.

Warning

It is expected that the QgsLayoutTableColumn.attribute() values in sortColumns are valid QGIS expression values, and that column references are correctly escaped accordingly.

See also

sortColumns()

New in version 3.14.

setVerticalGrid(self, verticalGrid: bool)

Sets whether the grid’s vertical lines should be drawn in the table

Parameters:

verticalGrid (bool) – set to True to draw grid’s vertical lines

See also

setShowGrid()

See also

setGridColor()

setWrapBehavior(self, behavior: QgsLayoutTable.WrapBehavior)

Sets the wrap behavior for the table, which controls how text within cells is automatically wrapped.

See also

wrapBehavior()

Parameters:

behavior (QgsLayoutTable.WrapBehavior) –

showEmptyRows(self) bool

Returns whether empty rows are drawn in the table.

Return type:

bool

showGrid(self) bool

Returns whether grid lines are drawn in the table

See also

setShowGrid()

See also

gridColor()

Return type:

bool

sortColumns(self) List[QgsLayoutTableColumn]

Returns a reference to the list of QgsLayoutTableSortColumns shown in the table.

Warning

It is expected that the QgsLayoutTableColumn.attribute() values in the columns are valid QGIS expression values, and that column references are correctly escaped accordingly.

See also

setSortColumns()

New in version 3.14.

Return type:

List[QgsLayoutTableColumn]

textFormatForCell(self, row: int, column: int) QgsTextFormat

Returns the text format to use for the cell at the specified row and column.

New in version 3.16.

Parameters:
  • row (int) –

  • column (int) –

Return type:

QgsTextFormat

textFormatForHeader(self, column: int) QgsTextFormat

Returns the text format to use for the header cell at the specified column.

New in version 3.16.

Parameters:

column (int) –

Return type:

QgsTextFormat

timerEvent(self, QTimerEvent)
totalHeight(self) float
Return type:

float

totalSize(self) QSizeF
Return type:

QSizeF

totalWidth(self) float
Return type:

float

verticalAlignmentForCell(self, row: int, column: int) Qt.Alignment

Returns the vertical alignment to use for the cell at the specified row and column.

New in version 3.16.

Parameters:
  • row (int) –

  • column (int) –

Return type:

Qt.Alignment

verticalGrid(self) bool

Returns whether the grid’s vertical lines are drawn in the table.

See also

setShowGrid()

See also

setGridColor()

Return type:

bool

wrapBehavior(self) QgsLayoutTable.WrapBehavior

Returns the wrap behavior for the table, which controls how text within cells is automatically wrapped.

Return type:

QgsLayoutTable.WrapBehavior

writeObjectPropertiesToElement(self, parentElement: QDomElement, document: QDomDocument, context: QgsReadWriteContext) bool

Stores object properties within an XML DOM element.

Parameters:
  • parentElement – is the parent DOM element to store the object’s properties in

  • document – DOM document

  • context – read write context

Returns:

True if write was successful

writePropertiesToElement(self, elem: QDomElement, doc: QDomDocument, context: QgsReadWriteContext) bool
Parameters:
Return type:

bool