Namespace with helper functions for layer tree operations. More...

#include <qgslayertree.h>

Inheritance diagram for QgsLayerTree:

[legend]

Signals
void	customLayerOrderChanged ()
	Emitted when the custom layer order has changed.

void	hasCustomLayerOrderChanged (bool hasCustomLayerOrder)
	Emitted when the hasCustomLayerOrder flag changes.

void	layerOrderChanged ()
	Emitted when the layer order has changed.

Signals inherited from QgsLayerTreeNode
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.

Public Member Functions
	QgsLayerTree ()
	Create a new empty layer tree.

void	clear ()
	Clear any information from this layer tree.

QgsLayerTree *	clone () const override
	Create a copy of the node. Returns new instance.

QList< QgsMapLayer * >	customLayerOrder () const
	The order in which layers will be rendered on the canvas.

bool	hasCustomLayerOrder () const
	Determines if the layer order should be derived from the layer tree or if a custom override order shall be used instead.

QList< QgsMapLayer * >	layerOrder () const
	The order in which layers will be rendered on the canvas.

void	readLayerOrderFromXml (const QDomElement &doc)
	Load the layer order from an XML element.

void	setCustomLayerOrder (const QList< QgsMapLayer * > &customLayerOrder)
	The order in which layers will be rendered on the canvas.

void	setCustomLayerOrder (const QStringList &customLayerOrder)
	The order in which layers will be rendered on the canvas.

void	setHasCustomLayerOrder (bool hasCustomLayerOrder)
	Determines if the layer order should be derived from the layer tree or if a custom override order shall be used instead.

void	writeXml (QDomElement &parentElement, const QgsReadWriteContext &context) override
	Write layer tree to XML.

Public Member Functions inherited from QgsLayerTreeGroup
	QgsLayerTreeGroup (const QgsLayerTreeGroup &other)

	QgsLayerTreeGroup (const QString &name=QString(), bool checked=true)
	Constructor.

void	addChildNode (QgsLayerTreeNode *node)
	Append an existing node.

QgsLayerTreeGroup *	addGroup (const QString &name)
	Append a new group node with given name.

QgsLayerTreeLayer *	addLayer (QgsMapLayer *layer)
	Append a new layer node for given map layer.

QgsLayerTreeGroup *	clone () const override
	Returns a clone of the group.

QgsGroupLayer *	convertToGroupLayer (const QgsGroupLayer::LayerOptions &options)
	Converts the group to a QgsGroupLayer.

QString	dump () const override
	Returns text representation of the tree.

QgsLayerTreeGroup *	findGroup (const QString &name)
	Find group node with specified name.

QList< QgsLayerTreeGroup * >	findGroups (bool recursive=false) const
	Find group layer nodes.

QgsLayerTreeLayer *	findLayer (const QString &layerId) const
	Find layer node representing the map layer specified by its ID.

QgsLayerTreeLayer *	findLayer (QgsMapLayer *layer) const
	Find layer node representing the map layer.

QStringList	findLayerIds () const
	Find layer IDs used in all layer nodes.

QList< QgsLayerTreeLayer * >	findLayers () const
	Find all layer nodes.

QgsGroupLayer *	groupLayer ()
	Returns a reference to the associated group layer, if the layer tree group will be treated as group layer during map rendering.

void	insertChildNode (int index, QgsLayerTreeNode *node)
	Insert existing node at specified position.

void	insertChildNodes (int index, const QList< QgsLayerTreeNode * > &nodes)
	Insert existing nodes at specified position.

QgsLayerTreeGroup *	insertGroup (int index, const QString &name)
	Insert a new group node with given name at specified position.

QgsLayerTreeLayer *	insertLayer (int index, QgsMapLayer *layer)
	Insert a new layer node for given map layer at specified position.

bool	isMutuallyExclusive () const
	Returns whether the group is mutually exclusive (only one child can be checked at a time)

