QGIS API Documentation  3.37.0-Master (a5b4d9743e8)
Public Member Functions | Static Public Member Functions | Protected Slots | Protected Member Functions | Protected Attributes | List of all members
QgsLayerTreeGroup Class Reference

Layer tree group node serves as a container for layers and further groups. More...

#include <qgslayertreegroup.h>

Inheritance diagram for QgsLayerTreeGroup:
Inheritance graph
[legend]

Public Member Functions

 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 reorderGroupLayers (const QList< QgsMapLayer * > &order)
 Reorders layers in the group to match the order specified by order. 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 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...
 
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...
 
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...
 
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...
 
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...
 
bool takeChild (QgsLayerTreeNode *node)
 Remove a child from a node. More...
 

Static Public Member Functions

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

Protected Slots

void nodeVisibilityChanged (QgsLayerTreeNode *node)
 

Protected Member Functions

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

Additional Inherited Members

- Public Types inherited from QgsLayerTreeNode
enum  NodeType { NodeGroup , NodeLayer }
 Enumeration of possible tree node types. 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...
 

Detailed Description

Layer tree group node serves as a container for layers and further groups.

Group names do not need to be unique within one tree nor within one parent.

While a layer tree group is typically used for hierarchical organisation of a QgsProject, they can optionally be associated with a QgsGroupLayer for map rendering purposes.

Definition at line 39 of file qgslayertreegroup.h.

Constructor & Destructor Documentation

◆ QgsLayerTreeGroup() [1/2]

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

Constructor.

Definition at line 28 of file qgslayertreegroup.cpp.

◆ QgsLayerTreeGroup() [2/2]

QgsLayerTreeGroup::QgsLayerTreeGroup ( const QgsLayerTreeGroup other)

Definition at line 35 of file qgslayertreegroup.cpp.

Member Function Documentation

◆ addChildNode()

void QgsLayerTreeGroup::addChildNode ( QgsLayerTreeNode node)

Append an existing node.

The node must not have a parent yet. The node will be owned by this group.

Definition at line 144 of file qgslayertreegroup.cpp.

◆ addGroup()

QgsLayerTreeGroup * QgsLayerTreeGroup::addGroup ( const QString &  name)

Append a new group node with given name.

Newly created node is owned by this group.

Definition at line 76 of file qgslayertreegroup.cpp.

◆ addLayer()

QgsLayerTreeLayer * QgsLayerTreeGroup::addLayer ( QgsMapLayer layer)

Append a new layer node for given map layer.

The newly created node is owned by this group.

Definition at line 95 of file qgslayertreegroup.cpp.

◆ clone()

QgsLayerTreeGroup * QgsLayerTreeGroup::clone ( ) const
overridevirtual

Returns a clone of the group.

The children are cloned too.

Implements QgsLayerTreeNode.

Definition at line 430 of file qgslayertreegroup.cpp.

◆ convertToGroupLayer()

QgsGroupLayer * QgsLayerTreeGroup::convertToGroupLayer ( const QgsGroupLayer::LayerOptions options)

Converts the group to a QgsGroupLayer.

This method will convert the layer tree group to an equivalent QgsGroupLayer, and return the result. The caller takes ownership of the returned layer, and it is the caller's responsibility to add the layer to the associated QgsProject.

If the group is already associated with a group layer (see groupLayer()), nullptr will be returned.

See also
groupLayer()
setGroupLayer()
Since
QGIS 3.24

Definition at line 500 of file qgslayertreegroup.cpp.

◆ dump()

QString QgsLayerTreeGroup::dump ( ) const
overridevirtual

Returns text representation of the tree.

For debugging purposes only.

Implements QgsLayerTreeNode.

Definition at line 419 of file qgslayertreegroup.cpp.

◆ findGroup()

QgsLayerTreeGroup * QgsLayerTreeGroup::findGroup ( const QString &  name)

Find group node with specified name.

Searches recursively the whole sub-tree.

Definition at line 311 of file qgslayertreegroup.cpp.

◆ findGroups()

QList< QgsLayerTreeGroup * > QgsLayerTreeGroup::findGroups ( bool  recursive = false) const

Find group layer nodes.

Searches recursively the whole sub-tree, if recursive is set.

Definition at line 331 of file qgslayertreegroup.cpp.

◆ findLayer() [1/2]

QgsLayerTreeLayer * QgsLayerTreeGroup::findLayer ( const QString &  layerId) const

Find layer node representing the map layer specified by its ID.

Searches recursively the whole sub-tree.

