QgsLayerTreeModel class

The QgsLayerTreeModel class is model implementation for Qt item views framework.

Reference

The model can be used in any QTreeView, it is however recommended to use it with QgsLayerTreeView which brings additional functionality specific to layer tree handling.

The model listens to the changes in the layer tree and signals the changes as appropriate, so that any view that uses the model is updated accordingly.

Behavior of the model can be customized with flags. For example, whether to show legend or whether to allow changes to the layer tree.

Derived classes

class QgsLegendModel: Item model implementation based on layer tree model for layout legend.

Public types

enum Flag { ShowLegend = 0x0001, ShowLegendAsTree = 0x0004, DeferredLegendInvalidation = 0x0008, UseEmbeddedWidgets = 0x0010, AllowNodeReorder = 0x1000, AllowNodeRename = 0x2000, AllowNodeChangeVisibility = 0x4000, AllowLegendChangeState = 0x8000, ActionHierarchical = 0x10000 }

Public static functions

static auto index2legendNode(const QModelIndex& index) -> QgsLayerTreeModelLegendNode*: Returns legend node for given index.

Constructors, destructors, conversion operators

QgsLayerTreeModel(QgsLayerTree* rootNode, QObject* parent = nullptr) explicit: Construct a new tree model with given layer tree (root node must not be null pointer).

Public functions

