Class: QgsLayoutItemLegend

class qgis.core.QgsLayoutItemLegend

Bases: QgsLayoutItem

A layout item subclass for map legends.

QgsLayoutItemLegend(layout: QgsLayout) Constructor for QgsLayoutItemLegend, with the specified parent layout.

Methods

accept

param visitor:

adjustBoxSize

Sets the legend's item bounds to fit the whole legend content.

adjustPointForReferencePosition

Adjusts the specified point at which a reference position of the item sits and returns the top left corner of the item, if reference point were placed at the specified position.

applyDataDefinedSize

Applies any present data defined size overrides to the specified layout size.

applyItemSizeConstraint

Applies any item-specific size constraint handling to a given targetSize in layout units.

autoUpdateModel

Returns whether the legend content should auto update to reflect changes in the project's layer tree.

boxSpace

Returns the legend box space.

childEvent

columnCount

Returns the legend column count.

columnSpace

Returns the legend column spacing.

connectNotify

containsAdvancedEffects

rtype:

bool

contextMenuEvent

create

Returns a new legend item for the specified layout.

createExpressionContext

rtype:

QgsExpressionContext

customEvent

disconnectNotify

displayName

rtype:

str

dragEnterEvent

dragLeaveEvent

dragMoveEvent

draw

param context:

drawBackground

Draws the background for the item.

drawDebugRect

Draws a debugging rectangle of the item's current bounds within the specified painter.

drawFrame

Draws the frame around the item.

drawRasterStroke

Returns whether a stroke will be drawn around raster symbol items.

drawRefreshingOverlay

Draws a "refreshing" overlay icon on the item.

dropEvent

equalColumnWidth

Returns whether column widths should be equalized.

exportLayerBehavior

rtype:

QgsLayoutItem.ExportLayerBehavior

filterByMapItems

Returns the maps to use when filtering legend content by map extents.

finalizeRestoreFromXml

focusInEvent

focusOutEvent

fontColor

Returns the legend font color.

framePath

Returns the path to use when drawing the item's frame or background.

hoverEnterEvent

hoverLeaveEvent

hoverMoveEvent

icon

rtype:

QIcon

inputMethodEvent

inputMethodQuery

invalidateCache

isRefreshing

rtype:

bool

isSignalConnected

itemChange

itemFlags

rtype:

QgsLayoutItem.Flags

keyPressEvent

keyReleaseEvent

legendFilterByMapEnabled

Find out whether legend items are filtered to show just the ones visible in the associated map

legendFilterOutAtlas

Returns whether to filter out legend elements outside of the current atlas feature.

legendSettings

Returns the legend's renderer settings object.

lineSpacing

Returns the spacing in-between lines in layout units.

linkedMap

Returns the associated map.

maximumSymbolSize

Returns the maximum symbol size (in mm).

minimumSymbolSize

Returns the minimum symbol size (in mm).

model

Returns the legend model.

mouseDoubleClickEvent

mouseMoveEvent

mousePressEvent

mouseReleaseEvent

paint

param painter:

positionAtReferencePoint

Returns the current position (in layout units) of a reference point for the item.

prepareGeometryChange

rasterStrokeColor

Returns the stroke color for the stroke drawn around raster symbol items.

rasterStrokeWidth

Returns the stroke width (in layout units) for the stroke drawn around raster symbol items.

readObjectPropertiesFromElement

Sets object properties from a DOM element

readPropertiesFromElement

param element:

receivers

refresh

refreshBackgroundColor

Refresh item's background color, considering data defined colors.

refreshBlendMode

Refresh item's blend mode, considering data defined blend mode.

refreshDataDefinedProperty

param property:

refreshFrame

Refresh item's frame, considering data defined colors and frame size.

refreshItemPosition

Refreshes an item's position by rechecking it against any possible overrides such as data defined positioning.

refreshItemRotation

Refreshes an item's rotation by rechecking it against any possible overrides such as data defined rotation.

refreshItemSize

Refreshes an item's size by rechecking it against any possible item fixed or minimum sizes.

refreshOpacity

Refresh item's opacity, considering data defined opacity.

requiresRasterization

rtype:

bool

resizeToContents

Returns whether the legend should automatically resize to fit its contents.

rstyle

Returns reference to modifiable legend style.