Definition at line 230 of file qgslayertreegroup.cpp.

◆ findLayer() [2/2]

QgsLayerTreeLayer * QgsLayerTreeGroup::findLayer ( QgsMapLayer layer) const

Find layer node representing the map layer.

Searches recursively the whole sub-tree.

Definition at line 222 of file qgslayertreegroup.cpp.

◆ findLayerIds()

QStringList QgsLayerTreeGroup::findLayerIds ( ) const

Find layer IDs used in all layer nodes.

Searches recursively the whole sub-tree.

Definition at line 526 of file qgslayertreegroup.cpp.

◆ findLayers()

QList< QgsLayerTreeLayer * > QgsLayerTreeGroup::findLayers ( ) const

Find all layer nodes.

Searches recursively the whole sub-tree.

Definition at line 250 of file qgslayertreegroup.cpp.

◆ groupLayer()

QgsGroupLayer * QgsLayerTreeGroup::groupLayer ( )

Returns a reference to the associated group layer, if the layer tree group will be treated as group layer during map rendering.

See also
setGroupLayer()
convertToGroupLayer()
Since
QGIS 3.24

Definition at line 482 of file qgslayertreegroup.cpp.

◆ insertChildNode()

void QgsLayerTreeGroup::insertChildNode ( int  index,
QgsLayerTreeNode node 
)

Insert existing node at specified position.

The node must not have a parent yet. The node will be owned by this group.

Definition at line 107 of file qgslayertreegroup.cpp.

◆ insertChildNodes()

void QgsLayerTreeGroup::insertChildNodes ( int  index,
const QList< QgsLayerTreeNode * > &  nodes 
)

Insert existing nodes at specified position.

The nodes must not have a parent yet. The nodes will be owned by this group.

Definition at line 114 of file qgslayertreegroup.cpp.

◆ insertGroup()

QgsLayerTreeGroup * QgsLayerTreeGroup::insertGroup ( int  index,
const QString &  name 
)

Insert a new group node with given name at specified position.

The newly created node is owned by this group.

Definition at line 69 of file qgslayertreegroup.cpp.

◆ insertLayer()

QgsLayerTreeLayer * QgsLayerTreeGroup::insertLayer ( int  index,
QgsMapLayer layer 
)

Insert a new layer node for given map layer at specified position.

The newly created node is owned by this group.

Definition at line 83 of file qgslayertreegroup.cpp.

◆ isMutuallyExclusive()

bool QgsLayerTreeGroup::isMutuallyExclusive ( ) const

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

Definition at line 449 of file qgslayertreegroup.cpp.

◆ layerOrderRespectingGroupLayers()

QList< QgsMapLayer * > QgsLayerTreeGroup::layerOrderRespectingGroupLayers ( ) const

Returns an ordered list of map layers in the group, ignoring any layers which are child layers of QgsGroupLayers.

Searches recursively the whole sub-tree.

Note
Not available in Python bindings
Since
QGIS 3.24

Definition at line 283 of file qgslayertreegroup.cpp.

◆ makeOrphan()

void QgsLayerTreeGroup::makeOrphan ( )
overrideprotectedvirtual

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

Reimplemented from QgsLayerTreeNode.

Definition at line 581 of file qgslayertreegroup.cpp.

◆ name()

QString QgsLayerTreeGroup::name ( ) const
overridevirtual

Returns the group's name.

Implements QgsLayerTreeNode.

Definition at line 54 of file qgslayertreegroup.cpp.

◆ nodeVisibilityChanged

void QgsLayerTreeGroup::nodeVisibilityChanged ( QgsLayerTreeNode node)
protectedslot

Definition at line 539 of file qgslayertreegroup.cpp.

◆ readChildrenFromXml()

void QgsLayerTreeGroup::readChildrenFromXml ( QDomElement &  element,
const QgsReadWriteContext context 
)

Read children from XML and append them to the group.

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

Definition at line 403 of file qgslayertreegroup.cpp.

◆ readXml() [1/2]

QgsLayerTreeGroup * QgsLayerTreeGroup::readXml ( QDomElement &  element,
const QgsProject project,
const QgsReadWriteContext context 
)
static

Read group (tree) from XML element <layer-tree-group> and return the newly created group (or nullptr on error).

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

Definition at line 373 of file qgslayertreegroup.cpp.

◆ readXml() [2/2]

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

Read group (tree) from XML element <layer-tree-group> and return the newly created group (or nullptr on error).

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

Definition at line 348 of file qgslayertreegroup.cpp.

