Class: QgsLayoutItemLegend¶

A layout item subclass for map legends.

Class Hierarchy¶

Base classes¶

`QgsLayoutItem`	Base class for graphical items within a `QgsLayout`.
`QgsLayoutObject`	A base class for objects which belong to a layout.
QObject
`QgsExpressionContextGenerator`	Abstract interface for generating an expression context.
QGraphicsRectItem
QAbstractGraphicsShapeItem
QGraphicsItem
`QgsLayoutUndoObjectInterface`	Interface for layout objects which support undo/redo commands.

Methods

`adjustBoxSize`	Sets the legend's item bounds to fit the whole legend content.
`autoUpdateModel`	Returns whether the legend content should auto update to reflect changes in the project's layer tree.
`autoWrapLinesAfter`	Returns the maximum line length (in millimeters) allowed before lines of text in the legend will be automatically word wrapped.
`boxSpace`	Returns the legend box space.
`columnCount`	Returns the legend column count.
`columnSpace`	Returns the legend column spacing.
`drawRasterStroke`	Returns whether a stroke will be drawn around raster symbol items.
`equalColumnWidth`	Returns whether column widths should be equalized.
`filterByMapItems`	Returns the maps to use when filtering legend content by map extents.
`fontColor`	Returns the legend font color.
`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.
`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.
`resizeToContents`	Returns whether the legend should automatically resize to fit its contents.
`rstyle`	Returns reference to modifiable legend style.
`setAutoUpdateModel`	Sets whether the legend content should auto update to reflect changes in the project's layer tree.
`setAutoWrapLinesAfter`	Sets the maximum line length (in millimeters) allowed before lines of text in the legend will be automatically word wrapped.
`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.
`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).
`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.
`title`	Returns the legend title.
`titleAlignment`	Returns the alignment of the legend title.
`updateFilterByMap`	Updates the legend content when filtered by map.
`updateLegend`	Updates the model and all legend entries.
`wmsLegendHeight`	Returns the WMS legend height.
`wmsLegendWidth`	Returns the WMS legend width.
`wrapString`	Returns the legend text wrapping string.

Static Methods

create

Returns a new legend item for the specified layout.

class qgis.core.QgsLayoutItemLegend[source]¶

Bases: QgsLayoutItem

__init__(layout: QgsLayout | None)

Constructor for QgsLayoutItemLegend, with the specified parent layout.

Parameters:: layout (Optional[QgsLayout])

adjustBoxSize(self)[source]¶: Sets the legend’s item bounds to fit the whole legend content.

autoUpdateModel(self) → bool[source]¶

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

See also

setAutoUpdateModel()

Return type:: bool

autoWrapLinesAfter(self) → float[source]¶

Returns the maximum line length (in millimeters) allowed before lines of text in the legend will be automatically word wrapped.

If the returned value is 0, then no automatic wrapping will occur.

See also

setAutoWrapLinesAfter()

Added in version 3.44.

Return type:: float

boxSpace(self) → float[source]¶

Returns the legend box space.

See also

setBoxSpace()

Return type:: float

columnCount(self) → int[source]¶

Returns the legend column count.

See also

setColumnCount()

Return type:: int

columnSpace(self) → float[source]¶

Returns the legend column spacing.

See also

setColumnSpace()

Return type:: float

static create(layout: QgsLayout | None) → QgsLayoutItemLegend | None[source]¶

Returns a new legend item for the specified layout.

The caller takes responsibility for deleting the returned object.

Parameters:: layout (Optional[QgsLayout])
Return type:: Optional[QgsLayoutItemLegend]

drawRasterStroke(self) → bool[source]¶

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

See also

setDrawRasterStroke()

See also

rasterStrokeColor()

See also

rasterStrokeWidth()

Return type:: bool

equalColumnWidth(self) → bool[source]¶

Returns whether column widths should be equalized.

See also

setEqualColumnWidth()

Return type:: bool

filterByMapItems(self) → List[QgsLayoutItemMap]¶

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

See also

setFilterByMapItems()

See also

setLinkedMap()

Added in version 3.32.

Return type:: List[QgsLayoutItemMap]

fontColor(self) → QColor[source]¶

Returns the legend font color.

See also

setFontColor()

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

Return type:: QColor

legendFilterByMapEnabled(self) → bool[source]¶

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

See also

setLegendFilterByMapEnabled()

Return type:: bool

legendFilterOutAtlas(self) → bool[source]¶

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

See also

setLegendFilterOutAtlas()

Return type:: bool

legendSettings(self) → QgsLegendSettings¶

Returns the legend’s renderer settings object.

Return type:: QgsLegendSettings

lineSpacing(self) → float[source]¶

Returns the spacing in-between lines in layout units.

See also

setLineSpacing()

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

Return type:: float

linkedMap(self) → QgsLayoutItemMap | None[source]¶

Returns the associated map.

See also

setLinkedMap()

Return type:: Optional[QgsLayoutItemMap]

maximumSymbolSize(self) → float[source]¶

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

See also

setMaximumSymbolSize()

Added in version 3.16.

Return type:: float

minimumSymbolSize(self) → float[source]¶

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

See also

setMinimumSymbolSize()

Added in version 3.16.

Return type:: float

model(self) → QgsLegendModel | None[source]¶

Returns the legend model.

Return type:: Optional[QgsLegendModel]

rasterStrokeColor(self) → QColor[source]¶

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

See also

setRasterStrokeColor()

See also

drawRasterStroke()

See also

rasterStrokeWidth()

Return type:: QColor

rasterStrokeWidth(self) → float[source]¶

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

See also

setRasterStrokeWidth()

See also

drawRasterStroke()

See also

rasterStrokeColor()

Return type:: float

resizeToContents(self) → bool[source]¶

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

See also

setResizeToContents()

Return type:: bool

rstyle(self, s: Qgis.LegendComponent) → QgsLegendStyle¶

Returns reference to modifiable legend style.

Parameters:: s (Qgis.LegendComponent)
Return type:: QgsLegendStyle

setAutoUpdateModel(self, autoUpdate: bool)[source]¶

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

See also

autoUpdateModel()

Parameters:: autoUpdate (bool)

setAutoWrapLinesAfter(self, length: float)[source]¶

Sets the maximum line length (in millimeters) allowed before lines of text in the legend will be automatically word wrapped.

If length is 0, then no automatic wrapping will occur.

See also

autoWrapLinesAfter()

Added in version 3.44.

Parameters:: length (float)

setBoxSpace(self, space: float)[source]¶

Sets the legend box space.

See also

boxSpace()

Parameters:: space (float)

setColumnCount(self, count: int)[source]¶

Sets the legend column count.

See also

columnCount()

Parameters:: count (int)

setColumnSpace(self, spacing: float)[source]¶

Sets the legend column spacing.

See also

columnSpace()

Parameters:: spacing (float)

setDrawRasterStroke(self, enabled: bool)[source]¶

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

Parameters:: enabled (bool) – set to True to draw borders

See also

drawRasterStroke()

See also

setRasterStrokeColor()

See also

setRasterStrokeWidth()

setEqualColumnWidth(self, equalize: bool)[source]¶

Sets whether column widths should be equalized.

See also

equalColumnWidth()

Parameters:: equalize (bool)

setFilterByMapItems(self, maps: Iterable[QgsLayoutItemMap])[source]¶

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

See also

filterByMapItems()

See also

setLinkedMap()

Added in version 3.32.

Parameters:: maps (Iterable[QgsLayoutItemMap])

setFontColor(self, color: QColor | Qt.GlobalColor)[source]¶

Sets the legend font color.

See also

fontColor()

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

Parameters:: color (Union[QColor, Qt.GlobalColor])

setLegendFilterByMapEnabled(self, enabled: bool)[source]¶

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

See also

legendFilterByMapEnabled()

Parameters:: enabled (bool)

setLegendFilterOutAtlas(self, doFilter: bool)[source]¶

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

See also

legendFilterOutAtlas()

Parameters:: doFilter (bool)

setLineSpacing(self, spacing: float)[source]¶

Sets the spacing in-between multiple lines.

See also

lineSpacing()

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

Parameters:: spacing (float)

setLinkedMap(self, map: QgsLayoutItemMap | None)[source]¶

Sets the map to associate with the legend.

See also

linkedMap()

See also

setFilterByMapItems()

Parameters:: map (Optional[QgsLayoutItemMap])

setMaximumSymbolSize(self, size: float)[source]¶

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

A symbol size of 0.0 indicates no maximum is set.

See also

maximumSymbolSize()

Added in version 3.16.

Parameters:: size (float)

setMinimumSymbolSize(self, size: float)[source]¶

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

A symbol size of 0.0 indicates no minimum is set.

See also

minimumSymbolSize()

Added in version 3.16.

Parameters:: size (float)

setRasterStrokeColor(self, color: QColor | Qt.GlobalColor)[source]¶

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

See also

rasterStrokeColor()

See also

setDrawRasterStroke()

See also

setRasterStrokeWidth()

Parameters:: color (Union[QColor, Qt.GlobalColor])

setRasterStrokeWidth(self, width: float)[source]¶

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

See also

rasterStrokeWidth()

See also

setDrawRasterStroke()

See also

setRasterStrokeColor()

Parameters:: width (float)

setResizeToContents(self, enabled: bool)[source]¶

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.

See also

resizeToContents()

setSplitLayer(self, enabled: bool)[source]¶