QList< QgsMapLayer * >	layerOrderRespectingGroupLayers () const
	Returns an ordered list of map layers in the group, ignoring any layers which are child layers of QgsGroupLayers.

QString	name () const override
	Returns the group's name.

void	readChildrenFromXml (QDomElement &element, const QgsReadWriteContext &context)
	Read children from XML and append them to the group.

void	removeAllChildren ()
	Remove all child nodes.

void	removeChildNode (QgsLayerTreeNode *node)
	Remove a child node from this group.

void	removeChildren (int from, int count)
	Remove child nodes from index "from".

void	removeChildrenGroupWithoutLayers ()
	Remove all child group nodes without layers.

void	removeLayer (QgsMapLayer *layer)
	Remove map layer's node from this group.

void	reorderGroupLayers (const QList< QgsMapLayer * > &order)
	Reorders layers in the group to match the order specified by order.

void	resolveReferences (const QgsProject *project, bool looseMatching=false) override
	Calls resolveReferences() on child tree nodes.

void	setGroupLayer (QgsGroupLayer *layer)
	Sets the associated group layer, if the layer tree group will be treated as group layer during map rendering.

void	setIsMutuallyExclusive (bool enabled, int initialChildIndex=-1)
	Set whether the group is mutually exclusive (only one child can be checked at a time).

void	setItemVisibilityCheckedRecursive (bool checked) override
	Check or uncheck a node and all its children (taking into account exclusion rules)

void	setName (const QString &n) override
	Sets the group's name.

void	writeXml (QDomElement &parentElement, const QgsReadWriteContext &context) override
	Write group (tree) as XML element <layer-tree-group> and add it to the given parent element.

Public Member Functions inherited from QgsLayerTreeNode
	~QgsLayerTreeNode () override

QList< QgsLayerTreeNode * >	abandonChildren ()
	Removes the children, disconnect all the forwarded and external signals and sets their parent to `nullptr`.

QList< QgsMapLayer * >	checkedLayers () const
	Returns a list of any checked layers which belong to this node or its children.

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

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

QStringList	customProperties () const
	Returns list of keys stored in custom properties.

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.

int	depth () const
	Returns the depth of this node, i.e.

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

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

bool	isItemVisibilityUncheckedRecursive () const
	Returns whether this node is unchecked and all its children.

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

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

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

QgsLayerTreeNode *	parent ()
	Gets pointer to the parent. If parent is `nullptr`, 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	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.

bool	takeChild (QgsLayerTreeNode *node)
	Remove a child from a node.

Static Public Member Functions
static bool	isGroup (QgsLayerTreeNode *node)
	Check whether the node is a valid group node.

static bool	isLayer (const QgsLayerTreeNode *node)
	Check whether the node is a valid layer node.

static QgsLayerTree *	readXml (QDomElement &element, const QgsReadWriteContext &context)
	Load the layer tree from an XML element.

static QgsLayerTreeGroup *	toGroup (QgsLayerTreeNode *node)
	Cast node to a group.

static const QgsLayerTreeLayer *	toLayer (const QgsLayerTreeNode *node)
	Cast node to a layer.

static QgsLayerTreeLayer *	toLayer (QgsLayerTreeNode *node)
	Cast node to a layer.

Static Public Member Functions inherited from QgsLayerTreeGroup
static QgsLayerTreeGroup *	readXml (QDomElement &element, const QgsProject *project, const QgsReadWriteContext &context)
	Read group (tree) from XML element <layer-tree-group> and return the newly created group (or `nullptr` on error).

static QgsLayerTreeGroup *	readXml (QDomElement &element, const QgsReadWriteContext &context)
	Read group (tree) from XML element <layer-tree-group> and return the newly created group (or `nullptr` on error).

Static Public Member Functions inherited from QgsLayerTreeNode
static QgsLayerTreeNode *	readXml (QDomElement &element, const QgsProject *project)
	Read layer tree from XML.

static QgsLayerTreeNode *	readXml (QDomElement &element, const QgsReadWriteContext &context)
	Read layer tree from XML.

