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

#include <qgslayertreenode.h>

Inheritance diagram for QgsLayerTreeNode:

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< QgsMapLayer *>	checkedLayers () const
	Returns a list of any checked layers which belong to this node or its children. More...

QList< QgsLayerTreeNode * >	children ()
	Get list of children of the node. Children are owned by the parent. More...

QList< QgsLayerTreeNode * >	children () const
	Get list of children of the node. Children are owned by the parent. More...

virtual QgsLayerTreeNode *	clone () const =0
	Create a copy of the node. Returns new instance. More...

QStringList	customProperties () const
	Return 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...

virtual QString	dump () const =0
	Return string with layer tree structure. For debug purposes only. More...

bool	isExpanded () const
	Return whether the node should be shown as expanded or collapsed in GUI. More...

bool	isItemVisibilityCheckedRecursive () const
	Return whether this node is checked and all its children. More...

bool	isItemVisibilityUncheckedRecursive () const
	Return 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
	Return 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...

QgsLayerTreeNode *	parent ()
	Get pointer to the parent. If parent is a null pointer, 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)
	Set a custom property for the node. Properties are stored in a map and saved in project file. More...

void	setExpanded (bool expanded)
	Set 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 QgsLayerTreeNode *	readXml (QDomElement &element, const QgsReadWriteContext &context)
	Read layer tree from XML. More...

static QgsLayerTreeNode *	readXml (QDomElement &element, const QgsProject *project)
	Read layer tree from XML. More...

Protected Member Functions
	QgsLayerTreeNode (NodeType t, bool checked=true)
	Constructor. More...

	QgsLayerTreeNode (const QgsLayerTreeNode &other)

void	insertChildrenPrivate (int index, QList< QgsLayerTreeNode *> nodes)
	Low-level insertion of children to the node. The children must not have any parent yet! 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...

QgsLayerTreeNode *	mParent = nullptr
	pointer to the parent node - null 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:

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 QgsLayerTree, QgsLayerTreeLayer, QgsLayerTreeGroup

Since: QGIS 2.4

Definition at line 72 of file qgslayertreenode.h.

Member Enumeration Documentation

◆ NodeType

enum QgsLayerTreeNode::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 97 of file qgslayertreenode.h.

Constructor & Destructor Documentation

◆ ~QgsLayerTreeNode()

QgsLayerTreeNode::~QgsLayerTreeNode ( )

override

Definition at line 45 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

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

Since: QGIS 3.0

Definition at line 146 of file qgslayertreenode.cpp.

◆ children() [1/2]

QList<QgsLayerTreeNode *> QgsLayerTreeNode::children ( )

inline

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

Definition at line 110 of file qgslayertreenode.h.

◆ children() [2/2]

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

inline

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

Definition at line 112 of file qgslayertreenode.h.

◆ clone()

virtual QgsLayerTreeNode* QgsLayerTreeNode::clone ( ) const

pure virtual

Create a copy of the node. Returns new instance.

Implemented in QgsLayerTree, QgsLayerTreeGroup, and QgsLayerTreeLayer.

◆ customProperties()

QStringList QgsLayerTreeNode::customProperties ( ) const

Return list of keys stored in custom properties.

Definition at line 180 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 169 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.

◆ dump()

virtual QString QgsLayerTreeNode::dump ( ) const

pure virtual

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

Implemented in QgsLayerTreeGroup, and QgsLayerTreeLayer.

◆ 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,
		QList< QgsLayerTreeNode *>	nodes
	)

protected

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

Definition at line 196 of file qgslayertreenode.cpp.

◆ isExpanded()

bool QgsLayerTreeNode::isExpanded ( ) const

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

Definition at line 102 of file qgslayertreenode.cpp.

◆ isItemVisibilityCheckedRecursive()

bool QgsLayerTreeNode::isItemVisibilityCheckedRecursive ( ) const

Return whether this node is checked and all its children.

Since: QGIS 3.0

Definition at line 107 of file qgslayertreenode.cpp.

◆ isItemVisibilityUncheckedRecursive()

bool QgsLayerTreeNode::isItemVisibilityUncheckedRecursive ( ) const

Return whether this node is unchecked and all its children.

Since: QGIS 3.0

Definition at line 120 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)

Since: QGIS 3.0

Definition at line 96 of file qgslayertreenode.cpp.

◆ itemVisibilityChecked()

bool QgsLayerTreeNode::itemVisibilityChecked ( ) const

inline

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

Since: QGIS 3.0

Definition at line 169 of file qgslayertreenode.h.

◆ name()

virtual QString QgsLayerTreeNode::name ( ) const

pure virtual

Return name of the node.

Since: QGIS 3.0

Implemented in QgsLayerTreeLayer, and QgsLayerTreeGroup.

◆ nameChanged

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

signal

Emitted when the name of the node is changed.

Since: QGIS 3.0

◆ 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 106 of file qgslayertreenode.h.

◆ parent()

QgsLayerTreeNode* QgsLayerTreeNode::parent ( )

inline