sceneEvent

sceneEventFilter

sender

senderSignalIndex

setAutoUpdateModel

Sets whether the legend content should auto update to reflect changes in the project's layer tree.

setBoxSpace

Sets the legend box space.

setColumnCount

Sets the legend column count.

setColumnSpace

Sets the legend column spacing.

setDrawRasterStroke

Sets whether a stroke will be drawn around raster symbol items.

setEqualColumnWidth

Sets whether column widths should be equalized.

setFilterByMapItems

Sets the maps to use when filtering legend content by map extents.

setFixedSize

Sets a fixed size for the layout item, which prevents it from being freely resized.

setFontColor

Sets the legend font color.

setLegendFilterByMapEnabled

Set whether legend items should be filtered to show just the ones visible in the associated map.

setLegendFilterOutAtlas

When set to True, during an atlas rendering, it will filter out legend elements where features are outside the current atlas feature.

setLineSpacing

Sets the spacing in-between multiple lines.

setLinkedMap

Sets the map to associate with the legend.

setMaximumSymbolSize

Set the maximum symbol size for symbol (in millimeters).

setMinimumSize

Sets the minimum allowed size for the layout item.

setMinimumSymbolSize

Set the minimum symbol size for symbol (in millimeters).

setRasterStrokeColor

Sets the stroke color for the stroke drawn around raster symbol items.

setRasterStrokeWidth

Sets the stroke width for the stroke drawn around raster symbol items.

setResizeToContents

Sets whether the legend should automatically resize to fit its contents.

setSplitLayer

Sets whether the legend items from a single layer can be split over multiple columns.

setStyle

Sets the style of component to style for the legend.

setStyleFont

Sets the style font for a legend component.

setStyleMargin

Set the margin for a legend component.

setSymbolAlignment

Sets the alignment for placement of legend symbols.

setSymbolHeight

Sets the legend symbol height.

setSymbolWidth

Sets the legend symbol width.

setTitle

Sets the legend title.

setTitleAlignment

Sets the alignment of the legend title.

setWmsLegendHeight

Sets the WMS legend height.

setWmsLegendWidth

Sets the WMS legend width.

setWrapString

Sets the legend text wrapping string.

splitLayer

Returns whether the legend items from a single layer can be split over multiple columns.

style

Returns legend style.

styleFont

Returns the font settings for a legend component.

symbolAlignment

Returns the alignment for placement of legend symbols.

symbolHeight

Returns the legend symbol height.

symbolWidth

Returns the legend symbol width.

themeName

Returns the name of the theme currently linked to the legend.

timerEvent

title

Returns the legend title.

titleAlignment

Returns the alignment of the legend title.

topLeftToReferencePoint

Returns the position for the reference point of the item, if the top-left of the item was placed at the specified point.

type

rtype:

int

updateFilterByMap

Updates the legend content when filtered by map.

updateLegend

Updates the model and all legend entries.

updateMicroFocus

wheelEvent

wmsLegendHeight

Returns the WMS legend height.

wmsLegendWidth

Returns the WMS legend width.

wrapString

Returns the legend text wrapping string.

writeObjectPropertiesToElement

Stores object properties within an XML DOM element.

writePropertiesToElement

param element:

accept(self, visitor: QgsStyleEntityVisitorInterface) bool
Parameters:

visitor (QgsStyleEntityVisitorInterface) –

Return type:

bool

adjustBoxSize(self)

Sets the legend’s item bounds to fit the whole legend content.

adjustPointForReferencePosition(self, point: QPointF | QPoint | float, size: QSizeF, reference: QgsLayoutItem.ReferencePoint) QPointF

Adjusts the specified point at which a reference position of the item sits and returns the top left corner of the item, if reference point were placed at the specified position.

applyDataDefinedSize(self, size: QgsLayoutSize) QgsLayoutSize

Applies any present data defined size overrides to the specified layout size.

applyItemSizeConstraint(self, targetSize: QSizeF) QSizeF

Applies any item-specific size constraint handling to a given targetSize in layout units. Subclasses can override this method if they need to apply advanced logic regarding item sizes, which cannot be covered by setFixedSize() or setMinimumSize(). Item size constraints are applied after fixed, minimum and data defined size constraints.

See also

setFixedSize()

See also

setMinimumSize()

