Class: QgsLayerTreeModelLegendNode

An abstract interface for legend items returned from QgsMapLayerLegend implementation.

The objects are used in QgsLayerTreeModel. Custom implementations may offer additional interactivity and customized look.

Note

This is an abstract class, with methods which must be implemented by a subclass.

The following methods must be implemented: data()

Class Hierarchy

Inheritance diagram of qgis.core.QgsLayerTreeModelLegendNode

Base classes

QObject

Subclasses

QgsColorRampLegendNode

A legend node which renders a color ramp.

QgsDataDefinedSizeLegendNode

A legend node with a marker symbol.

QgsImageLegendNode

Implementation of legend node interface for displaying arbitrary raster images.

QgsRasterSymbolLegendNode

Implementation of legend node interface for displaying raster legend entries.

QgsSimpleLegendNode

Implementation of legend node interface for displaying arbitrary labels with icons.

QgsSymbolLegendNode

Implementation of legend node interface for displaying preview of vector symbols and their labels and allowing interaction with the symbol / renderer.

QgsVectorLabelLegendNode

A legend node for a labeling text symbol.

QgsWmsLegendNode

Implementation of legend node interface for displaying WMS legend entries.

Enums

CustomRole

Legend node data roles

LegendNodeRoles

alias of CustomRole

Abstract Methods

data

Returns data associated with the item.

Methods

checkAllItems

Checks all checkable items belonging to the same layer as this node.

createTemporaryRenderContext

Returns a temporary context or None if legendMapViewData are not valid

exportToJson

Entry point called from QgsLegendRenderer to do the rendering in a JSON object.

layerNode

Returns pointer to the parent layer node

model

Returns pointer to model owning this legend node

toggleAllItems

Toggle all checkable items belonging to the same layer as this node.

uncheckAllItems

Unchecks all checkable items belonging to the same layer as this node.

Virtual Methods

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

columnBreak

Returns whether a forced column break should occur before the node.

draw

Entry point called from QgsLegendRenderer to do the rendering.

drawSymbol

Draws symbol on the left side of the item

drawSymbolText

Draws label on the right side of the item

exportSymbolToJson

Adds a symbol in base64 string within a JSON object with the key "icon".

flags

Returns item flags associated with the item.

invalidateMapBasedData

Notification from model that information from associated map view has changed.

isEmbeddedInParent

isScaleOK

setColumnBreak

Sets whether a forced column break should occur before the node.

setData

Sets some data associated with the item.

setEmbeddedInParent

setUserLabel

setUserPatchSize

Sets the user (overridden) size for the legend node.

userLabel

userPatchSize

Returns the user (overridden) size for the legend node.

Signals

dataChanged

Emitted on internal data change so the layer tree model can forward the signal to views

sizeChanged

Emitted when the size of this node changes.

Attributes

ColorRampLegend

DataDefinedSizeLegend

EmbeddedWidget

ImageLegend

RasterSymbolLegend

SimpleLegend

SymbolLegend

WmsLegend

class qgis.core.QgsLayerTreeModelLegendNode[source]

Bases: QObject

__init__(nodeL: QgsLayerTreeLayer | None, parent: QObject | None = None)

Construct the node with pointer to its parent layer node

Parameters:
ColorRampLegend = 7
class CustomRole(*values)

Bases: IntEnum

Legend node data roles

Note

Prior to QGIS 3.36 this was available as QgsLayerTreeModelLegendNode.LegendNodeRoles

Added in version 3.36.

  • RuleKey: Rule key of the node (QString)

    Available as QgsLayerTreeModelLegendNode.RuleKeyRole in older QGIS releases.

  • ParentRuleKey: Rule key of the parent legend node - for legends with tree hierarchy (QString). Added in 2.8

    Available as QgsLayerTreeModelLegendNode.ParentRuleKeyRole in older QGIS releases.

  • NodeType: Type of node. Added in 3.16

    Available as QgsLayerTreeModelLegendNode.NodeTypeRole in older QGIS releases.

  • IsDataDefinedSize: Set when a node is related to data defined size (title or separated legend items). Added in 3.38

    Available as QgsLayerTreeModelLegendNode.IsDataDefinedSizeRole in older QGIS releases.

