Class: QgsLayoutItemLegend

class qgis.core.QgsLayoutItemLegend

Bases: QgsLayoutItem

A layout item subclass for map legends.

New in version 3.0.

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

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.

dropEvent

equalColumnWidth

Returns whether column widths should be equalized.

exportLayerBehavior

rtype

QgsLayoutItem.ExportLayerBehavior

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

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.

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.

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: Union[QPointF, QPoint], 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)
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

dropEvent(self, QGraphicsSceneDragDropEvent)
equalColumnWidth(self) bool

Returns whether column widths should be equalized.

Return type

bool

exportLayerBehavior(self) QgsLayoutItem.ExportLayerBehavior
Return type

QgsLayoutItem.ExportLayerBehavior

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

Returns the legend font color.

See also

setFontColor()

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

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.AllProperties)
Parameters

property (QgsLayoutObject.DataDefinedProperty = QgsLayoutObject.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: Union[QPointF, QPoint] = 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.

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

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: Union[QColor, Qt.GlobalColor, QGradient])

Sets the legend font color.

See also

fontColor()

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

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: Union[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()

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

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