QgsLayoutTable class

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

Reference

Base classes

class QgsLayoutMultiFrame: Abstract base class for layout items with the ability to distribute the content to several frames (QgsLayoutFrame items).

Derived classes

class QgsLayoutItemAttributeTable: A layout table subclass that displays attributes from a vector layer.
class QgsLayoutItemTextTable: A text table item that reads text from string lists.

Public types

enum CellStyleGroup { OddColumns, EvenColumns, OddRows, EvenRows, FirstColumn, LastColumn, HeaderRow, FirstRow, LastRow }: Row or column groups for cell styling.
enum EmptyTableMode { HeadersOnly = 0, HideTable, ShowMessage }: Controls how empty tables are displayed.
enum HeaderHAlignment { FollowColumn, HeaderLeft, HeaderCenter, HeaderRight }: Controls how headers are horizontally aligned in a table.
enum HeaderMode { FirstFrame = 0, AllFrames, NoHeaders }: Controls where headers are shown in the table.
enum WrapBehavior { TruncateText = 0, WrapText }: Controls how long strings in the table are handled.

Constructors, destructors, conversion operators

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

Public functions

auto backgroundColor() const -> QColor: Returns the color used for the background of the table.
auto cellMargin() const -> double: Returns the margin distance between cell borders and their contents in mm.
auto cellStyle(CellStyleGroup group) const -> const QgsLayoutTableStyle*: Returns the cell style for a cell group.
auto columns() -> QgsLayoutTableColumns&: Returns a reference to the list of QgsLayoutTableColumns shown in the table.
auto contentFont() const -> QFont: Returns the font used to draw text in table body cells.
auto contentFontColor() const -> QColor: Returns the color used to draw text in table body cells.
auto contents() -> QgsLayoutTableContents&: Returns the current contents of the table.
auto emptyTableBehavior() const -> EmptyTableMode: Returns the behavior mode for empty tables.
auto emptyTableMessage() const -> QString: Returns the message for empty tables with no content rows.
auto fixedFrameSize(int frameIndex = -1) const -> QSizeF override: Returns the fixed size for a frame, if desired.
auto getTableContents(QgsLayoutTableContents& contents) -> bool pure virtual: Fetches the contents used for the cells in the table.
auto gridColor() const -> QColor: Returns the color used for grid lines in the table.
auto gridStrokeWidth() const -> double: Returns the width of grid lines in the table in mm.
auto headerFont() const -> QFont: Returns the font used to draw header text in the table.
auto headerFontColor() const -> QColor: Returns the color used to draw header text in the table.
auto headerHAlignment() const -> HeaderHAlignment: Returns the horizontal alignment for table headers.
auto headerLabels() const -> QMap<int, QString> virtual: Returns the text used in the column headers for the table.
auto headerMode() const -> HeaderMode: Returns the display mode for headers in the table.
auto horizontalGrid() const -> bool: Returns whether the grid's horizontal lines are drawn in the table.
auto minFrameSize(int frameIndex = -1) const -> QSizeF override: Returns the minimum size for a frames, if desired.
auto readPropertiesFromElement(const QDomElement& element, const QDomDocument& document, const QgsReadWriteContext& context) -> bool override: Sets multiframe state from a DOM element.
void render(QgsLayoutItemRenderContext& context, const QRectF& renderExtent, int frameIndex) override: Renders a portion of the multiframe's content into a render context.
void setBackgroundColor(const QColor& color): Sets the color used for background of table.
void setCellMargin(double margin): Sets the margin distance in mm between cell borders and their contents.
void setCellStyle(CellStyleGroup group, const QgsLayoutTableStyle& style): Sets the cell style for a cell group.
void setColumns(const QgsLayoutTableColumns& columns): Replaces the columns in the table with a specified list of QgsLayoutTableColumns.
void setContentFont(const QFont& font): Sets the font used to draw text in table body cells.
void setContentFontColor(const QColor& color): Sets the color used to draw text in table body cells.
void setEmptyTableBehavior(EmptyTableMode mode): Sets the behavior mode for empty tables with no content rows.
void setEmptyTableMessage(const QString& message): Sets the message for empty tables with no content rows.
void setGridColor(const QColor& color): Sets the color used for grid lines in the table.
void setGridStrokeWidth(double width): Sets the width in mm for grid lines in the table.
void setHeaderFont(const QFont& font): Sets the font used to draw header text in the table.
void setHeaderFontColor(const QColor& color): Sets the color used to draw header text in the table.
void setHeaderHAlignment(HeaderHAlignment alignment): Sets the horizontal alignment for table headers.
void setHeaderMode(HeaderMode mode): Sets the display mode for headers in the table.
void setHorizontalGrid(bool horizontalGrid): Sets whether the grid's horizontal lines should be drawn in the table.
void setShowEmptyRows(bool showEmpty): Sets whether empty rows should be drawn.
void setShowGrid(bool showGrid): Sets whether grid lines should be drawn in the table.
void setVerticalGrid(bool verticalGrid): Sets whether the grid's vertical lines should be drawn in the table.
void setWrapBehavior(WrapBehavior behavior): Sets the wrap behavior for the table, which controls how text within cells is automatically wrapped.
auto showEmptyRows() const -> bool: Returns whether empty rows are drawn in the table.
auto showGrid() const -> bool: Returns whether grid lines are drawn in the table.
auto totalSize() const -> QSizeF override: Returns the total size of the multiframe's content, in layout units.
auto verticalGrid() const -> bool: Returns whether the grid's vertical lines are drawn in the table.
auto wrapBehavior() const -> WrapBehavior: Returns the wrap behavior for the table, which controls how text within cells is automatically wrapped.
auto writePropertiesToElement(QDomElement& element, QDomDocument& document, const QgsReadWriteContext& context) const -> bool override: Stores multiframe state within an XML DOM element.