autoUpdateModel(self) bool

Returns whether the legend content should auto update to reflect changes in the project’s layer tree.

Return type:

bool

boxSpace(self) float

Returns the legend box space.

See also

setBoxSpace()

Return type:

float

childEvent(self, QChildEvent)
columnCount(self) int

Returns the legend column count.

See also

setColumnCount()

Return type:

int

columnSpace(self) float

Returns the legend column spacing.

See also

setColumnSpace()

Return type:

float

connectNotify(self, QMetaMethod)
containsAdvancedEffects(self) bool
Return type:

bool

contextMenuEvent(self, QGraphicsSceneContextMenuEvent)
create(layout: QgsLayout) QgsLayoutItemLegend

Returns a new legend item for the specified layout.

The caller takes responsibility for deleting the returned object.

Parameters:

layout (QgsLayout) –

Return type:

QgsLayoutItemLegend

createExpressionContext(self) QgsExpressionContext
Return type:

QgsExpressionContext

customEvent(self, QEvent)
disconnectNotify(self, QMetaMethod)
displayName(self) str
Return type:

str

dragEnterEvent(self, QGraphicsSceneDragDropEvent)
dragLeaveEvent(self, QGraphicsSceneDragDropEvent)
dragMoveEvent(self, QGraphicsSceneDragDropEvent)
draw(self, context: QgsLayoutItemRenderContext)
Parameters:

context (QgsLayoutItemRenderContext) –

drawBackground(self, context: QgsRenderContext)

Draws the background for the item.

See also

framePath()

drawDebugRect(self, painter: QPainter)

Draws a debugging rectangle of the item’s current bounds within the specified painter.

Parameters:

painter – destination QPainter

drawFrame(self, context: QgsRenderContext)

Draws the frame around the item.

See also

framePath()

drawRasterStroke(self) bool

Returns whether a stroke will be drawn around raster symbol items.

Return type:

bool

drawRefreshingOverlay(self, painter: QPainter, itemStyle: QStyleOptionGraphicsItem)

Draws a “refreshing” overlay icon on the item.

New in version 3.32.

dropEvent(self, QGraphicsSceneDragDropEvent)
equalColumnWidth(self) bool

Returns whether column widths should be equalized.

Return type:

bool

exportLayerBehavior(self) QgsLayoutItem.ExportLayerBehavior
Return type:

QgsLayoutItem.ExportLayerBehavior

filterByMapItems(self) List[QgsLayoutItemMap]

Returns the maps to use when filtering legend content by map extents.

See also

setLinkedMap()

New in version 3.32.

Return type:

List[QgsLayoutItemMap]

finalizeRestoreFromXml(self)
focusInEvent(self, QFocusEvent)
focusOutEvent(self, QFocusEvent)
fontColor(self) QColor

Returns the legend font color.

See also

setFontColor()

Deprecated since version use: QgsLegendStyle.setTextFormat() from style() instead.

Return type:

QColor

framePath(self) QPainterPath

Returns the path to use when drawing the item’s frame or background.

See also

drawFrame()

See also

drawBackground()

New in version 3.16.

hoverEnterEvent(self, QGraphicsSceneHoverEvent)
hoverLeaveEvent(self, QGraphicsSceneHoverEvent)
hoverMoveEvent(self, QGraphicsSceneHoverEvent)
icon(self) QIcon
Return type:

QIcon

inputMethodEvent(self, QInputMethodEvent)
inputMethodQuery(self, Qt.InputMethodQuery) Any
invalidateCache(self)
isRefreshing(self) bool
Return type:

bool

isSignalConnected(self, QMetaMethod) bool
itemChange(self, QGraphicsItem.GraphicsItemChange, Any) Any
itemFlags(self) QgsLayoutItem.Flags
Return type:

QgsLayoutItem.Flags

keyPressEvent(self, QKeyEvent)
keyReleaseEvent(self, QKeyEvent)
legendFilterByMapEnabled(self) bool

Find out whether legend items are filtered to show just the ones visible in the associated map

Return type:

bool

legendFilterOutAtlas(self) bool

Returns whether to filter out legend elements outside of the current atlas feature.

Return type:

bool

legendSettings(self) QgsLegendSettings

Returns the legend’s renderer settings object.

Return type:

QgsLegendSettings