Additional Inherited Members
Public Types inherited from QgsLayerTreeNode
enum	NodeType { NodeGroup , NodeLayer }
	Enumeration of possible tree node types. More...

Protected Slots inherited from QgsLayerTreeGroup
void	nodeVisibilityChanged (QgsLayerTreeNode *node)

Protected Member Functions inherited from QgsLayerTreeGroup
virtual void	makeOrphan () override
	Sets parent to `nullptr` and disconnects all external and forwarded signals.

void	updateChildVisibilityMutuallyExclusive ()
	Set check state of children - if mutually exclusive.

Protected Member Functions inherited from QgsLayerTreeNode
	QgsLayerTreeNode (const QgsLayerTreeNode &other)

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

void	insertChildrenPrivate (int index, const 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 Attributes inherited from QgsLayerTreeGroup
bool	mChangingChildVisibility = false

bool	mMutuallyExclusive = false
	Whether the group is mutually exclusive (i.e. only one child can be checked at a time)

int	mMutuallyExclusiveChildIndex = -1
	Keeps track which child has been most recently selected (so if the whole group is unchecked and checked again, we know which child to check)

QString	mName

Protected Attributes inherited from QgsLayerTreeNode
bool	mChecked

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 = nullptr
	pointer to the parent node - `nullptr` in case of root node

QgsObjectCustomProperties	mProperties
	custom properties attached to the node

Detailed Description

Namespace with helper functions for layer tree operations.

Only generally useful routines should be here. Miscellaneous utility functions for work with the layer tree are in QgsLayerTreeUtils class.

Definition at line 31 of file qgslayertree.h.

Constructor & Destructor Documentation

◆ QgsLayerTree()

QgsLayerTree::QgsLayerTree ( )

Create a new empty layer tree.

Definition at line 21 of file qgslayertree.cpp.

Member Function Documentation

◆ clear()

void QgsLayerTree::clear ( )

Clear any information from this layer tree.

Definition at line 154 of file qgslayertree.cpp.

◆ clone()

QgsLayerTree * QgsLayerTree::clone ( ) const

overridevirtual

Create a copy of the node. Returns new instance.

Implements QgsLayerTreeNode.

Definition at line 149 of file qgslayertree.cpp.

◆ customLayerOrder()

QList< QgsMapLayer * > QgsLayerTree::customLayerOrder ( ) const

The order in which layers will be rendered on the canvas.

Will only be used if the property hasCustomLayerOrder is true. If you need the current layer order that is active, prefer using layerOrder().

See also: setCustomLayerOrder; layerOrder; hasCustomLayerOrder

Definition at line 40 of file qgslayertree.cpp.

◆ customLayerOrderChanged

void QgsLayerTree::customLayerOrderChanged ( )

signal

Emitted when the custom layer order has changed.

◆ hasCustomLayerOrder()

bool QgsLayerTree::hasCustomLayerOrder ( ) const

Determines if the layer order should be derived from the layer tree or if a custom override order shall be used instead.

See also: customLayerOrder

Definition at line 92 of file qgslayertree.cpp.

◆ hasCustomLayerOrderChanged

void QgsLayerTree::hasCustomLayerOrderChanged ( bool hasCustomLayerOrder )

signal

Emitted when the hasCustomLayerOrder flag changes.

See also: hasCustomLayerOrder

◆ isGroup()

static bool QgsLayerTree::isGroup ( QgsLayerTreeNode * node )

inlinestatic

Check whether the node is a valid group node.

Definition at line 41 of file qgslayertree.h.

◆ isLayer()

static bool QgsLayerTree::isLayer ( const QgsLayerTreeNode * node )

inlinestatic

Check whether the node is a valid layer node.

Definition at line 50 of file qgslayertree.h.

◆ layerOrder()

QList< QgsMapLayer * > QgsLayerTree::layerOrder ( ) const

The order in which layers will be rendered on the canvas.

Depending on hasCustomLayerOrder, this will return either the override customLayerOrder or the layer order derived from the tree. This property is read only.

See also: customLayerOrder

Definition at line 80 of file qgslayertree.cpp.

◆ layerOrderChanged

void QgsLayerTree::layerOrderChanged ( )

signal

Emitted when the layer order has changed.

◆ readLayerOrderFromXml()

void QgsLayerTree::readLayerOrderFromXml ( const QDomElement & doc )

Load the layer order from an XML element.

Make sure that this is only called after the layers are loaded.

Definition at line 245 of file qgslayertree.cpp.

◆ readXml()

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

static

Load the layer tree from an XML element.

It is not required that layers are loaded at this point. resolveReferences() needs to be called after loading the layers and before using the tree.

Definition at line 108 of file qgslayertree.cpp.

◆ setCustomLayerOrder() [1/2]

void QgsLayerTree::setCustomLayerOrder ( const QList< QgsMapLayer * > & customLayerOrder )

The order in which layers will be rendered on the canvas.

Will only be used if the property hasCustomLayerOrder is true. If you need the current layer order that is active, prefer using layerOrder().

See also: customLayerOrder; layerOrder; hasCustomLayerOrder

Definition at line 45 of file qgslayertree.cpp.

◆ setCustomLayerOrder() [2/2]

void QgsLayerTree::setCustomLayerOrder ( const QStringList & customLayerOrder )

The order in which layers will be rendered on the canvas.

Will only be used if the property hasCustomLayerOrder is true. If you need the current layer order that is active, prefer using layerOrder().

See also: customLayerOrder; layerOrder; hasCustomLayerOrder

Definition at line 59 of file qgslayertree.cpp.

◆ setHasCustomLayerOrder()

void QgsLayerTree::setHasCustomLayerOrder ( bool hasCustomLayerOrder )

Determines if the layer order should be derived from the layer tree or if a custom override order shall be used instead.

See also: setCustomLayerOrder

Definition at line 97 of file qgslayertree.cpp.

◆ toGroup()

static QgsLayerTreeGroup * QgsLayerTree::toGroup ( QgsLayerTreeNode * node )

inlinestatic

Cast node to a group.

Note: Not available in Python bindings, because cast is automatic.

Definition at line 60 of file qgslayertree.h.

◆ toLayer() [1/2]

static const QgsLayerTreeLayer * QgsLayerTree::toLayer ( const QgsLayerTreeNode * node )

inlinestatic

Cast node to a layer.

Note: Not available in Python bindings, because cast is automatic.

Definition at line 80 of file qgslayertree.h.

◆ toLayer() [2/2]

static QgsLayerTreeLayer * QgsLayerTree::toLayer ( QgsLayerTreeNode * node )

inlinestatic

Cast node to a layer.

Note: Not available in Python bindings, because cast is automatic.

Definition at line 70 of file qgslayertree.h.

◆ writeXml()

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

overridevirtual

Write layer tree to XML.

Implements QgsLayerTreeNode.

Definition at line 119 of file qgslayertree.cpp.

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

/build/qgis-3.41.0+git20241214+cea29feecf2+99sid/src/core/layertree/qgslayertree.h
/build/qgis-3.41.0+git20241214+cea29feecf2+99sid/src/core/layertree/qgslayertree.cpp

Signals

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ QgsLayerTree()

Member Function Documentation

◆ clear()

◆ clone()

◆ customLayerOrder()

◆ customLayerOrderChanged

◆ hasCustomLayerOrder()

◆ hasCustomLayerOrderChanged

◆ isGroup()

◆ isLayer()

◆ layerOrder()

◆ layerOrderChanged

◆ readLayerOrderFromXml()

◆ readXml()

◆ setCustomLayerOrder() [1/2]

◆ setCustomLayerOrder() [2/2]

◆ setHasCustomLayerOrder()

◆ toGroup()

◆ toLayer() [1/2]

◆ toLayer() [2/2]

◆ writeXml()