◆ removeAllChildren()

void QgsLayerTreeGroup::removeAllChildren ( )

Remove all child nodes.

The nodes will be deleted.

Definition at line 217 of file qgslayertreegroup.cpp.

◆ removeChildNode()

void QgsLayerTreeGroup::removeChildNode ( QgsLayerTreeNode node)

Remove a child node from this group.

The node will be deleted.

Definition at line 151 of file qgslayertreegroup.cpp.

◆ removeChildren()

void QgsLayerTreeGroup::removeChildren ( int  from,
int  count 
)

Remove child nodes from index "from".

The nodes will be deleted.

Definition at line 178 of file qgslayertreegroup.cpp.

◆ removeChildrenGroupWithoutLayers()

void QgsLayerTreeGroup::removeChildrenGroupWithoutLayers ( )

Remove all child group nodes without layers.

The groupnodes will be deleted.

Definition at line 198 of file qgslayertreegroup.cpp.

◆ removeLayer()

void QgsLayerTreeGroup::removeLayer ( QgsMapLayer layer)

Remove map layer's node from this group.

The node will be deleted.

Definition at line 160 of file qgslayertreegroup.cpp.

◆ reorderGroupLayers()

void QgsLayerTreeGroup::reorderGroupLayers ( const QList< QgsMapLayer * > &  order)

Reorders layers in the group to match the order specified by order.

Only layers which are direct children of this group will be reordered, other layers will be ignored.

Note
This method does not recursively reorder child groups.
Matching layers will be moved to the start of the group, with any existing non-matching layers and group nodes moved to sit after the re-ordered matching layers.
Since
QGIS 3.30

Definition at line 263 of file qgslayertreegroup.cpp.

◆ resolveReferences()

void QgsLayerTreeGroup::resolveReferences ( const QgsProject project,
bool  looseMatching = false 
)
overridevirtual

Calls resolveReferences() on child tree nodes.

Implements QgsLayerTreeNode.

Definition at line 435 of file qgslayertreegroup.cpp.

◆ setGroupLayer()

void QgsLayerTreeGroup::setGroupLayer ( QgsGroupLayer layer)

Sets the associated group layer, if the layer tree group will be treated as group layer during map rendering.

This method does not take ownership of the group layer, and only a weak reference to the layer is stored.

See also
groupLayer()
convertToGroupLayer()
Since
QGIS 3.24

Definition at line 487 of file qgslayertreegroup.cpp.

◆ setIsMutuallyExclusive()

void QgsLayerTreeGroup::setIsMutuallyExclusive ( bool  enabled,
int  initialChildIndex = -1 
)

Set whether the group is mutually exclusive (only one child can be checked at a time).

The initial child index determines which child should be initially checked. The default value of -1 will determine automatically (either first one currently checked or none)

Definition at line 454 of file qgslayertreegroup.cpp.

◆ setItemVisibilityCheckedRecursive()

void QgsLayerTreeGroup::setItemVisibilityCheckedRecursive ( bool  checked)
overridevirtual

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

Reimplemented from QgsLayerTreeNode.

Definition at line 624 of file qgslayertreegroup.cpp.

◆ setName()

void QgsLayerTreeGroup::setName ( const QString &  n)
overridevirtual

Sets the group's name.

Implements QgsLayerTreeNode.

Definition at line 59 of file qgslayertreegroup.cpp.

◆ updateChildVisibilityMutuallyExclusive()

void QgsLayerTreeGroup::updateChildVisibilityMutuallyExclusive ( )
protected

Set check state of children - if mutually exclusive.

Definition at line 562 of file qgslayertreegroup.cpp.

◆ writeXml()

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

Write group (tree) as XML element <layer-tree-group> and add it to the given parent element.

Implements QgsLayerTreeNode.

Definition at line 381 of file qgslayertreegroup.cpp.

Member Data Documentation

◆ mChangingChildVisibility

bool QgsLayerTreeGroup::mChangingChildVisibility = false
protected

Definition at line 291 of file qgslayertreegroup.h.

◆ mMutuallyExclusive

bool QgsLayerTreeGroup::mMutuallyExclusive = false
protected

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

Definition at line 294 of file qgslayertreegroup.h.

◆ mMutuallyExclusiveChildIndex

int QgsLayerTreeGroup::mMutuallyExclusiveChildIndex = -1
protected

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)

Definition at line 300 of file qgslayertreegroup.h.

◆ mName

QString QgsLayerTreeGroup::mName
protected

Definition at line 289 of file qgslayertreegroup.h.


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