Class: QgsLayerTreeGroup¶

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.

Class Hierarchy¶

Base classes¶

`QgsLayerTreeNode`	Base class for nodes in a layer tree.
QObject

Subclasses¶

QgsLayerTree

Namespace with helper functions for layer tree operations.

Abstract Methods

`clone`	Returns a clone of the group.
`dump`	Returns text representation of the tree.
`name`	Returns the group's name.
`resolveReferences`	Calls `resolveReferences()` on child tree nodes
`setName`	Sets the group's name.
`writeXml`	Write group (tree) as XML element <layer-tree-group> and add it to the given parent element

Methods

`addChildNode`	Append an existing node.
`addGroup`	Append a new group node with given name.
`addLayer`	Append a new layer node for given map layer.
`convertToGroupLayer`	Converts the group to a `QgsGroupLayer`.
`findGroup`	Find group node with specified name.
`findGroups`	Find group layer nodes.
`findLayer`	Find layer node representing the map layer.
`findLayerIds`	Find layer IDs used in all layer nodes.
`findLayers`	Find all layer nodes.
`groupLayer`	Returns a reference to the associated group layer, if the layer tree group will be treated as group layer during map rendering.
`hasWmsTimeDimension`	Returns whether the WMS time dimension should be computed for this group or not.
`insertChildNode`	Insert existing node at specified position.
`insertChildNodes`	Insert existing nodes at specified position.
`insertGroup`	Insert a new group node with given name at specified position.
`insertLayer`	Insert a new layer node for given map layer at specified position.
`isMutuallyExclusive`	Returns whether the group is mutually exclusive (only one child can be checked at a time)
`nodeVisibilityChanged`
`readChildrenFromXml`	Read children from XML and append them to the group.
`removeAllChildren`	Remove all child nodes.
`removeChildNode`	Remove a child node from this group.
`removeChildren`	Remove child nodes from index "from".
`removeChildrenGroupWithoutLayers`	Remove all child group nodes without layers.
`removeLayer`	Remove map layer's node from this group.
`reorderGroupLayers`	Reorders layers in the group to match the order specified by order.
`serverProperties`	Returns QGIS Server Properties for the layer tree group
`setGroupLayer`	Sets the associated group layer, if the layer tree group will be treated as group layer during map rendering.
`setHasWmsTimeDimension`	Sets whether the WMS time dimension should be computed for this group or not
`setIsMutuallyExclusive`	Set whether the group is mutually exclusive (only one child can be checked at a time).
`updateChildVisibilityMutuallyExclusive`	Set check state of children - if mutually exclusive

Static Methods

readXml

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

class qgis.core.QgsLayerTreeGroup[source]¶

Bases: QgsLayerTreeNode

__init__(name: str | None = '', checked: bool = True)

Constructor

Parameters:

name (Optional[str] = '')
checked (bool = True)

addChildNode(self, node: QgsLayerTreeNode | None)[source]¶

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

Parameters:: node (Optional[QgsLayerTreeNode])

addGroup(self, name: str | None) → QgsLayerTreeGroup | None[source]¶

Append a new group node with given name. Newly created node is owned by this group.

Parameters:: name (Optional[str])
Return type:: Optional[QgsLayerTreeGroup]

addLayer(self, layer: QgsMapLayer | None) → QgsLayerTreeLayer | None[source]¶

Append a new layer node for given map layer. The newly created node is owned by this group.

Parameters:: layer (Optional[QgsMapLayer])
Return type:: Optional[QgsLayerTreeLayer]

abstract clone(self) → QgsLayerTreeGroup | None[source]¶

Returns a clone of the group. The children are cloned too.

Return type:: Optional[QgsLayerTreeGroup]

convertToGroupLayer(self, options: QgsGroupLayer.LayerOptions) → QgsGroupLayer | None[source]¶

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()), None will be returned.

See also

groupLayer()

See also

setGroupLayer()

Added in version 3.24.

Parameters:: options (QgsGroupLayer.LayerOptions)
Return type:: Optional[QgsGroupLayer]

abstract dump(self) → str[source]¶

Returns text representation of the tree. For debugging purposes only.

Return type:: str

findGroup(self, name: str | None) → QgsLayerTreeGroup | None[source]¶

Find group node with specified name. Searches recursively the whole sub-tree.

Parameters:: name (Optional[str])
Return type:: Optional[QgsLayerTreeGroup]

findGroups(self, recursive: bool = False) → List[QgsLayerTreeGroup]¶

Find group layer nodes. Searches recursively the whole sub-tree, if recursive is set.

Parameters:: recursive (bool = False)
Return type:: List[QgsLayerTreeGroup]

findLayer(self, layer: QgsMapLayer | None) → QgsLayerTreeLayer | None[source]¶

Find layer node representing the map layer. Searches recursively the whole sub-tree.

Parameters:: layer (Optional[QgsMapLayer])
Return type:: Optional[QgsLayerTreeLayer]

findLayer(self, layerId: str | None) → QgsLayerTreeLayer | None[source]

Find layer node representing the map layer specified by its ID. Searches recursively the whole sub-tree.

Parameters:: layerId (Optional[str])
Return type:: Optional[QgsLayerTreeLayer]

findLayerIds(self) → List[str][source]¶

Find layer IDs used in all layer nodes. Searches recursively the whole sub-tree.

Return type:: List[str]

findLayers(self) → List[QgsLayerTreeLayer]¶

Find all layer nodes. Searches recursively the whole sub-tree.

Return type:: List[QgsLayerTreeLayer]

groupLayer(self) → QgsGroupLayer | None[source]¶

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()

See also

convertToGroupLayer()

