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.

See also

setDrawRasterStroke()

See also

rasterStrokeColor()

See also

rasterStrokeWidth()

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.

See also

setEqualColumnWidth()

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:

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

layerFontColor(self) → QColor¶

Returns layer font color, defaults to fontColor()

See also

setLayerFontColor()

See also

fontColor()

Deprecated since version 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 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 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 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()

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.

See also

setMinimumSymbolSize()

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.

See also

setRasterStrokeColor()

See also

drawRasterStroke()

See also

rasterStrokeWidth()

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.

See also

setRasterStrokeWidth()

See also

drawRasterStroke()

See also

rasterStrokeColor()

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

See also

drawRasterStroke()

See also

setRasterStrokeColor()

See also

setRasterStrokeWidth()

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.

See also

equalColumnWidth()

Parameters:: s (bool) –

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

Sets the font color used for legend items.

See also

fontColor()

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

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

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

Parameters:: fontColor (Union[QColor) –

setLineSpacing(self, s: float)¶

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

See also

lineSpacing()

Deprecated since version 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 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 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()

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.

See also

minimumSymbolSize()

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

See also

rasterStrokeColor()

See also

setDrawRasterStroke()

See also

setRasterStrokeWidth()

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

See also

rasterStrokeWidth()

See also

setDrawRasterStroke()

See also

setRasterStrokeColor()

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:

s (QgsLegendStyle.Style) –
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()

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.

See also

setSymbolAlignment()

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.

See also

setTitleAlignment()

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.

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