Class: QgsLayoutTable

Displays a table in the print layout, and allows the table to span over multiple frames.

Note

This is an abstract class, with methods which must be implemented by a subclass.

The following methods must be implemented: getTableContents(), QgsLayoutMultiFrame.type()

Class Hierarchy

Base classes

QgsLayoutMultiFrame	Abstract base class for layout items with the ability to distribute the content to several frames (QgsLayoutFrame items).
QgsLayoutObject	A base class for objects which belong to a layout.
QObject
QgsExpressionContextGenerator	Abstract interface for generating an expression context.
QgsLayoutUndoObjectInterface	Interface for layout objects which support undo/redo commands.

Subclasses

QgsLayoutItemAttributeTable	A layout table subclass that displays attributes from a vector layer.
QgsLayoutItemManualTable	A layout table subclass that displays manually entered (and formatted) content.
QgsLayoutItemTextTable	A text table item that reads text from string lists.

Abstract Methods

getTableContents

Fetches the contents used for the cells in the table.

Methods

backgroundColor	Returns the color used for the background of the table.
cellMargin	Returns the margin distance between cell borders and their contents in mm.
cellStyle	Returns the cell style for a cell group.
columns	Returns a reference to the list of QgsLayoutTableColumns shown in the table
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
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.
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.
horizontalGrid	Returns whether the grid's horizontal lines are drawn in the table.
recalculateTableSize	Recalculates and updates the size of the table and all table frames.
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.
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.
totalHeight
totalWidth
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.

Virtual Methods

In PyQGIS, only methods marked as virtual can be safely overridden in a Python subclass of QgsLayoutTable. See the FAQ for more details.

calculateMaxColumnWidths	Calculates the maximum width of text shown in columns.
calculateMaxRowHeights	Calculates the maximum height of text shown in rows.
columnSpan	Returns the column span for the cell a row, column.
conditionalCellStyle	Returns the conditional style to use for the cell at row, column.
horizontalAlignmentForCell	Returns the horizontal alignment to use for the cell at the specified row and column.
refreshAttributes	Refreshes the contents shown in the table by querying for new data.
rowSpan	Returns the row span for the cell a row, column.
scopeForCell	Creates a new QgsExpressionContextScope for the cell at row, column.
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.
verticalAlignmentForCell	Returns the vertical alignment to use for the cell at the specified row and column.

Attributes

AllFrames
EvenColumns
EvenRows
FirstColumn
FirstFrame
FirstRow
FollowColumn
HeaderCenter
HeaderLeft
HeaderRight
HeaderRow
HeadersOnly
HideTable
LastColumn
LastRow
NoHeaders
OddColumns
OddRows
ShowMessage
TruncateText
WrapText

class qgis.core.QgsLayoutTable

Bases: QgsLayoutMultiFrame

__init__(layout: QgsLayout | None)

Constructor for QgsLayoutTable, belonging to the specified layout.

Parameters:

layout (Optional[QgsLayout])

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

setBackgroundColor()

See also

gridColor()

Return type:

QColor

virtual calculateMaxColumnWidths(self) → bool

Calculates the maximum width of text shown in columns.

Return type:

bool

virtual 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 | None

Returns the cell style for a cell group.

See also

setCellStyle()

Parameters:

group (QgsLayoutTable.CellStyleGroup)

Return type:

Optional[QgsLayoutTableStyle]

virtual columnSpan(self, row: int, column: int) → int

Returns the column span for the cell a row, column.

See also

rowSpan()

Added in version 3.40.

Parameters:

• row (int)

• column (int)

Return type:

int

columns(self) → List[QgsLayoutTableColumn]

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

See also

setColumns()

Return type:

List[QgsLayoutTableColumn]

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

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

Added in version 3.12.

Parameters:

• row (int)

• column (int)

Return type:

QgsConditionalStyle

contentFont(self) → QFont

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

See also

setContentFont()

See also

headerFont()

Deprecated since version 3.40: Use contextTextFormat() instead.

Return type:

QFont

contentFontColor(self) → QColor

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

See also

setContentFontColor()

See also

contentFont()

See also

headerFontColor()

Deprecated since version 3.40: Use contextTextFormat() instead.

Return type:

QColor

contentTextFormat(self) → QgsTextFormat

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

See also

setContentTextFormat()

See also

headerTextFormat()

Added in version 3.16.

Return type:

QgsTextFormat

contents(self) → Any

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

Return type:

Any

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

Checks whether a table contents contains a given row

Parameters:

• contents (Any) – table contents to check

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

Return type:

bool

Returns:

True if contents contains rows

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.

See also

setEmptyTableBehavior()

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.

See also

setEmptyTableMessage()

See also

emptyTableBehavior()

Return type:

str

abstract getTableContents(self, contents: Any) → bool

Fetches the contents used for the cells in the table.

Return type:

bool

Returns:

True if table contents were successfully retrieved.

Parameters:

contents (Any) – 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()

See also

