QGIS API Documentation 3.28.0-Firenze (ed3ad0430f)
Signals | Public Member Functions | Static Public Member Functions | List of all members
QgsLayerTree Class Reference

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

#include <qgslayertree.h>

Inheritance diagram for QgsLayerTree:
Inheritance graph
[legend]

Signals

void customLayerOrderChanged ()
 Emitted when the custom layer order has changed. More...
 
void hasCustomLayerOrderChanged (bool hasCustomLayerOrder)
 Emitted when the hasCustomLayerOrder flag changes. More...
 
void layerOrderChanged ()
 Emitted when the layer order has changed. More...
 
- 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. 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

 QgsLayerTree ()
 Create a new empty layer tree. More...
 
void clear ()
 Clear any information from this layer tree. More...
 
QgsLayerTreeclone () const override
 Create a copy of the node. Returns new instance. More...
 
QList< QgsMapLayer * > customLayerOrder () const
 The order in which layers will be rendered on the canvas. More...
 
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. More...
 
QList< QgsMapLayer * > layerOrder () const
 The order in which layers will be rendered on the canvas. More...
 
void readLayerOrderFromXml (const QDomElement &doc)
 Load the layer order from an XML element. More...
 
void setCustomLayerOrder (const QList< QgsMapLayer * > &customLayerOrder)
 The order in which layers will be rendered on the canvas. More...
 
void setCustomLayerOrder (const QStringList &customLayerOrder)
 The order in which layers will be rendered on the canvas. More...
 
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. More...
 
void writeXml (QDomElement &parentElement, const QgsReadWriteContext &context) override
 Write layer tree to XML. More...
 
- Public Member Functions inherited from QgsLayerTreeGroup
 QgsLayerTreeGroup (const QgsLayerTreeGroup &other)
 
 QgsLayerTreeGroup (const QString &name=QString(), bool checked=true)
 Constructor. More...
 
void addChildNode (QgsLayerTreeNode *node)
 Append an existing node. More...
 
QgsLayerTreeGroupaddGroup (const QString &name)
 Append a new group node with given name. More...
 
QgsLayerTreeLayeraddLayer (QgsMapLayer *layer)
 Append a new layer node for given map layer. More...
 
QgsLayerTreeGroupclone () const override
 Returns a clone of the group. More...
 
QgsGroupLayerconvertToGroupLayer (const QgsGroupLayer::LayerOptions &options)
 Converts the group to a QgsGroupLayer. More...
 
QString dump () const override
 Returns text representation of the tree. More...
 
QgsLayerTreeGroupfindGroup (const QString &name)
 Find group node with specified name. More...
 
QList< QgsLayerTreeGroup * > findGroups (bool recursive=false) const
 Find group layer nodes. More...
 
QgsLayerTreeLayerfindLayer (const QString &layerId) const
 Find layer node representing the map layer specified by its ID. More...
 
QgsLayerTreeLayerfindLayer (QgsMapLayer *layer) const
 Find layer node representing the map layer. More...
 
QStringList findLayerIds () const
 Find layer IDs used in all layer nodes. More...
 
QList< QgsLayerTreeLayer * > findLayers () const
 Find all layer nodes. More...
 
QgsGroupLayergroupLayer ()
 Returns a reference to the associated group layer, if the layer tree group will be treated as group layer during map rendering. More...
 
void insertChildNode (int index, QgsLayerTreeNode *node)
 Insert existing node at specified position. More...
 
void insertChildNodes (int index, const QList< QgsLayerTreeNode * > &nodes)
 Insert existing nodes at specified position. More...
 
QgsLayerTreeGroupinsertGroup (int index, const QString &name)
 Insert a new group node with given name at specified position. More...
 
QgsLayerTreeLayerinsertLayer (int index, QgsMapLayer *layer)
 Insert a new layer node for given map layer at specified position. More...
 
bool isMutuallyExclusive () const
 Returns whether the group is mutually exclusive (only one child can be checked at a time) More...
 
QList< QgsMapLayer * > layerOrderRespectingGroupLayers () const
 Returns an ordered list of map layers in the group, ignoring any layers which are child layers of QgsGroupLayers. More...
 
QString name () const override
 Returns the group's name. More...
 
void readChildrenFromXml (QDomElement &element, const QgsReadWriteContext &context)
 Read children from XML and append them to the group. More...
 
void removeAllChildren ()
 Remove all child nodes. More...
 
void removeChildNode (QgsLayerTreeNode *node)
 Remove a child node from this group. More...
 
void removeChildren (int from, int count)
 Remove child nodes from index "from". More...
 
void removeChildrenGroupWithoutLayers ()
 Remove all child group nodes without layers. More...
 
void removeLayer (QgsMapLayer *layer)
 Remove map layer's node from this group. More...
 
void resolveReferences (const QgsProject *project, bool looseMatching=false) override
 Calls resolveReferences() on child tree nodes. More...
 
void setGroupLayer (QgsGroupLayer *layer)
 Sets the associated group layer, if the layer tree group will be treated as group layer during map rendering. More...
 