DataDefinedSizeLegend = 5
EmbeddedWidget = 6
ImageLegend = 3
class ItemContext
class ItemContext(a0: QgsLayerTreeModelLegendNode.ItemContext)

Bases: object

columnLeft: float

Left side of current legend column. This should be used when determining where to render legend item content, correctly respecting the symbol and text alignment from the legend settings.

Added in version 3.10.

columnRight: float

Right side of current legend column. This should be used when determining where to render legend item content, correctly respecting the symbol and text alignment from the legend settings.

Added in version 3.10.

context: QgsRenderContext

Render context, if available

labelXOffset: float

Offset from the left side where label should start.

Deprecated since version 3.40: Use columnLeft, columnRight instead.

maxSiblingSymbolWidth: float

Largest symbol width, considering all other sibling legend components associated with the current component.

Added in version 3.10.

painter: QPainter

Painter

patchShape: QgsLegendPatchShape

The patch shape to render for the node.

Added in version 3.14.

patchSize: QSizeF

Symbol patch size to render for the node.

If either the width or height are zero, then the default width/height from QgsLegendSettings.symbolSize() should be used instead.

Added in version 3.14.

point: QPointF

Top-left corner of the legend item.

Deprecated since version 3.40: Use top, columnLeft, columnRight instead.

screenProperties: QgsScreenProperties

Destination screen properties.

Added in version 3.32.

textDocument: QgsTextDocument

Optional text document

Added in version 3.30.

textDocumentMetrics: QgsTextDocumentMetrics

Optional text document metrics.

Added in version 3.30.

top: float

Top y-position of legend item.

Added in version 3.10.

class ItemMetrics
class ItemMetrics(a0: QgsLayerTreeModelLegendNode.ItemMetrics)

Bases: object

labelSize
symbolSize
LegendNodeRoles

alias of CustomRole

class NodeTypes

Bases: int

RasterSymbolLegend = 2
SimpleLegend = 0
SymbolLegend = 1
WmsLegend = 4
checkAllItems(self)[source]

Checks all checkable items belonging to the same layer as this node.

See also

toggleAllItems()

Added in version 3.18.

virtual columnBreak(self) bool[source]

Returns whether a forced column break should occur before the node.

See also

setColumnBreak()

Added in version 3.14.

Return type:

bool

createTemporaryRenderContext(self) QgsRenderContext | None[source]

Returns a temporary context or None if legendMapViewData are not valid

Return type:

Optional[QgsRenderContext]

abstract data(self, role: int) Any[source]

Returns data associated with the item. Must be implemented in derived class.

Parameters:

role (int)

Return type:

Any

signal dataChanged[source]

Emitted on internal data change so the layer tree model can forward the signal to views

virtual draw(self, settings: QgsLegendSettings, ctx: QgsLayerTreeModelLegendNode.ItemContext | None) QgsLayerTreeModelLegendNode.ItemMetrics[source]

Entry point called from QgsLegendRenderer to do the rendering. Default implementation calls drawSymbol() and drawSymbolText() methods.

If ctx is None, this is just first stage when preparing layout - without actual rendering.

Parameters:
Return type:

QgsLayerTreeModelLegendNode.ItemMetrics

virtual drawSymbol(self, settings: QgsLegendSettings, ctx: QgsLayerTreeModelLegendNode.ItemContext | None, itemHeight: float) QSizeF[source]

Draws symbol on the left side of the item

Parameters:
  • settings (QgsLegendSettings) – Legend layout configuration

  • ctx (Optional[QgsLayerTreeModelLegendNode.ItemContext]) – Context for rendering - may be None if only doing layout without actual rendering

  • itemHeight (float) – Minimal height of the legend item - used for correct positioning when rendering