Get pointer to the parent. If parent is a null pointer, the node is a root node.

Definition at line 108 of file qgslayertreenode.h.

◆ readCommonXml()

void QgsLayerTreeNode::readCommonXml ( QDomElement & element )

protected

Read common XML elements.

Definition at line 185 of file qgslayertreenode.cpp.

◆ readXml() [1/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 50 of file qgslayertreenode.cpp.

◆ readXml() [2/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).

Since: QGIS 3.0

Definition at line 61 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 230 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 174 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 customisation from different projects where layers will have different layer IDs.

Since: QGIS 3.0

Implemented in QgsLayerTreeGroup, and QgsLayerTreeLayer.

◆ setCustomProperty()

void QgsLayerTreeNode::setCustomProperty	(	const QString &	key,
		const QVariant &	value
	)

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

Definition at line 163 of file qgslayertreenode.cpp.

◆ setExpanded()

void QgsLayerTreeNode::setExpanded ( bool expanded )

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

Definition at line 153 of file qgslayertreenode.cpp.

◆ setItemVisibilityChecked()

void QgsLayerTreeNode::setItemVisibilityChecked ( bool checked )

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

Since: QGIS 3.0

Definition at line 76 of file qgslayertreenode.cpp.

◆ setItemVisibilityCheckedParentRecursive()

void QgsLayerTreeNode::setItemVisibilityCheckedParentRecursive ( bool checked )

Check or uncheck a node and all its parents.

Since: QGIS 3.0

Definition at line 89 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)

Since: QGIS 3.0

Reimplemented in QgsLayerTreeGroup.

Definition at line 84 of file qgslayertreenode.cpp.

◆ setName()

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

pure virtual

Set name of the node.

Emits nameChanged signal.

Since: QGIS 3.0

Implemented in QgsLayerTreeLayer, and QgsLayerTreeGroup.

◆ takeChild()

bool QgsLayerTreeNode::takeChild ( QgsLayerTreeNode * node )

Remove a child from a node.

Definition at line 249 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 190 of file qgslayertreenode.cpp.

◆ writeXml()

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

pure virtual

Write layer tree to XML.

Implemented in QgsLayerTree, QgsLayerTreeGroup, and QgsLayerTreeLayer.

Member Data Documentation

◆ mChecked

bool QgsLayerTreeNode::mChecked

protected

Definition at line 268 of file qgslayertreenode.h.

◆ mChildren

QList<QgsLayerTreeNode *> QgsLayerTreeNode::mChildren

protected

list of children - node is responsible for their deletion

Definition at line 272 of file qgslayertreenode.h.

◆ mExpanded

bool QgsLayerTreeNode::mExpanded

protected

whether the node should be shown in GUI as expanded

Definition at line 274 of file qgslayertreenode.h.

◆ mNodeType

NodeType QgsLayerTreeNode::mNodeType

protected

type of the node - determines which subclass is used

Definition at line 267 of file qgslayertreenode.h.

◆ mParent

QgsLayerTreeNode* QgsLayerTreeNode::mParent = nullptr

protected

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

Definition at line 270 of file qgslayertreenode.h.

◆ mProperties

QgsObjectCustomProperties QgsLayerTreeNode::mProperties

protected

custom properties attached to the node

Definition at line 276 of file qgslayertreenode.h.

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

/tmp/buildd/qgis-3.0.2+14stretch/src/core/layertree/qgslayertreenode.h
/tmp/buildd/qgis-3.0.2+14stretch/src/core/layertree/qgslayertreenode.cpp

Public Types

Signals

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ NodeType

Constructor & Destructor Documentation

◆ ~QgsLayerTreeNode()

◆ QgsLayerTreeNode() [1/2]

◆ QgsLayerTreeNode() [2/2]

Member Function Documentation

◆ addedChildren

◆ checkedLayers()

◆ children() [1/2]

◆ children() [2/2]

◆ clone()

◆ customProperties()

◆ customProperty()

◆ customPropertyChanged

◆ dump()

◆ expandedChanged

◆ insertChildrenPrivate()

◆ isExpanded()

◆ isItemVisibilityCheckedRecursive()

◆ isItemVisibilityUncheckedRecursive()

◆ isVisible()

◆ itemVisibilityChecked()

◆ name()

◆ nameChanged

◆ nodeType()

◆ parent()

◆ readCommonXml()

◆ readXml() [1/2]

◆ readXml() [2/2]

◆ removeChildrenPrivate()

◆ removeCustomProperty()

◆ removedChildren

◆ resolveReferences()

◆ setCustomProperty()

◆ setExpanded()

◆ setItemVisibilityChecked()

◆ setItemVisibilityCheckedParentRecursive()

◆ setItemVisibilityCheckedRecursive()

◆ setName()

◆ takeChild()

◆ visibilityChanged

◆ willAddChildren

◆ willRemoveChildren

◆ writeCommonXml()

◆ writeXml()

Member Data Documentation

◆ mChecked

◆ mChildren

◆ mExpanded

◆ mNodeType

◆ mParent

◆ mProperties