Added in version 3.24.

Return type:: Optional[QgsGroupLayer]

hasWmsTimeDimension(self) → bool[source]¶

Returns whether the WMS time dimension should be computed for this group or not. if True, when a GetCapabilities request is sent, QGIS server would return a TIME dimension computed as an union of all time dimensions of its children recursively. Else, no TIME dimension will be returned.

See also

setHasWmsTimeDimension()

Added in version 3.44.

Return type:: bool

insertChildNode(self, index: int, node: QgsLayerTreeNode | None)[source]¶

Insert existing node at specified position. The node must not have a parent yet. The node will be owned by this group.

Parameters:

index (int)
node (Optional[QgsLayerTreeNode])

insertChildNodes(self, index: int, nodes: Iterable[QgsLayerTreeNode])[source]¶

Insert existing nodes at specified position. The nodes must not have a parent yet. The nodes will be owned by this group.

Parameters:

index (int)
nodes (Iterable[QgsLayerTreeNode])

insertGroup(self, index: int, name: str | None) → QgsLayerTreeGroup | None[source]¶

Insert a new group node with given name at specified position. The newly created node is owned by this group.

Parameters:

index (int)
name (Optional[str])

Return type:

Optional[QgsLayerTreeGroup]

insertLayer(self, index: int, layer: QgsMapLayer | None) → QgsLayerTreeLayer | None[source]¶

Insert a new layer node for given map layer at specified position. The newly created node is owned by this group.

Parameters:

index (int)
layer (Optional[QgsMapLayer])

Return type:

Optional[QgsLayerTreeLayer]

isMutuallyExclusive(self) → bool[source]¶

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

Return type:: bool

abstract name(self) → str[source]¶

Returns the group’s name.

Return type:: str

nodeVisibilityChanged(self, node: QgsLayerTreeNode | None)[source]¶

Parameters:: node (Optional[QgsLayerTreeNode])

readChildrenFromXml(self, element: QDomElement, context: QgsReadWriteContext)[source]¶

Read children from XML and append them to the group. Does not resolve textual references to layers. Call resolveReferences() afterwards to do it.

Parameters:

element (QDomElement)
context (QgsReadWriteContext)

static readXml(element: QDomElement, context: QgsReadWriteContext) → QgsLayerTreeGroup | None[source]¶

Read group (tree) from XML element <layer-tree-group> and return the newly created group (or None on error). Does not resolve textual references to layers. Call resolveReferences() afterwards to do it.

Parameters:

element (QDomElement)
context (QgsReadWriteContext)

Return type:

Optional[QgsLayerTreeGroup]

static readXml(element: QDomElement, project: QgsProject | None, context: QgsReadWriteContext) → QgsLayerTreeGroup | None[source]

Read group (tree) from XML element <layer-tree-group> and return the newly created group (or None on error). Also resolves textual references to layers from the project (calls resolveReferences() internally).

Parameters:

element (QDomElement)
project (Optional[QgsProject])
context (QgsReadWriteContext)

Return type:

Optional[QgsLayerTreeGroup]

removeAllChildren(self)[source]¶: Remove all child nodes. The nodes will be deleted.

removeChildNode(self, node: QgsLayerTreeNode | None)[source]¶

Remove a child node from this group. The node will be deleted.

Parameters:: node (Optional[QgsLayerTreeNode])

removeChildren(self, from_: int, count: int)[source]¶

Remove child nodes from index “from”. The nodes will be deleted.

Parameters:

from (int)
count (int)

removeChildrenGroupWithoutLayers(self)[source]¶: Remove all child group nodes without layers. The groupnodes will be deleted.

removeLayer(self, layer: QgsMapLayer | None)[source]¶

Remove map layer’s node from this group. The node will be deleted.

Parameters:: layer (Optional[QgsMapLayer])

reorderGroupLayers(self, order: Iterable[QgsMapLayer])[source]¶

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.

Note

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.

Added in version 3.30.

Parameters:: order (Iterable[QgsMapLayer])

abstract resolveReferences(self, project: QgsProject | None, looseMatching: bool = False)[source]¶

Calls resolveReferences() on child tree nodes

Parameters:

project (Optional[QgsProject])
looseMatching (bool = False)

serverProperties(self) → QgsMapLayerServerProperties | None[source]¶

Returns QGIS Server Properties for the layer tree group

Added in version 3.44.

Return type:: Optional[QgsMapLayerServerProperties]

setGroupLayer(self, layer: QgsGroupLayer | None)[source]¶

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()

See also

convertToGroupLayer()

Added in version 3.24.

Parameters:: layer (Optional[QgsGroupLayer])

setHasWmsTimeDimension(self, hasWmsTimeDimension: bool)[source]¶

Sets whether the WMS time dimension should be computed for this group or not

Parameters:: hasWmsTimeDimension (bool) – if True, when a GetCapabilities request is sent, QGIS server would return a TIME dimension computed as an union of all time dimensions of its children recursively. Else, no TIME dimension will be returned.

See also

hasWmsTimeDimension()

Added in version 3.44.

setIsMutuallyExclusive(self, enabled: bool, initialChildIndex: int = -1)[source]¶

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)

Parameters:

enabled (bool)
initialChildIndex (int = -1)

abstract setName(self, n: str | None)[source]¶

Sets the group’s name.

Parameters:: n (Optional[str])

updateChildVisibilityMutuallyExclusive(self)[source]¶: Set check state of children - if mutually exclusive

abstract writeXml(self, parentElement: QDomElement, context: QgsReadWriteContext)[source]¶

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

Parameters:

parentElement (QDomElement)
context (QgsReadWriteContext)