Class: QgsLegendSettings

Stores the appearance and layout settings for legend drawing with QgsLegendRenderer.

The content of the legend is driven by the QgsLegendModel class.

class qgis.core.QgsLegendSettings

Bases: object

autoWrapLinesAfter(self) → float

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

Returns the legend box space (in millimeters), which is the empty margin around the inside of the legend’s rectangle.

See also

setBoxSpace()

Return type:

float

columnCount(self) → int

Returns the desired minimum number of columns to show in the legend.

If legend components have forced column breaks then the actual number of columns in the rendered legend may be larger than this value.

See also

setColumnCount()

Return type:

int

columnSpace(self) → float

Returns the margin space between adjacent columns (in millimeters).

See also

setColumnSpace()

Return type:

float

dpi(self) → int

Deprecated since version 3.40.

Take dpi from render contexts instead.

Return type:

int

drawRasterStroke(self) → bool

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

See also

setDrawRasterStroke()

See also

rasterStrokeColor()

See also

rasterStrokeWidth()

Return type:

bool

drawText(self, p: QPainter | None, x: float, y: float, text: str | None, font: QFont)

Draws Text. Takes care about all the composer specific issues (calculation to pixel, scaling of font and painter to work around the Qt font bug)

drawText(self, p: Optional[QPainter], rect: QRectF, text: Optional[str], font: QFont, halignment: Qt.AlignmentFlag = Qt.AlignLeft, valignment: Qt.AlignmentFlag = Qt.AlignTop, flags: int = Qt.TextWordWrap) Like the above, but with a rectangle for multiline text

Parameters:

• p (Optional[QPainter]) – painter to use

• rect – rectangle to draw into

• text (Optional[str]) – text to draw

• font (QFont) – font to use

• halignment – optional horizontal alignment

• valignment – optional vertical alignment

• flags – allows for passing Qt.TextFlags to control appearance of rendered text

• x (float)

• y (float)

equalColumnWidth(self) → bool

Returns True if all columns should have equal widths.

If False is returned then columns will be individually resized to their minimum possible width.

See also

setEqualColumnWidth()

Return type:

bool

evaluateItemText(self, text: str | None, context: QgsExpressionContext) → List[str]

Returns the actual text to render for a legend item, split into separate lines.

The expression context argument is used to correctly evaluated expressions contained within legend item text.

Added in version 3.6.

Parameters:

• text (Optional[str])

• context (QgsExpressionContext)

Return type:

List[str]

fontAscentMillimeters(self, font: QFont) → float

Returns the font ascent in Millimeters (considers upscaling and downscaling with FONT_WORKAROUND_SCALE

Parameters:

font (QFont)

Return type:

float

fontColor(self) → QColor

Returns the font color used for legend items.

See also

setFontColor()

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

Return type:

QColor

fontDescentMillimeters(self, font: QFont) → float

Returns the font descent in Millimeters (considers upscaling and downscaling with FONT_WORKAROUND_SCALE

Parameters:

font (QFont)

Return type:

float

fontHeightCharacterMM(self, font: QFont, c: str) → float

Returns the font height of a character in millimeters

Parameters:

• font (QFont)

• c (str)

Return type:

float

jsonRenderFlags(self) → Qgis.LegendJsonRenderFlags

Returns the JSON export flags.

Added in version 3.36.

Return type:

Qgis.LegendJsonRenderFlags

layerFontColor(self) → QColor

Returns layer font color, defaults to fontColor()

See also

setLayerFontColor()

See also

fontColor()

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

Return type:

QColor

lineSpacing(self) → float

Returns the line spacing to use between lines of legend text.

See also

setLineSpacing()

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

Return type:

float

mapScale(self) → float

Returns the legend map scale. The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.

See also

setMapScale()

Deprecated since version 3.40: Take this property from the render context instead.

Return type:

float

mapUnitsPerPixel(self) → float

Returns the factor of map units per pixel for symbols with size given in map units calculated by dpi and mmPerMapUnit

See also

setMapUnitsPerPixel()

Deprecated since version 3.40: Take these properties on render contexts instead.

Return type:

float

maximumSymbolSize(self) → float

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

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

mmPerMapUnit(self) → float

Deprecated since version 3.40.

Use scale factor from render contexts instead.

Return type:

float

pixelFontSize(self, pointSize: float) → float

Calculates font to from point size to pixel size

Parameters:

pointSize (float)

Return type:

float

rasterStrokeColor(self) → QColor

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

Returns the stroke width (in millimeters) 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

scaledFontPixelSize(self, font: QFont) → QFont

Returns a font where size is in pixel and font size is upscaled with FONT_WORKAROUND_SCALE

Parameters:

font (QFont)

Return type:

QFont

setAutoWrapLinesAfter(self, length: float)

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, s: float)

Sets the legend box space (in millimeters), which is the empty margin around the inside of the legend’s rectangle.

See also

boxSpace()

Parameters:

s (float)

setColumnCount(self, c: int)

Sets the desired minimum number of columns to show in the legend.

If legend components have forced column breaks then the actual number of columns in the rendered legend may be larger than this value.

See also

columnCount()

Parameters:

c (int)

setColumnSpace(self, s: float)

Sets the margin space between adjacent columns (in millimeters).

See also

columnSpace()

Parameters:

s (float)

setDpi(self, dpi: int)

Deprecated since version 3.40.

Set dpi on render contexts instead.

Parameters:

dpi (int)

setDrawRasterStroke(self, enabled: bool)

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, s: bool)

Sets whether all columns should have equal widths.

If False, then then columns will be individually resized to their minimum possible width.

See also

equalColumnWidth()

Parameters:

s (bool)

setFontColor(self, c: QColor | Qt.GlobalColor)

Sets the font color used for legend items.

See also

fontColor()

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

Parameters:

c (Union[QColor, Qt.GlobalColor])

setJsonRenderFlags(self, jsonRenderFlags: Qgis.LegendJsonRenderFlags | Qgis.LegendJsonRenderFlag)

Sets the JSON export flags to jsonRenderFlags.

Added in version 3.36.

Parameters:

jsonRenderFlags (Union[Qgis.LegendJsonRenderFlags, Qgis.LegendJsonRenderFlag])

setLayerFontColor(self, fontColor: QColor | Qt.GlobalColor)

Sets layer font color to fontColor Overrides fontColor()

See also

layerFontColor()

See also

fontColor()

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

Parameters:

fontColor (Union[QColor, Qt.GlobalColor])

setLineSpacing(self, s: float)

Sets the line spacing to use between lines of legend text.

See also

lineSpacing()

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

Parameters:

s (float)

setMapScale(self, scale: float)

Sets the legend map scale. The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.

See also

mapScale()

Deprecated since version 3.40: Set this property on the render context instead.

Parameters:

scale (float)

setMapUnitsPerPixel(self, mapUnitsPerPixel: float)

Sets the mmPerMapUnit calculated by mapUnitsPerPixel mostly taken from the map settings.

See also

mapUnitsPerPixel()

Deprecated since version 3.40: Set these properties on render contexts instead.

Parameters:

mapUnitsPerPixel (float)

setMaximumSymbolSize(self, size: float)

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)

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)

setMmPerMapUnit(self, mmPerMapUnit: float)

Deprecated since version 3.40.

Set scale factor on render contexts instead.

Parameters:

mmPerMapUnit (float)

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

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, Qt.GlobalColor]) – stroke color

See also

rasterStrokeColor()

See also

setDrawRasterStroke()

See also

setRasterStrokeWidth()

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) – stroke width in millimeters

See also

rasterStrokeWidth()

See also

setDrawRasterStroke()

See also

setRasterStrokeColor()

setSplitLayer(self, s: bool)

Sets whether layer components can be split over multiple columns.

See also

splitLayer()

Parameters:

s (bool)

setStyle(self, s: Qgis.LegendComponent, style: QgsLegendStyle)

