QGIS API Documentation  3.37.0-Master (a5b4d9743e8)
Public Types | Signals | Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
QgsLayerTreeNode Class Referenceabstract

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

#include <qgslayertreenode.h>

Inheritance diagram for QgsLayerTreeNode:
Inheritance graph
[legend]

Public Types

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

Signals

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

Public Member Functions

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

Static Public Member Functions

static QgsLayerTreeNodereadXml (QDomElement &element, const QgsProject *project)
 Read layer tree from XML. More...
 
static QgsLayerTreeNodereadXml (QDomElement &element, const QgsReadWriteContext &context)
 Read layer tree from XML. More...
 

Protected Member Functions

 QgsLayerTreeNode (const QgsLayerTreeNode &other)
 
 QgsLayerTreeNode (NodeType t, bool checked=true)
 Constructor. More...
 
void insertChildrenPrivate (int index, const QList< QgsLayerTreeNode * > &nodes)
 Low-level insertion of children to the node. The children must not have any parent yet! More...
 
virtual void makeOrphan ()
 Sets parent to nullptr and disconnects all external and forwarded signals. More...
 
void readCommonXml (QDomElement &element)
 Read common XML elements. More...
 
void removeChildrenPrivate (int from, int count, bool destroy=true)
 Low-level removal of children from the node. More...
 
void writeCommonXml (QDomElement &element)
 Write common XML elements. More...
 

Protected Attributes

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

Detailed Description

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

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

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:

See also
QgsLayerTree
QgsLayerTreeLayer
QgsLayerTreeGroup

Definition at line 76 of file qgslayertreenode.h.

Member Enumeration Documentation

◆ NodeType

Enumeration of possible tree node types.

Enumerator
NodeGroup 

Container of other groups and layers.

NodeLayer 

Leaf node pointing to a layer.

Definition at line 101 of file qgslayertreenode.h.

Constructor & Destructor Documentation

◆ ~QgsLayerTreeNode()

QgsLayerTreeNode::~QgsLayerTreeNode ( )
override

Definition at line 46 of file qgslayertreenode.cpp.

◆ QgsLayerTreeNode() [1/2]

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

Constructor.

Definition at line 25 of file qgslayertreenode.cpp.

◆ QgsLayerTreeNode() [2/2]

QgsLayerTreeNode::QgsLayerTreeNode ( const QgsLayerTreeNode other)
protected

Definition at line 32 of file qgslayertreenode.cpp.

Member Function Documentation

◆ abandonChildren()

QList< QgsLayerTreeNode * > QgsLayerTreeNode::abandonChildren ( )

Removes the children, disconnect all the forwarded and external signals and sets their parent to nullptr.

Returns
the removed children
Since
QGIS 3.16

Definition at line 51 of file qgslayertreenode.cpp.

◆ addedChildren

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

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

◆ checkedLayers()

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

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

Definition at line 179 of file qgslayertreenode.cpp.

◆ children() [1/2]

QList<QgsLayerTreeNode *> QgsLayerTreeNode::children ( )
inline

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

Definition at line 122 of file qgslayertreenode.h.

◆ children() [2/2]

QList<QgsLayerTreeNode *> QgsLayerTreeNode::children ( ) const
inline

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

Definition at line 124 of file qgslayertreenode.h.

◆ clone()

virtual QgsLayerTreeNode* QgsLayerTreeNode::clone ( ) const
pure virtual

Create a copy of the node. Returns new instance.

Implemented in QgsLayerTreeLayer, QgsLayerTreeGroup, and QgsLayerTree.

◆ customProperties()

QStringList QgsLayerTreeNode::customProperties ( ) const

Returns list of keys stored in custom properties.

Definition at line 231 of file qgslayertreenode.cpp.

◆ customProperty()

QVariant QgsLayerTreeNode::customProperty ( const QString &  key,
const QVariant &  defaultValue = QVariant() 
) const

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

Definition at line 217 of file qgslayertreenode.cpp.

◆ customPropertyChanged

void QgsLayerTreeNode::customPropertyChanged ( QgsLayerTreeNode node,
const QString &  key 
)
signal

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

◆ depth()

int QgsLayerTreeNode::depth ( ) const

Returns the depth of this node, i.e.

the number of its ancestors

Since
QGIS 3.14

Definition at line 186 of file qgslayertreenode.cpp.

◆ dump()

virtual QString QgsLayerTreeNode::dump ( ) const
pure virtual

Returns string with layer tree structure. For debug purposes only.

Implemented in QgsLayerTreeLayer, and QgsLayerTreeGroup.

◆ expandedChanged

void QgsLayerTreeNode::expandedChanged ( QgsLayerTreeNode node,
bool  expanded 
)
signal

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

◆ insertChildrenPrivate()

void QgsLayerTreeNode::insertChildrenPrivate ( int  index,
const QList< QgsLayerTreeNode * > &  nodes 
)
protected

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

Definition at line 247 of file qgslayertreenode.cpp.

◆ isExpanded()

bool QgsLayerTreeNode::isExpanded ( ) const

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

Definition at line 121 of file qgslayertreenode.cpp.

◆ isItemVisibilityCheckedRecursive()

bool QgsLayerTreeNode::isItemVisibilityCheckedRecursive ( ) const

Returns whether this node is checked and all its children.

Definition at line 126 of file qgslayertreenode.cpp.

◆ isItemVisibilityUncheckedRecursive()

bool QgsLayerTreeNode::isItemVisibilityUncheckedRecursive ( ) const

Returns whether this node is unchecked and all its children.