void setIsMutuallyExclusive (bool enabled, int initialChildIndex=-1)
 Set whether the group is mutually exclusive (only one child can be checked at a time). More...
 
void setItemVisibilityCheckedRecursive (bool checked) override
 Check or uncheck a node and all its children (taking into account exclusion rules) More...
 
void setName (const QString &n) override
 Sets the group's name. More...
 
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. More...
 
- Public Member Functions inherited from QgsLayerTreeNode
 ~QgsLayerTreeNode () override
 
QList< QgsLayerTreeNode * > abandonChildren ()
 Removes the childrens, 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 bool isGroup (QgsLayerTreeNode *node)
 Check whether the node is a valid group node. More...
 
static bool isLayer (const QgsLayerTreeNode *node)
 Check whether the node is a valid layer node. More...
 
static QgsLayerTreereadXml (QDomElement &element, const QgsReadWriteContext &context)
 Load the layer tree from an XML element. More...
 
static QgsLayerTreeGrouptoGroup (QgsLayerTreeNode *node)
 Cast node to a group. More...
 
static const QgsLayerTreeLayertoLayer (const QgsLayerTreeNode *node)
 Cast node to a layer. More...
 
static QgsLayerTreeLayertoLayer (QgsLayerTreeNode *node)
 Cast node to a layer. More...
 
- Static Public Member Functions inherited from QgsLayerTreeGroup
static QgsLayerTreeGroupreadXml (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). More...
 
static QgsLayerTreeGroupreadXml (QDomElement &element, const QgsReadWriteContext &context)
 Read group (tree) from XML element <layer-tree-group> and return the newly created group (or nullptr on error). More...
 
- Static Public Member Functions inherited from QgsLayerTreeNode
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...
 

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. More...
 
void updateChildVisibilityMutuallyExclusive ()
 Set check state of children - if mutually exclusive. More...
 
- Protected Member Functions inherited from QgsLayerTreeNode
 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 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) More...
 
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) More...
 
QString mName
 
- Protected Attributes inherited from QgsLayerTreeNode
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

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.

Since
QGIS 3.0

Definition at line 32 of file qgslayertree.h.

Constructor & Destructor Documentation

◆ QgsLayerTree()

QgsLayerTree::QgsLayerTree ( )

Create a new empty layer tree.

Definition at line 20 of file qgslayertree.cpp.

Member Function Documentation

◆ clear()

void QgsLayerTree::clear ( )

Clear any information from this layer tree.

Since
QGIS 3.0

Definition at line 153 of file qgslayertree.cpp.

◆ clone()

QgsLayerTree * QgsLayerTree::clone ( ) const
overridevirtual

Create a copy of the node. Returns new instance.

Implements QgsLayerTreeNode.

Definition at line 148 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
Since
QGIS 3.0

Definition at line 39 of file qgslayertree.cpp.

◆ customLayerOrderChanged

void QgsLayerTree::customLayerOrderChanged ( )
signal

Emitted when the custom layer order has changed.

Since
QGIS 3.0

◆ 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
Since
QGIS 3.0

Definition at line 91 of file qgslayertree.cpp.

◆ hasCustomLayerOrderChanged

void QgsLayerTree::hasCustomLayerOrderChanged ( bool  hasCustomLayerOrder)
signal

Emitted when the hasCustomLayerOrder flag changes.

See also
hasCustomLayerOrder
Since
QGIS 3.0

◆ isGroup()

static bool QgsLayerTree::isGroup ( QgsLayerTreeNode node)
inlinestatic

Check whether the node is a valid group node.

Since
QGIS 2.4

Definition at line 43 of file qgslayertree.h.

◆ isLayer()

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

Check whether the node is a valid layer node.

Since
QGIS 2.4

Definition at line 53 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
Since
QGIS 3.0

Definition at line 79 of file qgslayertree.cpp.

◆ layerOrderChanged

void QgsLayerTree::layerOrderChanged ( )
signal

Emitted when the layer order has changed.

Since
QGIS 3.0

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

Since
QGIS 3.0

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

Since
QGIS 3.0

Definition at line 107 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
Since
QGIS 3.0

Definition at line 44 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
Since
QGIS 3.0

Definition at line 58 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
Since
QGIS 3.0

Definition at line 96 of file qgslayertree.cpp.

◆ toGroup()

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

Cast node to a group.

No type checking is done - use isGroup() to find out whether this operation is legal.

Note
Not available in Python bindings, because cast is automatic.
Since
QGIS 2.4

Definition at line 64 of file qgslayertree.h.

◆ toLayer() [1/2]

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

Cast node to a layer.

No type checking is done - use isLayer() to find out whether this operation is legal.

Note
Not available in Python bindings, because cast is automatic.
Since
QGIS 2.4

Definition at line 86 of file qgslayertree.h.

◆ toLayer() [2/2]

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

Cast node to a layer.

No type checking is done - use isLayer() to find out whether this operation is legal.

Note
Not available in Python bindings, because cast is automatic.
Since
QGIS 2.4

Definition at line 75 of file qgslayertree.h.

◆ writeXml()

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

Write layer tree to XML.

Implements QgsLayerTreeNode.

Definition at line 118 of file qgslayertree.cpp.


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