QgsLayerTreeGroup class

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

Reference

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

Base classes

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

Derived classes

class QgsLayerTree: Namespace with helper functions for layer tree operations.

Public static functions

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

Constructors, destructors, conversion operators

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

Public functions

void addChildNode(QgsLayerTreeNode* node): Append an existing node.
auto addGroup(const QString& name) -> QgsLayerTreeGroup*: Append a new group node with given name.
auto addLayer(QgsMapLayer* layer) -> QgsLayerTreeLayer*: Append a new layer node for given map layer.
auto clone() const -> QgsLayerTreeGroup* override: Returns a clone of the group.
auto dump() const -> QString override: Returns text representation of the tree.
auto findGroup(const QString& name) -> QgsLayerTreeGroup*: Find group node with specified name.
auto findGroups() const -> QList<QgsLayerTreeGroup*>: Find all group layer nodes.
auto findLayer(QgsMapLayer* layer) const -> QgsLayerTreeLayer*: Find layer node representing the map layer.
auto findLayer(const QString& layerId) const -> QgsLayerTreeLayer*: Find layer node representing the map layer specified by its ID.
auto findLayerIds() const -> QStringList: Find layer IDs used in all layer nodes.
auto findLayers() const -> QList<QgsLayerTreeLayer*>: Find all layer nodes.
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.
auto insertGroup(int index, const QString& name) -> QgsLayerTreeGroup*: Insert a new group node with given name at specified position.
auto insertLayer(int index, QgsMapLayer* layer) -> QgsLayerTreeLayer*: Insert a new layer node for given map layer at specified position.
auto isMutuallyExclusive() const -> bool: Returns whether the group is mutually exclusive (only one child can be checked at a time)
auto name() const -> QString 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 resolveReferences(const QgsProject* project, bool looseMatching = false) override: Calls resolveReferences() on child tree nodes.
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.

Protected functions

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

Protected variables

bool mMutuallyExclusive: Whether the group is mutually exclusive (i.e. only one child can be checked at a time)
int mMutuallyExclusiveChildIndex: 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)

Function documentation

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

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

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

static QgsLayerTreeGroup* 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 null on error).

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

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.

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

Append a new group node with given name.

Newly created node is owned by this group.

QgsLayerTreeLayer* QgsLayerTreeGroup::addLayer(QgsMapLayer* layer)

Append a new layer node for given map layer.

The newly created node is owned by this group.

QgsLayerTreeGroup* QgsLayerTreeGroup::clone() const override

Returns a clone of the group.

The children are cloned too.

QString QgsLayerTreeGroup::dump() const override

Returns text representation of the tree.

For debugging purposes only.