Class: QgsLegendSettings

class qgis.core.QgsLegendSettings

Bases: sip.wrapper

The QgsLegendSettings class stores the appearance and layout settings for legend drawing with QgsLegendRenderer. The content of the legend is given in QgsLegendModel class.

New in version 2.6:

Methods

boxSpace

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

columnCount

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

columnSpace

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

dpi

drawRasterStroke

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

drawText

Draws Text.

equalColumnWidth

Returns True if all columns should have equal widths.

evaluateItemText

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

fontAscentMillimeters

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

fontColor

Returns the font color used for legend items.

fontDescentMillimeters

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

fontHeightCharacterMM

Returns the font height of a character in millimeters

layerFontColor

Returns layer font color, defaults to fontColor()

lineSpacing

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

mapScale

Returns the legend map scale.

mapUnitsPerPixel

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

maximumSymbolSize

Returns the maximum symbol size (in mm).

minimumSymbolSize

Returns the minimum symbol size (in mm).

mmPerMapUnit

pixelFontSize

Calculates font to from point size to pixel size

rasterStrokeColor

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

rasterStrokeWidth

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

scaledFontPixelSize

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

setBoxSpace

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

setColumnCount

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

setColumnSpace

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

setDpi

setDrawRasterStroke

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

setEqualColumnWidth

Sets whether all columns should have equal widths.

setFontColor

Sets the font color used for legend items.

setLayerFontColor

Sets layer font color to fontColor Overrides fontColor()

setLineSpacing

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

setMapScale

Sets the legend map scale.

setMapUnitsPerPixel

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

setMaximumSymbolSize

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

setMinimumSymbolSize

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

setMmPerMapUnit

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.

setSplitLayer

Sets whether layer components can be split over multiple columns.

setStyle

Sets the style for a legend component.

setSymbolAlignment

Sets the alignment for placement of legend symbols.

setSymbolSize

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

setTitle

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

setTitleAlignment

Sets the alignment of the legend title.

setUseAdvancedEffects

setWmsLegendSize

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

setWrapChar

Sets a string to use as a wrapping character.

splitLayer

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

splitStringForWrapping

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

style

Returns the style for a legend component.

symbolAlignment

Returns the alignment for placement of legend symbols.

symbolSize

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

textWidthMillimeters

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

title

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

titleAlignment

Returns the alignment of the legend title.

useAdvancedEffects

wmsLegendSize

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

wrapChar

Returns the string used as a wrapping character.

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 Take: dpi from render contexts instead.

Return type:

int

drawRasterStroke(self) bool

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

New in version 2.12.

Return type:

bool

drawText(self, p: QPainter, x: float, y: float, text: str, 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: QPainter, rect: QRectF, text: 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 (QPainter) – painter to use

  • rect – rectangle to draw into

  • text (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.

Return type:

bool

evaluateItemText(self, text: str, 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.

New in version 3.6.

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

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

layerFontColor(self) QColor

Returns layer font color, defaults to fontColor()

See also

fontColor()

New in version 3.4.7.

Return type:

QColor

lineSpacing(self) float

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

See also

setLineSpacing()

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

Deprecated since version 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.

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

mmPerMapUnit(self) float

Deprecated since version 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.

New in version 2.12.

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.

New in version 2.12.

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

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

New in version 2.12.

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.

Parameters:

s (bool) –

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

Sets the font color used for legend items.

See also

fontColor()

Parameters:

c (Union[QColor) –

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

Sets layer font color to fontColor Overrides fontColor()

See also

layerFontColor()

See also

fontColor()

New in version 3.4.7.

Parameters:

fontColor (Union[QColor) –

setLineSpacing(self, s: float)

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

See also

lineSpacing()

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 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.

Deprecated since version 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.

New 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.

New in version 3.16.

Parameters:

size (float) –

setMmPerMapUnit(self, mmPerMapUnit: float)

Deprecated since version Set: scale factor on render contexts instead.

Parameters:

mmPerMapUnit (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) – stroke color

New in version 2.12.

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

New in version 2.12.

setSplitLayer(self, s: bool)

Sets whether layer components can be split over multiple columns.

See also

splitLayer()

Parameters:

s (bool) –

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

Sets the style for a legend component.

See also

style()

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

setSymbolSize(self, s: QSizeF)

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

See also

symbolSize()

Parameters:

s (QSizeF) –

setTitle(self, t: str)

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

See also

title()

Parameters:

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

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 (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) List[str]

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

Parameters:

stringToSplt (str) –

Return type:

List[str]

style(self, s: QgsLegendStyle.Style) QgsLegendStyle

Returns the style for a legend component.

See also

setStyle()

Parameters:

s (QgsLegendStyle.Style) –

Return type:

QgsLegendStyle

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

symbolSize(self) QSizeF

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

See also

setSymbolSize()

Return type:

QSizeF

textWidthMillimeters(self, font: QFont, text: str) float

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

Parameters:
  • font (QFont) –

  • text (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.

Return type:

Qt.AlignmentFlag

useAdvancedEffects(self) bool

Deprecated since version 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.

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