QgsLayoutItemAttributeTable class

A layout table subclass that displays attributes from a vector layer.

Reference

Base classes

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

Public types

enum ContentSource { LayerAttributes = 0, AtlasFeature, RelationChildren }: Specifies the content source for the attribute table.

Public static functions

static auto create(QgsLayout* layout) -> QgsLayoutItemAttributeTable*: Returns a new QgsLayoutItemAttributeTable for the specified parent layout.

Constructors, destructors, conversion operators

QgsLayoutItemAttributeTable(QgsLayout* layout): Constructor for QgsLayoutItemAttributeTable, attached to the specified layout.

Public functions

auto createExpressionContext() const -> QgsExpressionContext override: This method needs to be reimplemented in all classes which implement this interface and return an expression context.
auto displayName() const -> QString override: Returns the multiframe display name.
auto displayOnlyVisibleFeatures() const -> bool: Returns true if the table is set to show only features visible on a corresponding map item.
auto featureFilter() const -> QString: Returns the current expression used to filter features for the table.
auto filterFeatures() const -> bool: Returns true if a feature filter is active on the attribute table.
auto filterToAtlasFeature() const -> bool: Returns true if the table is set to only show features which intersect the current atlas feature.
void finalizeRestoreFromXml() override: Called after all pending items have been restored from XML.
auto getTableContents(QgsLayoutTableContents& contents) -> bool override: Queries the attribute table's vector layer for attributes to show in the table.
auto icon() const -> QIcon override: Returns the item's icon.
auto map() const -> QgsLayoutItemMap*: Returns the layout map whose extents are controlling the features shown in the table.
auto maximumNumberOfFeatures() const -> int: Returns the maximum number of features to be shown by the table.
void refreshDataDefinedProperty(QgsLayoutObject::DataDefinedProperty property = QgsLayoutObject::AllProperties) override: Refreshes a data defined property for the multi frame by reevaluating the property's value and redrawing the item with this new value.
auto relationId() const -> QString: Returns the relation id which the table displays child features from.
void resetColumns(): Resets the attribute table's columns to match the vector layer's fields.
void setDisplayedFields(const QStringList& fields, bool refresh = true): Sets the attributes to display in the table.
void setDisplayOnlyVisibleFeatures(bool visibleOnly): Sets the attribute table to only show features which are visible in a map item.
void setFeatureFilter(const QString& expression): Sets the expression used for filtering features in the table.
void setFilterFeatures(bool filter): Sets whether the feature filter is active for the attribute table.
void setFilterToAtlasFeature(bool filterToAtlas): Sets attribute table to only show features which intersect the current atlas feature.
void setMap(QgsLayoutItemMap* map): Sets a layout map to use to limit the extent of features shown in the attribute table.
void setMaximumNumberOfFeatures(int features): Sets the maximum number of features shown by the table.
void setRelationId(const QString& id): Sets the relation id from which to display child features.
void setSource(ContentSource source): Sets the source for attributes to show in table body.
void setUniqueRowsOnly(bool uniqueOnly): Sets attribute table to only show unique rows.
void setVectorLayer(QgsVectorLayer* layer): Sets the vector layer from which to display feature attributes.
void setWrapString(const QString& wrapString): Sets a string to wrap the contents of the table cells by.
auto sortAttributes() const -> QVector<QPair<int, bool>>: Returns the attributes used to sort the table's features.
auto source() const -> ContentSource: Returns the source for attributes shown in the table body.
auto sourceLayer() const -> QgsVectorLayer*: Returns the source layer for the table, considering the table source mode.
auto type() const -> int override: Returns unique multiframe type id.
auto uniqueRowsOnly() const -> bool: Returns true if the table is set to show only unique rows.
auto vectorLayer() const -> QgsVectorLayer*: Returns the vector layer the attribute table is currently using.
auto wrapString() const -> QString: Returns the string used to wrap the contents of the table cells by.

Protected functions

auto readPropertiesFromElement(const QDomElement& element, const QDomDocument& document, const QgsReadWriteContext& context) -> bool override: Sets multiframe state from a DOM element.
auto writePropertiesToElement(QDomElement& element, QDomDocument& document, const QgsReadWriteContext& context) const -> bool override: Stores multiframe state within an XML DOM element.

Enum documentation

enum QgsLayoutItemAttributeTable::ContentSource

Specifies the content source for the attribute table.

Enumerators
LayerAttributes	Table shows attributes from features in a vector layer.
AtlasFeature	Table shows attributes from the current atlas feature.
RelationChildren	Table shows attributes from related child features.

Function documentation

QgsLayoutItemAttributeTable::QgsLayoutItemAttributeTable(QgsLayout* layout)

Constructor for QgsLayoutItemAttributeTable, attached to the specified layout.

Ownership is transferred to the layout.

QgsExpressionContext QgsLayoutItemAttributeTable::createExpressionContext() const override

This method needs to be reimplemented in all classes which implement this interface and return an expression context.

bool QgsLayoutItemAttributeTable::displayOnlyVisibleFeatures() const

Returns true if the table is set to show only features visible on a corresponding map item.

QString QgsLayoutItemAttributeTable::featureFilter() const

Returns the current expression used to filter features for the table.

The filter is only active if filterFeatures() is true.

bool QgsLayoutItemAttributeTable::filterFeatures() const

Returns true if a feature filter is active on the attribute table.

bool QgsLayoutItemAttributeTable::filterToAtlasFeature() const

Returns true if the table is set to only show features which intersect the current atlas feature.

void QgsLayoutItemAttributeTable::finalizeRestoreFromXml() override

