Class: QgsLayerTreeNode

class qgis.core.QgsLayerTreeNode(t: QgsLayerTreeNode.NodeType, checked: bool = True)

Bases: PyQt5.QtCore.QObject

Constructor

QgsLayerTreeNode(other: QgsLayerTreeNode)

This class is a 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

also()

Methods

checkedLayers

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

childEvent

children

Gets list of children of the node.

clone

Create a copy of the node.

connectNotify

customEvent

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.

disconnectNotify

dump

Returns string with layer tree structure.

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.

isSignalConnected

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)

name

Returns name of the node

nodeType

Find out about type of the node.

parent

Gets pointer to the parent.

readCommonXml

Read common XML elements.

readXml

Read layer tree from XML.

receivers

removeChildrenPrivate

Low-level removal of children from the node.

removeCustomProperty

Remove a custom property from layer.

resolveReferences

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

sender

senderSignalIndex

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

setItemVisibilityCheckedRecursive

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

setName

Set name of the node.

takeChild

Remove a child from a node

timerEvent

writeCommonXml

Write common XML elements.

writeXml

Write layer tree to XML

Signals

addedChildren

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

customPropertyChanged

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

expandedChanged

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

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 [signal]

visibilityChanged

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

willAddChildren

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

willRemoveChildren

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

Attributes

NodeGroup

NodeLayer

NodeGroup = 0
NodeLayer = 1
class NodeType

Bases: int

addedChildren

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

Parameters
checkedLayers(self)List[QgsMapLayer]

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

New in version 3.0.

Return type

List[QgsMapLayer]

childEvent(self, QChildEvent)
children(self)List[QgsLayerTreeNode]

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

Return type

List[QgsLayerTreeNode]

clone(self)QgsLayerTreeNode

Create a copy of the node. Returns new instance

Return type

QgsLayerTreeNode

connectNotify(self, QMetaMethod)
customEvent(self, QEvent)
customProperties(self)List[str]

Returns list of keys stored in custom properties

Return type

List[str]

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

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

Parameters
  • key (str) –

  • defaultValue (Any = None) –

Return type

Any

customPropertyChanged

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

Parameters
depth(self)int

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

New in version 3.14.

Return type

int

disconnectNotify(self, QMetaMethod)
dump(self)str

Returns string with layer tree structure. For debug purposes only

Return type

str

expandedChanged

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

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

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

Parameters
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.

New in version 3.0.

Return type

bool

isItemVisibilityUncheckedRecursive(self)bool

Returns whether this node is unchecked and all its children.

New in version 3.0.

Return type

bool

isSignalConnected(self, QMetaMethod)bool
isVisible(self)bool

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

New in version 3.0.

Return type

bool

itemVisibilityChecked(self)bool

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

New in version 3.0.

Return type

bool

name(self)str

Returns name of the node

New in version 3.0.

Return type

str

nameChanged

Emitted when the name of the node is changed

New in version 3.0: [signal]

Parameters
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

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

Return type

QgsLayerTreeNode

readCommonXml(self, element: QDomElement)

Read common XML elements.

Parameters

element (QDomElement) –

readXml(element: QDomElement, context: QgsReadWriteContext)QgsLayerTreeNode

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

readXml(element: QDomElement, project: QgsProject) -> QgsLayerTreeNode Read layer tree from XML. Returns new instance. Also resolves textual references to layers from the project (calls resolveReferences() internally).

New in version 3.0.

Parameters
Return type

QgsLayerTreeNode

receivers(self, PYQT_SIGNAL)int
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)

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

Parameters

key (str) –

removedChildren

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

Parameters
resolveReferences(self, project: QgsProject, 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.

New in version 3.0.

Parameters
  • project (QgsProject) –

  • looseMatching (bool = False) –

sender(self)QObject
senderSignalIndex(self)int
setCustomProperty(self, key: str, value: Any)

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

Parameters
  • key (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()

New in version 3.0.

Parameters

checked (bool) –

setItemVisibilityCheckedParentRecursive(self, checked: bool)

Check or uncheck a node and all its parents

New in version 3.0.

Parameters

checked (bool) –

setItemVisibilityCheckedRecursive(self, checked: bool)

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

New in version 3.0.

Parameters

checked (bool) –

setName(self, name: str)

Set name of the node. Emits nameChanged signal.

New in version 3.0.

Parameters

name (str) –

takeChild(self, node: QgsLayerTreeNode)bool

Remove a child from a node

Parameters

node (QgsLayerTreeNode) –

Return type

bool

timerEvent(self, QTimerEvent)
visibilityChanged

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

Parameters

node (QgsLayerTreeNode) –

willAddChildren

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

Parameters
willRemoveChildren

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

Parameters
writeCommonXml(self, element: QDomElement)

Write common XML elements.

Parameters

element (QDomElement) –

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

Write layer tree to XML

Parameters