lineSpacing(self) float

Returns the spacing in-between lines in layout units.

See also

setLineSpacing()

Deprecated since version use: QgsLegendStyle.textFormat() from style() instead.

Return type:

float

linkedMap(self) QgsLayoutItemMap

Returns the associated map.

See also

setLinkedMap()

Return type:

QgsLayoutItemMap

maximumSymbolSize(self) float

Returns the maximum symbol size (in mm). 0.0 means there is no maximum set.

New in version 3.16.

Return type:

float

minimumSymbolSize(self) float

Returns the minimum symbol size (in mm). A value 0.0 means there is no minimum set.

New in version 3.16.

Return type:

float

model(self) QgsLegendModel

Returns the legend model.

Return type:

QgsLegendModel

mouseDoubleClickEvent(self, QGraphicsSceneMouseEvent)
mouseMoveEvent(self, QGraphicsSceneMouseEvent)
mousePressEvent(self, QGraphicsSceneMouseEvent)
mouseReleaseEvent(self, QGraphicsSceneMouseEvent)
paint(self, painter: QPainter, itemStyle: QStyleOptionGraphicsItem, pWidget: QWidget)
Parameters:
  • painter (QPainter) –

  • itemStyle (QStyleOptionGraphicsItem) –

  • pWidget (QWidget) –

positionAtReferencePoint(self, reference: QgsLayoutItem.ReferencePoint) QPointF

Returns the current position (in layout units) of a reference point for the item.

prepareGeometryChange(self)
rasterStrokeColor(self) QColor

Returns the stroke color for the stroke drawn around raster symbol items. The stroke is only drawn if drawRasterStroke() is True.

Return type:

QColor

rasterStrokeWidth(self) float

Returns the stroke width (in layout units) for the stroke drawn around raster symbol items. The stroke is only drawn if drawRasterStroke() is True.

Return type:

float

readObjectPropertiesFromElement(self, parentElement: QDomElement, document: QDomDocument, context: QgsReadWriteContext) bool

Sets object properties from a DOM element

Parameters:
  • parentElement – is the parent DOM element for the object

  • document – DOM document

  • context – read write context

Returns:

True if read was successful

readPropertiesFromElement(self, element: QDomElement, document: QDomDocument, context: QgsReadWriteContext) bool
Parameters:
Return type:

bool

receivers(self, PYQT_SIGNAL) int
refresh(self)
refreshBackgroundColor(self, updateItem: bool = True)

Refresh item’s background color, considering data defined colors. If updateItem is set to False, the item will not be automatically updated after the frame color is set and a later call to update() must be made.

refreshBlendMode(self)

Refresh item’s blend mode, considering data defined blend mode.

refreshDataDefinedProperty(self, property: QgsLayoutObject.DataDefinedProperty = QgsLayoutObject.DataDefinedProperty.AllProperties)
Parameters:

property (QgsLayoutObject.DataDefinedProperty = QgsLayoutObject.DataDefinedProperty.AllProperties) –

refreshFrame(self, updateItem: bool = True)

Refresh item’s frame, considering data defined colors and frame size. If updateItem is set to False, the item will not be automatically updated after the frame is set and a later call to update() must be made.

refreshItemPosition(self)

Refreshes an item’s position by rechecking it against any possible overrides such as data defined positioning.

refreshItemRotation(self, origin: QPointF | QPoint | float = None)

Refreshes an item’s rotation by rechecking it against any possible overrides such as data defined rotation.

The optional origin point specifies the origin (in item coordinates) around which the rotation should be applied.

refreshItemSize(self)

Refreshes an item’s size by rechecking it against any possible item fixed or minimum sizes.

See also

setFixedSize()

See also

setMinimumSize()

refreshOpacity(self, updateItem: bool = True)

Refresh item’s opacity, considering data defined opacity. If updateItem is set to False the item will not be automatically updated after the opacity is set and a later call to update() must be made.

requiresRasterization(self) bool
Return type:

bool

resizeToContents(self) bool

Returns whether the legend should automatically resize to fit its contents.

Return type:

bool

rstyle(self, s: QgsLegendStyle.Style) QgsLegendStyle

Returns reference to modifiable legend style.

Parameters:

s (QgsLegendStyle.Style) –

Return type:

QgsLegendStyle