Called after all pending items have been restored from XML.

Multiframes can use this method to run steps which must take place after all items have been restored to the layout, such as connecting to signals emitted by other items, which may not have existed in the layout at the time readXml() was called. E.g. a scalebar can use this to connect to its linked map item after restoration from XML.

bool QgsLayoutItemAttributeTable::getTableContents(QgsLayoutTableContents& contents) override

Queries the attribute table's vector layer for attributes to show in the table.

Parameters
contents	table content
Returns	true if attributes were successfully fetched

QgsLayoutItemMap* QgsLayoutItemAttributeTable::map() const

Returns the layout map whose extents are controlling the features shown in the table.

The extents of the map are only used if displayOnlyVisibleFeatures() is true.

int QgsLayoutItemAttributeTable::maximumNumberOfFeatures() const

Returns the maximum number of features to be shown by the table.

void QgsLayoutItemAttributeTable::refreshDataDefinedProperty(QgsLayoutObject::DataDefinedProperty property = QgsLayoutObject::AllProperties) override

Refreshes a data defined property for the multi frame by reevaluating the property's value and redrawing the item with this new value.

If property is set to QgsLayoutObject::AllProperties then all data defined properties for the item will be refreshed.

QString QgsLayoutItemAttributeTable::relationId() const

Returns the relation id which the table displays child features from.

void QgsLayoutItemAttributeTable::resetColumns()

Resets the attribute table's columns to match the vector layer's fields.

void QgsLayoutItemAttributeTable::setDisplayedFields(const QStringList& fields, bool refresh = true)

Sets the attributes to display in the table.

Parameters
fields	list of fields names from the vector layer to show. Set to an empty list to show all feature attributes.
refresh	set to true to force the table to refetch features from its vector layer and immediately update the display of the table. This may result in the table changing size to accommodate the new displayed feature attributes.

void QgsLayoutItemAttributeTable::setDisplayOnlyVisibleFeatures(bool visibleOnly)

Sets the attribute table to only show features which are visible in a map item.

Changing this setting forces the table to refetch features from its vector layer, and may result in the table changing size to accommodate the new displayed feature attributes.

void QgsLayoutItemAttributeTable::setFeatureFilter(const QString& expression)

Sets the expression used for filtering features in the table.

The filter is only active if filterFeatures() is set to true. Changing this setting forces the table to refetch features from its vector layer, and may result in the table changing size to accommodate the new displayed feature attributes.

void QgsLayoutItemAttributeTable::setFilterFeatures(bool filter)

Sets whether the feature filter is active for the attribute table.

Changing this setting forces the table to refetch features from its vector layer, and may result in the table changing size to accommodate the new displayed feature attributes.

void QgsLayoutItemAttributeTable::setFilterToAtlasFeature(bool filterToAtlas)

Sets attribute table to only show features which intersect the current atlas feature.

void QgsLayoutItemAttributeTable::setMap(QgsLayoutItemMap* map)

Sets a layout map to use to limit the extent of features shown in the attribute table.

This setting only has an effect if setDisplayOnlyVisibleFeatures is set to true. Changing the map forces the table to refetch features from its vector layer, and may result in the table changing size to accommodate the new displayed feature attributes.

void QgsLayoutItemAttributeTable::setMaximumNumberOfFeatures(int features)

Sets the maximum number of features shown by the table.

Changing this setting may result in the attribute table changing its size to accommodate the new number of rows, and requires the table to refetch features from its vector layer.

void QgsLayoutItemAttributeTable::setRelationId(const QString& id)

Sets the relation id from which to display child features.

void QgsLayoutItemAttributeTable::setSource(ContentSource source)

Sets the source for attributes to show in table body.

void QgsLayoutItemAttributeTable::setUniqueRowsOnly(bool uniqueOnly)

Sets attribute table to only show unique rows.

Set uniqueOnly to true to show only unique rows. Duplicate rows will be stripped from the table.

void QgsLayoutItemAttributeTable::setVectorLayer(QgsVectorLayer* layer)

Sets the vector layer from which to display feature attributes.

This is only considered if the table source() is LayerAttributes.

void QgsLayoutItemAttributeTable::setWrapString(const QString& wrapString)

Sets a string to wrap the contents of the table cells by.

Parameters
wrapString	string to replace with line break

Occurrences of this string will be replaced by a line break.

QVector<QPair<int, bool>> QgsLayoutItemAttributeTable::sortAttributes() const

Returns the attributes used to sort the table's features.

Returns	a QList of integer/bool pairs, where the integer refers to the attribute index and the bool to the sort order for the attribute. If true the attribute is sorted ascending, if false, the attribute is sorted in descending order.

ContentSource QgsLayoutItemAttributeTable::source() const

Returns the source for attributes shown in the table body.

QgsVectorLayer* QgsLayoutItemAttributeTable::sourceLayer() const

Returns the source layer for the table, considering the table source mode.

For example, if the table is set to atlas feature mode, then the source layer will be the atlas coverage layer. If the table is set to layer attributes mode, then the source layer will be the user specified vector layer.

bool QgsLayoutItemAttributeTable::uniqueRowsOnly() const

Returns true if the table is set to show only unique rows.

QgsVectorLayer* QgsLayoutItemAttributeTable::vectorLayer() const

Returns the vector layer the attribute table is currently using.

This is only considered if the table source() is LayerAttributes.

QString QgsLayoutItemAttributeTable::wrapString() const

Returns the string used to wrap the contents of the table cells by.

Occurrences of this string will be replaced by a line break.

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

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

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

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