Return type:

QSizeF

Returns:

Real size of the symbol (may be bigger than “normal” symbol size from settings)

virtual drawSymbolText(self, settings: QgsLegendSettings, ctx: QgsLayerTreeModelLegendNode.ItemContext | None, symbolSize: QSizeF) QSizeF[source]

Draws label on the right side of the item

Parameters:
  • settings (QgsLegendSettings) – Legend layout configuration

  • ctx (Optional[QgsLayerTreeModelLegendNode.ItemContext]) – Context for rendering - may be None if only doing layout without actual rendering

  • symbolSize (QSizeF) – Real size of the associated symbol - used for correct positioning when rendering

Return type:

QSizeF

Returns:

Size of the label (may span multiple lines)

virtual exportSymbolToJson(self, settings: QgsLegendSettings, context: QgsRenderContext) Dict[str, QJsonValue][source]

Adds a symbol in base64 string within a JSON object with the key “icon”.

Parameters:

Added in version 3.8.

Return type:

Dict[str, QJsonValue]

exportToJson(self, settings: QgsLegendSettings, context: QgsRenderContext) Dict[str, QJsonValue][source]

Entry point called from QgsLegendRenderer to do the rendering in a JSON object.

Parameters:

Added in version 3.8.

Return type:

Dict[str, QJsonValue]

virtual flags(self) Qt.ItemFlags[source]

Returns item flags associated with the item. Default implementation returns Qt.ItemIsEnabled.

Return type:

Qt.ItemFlags

virtual invalidateMapBasedData(self)[source]

Notification from model that information from associated map view has changed. Default implementation does nothing.

virtual isEmbeddedInParent(self) bool[source]
Return type:

bool

virtual isScaleOK(self, scale: float) bool[source]
Parameters:

scale (float)

Return type:

bool

layerNode(self) QgsLayerTreeLayer | None[source]

Returns pointer to the parent layer node

Return type:

Optional[QgsLayerTreeLayer]

model(self) QgsLayerTreeModel | None[source]

Returns pointer to model owning this legend node

Return type:

Optional[QgsLayerTreeModel]

virtual setColumnBreak(self, breakBeforeNode: bool)[source]

Sets whether a forced column break should occur before the node.

See also

columnBreak()

Added in version 3.14.

Parameters:

breakBeforeNode (bool)

virtual setData(self, value: Any, role: int) bool[source]

Sets some data associated with the item. Default implementation does nothing and returns False.

Parameters:
  • value (Any)

  • role (int)

Return type:

bool

virtual setEmbeddedInParent(self, embedded: bool)[source]
Parameters:

embedded (bool)

virtual setUserLabel(self, userLabel: str | None)[source]
Parameters:

userLabel (Optional[str])

virtual setUserPatchSize(self, size: QSizeF)[source]

Sets the user (overridden) size for the legend node.

If either the width or height are non-zero, they will be used when rendering the legend node instead of the default symbol width or height from QgsLegendSettings.

See also

userPatchSize()

Added in version 3.14.

Parameters:

size (QSizeF)

signal sizeChanged[source]

Emitted when the size of this node changes.

Added in version 3.16.

toggleAllItems(self)[source]

Toggle all checkable items belonging to the same layer as this node.

See also

checkAllItems()

Added in version 3.18.

uncheckAllItems(self)[source]

Unchecks all checkable items belonging to the same layer as this node.

See also

checkAllItems()

See also

toggleAllItems()

Added in version 3.18.

virtual userLabel(self) str[source]
Return type:

str

virtual userPatchSize(self) QSizeF[source]

Returns the user (overridden) size for the legend node.

If either the width or height are non-zero, they will be used when rendering the legend node instead of the default symbol width or height from QgsLegendSettings.

Added in version 3.14.

Return type:

QSizeF