sceneEvent(self, QEvent) bool
sceneEventFilter(self, QGraphicsItem, QEvent) bool
sender(self) QObject
senderSignalIndex(self) int
setAutoUpdateModel(self, autoUpdate: bool)

Sets whether the legend content should auto update to reflect changes in the project’s layer tree.

Parameters:

autoUpdate (bool) –

setBoxSpace(self, space: float)

Sets the legend box space.

See also

boxSpace()

Parameters:

space (float) –

setColumnCount(self, count: int)

Sets the legend column count.

See also

columnCount()

Parameters:

count (int) –

setColumnSpace(self, spacing: float)

Sets the legend column spacing.

See also

columnSpace()

Parameters:

spacing (float) –

setDrawRasterStroke(self, enabled: bool)

Sets whether a stroke will be drawn around raster symbol items.

Parameters:

enabled (bool) – set to True to draw borders

setEqualColumnWidth(self, equalize: bool)

Sets whether column widths should be equalized.

Parameters:

equalize (bool) –

setFilterByMapItems(self, maps: Iterable[QgsLayoutItemMap])

Sets the maps to use when filtering legend content by map extents.

See also

setLinkedMap()

New in version 3.32.

Parameters:

maps (Iterable[QgsLayoutItemMap]) –

setFixedSize(self, size: QgsLayoutSize)

Sets a fixed size for the layout item, which prevents it from being freely resized. Set an empty size if item can be freely resized.

See also

fixedSize()

See also

setMinimumSize()

setFontColor(self, color: QColor | Qt.GlobalColor | QGradient)

Sets the legend font color.

See also

fontColor()

Deprecated since version use: QgsLegendStyle.setTextFormat() from style() instead.

Parameters:

