QgsLayerTreeNode class

This class is a base class for nodes in a layer tree.

Reference

Layer tree is a hierarchical structure consisting of group and layer nodes:

group nodes are containers and may contain children (layer and group nodes)
layer nodes point to map layers, they do not contain further children

Layer trees may be used for organization of layers, typically a layer tree is exposed to the user using QgsLayerTreeView widget which shows the tree and allows manipulation with the tree.

Ownership of nodes: every node is owned by its parent. Therefore once node is added to a layer tree, it is the responsibility of the parent to delete it when the node is not needed anymore. Deletion of root node of a tree will delete all nodes of the tree.

Signals: signals are propagated from children to parent. That means it is sufficient to connect to root node in order to get signals about updates in the whole layer tree. When adding or removing a node that contains further children (i.e. a whole subtree), the addition/removal signals are emitted only for the root node of the subtree that is being added or removed.

Custom properties: Every node may have some custom properties assigned to it. This mechanism allows third parties store additional data with the nodes. The properties are used within QGIS code (whether to show layer in overview, whether the node is embedded from another project etc), but may be also used by third party plugins. Custom properties are stored also in the project file. The storage is not efficient for large amount of data.

Custom properties that have already been used within QGIS:

"loading" - whether the project is being currently loaded (root node only)
"overview" - whether to show a layer in overview
"showFeatureCount" - whether to show feature counts in layer tree (vector only)
"embedded" - whether the node comes from an external project
"embedded_project" - path to the external project (embedded root node only)
"legend/..." - properties for legend appearance customization
"expandedLegendNodes" - list of layer's legend nodes' rules in expanded state

Derived classes

class QgsLayerTreeGroup: Layer tree group node serves as a container for layers and further groups.
class QgsLayerTreeLayer: Layer tree node points to a map layer.

Public types

enum NodeType { NodeGroup, NodeLayer }: Enumeration of possible tree node types.

Public static functions

static auto readXml(QDomElement& element, const QgsReadWriteContext& context) -> QgsLayerTreeNode*: Read layer tree from XML.
static auto readXml(QDomElement& element, const QgsProject* project) -> QgsLayerTreeNode*: Read layer tree from XML.

Constructors, destructors, conversion operators

QgsLayerTreeNode(NodeType t, bool checked = true) protected: Constructor.

Public functions

auto checkedLayers() const -> QList<QgsMapLayer*>: Returns a list of any checked layers which belong to this node or its children.
auto children() -> QList<QgsLayerTreeNode*>: Gets list of children of the node. Children are owned by the parent.
auto children() const -> QList<QgsLayerTreeNode*>: Gets list of children of the node. Children are owned by the parent.
auto clone() const -> QgsLayerTreeNode* pure virtual: Create a copy of the node. Returns new instance.
auto customProperties() const -> QStringList: Returns list of keys stored in custom properties.
auto customProperty(const QString& key, const QVariant& defaultValue = QVariant()) const -> QVariant: Read a custom property from layer. Properties are stored in a map and saved in project file.
auto dump() const -> QString pure virtual: Returns string with layer tree structure. For debug purposes only.
auto isExpanded() const -> bool: Returns whether the node should be shown as expanded or collapsed in GUI.
auto isItemVisibilityCheckedRecursive() const -> bool: Returns whether this node is checked and all its children.
auto isItemVisibilityUncheckedRecursive() const -> bool: Returns whether this node is unchecked and all its children.
auto isVisible() const -> bool: Returns whether a node is really visible (ie checked and all its ancestors checked as well)
auto itemVisibilityChecked() const -> bool: Returns whether a node is checked (independently of its ancestors or children)
auto name() const -> QString pure virtual: Returns name of the node.
auto nodeType() const -> NodeType: Find out about type of the node. It is usually shorter to use convenience functions from QgsLayerTree namespace for that.
auto parent() -> QgsLayerTreeNode*: Gets pointer to the parent. If parent is a null pointer, the node is a root node.
void removeCustomProperty(const QString& key): Remove a custom property from layer. Properties are stored in a map and saved in project file.
void resolveReferences(const QgsProject* project, bool looseMatching = false) pure virtual: Turn textual references to layers into map layer object from project.
void setCustomProperty(const QString& key, const QVariant& value): Sets a custom property for the node. Properties are stored in a map and saved in project file.
void setExpanded(bool expanded): Sets whether the node should be shown as expanded or collapsed in GUI.
void setItemVisibilityChecked(bool checked): Check or uncheck a node (independently of its ancestors or children)
void setItemVisibilityCheckedParentRecursive(bool checked): Check or uncheck a node and all its parents.
void setItemVisibilityCheckedRecursive(bool checked) virtual: Check or uncheck a node and all its children (taking into account exclusion rules)
void setName(const QString& name) pure virtual: Set name of the node.
auto takeChild(QgsLayerTreeNode* node) -> bool: Remove a child from a node.
void writeXml(QDomElement& parentElement, const QgsReadWriteContext& context) pure virtual: Write layer tree to XML.