Definition at line 140 of file qgslayertreenode.cpp.

◆ isVisible()

bool QgsLayerTreeNode::isVisible ( ) const

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

Definition at line 115 of file qgslayertreenode.cpp.

◆ itemVisibilityChecked()

bool QgsLayerTreeNode::itemVisibilityChecked ( ) const
inline

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

Definition at line 182 of file qgslayertreenode.h.

◆ makeOrphan()

void QgsLayerTreeNode::makeOrphan ( )
protectedvirtual

Sets parent to nullptr and disconnects all external and forwarded signals.

Reimplemented in QgsLayerTreeGroup.

Definition at line 62 of file qgslayertreenode.cpp.

◆ name()

virtual QString QgsLayerTreeNode::name ( ) const
pure virtual

Returns name of the node.

Implemented in QgsLayerTreeLayer, and QgsLayerTreeGroup.

◆ nameChanged

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

Emitted when the name of the node is changed.

◆ nodeType()

NodeType QgsLayerTreeNode::nodeType ( ) const
inline

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

Definition at line 118 of file qgslayertreenode.h.

◆ parent()

QgsLayerTreeNode* QgsLayerTreeNode::parent ( )
inline

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

Definition at line 120 of file qgslayertreenode.h.

◆ readCommonXml()

void QgsLayerTreeNode::readCommonXml ( QDomElement &  element)
protected

Read common XML elements.

Definition at line 236 of file qgslayertreenode.cpp.

◆ readXml() [1/2]

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

Read layer tree from XML.

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

Definition at line 79 of file qgslayertreenode.cpp.

◆ readXml() [2/2]

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

Read layer tree from XML.

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

Definition at line 68 of file qgslayertreenode.cpp.

◆ removeChildrenPrivate()

void QgsLayerTreeNode::removeChildrenPrivate ( int  from,
int  count,
bool  destroy = true 
)
protected

Low-level removal of children from the node.

Definition at line 292 of file qgslayertreenode.cpp.

◆ removeCustomProperty()

void QgsLayerTreeNode::removeCustomProperty ( const QString &  key)

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

Definition at line 222 of file qgslayertreenode.cpp.

◆ removedChildren

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

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

◆ resolveReferences()

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

Implemented in QgsLayerTreeLayer, and QgsLayerTreeGroup.

◆ setCustomProperty()

void QgsLayerTreeNode::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.

Definition at line 208 of file qgslayertreenode.cpp.

◆ setExpanded()

void QgsLayerTreeNode::setExpanded ( bool  expanded)

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

Definition at line 198 of file qgslayertreenode.cpp.

◆ setItemVisibilityChecked()

void QgsLayerTreeNode::setItemVisibilityChecked ( bool  checked)

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

See also
QgsLayerTreeView::setLayerVisible()

Definition at line 95 of file qgslayertreenode.cpp.

◆ setItemVisibilityCheckedParentRecursive()

void QgsLayerTreeNode::setItemVisibilityCheckedParentRecursive ( bool  checked)

Check or uncheck a node and all its parents.

Definition at line 108 of file qgslayertreenode.cpp.

◆ setItemVisibilityCheckedRecursive()

void QgsLayerTreeNode::setItemVisibilityCheckedRecursive ( bool  checked)
virtual

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

Reimplemented in QgsLayerTreeGroup.

Definition at line 103 of file qgslayertreenode.cpp.

◆ setName()

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

Set name of the node.

Emits nameChanged signal.

Implemented in QgsLayerTreeLayer, and QgsLayerTreeGroup.

◆ takeChild()

bool QgsLayerTreeNode::takeChild ( QgsLayerTreeNode node)

Remove a child from a node.

Definition at line 328 of file qgslayertreenode.cpp.

◆ visibilityChanged

void QgsLayerTreeNode::visibilityChanged ( QgsLayerTreeNode node)
signal

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

◆ willAddChildren

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

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

◆ willRemoveChildren

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

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

◆ writeCommonXml()

void QgsLayerTreeNode::writeCommonXml ( QDomElement &  element)
protected

Write common XML elements.

Definition at line 241 of file qgslayertreenode.cpp.

◆ writeXml()

virtual void QgsLayerTreeNode::writeXml ( QDomElement &  parentElement,
const QgsReadWriteContext context 
)
pure virtual

Write layer tree to XML.

Implemented in QgsLayerTreeLayer, QgsLayerTreeGroup, and QgsLayerTree.

Member Data Documentation

◆ mChecked

bool QgsLayerTreeNode::mChecked
protected

Definition at line 283 of file qgslayertreenode.h.

◆ mChildren

QList<QgsLayerTreeNode *> QgsLayerTreeNode::mChildren
protected

list of children - node is responsible for their deletion

Definition at line 287 of file qgslayertreenode.h.

◆ mExpanded

bool QgsLayerTreeNode::mExpanded
protected

whether the node should be shown in GUI as expanded

Definition at line 289 of file qgslayertreenode.h.

◆ mNodeType

NodeType QgsLayerTreeNode::mNodeType
protected

type of the node - determines which subclass is used

Definition at line 282 of file qgslayertreenode.h.

◆ mParent

QgsLayerTreeNode* QgsLayerTreeNode::mParent = nullptr
protected

pointer to the parent node - nullptr in case of root node

Definition at line 285 of file qgslayertreenode.h.

◆ mProperties

QgsObjectCustomProperties QgsLayerTreeNode::mProperties
protected

custom properties attached to the node

Definition at line 291 of file qgslayertreenode.h.


The documentation for this class was generated from the following files: