Class: QgsLayerTreeModel

A model representing the layer tree, including layers and groups of layers.

The model can be used in any QTreeView, it is however recommended to use it with QgsLayerTreeView which brings additional functionality specific to layer tree handling.

The model listens to the changes in the layer tree and signals the changes as appropriate, so that any view that uses the model is updated accordingly.

Behavior of the model can be customized with flags. For example, whether to show legend or whether to allow changes to the layer tree.

See also

QgsLayerTreeView

Class Hierarchy

Base classes

QAbstractItemModel
QObject

Subclasses

QgsLegendModel

Item model implementation based on layer tree model for layout legend.

Methods

addLegendToLayer
addTargetScreenProperties	Adds additional target screen properties to use when generating icons for Qt.DecorationRole data.
autoCollapseLegendNodes	Returns at what number of legend nodes the layer node should be collapsed.
connectToLayer
connectToLayers
connectToRootNode
currentIndex	Gets index of the item marked as current.
disconnectFromLayer
disconnectFromLayers
disconnectFromRootNode
filterLegendNodes	Filter nodes from QgsMapLayerLegend according to the current filtering rules
filterSettings	Returns the filter settings to use to filter legend nodes.
findLegendNode	Searches through the layer tree to find a legend node with a matching layer ID and rule key.
hitTestInProgress	Returns True if a hit test for visible legend items is currently in progress.
index2node	Returns layer tree node for given index.
indexOfParentLayerTreeNode
indexes2nodes	Convert a list of indexes to a list of layer tree nodes.
invalidateLegendMapBasedData
layerFlagsChanged	Triggered when layer flags have changed.
layerLegendChanged
layerLegendNodes	Returns filtered list of active legend nodes attached to a particular layer node (by default it returns also legend node embedded in parent layer node (if any) unless skipNodeEmbeddedInParent is True)
layerNeedsUpdate
layerOriginalLegendNodes	Returns original (unfiltered) list of legend nodes attached to a particular layer node
layerStyleOverrides	Gets map of map layer style overrides (key: layer ID, value: style name) where a different style should be used instead of the current one
layerTreeNodeFont	Gets font for a particular type of layer tree node.
legendCleanup
legendEmbeddedInParent
legendFilterByScale	Returns the scale which restricts the legend nodes which are visible.
legendFilterMapSettings	Returns the current map settings used for the current legend filter (or None if none is enabled)
legendIconEmbeddedInParent
legendInvalidateMapBasedData
legendMapViewData	Gets hints about map view - to be used in legend nodes.
legendNode2index	Returns index for a given legend node.
legendNodeData
legendNodeDataChanged
legendNodeEmbeddedInParent	Returns legend node that may be embedded in parent (i.e. its icon will be used for layer's icon).
legendNodeFlags
legendNodeIndex
legendNodeRowCount
legendParent
legendRootIndex
legendRootRowCount
node2index	Returns index for a given node.
nodeAddedChildren
nodeCustomPropertyChanged
nodeLayerLoaded
nodeLayerWillBeUnloaded
nodeNameChanged	Updates model when node's name has changed
nodeRemovedChildren
nodeVisibilityChanged
nodeWillAddChildren
nodeWillRemoveChildren
recursivelyEmitDataChanged	emit dataChanged() for layer tree node items
refreshLayerLegend	Force a refresh of legend nodes of a layer node.
refreshScaleBasedLayers	Updates layer data for scale dependent layers, should be called when map scale changes.
removeLegendFromLayer
rootGroup	Returns pointer to the root node of the layer tree.
setAutoCollapseLegendNodes	Sets at what number of legend nodes the layer node should be collapsed.
setCurrentIndex	Sets index of the current item.
setFilterSettings	Sets the filter settings to use to filter legend nodes.
setFlag	Enable or disable a model flag
setFlags	Sets OR-ed combination of model flags
setLayerStyleOverrides	Sets map of map layer style overrides (key: layer ID, value: style name) where a different style should be used instead of the current one
setLayerTreeNodeFont	Sets font for a particular type of layer tree node.
setLegendFilter	Filter display of legend nodes for given map settings
setLegendFilterByMap	Force only display of legend nodes which are valid for given map settings.
setLegendFilterByScale	Force only display of legend nodes which are valid for a given scale.
setLegendMapViewData	Give the layer tree model hints about the currently associated map view so that legend nodes that use map units can be scaled correctly
setRootGroup	Reset the model and use a new root group node
targetScreenProperties	Returns the target screen properties to use when generating icons.
testFlag	Check whether a flag is enabled
waitForHitTestBlocking	When a current hit test for visible legend items is in progress, calling this method will block until that hit test is complete.

Virtual Methods

In PyQGIS, only methods marked as virtual can be safely overridden in a Python subclass of QgsLayerTreeModel. See the FAQ for more details.

flags

Static Methods

iconGroup
index2legendNode	Returns legend node for given index.
scaleIconSize	Scales an layer tree model icon size to compensate for display pixel density, making the icon size hi-dpi friendly, whilst still resulting in pixel-perfect sizes for low-dpi displays.

Signals

hitTestCompleted	Emitted when a hit test for visible legend items completes.
hitTestStarted	Emitted when a hit test for visible legend items starts.
messageEmitted	Emits a message than can be displayed to the user in a GUI class

Attributes

ActionHierarchical
AllowLegendChangeState
AllowNodeChangeVisibility
AllowNodeRename
AllowNodeReorder
DeferredLegendInvalidation
ShowLegend
ShowLegendAsTree
UseEmbeddedWidgets
UseTextFormatting
UseThreadedHitTest

class qgis.core.QgsLayerTreeModel

Bases: QAbstractItemModel

__init__(rootNode: QgsLayerTree | None, parent: QObject | None = None)

Construct a new tree model with given layer tree (root node must not be None). The root node is not transferred by the model.

Parameters:

• rootNode (Optional[QgsLayerTree])

• parent (Optional[QObject] = None)

ActionHierarchical = 65536

AllowLegendChangeState = 32768

AllowNodeChangeVisibility = 16384

AllowNodeRename = 8192

AllowNodeReorder = 4096

DeferredLegendInvalidation = 8

class Flag

Bases: int

class Flags

class Flags(f: QgsLayerTreeModel.Flags | QgsLayerTreeModel.Flag)

class Flags(a0: QgsLayerTreeModel.Flags)

Bases: object

ShowLegend = 1

ShowLegendAsTree = 4

UseEmbeddedWidgets = 16

UseTextFormatting = 32

UseThreadedHitTest = 131072

addLegendToLayer(self, nodeL: QgsLayerTreeLayer | None)

Parameters:

nodeL (Optional[QgsLayerTreeLayer])

addTargetScreenProperties(self, properties: QgsScreenProperties)

Adds additional target screen properties to use when generating icons for Qt.DecorationRole data.

This allows icons to be generated at an icon device pixel ratio and DPI which corresponds exactly to the view’s screen properties in which this model is used.

Added in version 3.32.

Parameters:

properties (QgsScreenProperties)

autoCollapseLegendNodes(self) → int

Returns at what number of legend nodes the layer node should be collapsed. -1 means no auto-collapse (default).

Return type:

int

connectToLayer(self, nodeLayer: QgsLayerTreeLayer | None)

Parameters:

nodeLayer (Optional[QgsLayerTreeLayer])

connectToLayers(self, parentGroup: QgsLayerTreeGroup | None)

Parameters:

parentGroup (Optional[QgsLayerTreeGroup])

connectToRootNode(self)

currentIndex(self) → QModelIndex

Gets index of the item marked as current. Item marked as current is underlined.

Return type:

QModelIndex

disconnectFromLayer(self, nodeLayer: QgsLayerTreeLayer | None)

Parameters:

nodeLayer (Optional[QgsLayerTreeLayer])

disconnectFromLayers(self, parentGroup: QgsLayerTreeGroup | None)

Parameters:

parentGroup (Optional[QgsLayerTreeGroup])

disconnectFromRootNode(self)

filterLegendNodes(self, nodes: Iterable[QgsLayerTreeModelLegendNode]) → List[QgsLayerTreeModelLegendNode]

Filter nodes from QgsMapLayerLegend according to the current filtering rules

Parameters:

nodes (Iterable[QgsLayerTreeModelLegendNode])

Return type:

List[QgsLayerTreeModelLegendNode]

filterSettings(self) → QgsLayerTreeFilterSettings | None

Returns the filter settings to use to filter legend nodes. May be None.

See also

setFilterSettings()

Added in version 3.32.

Return type:

Optional[QgsLayerTreeFilterSettings]

findLegendNode(self, layerId: str | None, ruleKey: str | None) → QgsLayerTreeModelLegendNode | None

Searches through the layer tree to find a legend node with a matching layer ID and rule key.

Parameters:

• layerId (Optional[str]) – map layer ID

• ruleKey (Optional[str]) – legend node rule key

Return type:

Optional[QgsLayerTreeModelLegendNode]

Returns:

QgsLayerTreeModelLegendNode if found

virtual flags(self, index: QModelIndex) → Qt.ItemFlags

Parameters:

index (QModelIndex)

Return type:

Qt.ItemFlags

virtual flags(self) → QgsLayerTreeModel.Flags

Returns OR-ed combination of model flags

Return type:

QgsLayerTreeModel.Flags

signal hitTestCompleted

Emitted when a hit test for visible legend items completes.

See also

hitTestInProgress()

See also

hitTestStarted()

Added in version 3.32.

hitTestInProgress(self) → bool

Returns True if a hit test for visible legend items is currently in progress.

See also

hitTestStarted()

See also

hitTestCompleted()

Added in version 3.32.

Return type:

bool

signal hitTestStarted

Emitted when a hit test for visible legend items starts.

See also

hitTestInProgress()

See also

hitTestCompleted()

Added in version 3.32.

static iconGroup() → QIcon

Return type:

QIcon

static index2legendNode(index: QModelIndex) → QgsLayerTreeModelLegendNode | None

Returns legend node for given index. Returns None for invalid index

Parameters:

index (QModelIndex)

Return type:

Optional[QgsLayerTreeModelLegendNode]

index2node(self, index: QModelIndex) → QgsLayerTreeNode | None

Returns layer tree node for given index. Returns root node for invalid index. Returns None if index does not refer to a layer tree node (e.g. it is a legend node)

Parameters:

index (QModelIndex)

Return type:

Optional[QgsLayerTreeNode]

indexOfParentLayerTreeNode(self, parentNode: QgsLayerTreeNode | None) → QModelIndex

Parameters:

parentNode (Optional[QgsLayerTreeNode])

Return type:

QModelIndex

indexes2nodes(self, list: Iterable[QModelIndex], skipInternal: bool = False) → List[QgsLayerTreeNode]

Convert a list of indexes to a list of layer tree nodes. Indices that do not represent layer tree nodes are skipped. If skipInternal is True, a node is included in the output list only if no parent node is in the list.

Parameters:

• list (Iterable[QModelIndex])

• skipInternal (bool = False)

Return type:

List[QgsLayerTreeNode]

invalidateLegendMapBasedData(self)

layerFlagsChanged(self)

Triggered when layer flags have changed.

Added in version 3.18.

layerLegendChanged(self)

layerLegendNodes(self, nodeLayer: QgsLayerTreeLayer | None, skipNodeEmbeddedInParent: bool = False) → List[QgsLayerTreeModelLegendNode]

Returns filtered list of active legend nodes attached to a particular layer node (by default it returns also legend node embedded in parent layer node (if any) unless skipNodeEmbeddedInParent is True)

Note

Parameter skipNodeEmbeddedInParent added in QGIS 2.18

See also

layerOriginalLegendNodes()

Parameters:

• nodeLayer (Optional[QgsLayerTreeLayer])

• skipNodeEmbeddedInParent (bool = False)

Return type:

List[QgsLayerTreeModelLegendNode]

layerNeedsUpdate(self)

layerOriginalLegendNodes(self, nodeLayer: QgsLayerTreeLayer | None) → List[QgsLayerTreeModelLegendNode]

Returns original (unfiltered) list of legend nodes attached to a particular layer node

See also

layerLegendNodes()

Parameters:

nodeLayer (Optional[QgsLayerTreeLayer])

Return type:

List[QgsLayerTreeModelLegendNode]

layerStyleOverrides(self) → Dict[str, str]

Gets map of map layer style overrides (key: layer ID, value: style name) where a different style should be used instead of the current one

Return type:

Dict[str, str]

layerTreeNodeFont(self, nodeType: int) → QFont

Gets font for a particular type of layer tree node. nodeType should come from QgsLayerTreeNode.NodeType enumeration

Parameters:

nodeType (int)

Return type:

QFont

legendCleanup(self)

legendEmbeddedInParent(self, nodeLayer: QgsLayerTreeLayer | None) → bool

Parameters:

nodeLayer (Optional[QgsLayerTreeLayer])

Return type:

bool

legendFilterByScale(self) → float

Returns the scale which restricts the legend nodes which are visible. The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map. A scale <= 0 indicates that no scale filtering is being performed.

See also

setLegendFilterByScale()

Return type:

float

legendFilterMapSettings(self) → QgsMapSettings | None

Returns the current map settings used for the current legend filter (or None if none is enabled)

Return type:

Optional[QgsMapSettings]

legendIconEmbeddedInParent(self, nodeLayer: QgsLayerTreeLayer | None) → QIcon

Parameters:

nodeLayer (Optional[QgsLayerTreeLayer])

Return type:

QIcon

legendInvalidateMapBasedData(self)

legendMapViewData(self)

Gets hints about map view - to be used in legend nodes. Arguments that are not None will receive values. If there are no valid map view data (from previous call to setLegendMapViewData()), returned values are zeros.

legendNode2index(self, legendNode: QgsLayerTreeModelLegendNode | None) → QModelIndex

Returns index for a given legend node. If the legend node does not belong to the layer tree, the result is undefined. If the legend node is belongs to the tree but it is filtered out, invalid model index is returned.

Parameters:

legendNode (Optional[QgsLayerTreeModelLegendNode])

Return type:

QModelIndex

legendNodeData(self, node: QgsLayerTreeModelLegendNode | None, role: int) → Any

Parameters:

• node (Optional[QgsLayerTreeModelLegendNode])

• role (int)

Return type:

Any

legendNodeDataChanged(self)

legendNodeEmbeddedInParent(self, nodeLayer: QgsLayerTreeLayer | None) → QgsLayerTreeModelLegendNode | None

Returns legend node that may be embedded in parent (i.e. its icon will be used for layer’s icon).

Parameters:

nodeLayer (Optional[QgsLayerTreeLayer])

Return type:

Optional[QgsLayerTreeModelLegendNode]

legendNodeFlags(self, node: QgsLayerTreeModelLegendNode | None) → Qt.ItemFlags

Parameters:

node (Optional[QgsLayerTreeModelLegendNode])

Return type:

Qt.ItemFlags

legendNodeIndex(self, row: int, column: int, node: QgsLayerTreeModelLegendNode | None) → QModelIndex

Parameters:

• row (int)

• column (int)

• node (Optional[QgsLayerTreeModelLegendNode])

Return type:

QModelIndex

legendNodeRowCount(self, node: QgsLayerTreeModelLegendNode | None) → int

Parameters:

node (Optional[QgsLayerTreeModelLegendNode])

Return type:

int

legendParent(self, legendNode: QgsLayerTreeModelLegendNode | None) → QModelIndex

Parameters:

legendNode (Optional[QgsLayerTreeModelLegendNode])

Return type:

QModelIndex

legendRootIndex(self, row: int, column: int, nL: QgsLayerTreeLayer | None) → QModelIndex

Parameters:

• row (int)

• column (int)

• nL (Optional[QgsLayerTreeLayer])

Return type:

QModelIndex

legendRootRowCount(self, nL: QgsLayerTreeLayer | None) → int

Parameters:

nL (Optional[QgsLayerTreeLayer])

Return type:

int

signal messageEmitted(message: str, level: Qgis.MessageLevel = Qgis.MessageLevel.Info, duration: int = 5)

Emits a message than can be displayed to the user in a GUI class

Added in version 3.14.

Parameters:

• message (str)

• level (Qgis.MessageLevel = Qgis.MessageLevel.Info)

• duration (int = 5)

node2index(self, node: QgsLayerTreeNode | None) → QModelIndex

Returns index for a given node. If the node does not belong to the layer tree, the result is undefined

Parameters:

node (Optional[QgsLayerTreeNode])

Return type:

QModelIndex

nodeAddedChildren(self, node: QgsLayerTreeNode | None, indexFrom: int, indexTo: int)

Parameters:

• node (Optional[QgsLayerTreeNode])

• indexFrom (int)

• indexTo (int)

nodeCustomPropertyChanged(self, node: QgsLayerTreeNode | None, key: str | None)

Parameters:

• node (Optional[QgsLayerTreeNode])

• key (Optional[str])

nodeLayerLoaded(self)

nodeLayerWillBeUnloaded(self)

nodeNameChanged(self, node: QgsLayerTreeNode | None, name: str | None)

Updates model when node’s name has changed

Parameters:

• node (Optional[QgsLayerTreeNode])

• name (Optional[str])

nodeRemovedChildren(self)

nodeVisibilityChanged(self, node: QgsLayerTreeNode | None)

Parameters:

node (Optional[QgsLayerTreeNode])

nodeWillAddChildren(self, node: QgsLayerTreeNode | None, indexFrom: int, indexTo: int)

Parameters:

• node (Optional[QgsLayerTreeNode])

• indexFrom (int)

• indexTo (int)

nodeWillRemoveChildren(self, node: QgsLayerTreeNode | None, indexFrom: int, indexTo: int)

Parameters:

• node (Optional[QgsLayerTreeNode])

• indexFrom (int)

• indexTo (int)

recursivelyEmitDataChanged(self, index: QModelIndex = QModelIndex())

emit dataChanged() for layer tree node items

Parameters:

index (QModelIndex = QModelIndex())

refreshLayerLegend(self, nodeLayer: QgsLayerTreeLayer | None)

Force a refresh of legend nodes of a layer node. Not necessary to call when layer’s renderer is changed as the model listens to these events.

Parameters:

nodeLayer (Optional[QgsLayerTreeLayer])

refreshScaleBasedLayers(self, index: QModelIndex = QModelIndex(), previousScale: float = 0)

Updates layer data for scale dependent layers, should be called when map scale changes. Emits dataChanged() for all scale dependent layers.

Parameters:

• index (QModelIndex = QModelIndex())

• previousScale (float = 0)

removeLegendFromLayer(self, nodeLayer: QgsLayerTreeLayer | None)

Parameters:

nodeLayer (Optional[QgsLayerTreeLayer])

rootGroup(self) → QgsLayerTree | None

Returns pointer to the root node of the layer tree. Always a non None value.

Return type:

Optional[QgsLayerTree]

static scaleIconSize(standardSize: int) → int

Scales an layer tree model icon size to compensate for display pixel density, making the icon size hi-dpi friendly, whilst still resulting in pixel-perfect sizes for low-dpi displays.

standardSize should be set to a standard icon size, e.g. 16, 24, 48, etc.

Added in version 3.6.

Parameters:

standardSize (int)

Return type:

int

setAutoCollapseLegendNodes(self, nodeCount: int)

Sets at what number of legend nodes the layer node should be collapsed. Setting -1 disables the auto-collapse (default).

Parameters:

nodeCount (int)

setCurrentIndex(self, currentIndex: QModelIndex)

Sets index of the current item. May be used by view. Item marked as current is underlined.

Parameters:

currentIndex (QModelIndex)

setFilterSettings(self, settings: QgsLayerTreeFilterSettings | None = None)

Sets the filter settings to use to filter legend nodes.

Set to None to disable legend filter.

See also

filterSettings()

Added in version 3.32.

Parameters:

settings (Optional[QgsLayerTreeFilterSettings] = None)

setFlag(self, f: QgsLayerTreeModel.Flag, on: bool = True)

Enable or disable a model flag

Parameters:

• f (QgsLayerTreeModel.Flag)

• on (bool = True)

setFlags(self, f: QgsLayerTreeModel.Flags | QgsLayerTreeModel.Flag)

Sets OR-ed combination of model flags

Parameters:

f (Union[QgsLayerTreeModel.Flags, QgsLayerTreeModel.Flag])

setLayerStyleOverrides(self, overrides: Dict[str | None, str | None])

Sets map of map layer style overrides (key: layer ID, value: style name) where a different style should be used instead of the current one

Parameters:

overrides (Dict[Optional[str], Optional[str]])

setLayerTreeNodeFont(self, nodeType: int, font: QFont)

Sets font for a particular type of layer tree node. nodeType should come from QgsLayerTreeNode.NodeType enumeration

Parameters:

• nodeType (int)

• font (QFont)

setLegendFilter(self, settings: QgsMapSettings | None, useExtent: bool = True, polygon: QgsGeometry = QgsGeometry(), useExpressions: bool = True)

Filter display of legend nodes for given map settings

Parameters:

• settings (Optional[QgsMapSettings]) – Map settings. Setting None or invalid settings will disable any filter. Ownership is not changed, a copy is made

• useExtent (bool = True) – Whether to use the extent of the map settings as a first spatial filter on legend nodes

• polygon (QgsGeometry = QgsGeometry()) – If not empty, this polygon will be used instead of the map extent to filter legend nodes

• useExpressions (bool = True) – Whether to use legend node filter expressions

Deprecated since version 3.32: Use setFilterSettings() instead.

setLegendFilterByMap(self, settings: QgsMapSettings | None)

Force only display of legend nodes which are valid for given map settings. Setting None or invalid map settings will disable the functionality. Ownership of map settings pointer does not change, a copy is made.

Deprecated since version 3.32: Use setFilterSettings() instead.

Parameters:

settings (Optional[QgsMapSettings])

setLegendFilterByScale(self, scale: float)

Force only display of legend nodes which are valid for a given scale. The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map. Setting scale <= 0 will disable the functionality.

See also

legendFilterByScale()

Parameters:

scale (float)

setLegendMapViewData(self, mapUnitsPerPixel: float, dpi: int, scale: float)

Give the layer tree model hints about the currently associated map view so that legend nodes that use map units can be scaled correctly

Parameters:

• mapUnitsPerPixel (float)

• dpi (int)

• scale (float)

setRootGroup(self, newRootGroup: QgsLayerTree | None)

Reset the model and use a new root group node

Parameters:

newRootGroup (Optional[QgsLayerTree])

targetScreenProperties(self) → Set[QgsScreenProperties]

Returns the target screen properties to use when generating icons.

This allows icons to be generated at an icon device pixel ratio and DPI which corresponds exactly to the view’s screen properties in which this model is used.

See also

addTargetScreenProperties()

Added in version 3.32.

Return type:

Set[QgsScreenProperties]

testFlag(self, f: QgsLayerTreeModel.Flag) → bool

Check whether a flag is enabled

Parameters:

f (QgsLayerTreeModel.Flag)

Return type:

bool

waitForHitTestBlocking(self)

When a current hit test for visible legend items is in progress, calling this method will block until that hit test is complete.

Added in version 3.32.