Public slots

void refreshAttributes() virtual: Refreshes the contents shown in the table by querying for new data.

Protected functions

auto calculateMaxColumnWidths() -> bool virtual: Calculates the maximum width of text shown in columns.
auto calculateMaxRowHeights() -> bool virtual: Calculates the maximum height of text shown in rows.
auto contentsContainsRow(const QgsLayoutTableContents& contents, const QgsLayoutTableRow& row) const -> bool: Checks whether a table contents contains a given row.
void drawHorizontalGridLines(QPainter* painter, int firstRow, int lastRow, bool drawHeaderLines) const: Draws the horizontal grid lines for the table.
void drawVerticalGridLines(QPainter* painter, const QMap<int, double>& maxWidthMap, int firstRow, int lastRow, bool hasHeader, bool mergeCells = false) const: Draws the vertical grid lines for the table.
void recalculateTableSize(): Recalculates and updates the size of the table and all table frames.
auto rowRange(int frameIndex) const -> QPair<int, int>: Calculates a range of rows which should be visible in a given frame.
auto rowsVisible(double frameHeight, int firstRow, bool includeHeader, bool includeEmptyRows) const -> int: Calculates how many content rows would be visible within a frame of the specified height.
auto rowsVisible(int frameIndex, int firstRow, bool includeEmptyRows) const -> int: Calculates how many content rows are visible within a given frame.
auto totalHeight() -> double: Returns total height of table contents.
auto totalWidth() -> double: Returns total width of table contents.

Protected variables

QColor mBackgroundColor: Color for table background.
double mCellMargin: Margin between cell borders and cell text.
QgsLayoutTableColumns mColumns: Columns to show in table.
QFont mContentFont: Table contents font.
QColor mContentFontColor: Table contents font color.
QString mEmptyTableMessage: String to show in empty tables.
EmptyTableMode mEmptyTableMode: Behavior for empty tables.
QColor mGridColor: Color for grid lines.
double mGridStrokeWidth: Width of grid lines.
QFont mHeaderFont: Header font.
QColor mHeaderFontColor: Header font color.
HeaderHAlignment mHeaderHAlignment: Alignment for table headers.
HeaderMode mHeaderMode: Header display mode.
bool mHorizontalGrid: True if grid should be shown.
QMap<int, double> mMaxColumnWidthMap: Map of maximum width for each column.
QMap<int, double> mMaxRowHeightMap: Map of maximum height for each row.
bool mShowEmptyRows: True if empty rows should be shown in the table.
bool mShowGrid: True if grid should be shown.
QgsLayoutTableContents mTableContents: Contents to show in table.
bool mVerticalGrid: True if grid should be shown.

Enum documentation

enum QgsLayoutTable::CellStyleGroup

Row or column groups for cell styling.

Enumerators
OddColumns	Style odd numbered columns.
EvenColumns	Style even numbered columns.
OddRows	Style odd numbered rows.
EvenRows	Style even numbered rows.
FirstColumn	Style first column only.
LastColumn	Style last column only.
HeaderRow	Style header row.
FirstRow	Style first row only.
LastRow	Style last row only.

enum QgsLayoutTable::EmptyTableMode

Controls how empty tables are displayed.

Enumerators
HeadersOnly	Show header rows only.
HideTable	Hides entire table if empty.
ShowMessage	Shows preset message instead of table contents.