auto autoCollapseLegendNodes() const -> int: Returns at what number of legend nodes the layer node should be collapsed. -1 means no auto-collapse (default).
auto currentIndex() const -> QModelIndex: Gets index of the item marked as current. Item marked as current is underlined.
auto findLegendNode(const QString& layerId, const QString& ruleKey) const -> QgsLayerTreeModelLegendNode*: Searches through the layer tree to find a legend node with a matching layer ID and rule key.
auto flags() const -> Flags: Returns OR-ed combination of model flags.
auto index2node(const QModelIndex& index) const -> QgsLayerTreeNode*: Returns layer tree node for given index.
auto indexes2nodes(const QModelIndexList& list, bool skipInternal = false) const -> QList<QgsLayerTreeNode*>: Convert a list of indexes to a list of layer tree nodes.
auto layerLegendNodes(QgsLayerTreeLayer* nodeLayer, bool skipNodeEmbeddedInParent = false) -> QList<QgsLayerTreeModelLegendNode*>: Returns filtered list of active legend nodes attached to a particular layer node (by default it returns also legend node embedded in parent layer node (if any) unless skipNodeEmbeddedInParent is true)
auto layerOriginalLegendNodes(QgsLayerTreeLayer* nodeLayer) -> QList<QgsLayerTreeModelLegendNode*>: Returns original (unfiltered) list of legend nodes attached to a particular layer node.
auto layerStyleOverrides() const -> QMap<QString, QString>: Gets map of map layer style overrides (key: layer ID, value: style name) where a different style should be used instead of the current one.
auto layerTreeNodeFont(int nodeType) const -> QFont: Gets font for a particular type of layer tree node. nodeType should come from QgsLayerTreeNode::NodeType enumeration.
auto legendFilterByScale() const -> double: Returns the scale which restricts the legend nodes which are visible.
auto legendFilterMapSettings() const -> const QgsMapSettings*: Returns the current map settings used for the current legend filter (or null if none is enabled)
void legendMapViewData(double* mapUnitsPerPixel, int* dpi, double* scale) const: Gets hints about map view - to be used in legend nodes.
auto legendNode2index(QgsLayerTreeModelLegendNode* legendNode) -> QModelIndex: Returns index for a given legend node.
auto legendNodeEmbeddedInParent(QgsLayerTreeLayer* nodeLayer) const -> QgsLayerTreeModelLegendNode*: Returns legend node that may be embedded in parent (i.e.
auto node2index(QgsLayerTreeNode* node) const -> QModelIndex: Returns index for a given node. If the node does not belong to the layer tree, the result is undefined.
void refreshLayerLegend(QgsLayerTreeLayer* nodeLayer): Force a refresh of legend nodes of a layer node.
auto rootGroup() const -> QgsLayerTree*: Returns pointer to the root node of the layer tree. Always a non-null pointer.
void setAutoCollapseLegendNodes(int nodeCount): Sets at what number of legend nodes the layer node should be collapsed. Setting -1 disables the auto-collapse (default).
void setCurrentIndex(const QModelIndex& currentIndex): Sets index of the current item. May be used by view. Item marked as current is underlined.
void setFlag(Flag f, bool on = true): Enable or disable a model flag.
void setFlags(QgsLayerTreeModel::Flags f): Sets OR-ed combination of model flags.
void setLayerStyleOverrides(const QMap<QString, QString>& overrides): Sets map of map layer style overrides (key: layer ID, value: style name) where a different style should be used instead of the current one.
void setLayerTreeNodeFont(int nodeType, const QFont& font): Sets font for a particular type of layer tree node. nodeType should come from QgsLayerTreeNode::NodeType enumeration.
void setLegendFilter(const QgsMapSettings* settings, bool useExtent = true, const QgsGeometry& polygon = QgsGeometry(), bool useExpressions = true): Filter display of legend nodes for given map settings.
void setLegendFilterByMap(const QgsMapSettings* settings): Force only display of legend nodes which are valid for given map settings.
void setLegendFilterByScale(double scale): Force only display of legend nodes which are valid for a given scale.
void setLegendMapViewData(double mapUnitsPerPixel, int dpi, double scale): Give the layer tree model hints about the currently associated map view so that legend nodes that use map units can be scaled currectly.
void setRootGroup(QgsLayerTree* newRootGroup): Reset the model and use a new root group node.
auto testFlag(Flag f) const -> bool: Check whether a flag is enabled.

Protected types

struct LayerLegendData: Structure that stores all data associated with one map layer.
struct LayerLegendTree: Structure that stores tree representation of map layer's legend.

Protected functions

auto filterLegendNodes(const QList<QgsLayerTreeModelLegendNode*>& nodes) -> QList<QgsLayerTreeModelLegendNode*>: Filter nodes from QgsMapLayerLegend according to the current filtering rules.
void recursivelyEmitDataChanged(const QModelIndex& index = QModelIndex()): emit dataChanged() for layer tree node items
void refreshScaleBasedLayers(const QModelIndex& index = QModelIndex()): Updates layer data for scale dependent layers, should be called when map scale changes.
auto tryBuildLegendTree(const QList<QgsLayerTreeModelLegendNode*>& nodes) -> LayerLegendTree*

Protected slots

void nodeNameChanged(QgsLayerTreeNode* node, const QString& name): Updates model when node's name has changed.

Protected variables

int mAutoCollapseLegendNodesCount: Minimal number of nodes when legend should be automatically collapsed. -1 = disabled.
QPersistentModelIndex mCurrentIndex: Current index - will be underlined.
Flags mFlags: Sets of flags for the model.
QMap<QString, QString> mLayerStyleOverrides: Overrides of map layers' styles: key = layer ID, value = style XML.
QMap<QgsLayerTreeLayer*, LayerLegendData> mLegend: Per layer data about layer's legend nodes.
double mLegendFilterByScale: scale denominator for filtering of legend nodes (<= 0 means no filtering)
bool mLegendFilterUsesExtent: whether to use map filtering
QgsLayerTree* mRootNode: Pointer to the root node of the layer tree. Not owned by the model.

Enum documentation

enum QgsLayerTreeModel::Flag

Enumerators
ShowLegend	Add legend nodes for layer nodes.
ShowLegendAsTree	For legends that support it, will show them in a tree instead of a list (needs also ShowLegend). Added in 2.8.
DeferredLegendInvalidation	Defer legend model invalidation.
UseEmbeddedWidgets	Layer nodes may optionally include extra embedded widgets (if used in QgsLayerTreeView). Added in 2.16.
AllowNodeReorder	Allow reordering with drag'n'drop.
AllowNodeRename	Allow renaming of groups and layers.
AllowNodeChangeVisibility	Allow user to set node visibility with a checkbox.
AllowLegendChangeState	Allow check boxes for legend nodes (if supported by layer's legend)
ActionHierarchical	Check/uncheck action has consequences on children (or parents for leaf node)

Function documentation

static QgsLayerTreeModelLegendNode* QgsLayerTreeModel::index2legendNode(const QModelIndex& index)

Returns legend node for given index.

Returns null for invalid index

QgsLayerTreeModel::QgsLayerTreeModel(QgsLayerTree* rootNode, QObject* parent = nullptr) explicit

Construct a new tree model with given layer tree (root node must not be null pointer).

The root node is not transferred by the model.

QgsLayerTreeModelLegendNode* QgsLayerTreeModel::findLegendNode(const QString& layerId, const QString& ruleKey) const

Searches through the layer tree to find a legend node with a matching layer ID and rule key.

Parameters
layerId	map layer ID
ruleKey	legend node rule key
Returns	QgsLayerTreeModelLegendNode if found

QgsLayerTreeNode* QgsLayerTreeModel::index2node(const QModelIndex& index) const

Returns layer tree node for given index.

Returns root node for invalid index. Returns null pointer if index does not refer to a layer tree node (e.g. it is a legend node)

QList<QgsLayerTreeNode*> QgsLayerTreeModel::indexes2nodes(const QModelIndexList& list, bool skipInternal = false) const

Convert a list of indexes to a list of layer tree nodes.

Indices that do not represent layer tree nodes are skipped. If skipInternal is true, a node is included in the output list only if no parent node is in the list.

QList<QgsLayerTreeModelLegendNode> QgsLayerTreeModel::layerLegendNodes(QgsLayerTreeLayer nodeLayer, bool skipNodeEmbeddedInParent = false)

Returns filtered list of active legend nodes attached to a particular layer node (by default it returns also legend node embedded in parent layer node (if any) unless skipNodeEmbeddedInParent is true)

QList<QgsLayerTreeModelLegendNode> QgsLayerTreeModel::layerOriginalLegendNodes(QgsLayerTreeLayer nodeLayer)

Returns original (unfiltered) list of legend nodes attached to a particular layer node.

QMap<QString, QString> QgsLayerTreeModel::layerStyleOverrides() const

Gets map of map layer style overrides (key: layer ID, value: style name) where a different style should be used instead of the current one.

double QgsLayerTreeModel::legendFilterByScale() const

Returns the scale which restricts the legend nodes which are visible.

The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map. A scale <= 0 indicates that no scale filtering is being performed.

const QgsMapSettings* QgsLayerTreeModel::legendFilterMapSettings() const

Returns the current map settings used for the current legend filter (or null if none is enabled)

void QgsLayerTreeModel::legendMapViewData(double* mapUnitsPerPixel, int* dpi, double* scale) const

Gets hints about map view - to be used in legend nodes.

Arguments that are not null will receive values. If there are no valid map view data (from previous call to setLegendMapViewData()), returned values are zeros.

QModelIndex QgsLayerTreeModel::legendNode2index(QgsLayerTreeModelLegendNode* legendNode)

Returns index for a given legend node.

If the legend node does not belong to the layer tree, the result is undefined. If the legend node is belongs to the tree but it is filtered out, invalid model index is returned.

QgsLayerTreeModelLegendNode* QgsLayerTreeModel::legendNodeEmbeddedInParent(QgsLayerTreeLayer* nodeLayer) const

Returns legend node that may be embedded in parent (i.e.

its icon will be used for layer's icon).

void QgsLayerTreeModel::refreshLayerLegend(QgsLayerTreeLayer* nodeLayer)

Force a refresh of legend nodes of a layer node.

Not necessary to call when layer's renderer is changed as the model listens to these events.

void QgsLayerTreeModel::setLayerStyleOverrides(const QMap<QString, QString>& overrides)

Sets map of map layer style overrides (key: layer ID, value: style name) where a different style should be used instead of the current one.

void QgsLayerTreeModel::setLegendFilter(const QgsMapSettings* settings, bool useExtent = true, const QgsGeometry& polygon = QgsGeometry(), bool useExpressions = true)

Filter display of legend nodes for given map settings.

Parameters
settings	Map settings. Setting a null pointer or invalid settings will disable any filter. Ownership is not changed, a copy is made
useExtent	Whether to use the extent of the map settings as a first spatial filter on legend nodes
polygon	If not empty, this polygon will be used instead of the map extent to filter legend nodes
useExpressions	Whether to use legend node filter expressions

void QgsLayerTreeModel::setLegendFilterByMap(const QgsMapSettings* settings)

Force only display of legend nodes which are valid for given map settings.

Setting null pointer or invalid map settings will disable the functionality. Ownership of map settings pointer does not change, a copy is made.

void QgsLayerTreeModel::setLegendFilterByScale(double scale)

Force only display of legend nodes which are valid for a given scale.

The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map. Setting scale <= 0 will disable the functionality.

void QgsLayerTreeModel::setLegendMapViewData(double mapUnitsPerPixel, int dpi, double scale)

Give the layer tree model hints about the currently associated map view so that legend nodes that use map units can be scaled currectly.

void QgsLayerTreeModel::setRootGroup(QgsLayerTree* newRootGroup)

Reset the model and use a new root group node.

void QgsLayerTreeModel::refreshScaleBasedLayers(const QModelIndex& index = QModelIndex()) protected

Updates layer data for scale dependent layers, should be called when map scale changes.

Emits dataChanged() for all scale dependent layers.

LayerLegendTree* QgsLayerTreeModel::tryBuildLegendTree(const QList<QgsLayerTreeModelLegendNode*>& nodes) protected

void QgsLayerTreeModel::nodeNameChanged(QgsLayerTreeNode* node, const QString& name) protected slot

Updates model when node's name has changed.

Variable documentation

QMap<QString, QString> QgsLayerTreeModel::mLayerStyleOverrides protected

Overrides of map layers' styles: key = layer ID, value = style XML.

This allows showing a legend that is different from the current style of layers