Signals

void addedChildren(QgsLayerTreeNode* node, int indexFrom, int indexTo): Emitted when one or more nodes have been added to a node within the tree.
void customPropertyChanged(QgsLayerTreeNode* node, const QString& key): Emitted when a custom property of a node within the tree has been changed or removed.
void expandedChanged(QgsLayerTreeNode* node, bool expanded): Emitted when the collapsed/expanded state of a node within the tree has been changed.
void nameChanged(QgsLayerTreeNode* node, QString name): Emitted when the name of the node is changed.
void removedChildren(QgsLayerTreeNode* node, int indexFrom, int indexTo): Emitted when one or more nodes has been removed from a node within the tree.
void visibilityChanged(QgsLayerTreeNode* node): Emitted when check state of a node within the tree has been changed.
void willAddChildren(QgsLayerTreeNode* node, int indexFrom, int indexTo): Emitted when one or more nodes will be added to a node within the tree.
void willRemoveChildren(QgsLayerTreeNode* node, int indexFrom, int indexTo): Emitted when one or more nodes will be removed from a node within the tree.

Protected functions

void insertChildrenPrivate(int index, QList<QgsLayerTreeNode*> nodes): Low-level insertion of children to the node. The children must not have any parent yet!
void readCommonXml(QDomElement& element): Read common XML elements.
void removeChildrenPrivate(int from, int count, bool destroy = true): Low-level removal of children from the node.
void writeCommonXml(QDomElement& element): Write common XML elements.

Protected variables

QList<QgsLayerTreeNode*> mChildren: list of children - node is responsible for their deletion
bool mExpanded: whether the node should be shown in GUI as expanded
NodeType mNodeType: type of the node - determines which subclass is used
QgsLayerTreeNode* mParent: pointer to the parent node - null in case of root node
QgsObjectCustomProperties mProperties: custom properties attached to the node

Enum documentation

enum QgsLayerTreeNode::NodeType

Enumeration of possible tree node types.

Enumerators
NodeGroup	Container of other groups and layers.
NodeLayer	Leaf node pointing to a layer.

Function documentation

static QgsLayerTreeNode* QgsLayerTreeNode::readXml(QDomElement& element, const QgsReadWriteContext& context)

Read layer tree from XML.

Returns new instance. Does not resolve textual references to layers. Call resolveReferences() afterwards to do it.

static QgsLayerTreeNode* QgsLayerTreeNode::readXml(QDomElement& element, const QgsProject* project)

Read layer tree from XML.

Returns new instance. Also resolves textual references to layers from the project (calls resolveReferences() internally).

QList<QgsMapLayer*> QgsLayerTreeNode::checkedLayers() const

Returns a list of any checked layers which belong to this node or its children.

bool QgsLayerTreeNode::isItemVisibilityCheckedRecursive() const

Returns whether this node is checked and all its children.

bool QgsLayerTreeNode::isItemVisibilityUncheckedRecursive() const

Returns whether this node is unchecked and all its children.

bool QgsLayerTreeNode::isVisible() const

Returns whether a node is really visible (ie checked and all its ancestors checked as well)

bool QgsLayerTreeNode::itemVisibilityChecked() const

Returns whether a node is checked (independently of its ancestors or children)

QString QgsLayerTreeNode::name() const pure virtual

Returns name of the node.

void QgsLayerTreeNode::resolveReferences(const QgsProject* project, bool looseMatching = false) pure virtual

Turn textual references to layers into map layer object from project.

This method should be called after readXml() If looseMatching is true then a looser match will be used, where a layer will match if the name, public source, and data provider match. This can be used to match legend customization from different projects where layers will have different layer IDs.

void QgsLayerTreeNode::setItemVisibilityChecked(bool checked)

Check or uncheck a node (independently of its ancestors or children)

void QgsLayerTreeNode::setItemVisibilityCheckedParentRecursive(bool checked)

Check or uncheck a node and all its parents.

void QgsLayerTreeNode::setItemVisibilityCheckedRecursive(bool checked) virtual

Check or uncheck a node and all its children (taking into account exclusion rules)

void QgsLayerTreeNode::setName(const QString& name) pure virtual

Set name of the node.

Emits nameChanged signal.

void QgsLayerTreeNode::nameChanged(QgsLayerTreeNode* node, QString name) signal

Emitted when the name of the node is changed.