Class: QgsLayerTreeUtils

Assorted functions for dealing with layer trees.

Static Methods

checkStateFromXml

Convert string to Qt.CheckState

checkStateToXml

Convert Qt.CheckState to string

collectMapLayersRecursive

Returns map layers from the given list of layer tree nodes.

countMapLayerInTree

Returns how many occurrences of a map layer are there in a layer tree.

firstGroupWithoutCustomProperty

Returns the first parent which doesn't have the given custom property or the group itself if it doesn't hold the property

hasLegendFilterExpression

Test if one of the layers in a group has an expression filter

insertLayerAtOptimalPlacement

Inserts a layer within a given group at an optimal index position by insuring a given layer type will always sit on top of or below other types.

insertLayerBelow

Insert a QgsMapLayer just below another one

invisibleLayerList

Gets invisible layers

layersEditable

Returns True if any of the specified layers is editable.

layersModified

Returns True if any of the layers is modified

legendFilterByExpression

Returns the expression filter of a legend layer

readOldLegend

Try to load layer tree from verbatim <legend> endverbatim tag from project files from QGIS 2.2 and below

readOldLegendLayerOrder

Try to load custom layer order from verbatim <legend> endverbatim tag from project files from QGIS 2.2 and below

removeInvalidLayers

Removes layer nodes that refer to invalid layers

replaceChildrenOfEmbeddedGroups

Remove subtree of embedded groups and replaces it with a custom property embedded-visible-layers

setLegendFilterByExpression

Sets the expression filter of a legend layer

storeOriginalLayersProperties

Stores in a layer's originalXmlProperties the layer properties information

updateEmbeddedGroupsProjectPath

Updates an embedded group from a project.

writeOldLegend

Returns verbatim <legend> endverbatim tag used in QGIS 2.2 and below
class qgis.core.QgsLayerTreeUtils[source]

Bases: object

static checkStateFromXml(txt: str | None) → Qt.CheckState[source]

Convert string to Qt.CheckState

Parameters:

txt (Optional[str])

Return type:

Qt.CheckState

static checkStateToXml(state: Qt.CheckState) → str[source]

Convert Qt.CheckState to string

Parameters:

state (Qt.CheckState)

Return type:

str

static collectMapLayersRecursive(nodes: Iterable[QgsLayerTreeNode]) → Set[QgsMapLayer]

Returns map layers from the given list of layer tree nodes. Also recursively visits child nodes of groups.

Added in version 3.4.

Parameters:

nodes (Iterable[QgsLayerTreeNode])

Return type:

Set[QgsMapLayer]

static countMapLayerInTree(tree: QgsLayerTreeNode | None, layer: QgsMapLayer | None) → int[source]

Returns how many occurrences of a map layer are there in a layer tree. In normal situations there is at most one occurrence, but sometimes there may be temporarily more: for example, during drag&drop, upon drop a new layer node is created while the original dragged node is still in the tree, resulting in two occurrences.

This is useful when deciding whether to start or stop listening to a signal of a map layer within a layer tree and only connecting/disconnecting when there is only one occurrence of that layer.

Added in version 3.4.

Parameters:
Return type:

int

static firstGroupWithoutCustomProperty(group: QgsLayerTreeGroup | None, property: str | None) → QgsLayerTreeGroup | None[source]

Returns the first parent which doesn’t have the given custom property or the group itself if it doesn’t hold the property

Parameters:

  • group (Optional[QgsLayerTreeGroup]) – the layer tree group

  • property (Optional[str]) – the property

Added in version 3.8.

Return type:

Optional[QgsLayerTreeGroup]

static hasLegendFilterExpression(group: QgsLayerTreeGroup) → bool[source]

Test if one of the layers in a group has an expression filter

Parameters:

group (QgsLayerTreeGroup)

Return type:

bool

static insertLayerAtOptimalPlacement(group: QgsLayerTreeGroup | None, layer: QgsMapLayer | None) → QgsLayerTreeLayer | None[source]

