Class: QgsLayerTreeNode

Base class for nodes in a layer tree.

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

See also

QgsLayerTree

See also

QgsLayerTreeLayer

See also

QgsLayerTreeGroup

Note

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

The following methods must be implemented: clone(), dump(), name(), resolveReferences(), setName(), writeXml()

Class Hierarchy

Base classes

QObject

Subclasses

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

Abstract Methods

clone	Create a copy of the node.
dump	Returns string with layer tree structure.
name	Returns name of the node
resolveReferences	Turn textual references to layers into map layer object from project.
setName	Set name of the node.
writeXml	Write layer tree to XML

Methods

checkedLayers	Returns a list of any checked layers which belong to this node or its children.
children	Gets list of children of the node.
customProperties	Returns list of keys stored in custom properties
customProperty	Read a custom property from layer.
depth	Returns the depth of this node, i.e. the number of its ancestors.
insertChildrenPrivate	Low-level insertion of children to the node.
isExpanded	Returns whether the node should be shown as expanded or collapsed in GUI
isItemVisibilityCheckedRecursive	Returns whether this node is checked and all its children.
isItemVisibilityUncheckedRecursive	Returns whether this node is unchecked and all its children.
isVisible	Returns whether a node is really visible (ie checked and all its ancestors checked as well)
itemVisibilityChecked	Returns whether a node is checked (independently of its ancestors or children)
nodeType	Find out about type of the node.
parent	Gets pointer to the parent.
readCommonXml	Read common XML elements.
removeChildrenPrivate	Low-level removal of children from the node.
removeCustomProperty	Remove a custom property from layer.
setCustomProperty	Sets a custom property for the node.
setExpanded	Sets whether the node should be shown as expanded or collapsed in GUI
setItemVisibilityChecked	Check or uncheck a node (independently of its ancestors or children)
setItemVisibilityCheckedParentRecursive	Check or uncheck a node and all its parents
takeChild	Remove a child from a node
writeCommonXml	Write common XML elements.

Virtual Methods

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

setItemVisibilityCheckedRecursive

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

Static Methods

readXml

Read layer tree from XML.

Signals

addedChildren	Emitted when one or more nodes have been added to a node within the tree
customPropertyChanged	Emitted when a custom property of a node within the tree has been changed or removed
expandedChanged	Emitted when the collapsed/expanded state of a node within the tree has been changed
nameChanged	Emitted when the name of the node is changed
removedChildren	Emitted when one or more nodes has been removed from a node within the tree
visibilityChanged	Emitted when check state of a node within the tree has been changed
willAddChildren	Emitted when one or more nodes will be added to a node within the tree
willRemoveChildren	Emitted when one or more nodes will be removed from a node within the tree

Attributes

NodeGroup
NodeLayer

class qgis.core.QgsLayerTreeNode

Bases: QObject

__init__(t: QgsLayerTreeNode.NodeType, checked: bool = True)

Constructor

Parameters:

• t (QgsLayerTreeNode.NodeType)

• checked (bool = True)

__init__(other: QgsLayerTreeNode)

Parameters:

other (QgsLayerTreeNode)

NodeGroup = 0

NodeLayer = 1

class NodeType

Bases: int

signal addedChildren(node: QgsLayerTreeNode, indexFrom: int, indexTo: int)

Emitted when one or more nodes have been added to a node within the tree

Parameters:

• node (QgsLayerTreeNode)

• indexFrom (int)

• indexTo (int)

checkedLayers(self) → List[QgsMapLayer]

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

Return type:

List[QgsMapLayer]

children(self) → List[QgsLayerTreeNode]

Gets list of children of the node. Children are owned by the parent

Return type:

List[QgsLayerTreeNode]

abstract clone(self) → QgsLayerTreeNode | None

Create a copy of the node. Returns new instance

Return type:

Optional[QgsLayerTreeNode]

customProperties(self) → List[str]

Returns list of keys stored in custom properties

Return type:

List[str]

customProperty(self, key: str | None, defaultValue: Any = None) → Any

Read a custom property from layer. Properties are stored in a map and saved in project file.

Parameters:

• key (Optional[str])

• defaultValue (Any = None)

Return type:

Any

signal customPropertyChanged(node: QgsLayerTreeNode, key: str)

Emitted when a custom property of a node within the tree has been changed or removed

Parameters:

• node (QgsLayerTreeNode)

• key (str)

depth(self) → int

Returns the depth of this node, i.e. the number of its ancestors

Added in version 3.14.

Return type:

int

abstract dump(self) → str

Returns string with layer tree structure. For debug purposes only

Return type:

str

signal expandedChanged(node: QgsLayerTreeNode, expanded: bool)

Emitted when the collapsed/expanded state of a node within the tree has been changed

Parameters:

• node (QgsLayerTreeNode)

• expanded (bool)

insertChildrenPrivate(self, index: int, nodes: Iterable[QgsLayerTreeNode])

Low-level insertion of children to the node. The children must not have any parent yet!

Parameters:

• index (int)

• nodes (Iterable[QgsLayerTreeNode])

isExpanded(self) → bool

Returns whether the node should be shown as expanded or collapsed in GUI

Return type:

bool

isItemVisibilityCheckedRecursive(self) → bool

Returns whether this node is checked and all its children.

Return type:

bool

isItemVisibilityUncheckedRecursive(self) → bool

Returns whether this node is unchecked and all its children.

Return type:

bool

isVisible(self) → bool

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

Return type:

bool

itemVisibilityChecked(self) → bool

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

Return type:

bool

abstract name(self) → str

Returns name of the node

Return type:

str

signal nameChanged(node: QgsLayerTreeNode, name: str)

Emitted when the name of the node is changed

Parameters:

• node (QgsLayerTreeNode)

• name (str)

nodeType(self) → QgsLayerTreeNode.NodeType

Find out about type of the node. It is usually shorter to use convenience functions from QgsLayerTree namespace for that

Return type:

QgsLayerTreeNode.NodeType

parent(self) → QgsLayerTreeNode | None

Gets pointer to the parent. If parent is None, the node is a root node

Return type:

Optional[QgsLayerTreeNode]

readCommonXml(self, element: QDomElement)

Read common XML elements.

Parameters:

element (QDomElement)

static readXml(element: QDomElement, context: QgsReadWriteContext) → QgsLayerTreeNode | None

Read layer tree from XML. Returns new instance. Does not resolve textual references to layers. Call resolveReferences() afterwards to do it.

Parameters:

• element (QDomElement)

• context (QgsReadWriteContext)

Return type:

Optional[QgsLayerTreeNode]

static readXml(element: QDomElement, project: QgsProject | None) → QgsLayerTreeNode | None

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

Parameters:

• element (QDomElement)

• project (Optional[QgsProject])

Return type:

Optional[QgsLayerTreeNode]

removeChildrenPrivate(self, from_: int, count: int, destroy: bool = True)

Low-level removal of children from the node.

Parameters:

• from (int)

• count (int)

• destroy (bool = True)

removeCustomProperty(self, key: str | None)

Remove a custom property from layer. Properties are stored in a map and saved in project file.

Parameters:

key (Optional[str])

signal removedChildren(node: QgsLayerTreeNode, indexFrom: int, indexTo: int)

Emitted when one or more nodes has been removed from a node within the tree

Parameters:

• node (QgsLayerTreeNode)

• indexFrom (int)

• indexTo (int)

abstract resolveReferences(self, project: QgsProject | None, looseMatching: bool = False)

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.

Parameters:

• project (Optional[QgsProject])

• looseMatching (bool = False)

setCustomProperty(self, key: str | None, value: Any)

Sets a custom property for the node. Properties are stored in a map and saved in project file.

Parameters:

• key (Optional[str])

• value (Any)

setExpanded(self, expanded: bool)

Sets whether the node should be shown as expanded or collapsed in GUI

Parameters:

expanded (bool)

setItemVisibilityChecked(self, checked: bool)

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

See also

QgsLayerTreeView.setLayerVisible()

Parameters:

checked (bool)

setItemVisibilityCheckedParentRecursive(self, checked: bool)

Check or uncheck a node and all its parents

Parameters:

checked (bool)

virtual setItemVisibilityCheckedRecursive(self, checked: bool)

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

Parameters:

checked (bool)

abstract setName(self, name: str | None)

Set name of the node. Emits nameChanged signal.

Parameters:

name (Optional[str])

takeChild(self, node: QgsLayerTreeNode | None) → bool

Remove a child from a node

Parameters:

node (Optional[QgsLayerTreeNode])

Return type:

bool

signal visibilityChanged(node: QgsLayerTreeNode)

Emitted when check state of a node within the tree has been changed

Parameters:

node (QgsLayerTreeNode)

signal willAddChildren(node: QgsLayerTreeNode, indexFrom: int, indexTo: int)

Emitted when one or more nodes will be added to a node within the tree

Parameters:

• node (QgsLayerTreeNode)

• indexFrom (int)

• indexTo (int)

signal willRemoveChildren(node: QgsLayerTreeNode, indexFrom: int, indexTo: int)

Emitted when one or more nodes will be removed from a node within the tree

Parameters:

• node (QgsLayerTreeNode)

• indexFrom (int)

• indexTo (int)

writeCommonXml(self, element: QDomElement)

Write common XML elements.

Parameters:

element (QDomElement)

abstract writeXml(self, parentElement: QDomElement, context: QgsReadWriteContext)

Write layer tree to XML

Parameters:

• parentElement (QDomElement)

• context (QgsReadWriteContext)