gridStrokeWidth()

Return type:

QColor

gridStrokeWidth(self) → float

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

See also

setGridStrokeWidth()

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 3.40: Use headerTextFormat() instead.

Return type:

QFont

headerFontColor(self) → QColor

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

See also

setHeaderFontColor()

See also

headerFont()

See also

contentFontColor()

Deprecated since version 3.40: Use headerTextFormat() instead.

Return type:

QColor

headerHAlignment(self) → QgsLayoutTable.HeaderHAlignment

Returns the horizontal alignment for table headers.

See also

setHeaderHAlignment()

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.

See also

setHeaderTextFormat()

See also

contentTextFormat()

Added in version 3.16.

Return type:

QgsTextFormat

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

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

See also

verticalAlignmentForCell()

Added 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

setGridStrokeWidth()

See also

setGridColor()

See also

setVerticalGrid()

Return type:

bool

recalculateTableSize(self)

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

virtual 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.

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

virtual rowSpan(self, row: int, column: int) → int

Returns the row span for the cell a row, column.

See also

columnSpan()

Added in version 3.40.

Parameters:

• row (int)

• column (int)

Return type:

int

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.

Return type:

int

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 (QgsRenderContext) – render context

• frameIndex (int) – index number for frame

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

• 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.

Return type:

int

Returns:

number of visible content rows (excludes header rows)

virtual scopeForCell(self, row: int, column: int) → QgsExpressionContextScope | None

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

Added in version 3.16.

Parameters:

• row (int)

• column (int)

Return type:

Optional[QgsExpressionContextScope]

setBackgroundColor(self, color: QColor | Qt.GlobalColor)

Sets the color used for background of table.

See also

backgroundColor()

See also

setGridColor()

Parameters:

color (Union[QColor, Qt.GlobalColor])

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:

• group (QgsLayoutTable.CellStyleGroup)

• style (QgsLayoutTableStyle)

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 3.40: Use setContentTextFormat() instead.

Parameters:

font (QFont)

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

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

See also

contentFontColor()

See also

setContentFont()

See also

setHeaderFontColor()

Deprecated since version 3.40: Use setContentTextFormat() instead.

Parameters:

color (Union[QColor, Qt.GlobalColor])

setContentTextFormat(self, format: QgsTextFormat)

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

See also

contentTextFormat()

See also

setHeaderTextFormat()

Added in version 3.16.

Parameters:

format (QgsTextFormat)

setEmptyTableBehavior(self, mode: QgsLayoutTable.EmptyTableMode)

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

See also

emptyTableBehavior()

Parameters:

mode (QgsLayoutTable.EmptyTableMode)

setEmptyTableMessage(self, message: str | None)

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.

See also

emptyTableMessage()

See also

setEmptyTableBehavior()

Parameters:

message (Optional[str])

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

Sets the color used for grid lines in the table.

See also

gridColor()

See also

setShowGrid()

See also

setGridStrokeWidth()

Parameters:

color (Union[QColor, Qt.GlobalColor])

setGridStrokeWidth(self, width: float)

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

See also

gridStrokeWidth()

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 3.40: Use setHeaderTextFormat() instead.

Parameters:

font (QFont)

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

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

See also

headerFontColor()

See also

setHeaderFont()

See also

setContentFontColor()

Deprecated since version 3.40: Use setHeaderTextFormat() instead.

Parameters:

color (Union[QColor, Qt.GlobalColor])

setHeaderHAlignment(self, alignment: QgsLayoutTable.HeaderHAlignment)

Sets the horizontal alignment for table headers.

See also

headerHAlignment()

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.

See also

headerTextFormat()

See also

setContentTextFormat()

Added 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

setGridStrokeWidth()

See also

setGridColor()

See also

setVerticalGrid()

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

setGridStrokeWidth()

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()

Added 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

setGridStrokeWidth()

See also

setGridColor()

See also

setHorizontalGrid()

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.

See also

setShowEmptyRows()

Return type:

bool

showGrid(self) → bool

Returns whether grid lines are drawn in the table

See also

setShowGrid()

See also

gridStrokeWidth()

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()

Added in version 3.14.

Return type:

List[QgsLayoutTableColumn]

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

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

See also

textFormatForHeader()

Added in version 3.16.

Parameters:

• row (int)

• column (int)

Return type:

QgsTextFormat

virtual textFormatForHeader(self, column: int) → QgsTextFormat

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

See also

textFormatForCell()

Added in version 3.16.

Parameters:

column (int)

Return type:

QgsTextFormat

totalHeight(self) → float

Return type:

float

totalWidth(self) → float

Return type:

float

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

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

See also

horizontalAlignmentForCell()

Added 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

setGridStrokeWidth()

See also

setGridColor()

See also

setHorizontalGrid()

Return type:

bool

wrapBehavior(self) → QgsLayoutTable.WrapBehavior

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

See also

setWrapBehavior()

Return type:

QgsLayoutTable.WrapBehavior