Sets the style for a legend component.

See also

style()

Parameters:

• s (Qgis.LegendComponent)

• style (QgsLegendStyle)

setSymbolAlignment(self, alignment: Qt.AlignmentFlag)

Sets the alignment for placement of legend symbols.

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

See also

symbolAlignment()

Added in version 3.10.

Parameters:

alignment (Qt.AlignmentFlag)

setSymbolSize(self, s: QSizeF)

Sets the default symbol size (in millimeters) used for legend items.

See also

symbolSize()

Parameters:

s (QSizeF)

setSynchronousLegendRequests(self, b: bool)

Sets whether to request legend graphics synchronously.

See also

synchronousLegendRequests()

Added in version 3.34.

Parameters:

b (bool)

setTitle(self, t: str | None)

Sets the title for the legend, which will be rendered above all legend items.

See also

title()

Parameters:

t (Optional[str])

setTitleAlignment(self, alignment: Qt.AlignmentFlag)

Sets the alignment of the legend title.

See also

titleAlignment()

Parameters:

alignment (Qt.AlignmentFlag)

setUseAdvancedEffects(self, use: bool)

Deprecated since version 3.40.

Set flag on render contexts instead.

Parameters:

use (bool)

setWmsLegendSize(self, s: QSizeF)

Sets the desired size (in millimeters) of WMS legend graphics shown in the legend.

See also

wmsLegendSize()

Parameters:

s (QSizeF)

setWrapChar(self, t: str | None)

Sets a string to use as a wrapping character.

Whenever this string is encountered inside legend component text it will be automatically replaced with a new line character.

See also

wrapChar()

Parameters:

t (Optional[str])

splitLayer(self) → bool

Returns True if layer components can be split over multiple columns.

See also

setSplitLayer()

Return type:

bool

splitStringForWrapping(self, stringToSplt: str | None) → List[str]

Splits a string using the wrap char taking into account handling empty wrap char which means no wrapping

Parameters:

stringToSplt (Optional[str])

Return type:

List[str]

style(self, s: Qgis.LegendComponent) → QgsLegendStyle

Returns the style for a legend component.

See also

setStyle()

Parameters:

s (Qgis.LegendComponent)

Return type:

QgsLegendStyle

symbolAlignment(self) → Qt.AlignmentFlag

Returns the alignment for placement of legend symbols.

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

See also

setSymbolAlignment()

Added in version 3.10.

Return type:

Qt.AlignmentFlag

symbolSize(self) → QSizeF

Returns the default symbol size (in millimeters) used for legend items.

See also

setSymbolSize()

Return type:

QSizeF

synchronousLegendRequests(self) → bool

Returns whether to request legend graphics synchronously.

See also

setSynchronousLegendRequests()

Added in version 3.34.

Return type:

bool

textWidthMillimeters(self, font: QFont, text: str | None) → float

Returns the font width in millimeters (considers upscaling and downscaling with FONT_WORKAROUND_SCALE

Parameters:

• font (QFont)

• text (Optional[str])

Return type:

float

title(self) → str

Returns the title for the legend, which will be rendered above all legend items.

See also

setTitle()

Return type:

str

titleAlignment(self) → Qt.AlignmentFlag

Returns the alignment of the legend title.

See also

setTitleAlignment()

Return type:

Qt.AlignmentFlag

updateDataDefinedProperties(self, context: QgsRenderContext)

Updates any data-defined properties in the settings, using the specified render context.

Added in version 3.42.

Parameters:

context (QgsRenderContext)

useAdvancedEffects(self) → bool

Deprecated since version 3.40.

Use flags from render contexts instead.

Return type:

bool

wmsLegendSize(self) → QSizeF

Returns the size (in millimeters) of WMS legend graphics shown in the legend.

See also

setWmsLegendSize()

Return type:

QSizeF

wrapChar(self) → str

Returns the string used as a wrapping character.

Whenever this string is encountered inside legend component text it will be automatically replaced with a new line character.

See also

setWrapChar()

Return type:

str