Class: QgsLayerTreeGroup

class qgis.core.QgsLayerTreeGroup

Bases: QgsLayerTreeNode

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.

QgsLayerTreeGroup(name: str = ‘’, checked: bool = True) Constructor

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.

childEvent

clone

Returns a clone of the group.

connectNotify

convertToGroupLayer

Converts the group to a QgsGroupLayer.

customEvent

disconnectNotify

dump

Returns text representation of the tree.

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.

insertChildNode

Insert existing node at specified position.

insertChildNodes

Insert existing nodes at specified position.

insertChildrenPrivate

Low-level insertion of children to the node.

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)

isSignalConnected

name

Returns the group's name.

nodeVisibilityChanged

param node:

readChildrenFromXml

Read children from XML and append them to the group.

readCommonXml

Read common XML elements.

readXml

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

receivers

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.

removeChildrenPrivate

Low-level removal of children from the node.

removeLayer

Remove map layer's node from this group.

reorderGroupLayers

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

resolveReferences

Calls resolveReferences() on child tree nodes

sender

senderSignalIndex

setGroupLayer

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

setIsMutuallyExclusive

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

setItemVisibilityCheckedRecursive

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

setName

Sets the group's name.

timerEvent

updateChildVisibilityMutuallyExclusive

Set check state of children - if mutually exclusive

writeCommonXml

Write common XML elements.

writeXml

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

addChildNode(self, node: QgsLayerTreeNode)

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

Parameters:

node (QgsLayerTreeNode) –

addGroup(self, name: str) QgsLayerTreeGroup

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

Parameters:

name (str) –

Return type:

QgsLayerTreeGroup

addLayer(self, layer: QgsMapLayer) QgsLayerTreeLayer

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

Parameters:

layer (QgsMapLayer) –

Return type:

QgsLayerTreeLayer

childEvent(self, QChildEvent)
clone(self) QgsLayerTreeGroup

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

Return type:

QgsLayerTreeGroup

connectNotify(self, QMetaMethod)
convertToGroupLayer(self, options: QgsGroupLayer.LayerOptions) QgsGroupLayer

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

New in version 3.24.

Parameters:

options (QgsGroupLayer.LayerOptions) –

Return type:

QgsGroupLayer

customEvent(self, QEvent)
disconnectNotify(self, QMetaMethod)
dump(self) str

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

Return type:

str

findGroup(self, name: str) QgsLayerTreeGroup

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

Parameters:

name (str) –

Return type:

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

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

findLayer(self, layerId: str) -> QgsLayerTreeLayer Find layer node representing the map layer specified by its ID. Searches recursively the whole sub-tree.

Parameters:

layer (QgsMapLayer) –

Return type:

QgsLayerTreeLayer

findLayerIds(self) List[str]

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

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

New in version 3.24.

Return type:

QgsGroupLayer

insertChildNode(self, index: int, node: QgsLayerTreeNode)

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

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

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

Parameters:
insertChildrenPrivate(self, index: int, nodes: Iterable[QgsLayerTreeNode])

Low-level insertion of children to the node. The children must not have any parent yet!

insertGroup(self, index: int, name: str) QgsLayerTreeGroup

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

Parameters:
  • index (int) –

  • name (str) –

Return type:

QgsLayerTreeGroup

insertLayer(self, index: int, layer: QgsMapLayer) QgsLayerTreeLayer

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

Parameters:
Return type:

QgsLayerTreeLayer

isMutuallyExclusive(self) bool

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

Return type:

bool

isSignalConnected(self, QMetaMethod) bool
name(self) str

Returns the group’s name.

Return type:

str

nodeVisibilityChanged(self, node: QgsLayerTreeNode)
Parameters:

node (QgsLayerTreeNode) –

readChildrenFromXml(self, element: QDomElement, context: QgsReadWriteContext)

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

Parameters:
readCommonXml(self, element: QDomElement)

Read common XML elements.

readXml(element: QDomElement, context: QgsReadWriteContext) QgsLayerTreeGroup

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.

readXml(element: QDomElement, project: QgsProject, context: QgsReadWriteContext) -> QgsLayerTreeGroup 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:
Return type:

QgsLayerTreeGroup

receivers(self, PYQT_SIGNAL) int
removeAllChildren(self)

Remove all child nodes. The nodes will be deleted.

removeChildNode(self, node: QgsLayerTreeNode)

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

Parameters:

node (QgsLayerTreeNode) –

removeChildren(self, from_: int, count: int)

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

Parameters:
  • from (int) –

  • count (int) –

removeChildrenGroupWithoutLayers(self)

Remove all child group nodes without layers. The groupnodes will be deleted.

removeChildrenPrivate(self, from_: int, count: int, destroy: bool = True)

Low-level removal of children from the node.

removeLayer(self, layer: QgsMapLayer)

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

Parameters:

layer (QgsMapLayer) –

reorderGroupLayers(self, order: Iterable[QgsMapLayer])

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.

New in version 3.30.

Parameters:

order (Iterable[QgsMapLayer]) –

resolveReferences(self, project: QgsProject, looseMatching: bool = False)

Calls resolveReferences() on child tree nodes

Parameters:
  • project (QgsProject) –

  • looseMatching (bool = False) –

sender(self) QObject
senderSignalIndex(self) int
setGroupLayer(self, layer: QgsGroupLayer)

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

New in version 3.24.

Parameters:

layer (QgsGroupLayer) –

setIsMutuallyExclusive(self, enabled: bool, initialChildIndex: int = -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)

Parameters:
  • enabled (bool) –

  • initialChildIndex (int = -1) –

setItemVisibilityCheckedRecursive(self, checked: bool)

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

Parameters:

checked (bool) –

setName(self, n: str)

Sets the group’s name.

Parameters:

n (str) –

timerEvent(self, QTimerEvent)
updateChildVisibilityMutuallyExclusive(self)

Set check state of children - if mutually exclusive

writeCommonXml(self, element: QDomElement)

Write common XML elements.

writeXml(self, parentElement: QDomElement, context: QgsReadWriteContext)

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

Parameters: