Class: QgsLayoutItemLegend

class qgis.core.QgsLayoutItemLegend(layout: QgsLayout)

Bases: QgsLayoutItem

Constructor for QgsLayoutItemLegend, with the specified parent layout.

A layout item subclass for map legends.

New in version 3.0.

Parameters

layout

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