Inserts a layer within a given group at an optimal index position by insuring a given layer type will always sit on top of or below other types. From top to bottom, the stacking logic is as follow:

  • vector points

  • vector lines

  • vector polygons

  • point clouds

  • meshes

  • rasters

  • base maps

A base map is defined as a non-gdal provider raster layer (e.g. XYZ raster layer, vector tile layer, etc.)

Added in version 3.28.

Parameters:
Return type:

Optional[QgsLayerTreeLayer]

static insertLayerBelow(group: QgsLayerTreeGroup | None, refLayer: QgsMapLayer | None, layerToInsert: QgsMapLayer | None) → QgsLayerTreeLayer | None[source]

Insert a QgsMapLayer just below another one

Parameters:

  • group (Optional[QgsLayerTreeGroup]) – the tree group where layers are (can be the root group)

  • refLayer (Optional[QgsMapLayer]) – the reference layer

  • layerToInsert (Optional[QgsMapLayer]) – the new layer to insert just below the reference layer

Return type:

Optional[QgsLayerTreeLayer]

Returns:

the new tree layer

static invisibleLayerList(node: QgsLayerTreeNode | None) → List[str][source]

Gets invisible layers

Parameters:

node (Optional[QgsLayerTreeNode])

Return type:

List[str]

static layersEditable(layerNodes: Iterable[QgsLayerTreeLayer], ignoreLayersWhichCannotBeToggled: bool = False) → bool[source]

Returns True if any of the specified layers is editable.

The ignoreLayersWhichCannotBeToggled argument can be used to control whether layers which cannot have their edit states toggled by users should be ignored or not (since QGIS 3.22).

Parameters:

  • layerNodes (Iterable[QgsLayerTreeLayer])

  • ignoreLayersWhichCannotBeToggled (bool = False)

Return type:

bool

static layersModified(layerNodes: Iterable[QgsLayerTreeLayer]) → bool[source]

Returns True if any of the layers is modified

Parameters:

layerNodes (Iterable[QgsLayerTreeLayer])

Return type:

bool

static legendFilterByExpression(layer: QgsLayerTreeLayer)[source]

Returns the expression filter of a legend layer

Parameters:

layer (QgsLayerTreeLayer) -> (str)

static readOldLegend(root: QgsLayerTreeGroup | None, legendElem: QDomElement) → bool[source]

Try to load layer tree from verbatim <legend> endverbatim tag from project files from QGIS 2.2 and below

Parameters:
Return type:

bool

static readOldLegendLayerOrder(legendElem: QDomElement, order: Iterable[str | None])[source]

Try to load custom layer order from verbatim <legend> endverbatim tag from project files from QGIS 2.2 and below

Parameters:

  • legendElem (QDomElement)

  • order (Iterable[Optional[str]]) -> (bool)

static removeInvalidLayers(group: QgsLayerTreeGroup | None)[source]

Removes layer nodes that refer to invalid layers

Parameters:

group (Optional[QgsLayerTreeGroup])

static replaceChildrenOfEmbeddedGroups(group: QgsLayerTreeGroup | None)[source]

Remove subtree of embedded groups and replaces it with a custom property embedded-visible-layers

Parameters:

group (Optional[QgsLayerTreeGroup])

static setLegendFilterByExpression(layer: QgsLayerTreeLayer, expr: str | None, enabled: bool = True)[source]

Sets the expression filter of a legend layer

Parameters:
static storeOriginalLayersProperties(group: QgsLayerTreeGroup | None, doc: QDomDocument | None)[source]

Stores in a layer’s originalXmlProperties the layer properties information

Added in version 3.6.

Parameters:
static updateEmbeddedGroupsProjectPath(group: QgsLayerTreeGroup | None, project: QgsProject | None)[source]

Updates an embedded group from a project.

Parameters:
static writeOldLegend(doc: QDomDocument, root: QgsLayerTreeGroup | None, hasCustomOrder: bool, order: Iterable[QgsMapLayer]) → QDomElement[source]

Returns verbatim <legend> endverbatim tag used in QGIS 2.2 and below

Parameters:
Return type:

QDomElement