enum QgsLayoutTable::HeaderHAlignment

Controls how headers are horizontally aligned in a table.

Enumerators
FollowColumn	Header uses the same alignment as the column.
HeaderLeft	Align headers left.
HeaderCenter	Align headers to center.
HeaderRight	Align headers right.

enum QgsLayoutTable::HeaderMode

Controls where headers are shown in the table.

Enumerators
FirstFrame	Header shown on first frame only.
AllFrames	Headers shown on all frames.
NoHeaders	No headers shown for table.

enum QgsLayoutTable::WrapBehavior

Controls how long strings in the table are handled.

Enumerators
TruncateText	Text which doesn't fit inside the cell is truncated.
WrapText	Text which doesn't fit inside the cell is wrapped. Note that this only applies to text in columns with a fixed width.

Function documentation

QColor QgsLayoutTable::backgroundColor() const

Returns the color used for the background of the table.

double QgsLayoutTable::cellMargin() const

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

const QgsLayoutTableStyle* QgsLayoutTable::cellStyle(CellStyleGroup group) const

Returns the cell style for a cell group.

QgsLayoutTableColumns& QgsLayoutTable::columns()

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

QFont QgsLayoutTable::contentFont() const

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

QColor QgsLayoutTable::contentFontColor() const

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

QgsLayoutTableContents& QgsLayoutTable::contents()

Returns the current contents of the table.

Excludes header cells.

EmptyTableMode QgsLayoutTable::emptyTableBehavior() const

Returns the behavior mode for empty tables.

This property controls how the table is drawn if it contains no content rows.

QString QgsLayoutTable::emptyTableMessage() const

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.

QSizeF QgsLayoutTable::fixedFrameSize(int frameIndex = -1) const override

Returns the fixed size for a frame, if desired.

Parameters
frameIndex	frame number
Returns	fixed size for frame. If the size has a width or height of 0, then the frame size is not fixed in that direction and frames can have variable width or height accordingly.

If the fixed frame size changes, the sizes of all frames can be recalculated by calling recalculateFrameRects().

bool QgsLayoutTable::getTableContents(QgsLayoutTableContents& contents) pure virtual

Fetches the contents used for the cells in the table.

Parameters
contents	QgsLayoutTableContents to store retrieved row data in
Returns	true if table contents were successfully retrieved.

QColor QgsLayoutTable::gridColor() const

Returns the color used for grid lines in the table.

double QgsLayoutTable::gridStrokeWidth() const

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

QFont QgsLayoutTable::headerFont() const

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

QColor QgsLayoutTable::headerFontColor() const

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

HeaderHAlignment QgsLayoutTable::headerHAlignment() const

Returns the horizontal alignment for table headers.

QMap<int, QString> QgsLayoutTable::headerLabels() const virtual

Returns the text used in the column headers for the table.

Returns	QMap of int to QString, where the int is the column index (starting at 0), and the string is the text to use for the column's header

HeaderMode QgsLayoutTable::headerMode() const

Returns the display mode for headers in the table.

This property controls if and where headers are shown in the table.

bool QgsLayoutTable::horizontalGrid() const

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

QSizeF QgsLayoutTable::minFrameSize(int frameIndex = -1) const override

Returns the minimum size for a frames, if desired.

Parameters
frameIndex	frame number
Returns	minimum size for frame. If the size has a width or height of 0, then the frame size has no minimum in that direction.

If the minimum size changes, the sizes of all frames can be recalculated by calling recalculateFrameRects().

bool QgsLayoutTable::readPropertiesFromElement(const QDomElement& element, const QDomDocument& document, const QgsReadWriteContext& context) override

Sets multiframe state from a DOM element.

Parameters
element	is the DOM element for the multiframe
document	DOM document
context	read write context

Note that item subclasses should not rely on all other items being present in the layout at the time this method is called. Instead, any connections and links to other items must be made in the finalizeRestoreFromXml() method. E.g. when restoring a scalebar, the connection to the linked map's signals should be implemented in finalizeRestoreFromXml(), not readPropertiesFromElement().

void QgsLayoutTable::render(QgsLayoutItemRenderContext& context, const QRectF& renderExtent, int frameIndex) override

Renders a portion of the multiframe's content into a render context.

Parameters
context	destination render painter
renderExtent	visible extent of content to render into the painter.
frameIndex	frame number for content

void QgsLayoutTable::setBackgroundColor(const QColor& color)

Sets the color used for background of table.

void QgsLayoutTable::setCellMargin(double margin)

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

void QgsLayoutTable::setCellStyle(CellStyleGroup group, const QgsLayoutTableStyle& style)

Sets the cell style for a cell group.

void QgsLayoutTable::setColumns(const QgsLayoutTableColumns& columns)

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

Parameters
columns	list of QgsLayoutTableColumns to show in table.

void QgsLayoutTable::setContentFont(const QFont& font)

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

void QgsLayoutTable::setContentFontColor(const QColor& color)

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

void QgsLayoutTable::setEmptyTableBehavior(EmptyTableMode mode)

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

void QgsLayoutTable::setEmptyTableMessage(const QString& message)

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.

void QgsLayoutTable::setGridColor(const QColor& color)

Sets the color used for grid lines in the table.

void QgsLayoutTable::setGridStrokeWidth(double width)

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

void QgsLayoutTable::setHeaderFont(const QFont& font)

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

void QgsLayoutTable::setHeaderFontColor(const QColor& color)

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

void QgsLayoutTable::setHeaderHAlignment(HeaderHAlignment alignment)

Sets the horizontal alignment for table headers.

void QgsLayoutTable::setHeaderMode(HeaderMode mode)

Sets the display mode for headers in the table.

This property controls if and where headers are shown in the table.

void QgsLayoutTable::setHorizontalGrid(bool horizontalGrid)

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

Parameters
horizontalGrid	set to true to draw grid's horizontal lines

void QgsLayoutTable::setShowEmptyRows(bool showEmpty)

Sets whether empty rows should be drawn.

Parameters
showEmpty	set to true to show empty rows in the table

Tables default to hiding empty rows.

void QgsLayoutTable::setShowGrid(bool showGrid)

Sets whether grid lines should be drawn in the table.

Parameters
showGrid	set to true to show grid lines

void QgsLayoutTable::setVerticalGrid(bool verticalGrid)

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

Parameters
verticalGrid	set to true to draw grid's vertical lines

void QgsLayoutTable::setWrapBehavior(WrapBehavior behavior)

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

bool QgsLayoutTable::showEmptyRows() const

Returns whether empty rows are drawn in the table.

bool QgsLayoutTable::showGrid() const

Returns whether grid lines are drawn in the table.

bool QgsLayoutTable::verticalGrid() const

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

WrapBehavior QgsLayoutTable::wrapBehavior() const

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

bool QgsLayoutTable::writePropertiesToElement(QDomElement& element, QDomDocument& document, const QgsReadWriteContext& context) const override

Stores multiframe state within an XML DOM element.

Parameters
element	is the DOM element to store the multiframe's properties in
document	DOM document
context	read write context

void QgsLayoutTable::refreshAttributes() virtual public slot

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.

bool QgsLayoutTable::contentsContainsRow(const QgsLayoutTableContents& contents, const QgsLayoutTableRow& row) const protected

Checks whether a table contents contains a given row.

Parameters
contents	table contents to check
row	row to check for
Returns	true if contents contains rows

void QgsLayoutTable::drawHorizontalGridLines(QPainter* painter, int firstRow, int lastRow, bool drawHeaderLines) const protected

Draws the horizontal grid lines for the table.

Parameters
painter	destination painter for grid lines
firstRow	index corresponding to first row shown in frame
lastRow	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	set to true to include for the table header

void QgsLayoutTable::drawVerticalGridLines(QPainter* painter, const QMap<int, double>& maxWidthMap, int firstRow, int lastRow, bool hasHeader, bool mergeCells = false) const protected

Draws the vertical grid lines for the table.

Parameters
painter	destination painter for grid lines
maxWidthMap	QMap of int to double, where the int contains the column number and the double is the maximum width of text present in the column.
firstRow	index corresponding to first row shown in frame
lastRow	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.
hasHeader	set to true if table frame includes header cells
mergeCells	set to true to merge table content cells

QPair<int, int> QgsLayoutTable::rowRange(int frameIndex) const protected

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

Parameters
frameIndex	index number for frame
Returns	row range

int QgsLayoutTable::rowsVisible(double frameHeight, int firstRow, bool includeHeader, bool includeEmptyRows) const protected

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

Parameters
frameHeight	height of frame
firstRow	index of first row visible in frame (where 0 = first row in table)
includeHeader	set to true if frame would include a header row
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.
Returns	number of visible content rows (excluding header row)

int QgsLayoutTable::rowsVisible(int frameIndex, int firstRow, bool includeEmptyRows) const protected

Calculates how many content rows are visible within a given frame.

Parameters
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.
Returns	number of visible content rows (excludes header rows)

double QgsLayoutTable::totalHeight() protected

Returns total height of table contents.

double QgsLayoutTable::totalWidth() protected

Returns total width of table contents.

Returns	table width