color (Union[QColor) –

setLegendFilterByMapEnabled(self, enabled: bool)

Set whether legend items should be filtered to show just the ones visible in the associated map.

Parameters:

enabled (bool) –

setLegendFilterOutAtlas(self, doFilter: bool)

When set to True, during an atlas rendering, it will filter out legend elements where features are outside the current atlas feature.

Parameters:

doFilter (bool) –

setLineSpacing(self, spacing: float)

Sets the spacing in-between multiple lines.

See also

lineSpacing()

Deprecated since version use: QgsLegendStyle.setTextFormat() from style() instead.

Parameters:

spacing (float) –

setLinkedMap(self, map: QgsLayoutItemMap)

Sets the map to associate with the legend.

See also

linkedMap()

Parameters:

map (QgsLayoutItemMap) –

setMaximumSymbolSize(self, size: float)

Set the maximum symbol size for symbol (in millimeters).

A symbol size of 0.0 indicates no maximum is set.

New in version 3.16.

Parameters:

size (float) –

setMinimumSize(self, size: QgsLayoutSize)

Sets the minimum allowed size for the layout item. Set an empty size if item can be freely resized.

See also

minimumSize()

See also

setFixedSize()

setMinimumSymbolSize(self, size: float)

Set the minimum symbol size for symbol (in millimeters).

A symbol size of 0.0 indicates no minimum is set.

New in version 3.16.

Parameters:

size (float) –

setRasterStrokeColor(self, color: QColor | Qt.GlobalColor | QGradient)

Sets the stroke color for the stroke drawn around raster symbol items. The stroke is only drawn if drawRasterStroke() is True.

Parameters:

color (Union[QColor) –

setRasterStrokeWidth(self, width: float)

Sets the stroke width for the stroke drawn around raster symbol items. The stroke is only drawn if drawRasterStroke() is True.

Parameters:

width (float) –

setResizeToContents(self, enabled: bool)

Sets whether the legend should automatically resize to fit its contents.

Parameters:

enabled (bool) – set to False to disable automatic resizing. The legend frame will not be expanded to fit legend items, and items may be cropped from display.

setSplitLayer(self, enabled: bool)

Sets whether the legend items from a single layer can be split over multiple columns.

See also

splitLayer()

Parameters:

enabled (bool) –

setStyle(self, component: QgsLegendStyle.Style, style: QgsLegendStyle)

Sets the style of component to style for the legend.

Parameters:
setStyleFont(self, component: QgsLegendStyle.Style, font: QFont)

Sets the style font for a legend component.

See also

styleFont()

Deprecated since version use: QgsLegendStyle.setTextFormat() from style() instead.

Parameters:
setStyleMargin(self, component: QgsLegendStyle.Style, margin: float)

Set the margin for a legend component.

setStyleMargin(self, component: QgsLegendStyle.Style, side: QgsLegendStyle.Side, margin: float) Set the margin for a particular side of a legend component.

Parameters:
setSymbolAlignment(self, alignment: Qt.AlignmentFlag)

Sets the alignment for placement of legend symbols.

Only Qt.AlignLeft or Qt.AlignRight are supported values.

New in version 3.10.

Parameters:

alignment (Qt.AlignmentFlag) –

setSymbolHeight(self, height: float)

Sets the legend symbol height.

See also

symbolHeight()

Parameters:

height (float) –

setSymbolWidth(self, width: float)

Sets the legend symbol width.

See also

symbolWidth()

Parameters:

width (float) –

setTitle(self, title: str)

Sets the legend title.

See also

title()

Parameters:

title (str) –

setTitleAlignment(self, alignment: Qt.AlignmentFlag)

Sets the alignment of the legend title.

See also

titleAlignment()

Parameters:

alignment (Qt.AlignmentFlag) –

setWmsLegendHeight(self, height: float)

Sets the WMS legend height.

Parameters:

height (float) –

setWmsLegendWidth(self, width: float)

Sets the WMS legend width.

See also

wmsLegendWidth()

Parameters:

width (float) –

setWrapString(self, string: str)

Sets the legend text wrapping string.

See also

wrapString()

Parameters:

string (str) –

splitLayer(self) bool

Returns whether the legend items from a single layer can be split over multiple columns.

See also

setSplitLayer()

Return type:

bool

style(self, s: QgsLegendStyle.Style) QgsLegendStyle

Returns legend style.

Parameters:

s (QgsLegendStyle.Style) –

Return type:

QgsLegendStyle

styleFont(self, component: QgsLegendStyle.Style) QFont

Returns the font settings for a legend component.

See also

setStyleFont()

Deprecated since version use: QgsLegendStyle.textFormat() from style() instead.

Parameters:

component (QgsLegendStyle.Style) –

Return type:

QFont

symbolAlignment(self) Qt.AlignmentFlag

Returns the alignment for placement of legend symbols.

Only Qt.AlignLeft or Qt.AlignRight are supported values.

New in version 3.10.

Return type:

Qt.AlignmentFlag

symbolHeight(self) float

Returns the legend symbol height.

Return type:

float

symbolWidth(self) float

Returns the legend symbol width.

See also

setSymbolWidth()

Return type:

float

themeName(self) str

Returns the name of the theme currently linked to the legend.

This usually equates to the theme rendered in the linkedMap().

New in version 3.14.

Return type:

str

timerEvent(self, QTimerEvent)
title(self) str

Returns the legend title.

See also

setTitle()

Return type:

str

titleAlignment(self) Qt.AlignmentFlag

Returns the alignment of the legend title.

Return type:

Qt.AlignmentFlag

topLeftToReferencePoint(self, point: QgsLayoutPoint) QgsLayoutPoint

Returns the position for the reference point of the item, if the top-left of the item was placed at the specified point.

type(self) int
Return type:

int

updateFilterByMap(self, redraw: bool = True)

Updates the legend content when filtered by map.

Parameters:

redraw (bool = True) –

updateLegend(self)

Updates the model and all legend entries.

updateMicroFocus(self)
wheelEvent(self, QGraphicsSceneWheelEvent)
wmsLegendHeight(self) float

Returns the WMS legend height.

Return type:

float

wmsLegendWidth(self) float

Returns the WMS legend width.

Return type:

float

wrapString(self) str

Returns the legend text wrapping string.

See also

setWrapString()

Return type:

str

writeObjectPropertiesToElement(self, parentElement: QDomElement, document: QDomDocument, context: QgsReadWriteContext) bool

Stores object properties within an XML DOM element.

Parameters:
  • parentElement – is the parent DOM element to store the object’s properties in

  • document – DOM document

  • context – read write context

Returns:

True if write was successful

writePropertiesToElement(self, element: QDomElement, document: QDomDocument, context: QgsReadWriteContext) bool
Parameters:
Return type:

bool