Class: QgsPalLayerSettings

Contains settings for how a map layer will be labeled.

Enums

MultiLineAlign	alias of LabelMultiLineAlignment
ObstacleType	Valid obstacle types, which affect how features within the layer will act as obstacles for labels.
OffsetType	alias of LabelOffsetType
Placement	alias of LabelPlacement
PredefinedPointPosition	alias of LabelPredefinedPointPosition
Property	Data definable properties.
QuadrantPosition	alias of LabelQuadrantPosition
UpsideDownLabels	alias of UpsideDownLabelHandling

Methods

calculateLabelSize	Calculates the space required to render the provided text in map units.
callout	Returns the label callout renderer, responsible for drawing label callouts.
containsAdvancedEffects	Returns True if any component of the label settings requires advanced effects such as blend modes, which require output in raster formats to be fully respected.
dataDefinedProperties	Returns a reference to the label's property collection, used for data defined overrides.
format	Returns the label text formatting settings, e.g., font settings, buffer settings, etc.
getLabelExpression	Returns the QgsExpression for this label settings.
legendString	legendString
lineSettings	Returns the label line settings, which contain settings related to how the label engine places and formats labels for line features (or polygon features which are labeled in a "perimeter" style mode).
obstacleSettings	Returns the label obstacle settings.
placementSettings	Returns the label placement settings.
pointSettings	Returns the label point settings, which contain settings related to how the label engine places and formats labels for point features, or polygon features which are labeled in the "around" or "over" centroid placement modes.
polygonPlacementFlags	Returns the polygon placement flags, which dictate how polygon labels can be placed.
prepare	Prepare for registration of features.
propertyDefinitions	Returns the labeling property definitions.
readXml	Read settings from a DOM element
referencedFields	Returns all field names referenced by the configuration (e.g. field name or expression, data defined properties).
registerFeature	Registers a feature for labeling.
rotationUnit	Unit for rotation of labels.
setCallout	Sets the label callout renderer, responsible for drawing label callouts.
setDataDefinedProperties	Sets the label's property collection, used for data defined overrides.
setFormat	Sets the label text formatting settings, e.g., font settings, buffer settings, etc.
setLegendString	setLegendString
setLineSettings	Sets the label line settings, which contain settings related to how the label engine places and formats labels for line features (or polygon features which are labeled in a "perimeter" style mode).
setObstacleSettings	Sets the label obstacle settings.
setPlacementSettings	Sets the label placement settings.
setPointSettings	Sets the label point settings, which contain settings related to how the label engine places and formats labels for point features, or polygon features which are labeled in the "around" or "over" centroid placement modes.
setPolygonPlacementFlags	Sets the polygon placement flags, which dictate how polygon labels can be placed.
setRotationUnit	Set unit for rotation of labels.
setThinningSettings	Sets the label thinning settings.
setUnplacedVisibility	Sets the layer's unplaced label visibility.
startRender	Prepares the label settings for rendering.
stopRender	Finalises the label settings after use.
thinningSettings	Returns the label thinning settings.
unplacedVisibility	Returns the layer's unplaced label visibility.
writeXml	Write settings into a DOM element

Static Methods

labelSettingsPreviewPixmap

Returns a pixmap preview for label settings.

Attributes

AboveLine
BelowLine
MapOrientation
OnLine
SymbolAbove
SymbolBelow
SymbolLeftRight
angleOffset	Label rotation, in degrees clockwise
autoWrapLength	If non-zero, indicates that label text should be automatically wrapped to (ideally) the specified number of characters.
centroidInside	True if centroid positioned labels must be placed inside their corresponding feature polygon, or False if centroids which fall outside the polygon are permitted.
centroidWhole	True if feature centroid should be calculated from the whole feature, or False if only the visible part of the feature should be considered.
ct
decimals	Number of decimal places to show for numeric labels.
dist	Distance from feature to the label.
distMapUnitScale	Map unit scale for label feature distance.
distUnits	Units the distance from feature to the label.
drawLabels	Whether to draw labels for this layer.
extentGeom
fieldIndex
fieldName	Name of field (or an expression) to use for label text.
fitInPolygonOnly	True if only labels which completely fit within a polygon are allowed.
fontLimitPixelSize	True if label sizes should be limited by pixel size.
fontMaxPixelSize	Maximum pixel size for showing rendered map unit labels (1 - 10000).
fontMinPixelSize	Minimum pixel size for showing rendered map unit labels (1 - 1000).
formatNumbers	Set to True to format numeric label text as numbers (e.g. inserting thousand separators and fixed number of decimal places).
geometryGenerator	The geometry generator expression.
geometryGeneratorEnabled	Defines if the geometry generator is enabled or not.
geometryGeneratorType	The type of the result geometry of the geometry generator.
isExpression	True if this label is made from a expression string, e.g., FieldName || 'mm'
labelOffsetMapUnitScale	Map unit scale for label offset.
labelPerPart	True if every part of a multi-part feature should be labeled.
layerType	Geometry type of layers associated with these settings.
mCurFeat
mCurFields
mFeatsRegPal
mFeatsSendingToPal
mFeaturesToLabel
maxCurvedCharAngleIn	Maximum angle between inside curved label characters (valid range 20.0 to 60.0).
maxCurvedCharAngleOut	Maximum angle between outside curved label characters (valid range -20.0 to -95.0)
maximumScale	The maximum map scale (i.e. most "zoomed in" scale) at which the labels will be visible.
minimumScale	The minimum map scale (i.e. most "zoomed out" scale) at which the labels will be visible.
multilineAlign	Horizontal alignment of multi-line labels.
offsetType	Offset type for layer (only applies in certain placement modes)
offsetUnits	Units for offsets of label.
placement	Label placement mode
plusSign	Whether '+' signs should be prepended to positive numeric labels.
preserveRotation	True if label rotation should be preserved during label pin/unpin operations.
previewBkgrdColor
priority	Label priority.
ptOne
ptZero
repeatDistance	Distance for repeating labels for a single feature.
repeatDistanceMapUnitScale	Map unit scale for repeating labels for a single feature.
repeatDistanceUnit	Units for repeating labels for a single feature.
scaleVisibility	Set to True to limit label visibility to a range of scales.
substitutions	Substitution collection for automatic text substitution with labels
upsidedownLabels	Controls whether upside down labels are displayed and how they are handled.
useMaxLineLengthForAutoWrap	If True, indicates that when auto wrapping label text the autoWrapLength length indicates the maximum ideal length of text lines.
useSubstitutions	True if substitutions should be applied
wrapChar	Wrapping character string.
xOffset	Horizontal offset of label.
xform
yOffset	Vertical offset of label.
zIndex	Z-Index of label, where labels with a higher z-index are rendered on top of labels with a lower z-index

class qgis.core.QgsPalLayerSettings

Bases: object

AboveLine = 2

BelowLine = 4

DirectionSymbols

alias of _DirectionSymbols

LinePlacementFlags

alias of _LinePlacementFlags

MapOrientation = 8

MultiLineAlign

alias of LabelMultiLineAlignment

class ObstacleType(*values)

Bases: IntEnum

Valid obstacle types, which affect how features within the layer will act as obstacles for labels.

• PolygonInterior: Avoid placing labels over interior of polygon (prefer placing labels totally outside or just slightly inside polygon)

• PolygonBoundary: Avoid placing labels over boundary of polygon (prefer placing outside or completely inside polygon)

• PolygonWhole: Avoid placing labels over ANY part of polygon. Where PolygonInterior will prefer to place labels with the smallest area of intersection between the label and the polygon, PolygonWhole will penalise any label which intersects with the polygon by an equal amount, so that placing labels over any part of the polygon is avoided

OffsetType

alias of LabelOffsetType

OnLine = 1

Placement

alias of LabelPlacement

PredefinedPointPosition

alias of LabelPredefinedPointPosition

class Property(*values)

Bases: IntEnum

Data definable properties.

• Size: Label size

• Bold: Use bold style

• Italic: Use italic style

• Underline: Use underline

• Color: Text color

• Strikeout: Use strikeout

• Family: Font family

• FontStyle: Font style name

• FontSizeUnit: Font size units

• FontTransp: Text transparency (deprecated)

• FontOpacity: Text opacity

• FontCase: Label text case

• FontLetterSpacing: Letter spacing

• FontWordSpacing: Word spacing

• FontBlendMode: Text blend mode

• FontStretchFactor: Font stretch factor, since QGIS 3.24

• MultiLineWrapChar:

• AutoWrapLength:

• MultiLineHeight:

• MultiLineAlignment:

• TextOrientation:

• TabStopDistance: Tab stop distance, since QGIS 3.38

• DirSymbDraw:

• DirSymbLeft:

• DirSymbRight:

• DirSymbPlacement:

• DirSymbReverse:

• NumFormat:

• NumDecimals:

• NumPlusSign:

• BufferDraw:

• BufferSize:

• BufferUnit:

• BufferColor:

• BufferTransp: Buffer transparency (deprecated)

• BufferOpacity: Buffer opacity

• BufferJoinStyle:

• BufferBlendMode:

• MaskEnabled: Whether the mask is enabled

• MaskBufferSize: Mask buffer size

• MaskBufferUnit: Mask buffer size unit

• MaskOpacity: Mask opacity

• MaskJoinStyle: Mask join style

• ShapeDraw:

• ShapeKind:

• ShapeSVGFile:

• ShapeSizeType:

• ShapeSizeX:

• ShapeSizeY:

• ShapeSizeUnits:

• ShapeRotationType:

• ShapeRotation:

• ShapeOffset:

• ShapeOffsetUnits:

• ShapeRadii:

• ShapeRadiiUnits:

• ShapeTransparency: Shape transparency (deprecated)

• ShapeOpacity: Shape opacity

• ShapeBlendMode:

• ShapeFillColor:

• ShapeStrokeColor:

• ShapeStrokeWidth:

• ShapeStrokeWidthUnits:

• ShapeJoinStyle:

• ShadowDraw:

• ShadowUnder:

• ShadowOffsetAngle:

• ShadowOffsetDist:

• ShadowOffsetUnits:

• ShadowRadius:

• ShadowRadiusUnits:

• ShadowTransparency: Shadow transparency (deprecated)

• ShadowOpacity: Shadow opacity

• ShadowScale:

• ShadowColor:

• ShadowBlendMode:

• CentroidWhole:

• OffsetQuad:

• OffsetXY:

• OffsetUnits:

• LabelDistance:

• MaximumDistance: Maximum distance of label from feature

• DistanceUnits:

• OffsetRotation:

• CurvedCharAngleInOut:

• PositionX: X-coordinate data defined label position

• PositionY: Y-coordinate data defined label position

• PositionPoint: Point-coordinate data defined label position

• Hali: Horizontal alignment for data defined label position (Left, Center, Right)

• Vali: Vertical alignment for data defined label position (Bottom, Base, Half, Cap, Top)

• Rotation: Label rotation (deprecated, for old project compatibility only)

• LabelRotation: Label rotation

• RepeatDistance:

• RepeatDistanceUnit:

• Priority:

• PredefinedPositionOrder:

• LinePlacementOptions: Line placement flags

• OverrunDistance: Distance which labels can extend past either end of linear features

• LabelAllParts: Whether all parts of multi-part features should be labeled

• PolygonLabelOutside: Whether labels outside a polygon feature are permitted, or should be forced

  Added in version 3.14.

• LineAnchorPercent: Portion along line at which labels should be anchored

  Added in version 3.16.

• LineAnchorClipping: Clipping mode for line anchor calculation

  Added in version 3.20.

• LineAnchorType: Line anchor type

  Added in version 3.26.

• LineAnchorTextPoint: Line anchor text point

  Added in version 3.26.

• ScaleVisibility:

• MinScale: Min scale (deprecated, for old project compatibility only)

• MinimumScale: Minimum map scale (ie most “zoomed out”)

• MaxScale: Max scale (deprecated, for old project compatibility only)

• MaximumScale: Maximum map scale (ie most “zoomed in”)

• FontLimitPixel:

• FontMinPixel:

• FontMaxPixel:

• IsObstacle:

• ObstacleFactor:

• ZIndex:

• CalloutDraw: Show callout

• AllowDegradedPlacement: Allow degraded label placements

  Added in version 3.26.

• OverlapHandling: Overlap handling technique

  Added in version 3.26.

• LabelMarginDistance: Minimum distance from labels for this feature to other labels

  Added in version 3.44.

• RemoveDuplicateLabels: Whether this feature can cause removal of duplicate labels

  Added in version 3.44.

• RemoveDuplicateLabelDistance: Minimum distance from labels for this feature to other labels with duplicate text

  Added in version 3.44.

• Show:

• AlwaysShow:

QuadrantPosition

alias of LabelQuadrantPosition

SymbolAbove = 1

SymbolBelow = 2

SymbolLeftRight = 0

UpsideDownLabels

alias of UpsideDownLabelHandling

property addDirectionSymbol

angleOffset: float

Label rotation, in degrees clockwise

autoWrapLength: int

If non-zero, indicates that label text should be automatically wrapped to (ideally) the specified number of characters. If zero, auto wrapping is disabled.

See also

useMaxLineLengthForAutoWrap()

Added in version 3.4.

calculateLabelSize(self, fm: QFontMetricsF | None, text: str | None, f: QgsFeature | None = None, context: QgsRenderContext | None = None)

Calculates the space required to render the provided text in map units. Results will be written to labelX and labelY.

If the text orientation is set to rotation-based, the spaced taken to render vertically oriented text will be written to rotatedLabelX and rotatedLabelY.

Warning

This method only returns an approximate label size, and eg will not consider HTML formatted text correctly.

Deprecated since version 3.40: Will be removed from public API in QGIS 4.0.

Parameters:

• fm (Optional[QFontMetricsF])

• text (Optional[str])

• f (Optional[QgsFeature] = None)

• context (Optional[QgsRenderContext] = None) -> (float)

callout(self) → QgsCallout | None

Returns the label callout renderer, responsible for drawing label callouts.

Ownership is not transferred.

See also

setCallout()

Added in version 3.10.

Return type:

Optional[QgsCallout]

centroidInside: bool

True if centroid positioned labels must be placed inside their corresponding feature polygon, or False if centroids which fall outside the polygon are permitted.

centroidWhole: bool

True if feature centroid should be calculated from the whole feature, or False if only the visible part of the feature should be considered.

containsAdvancedEffects(self) → bool

Returns True if any component of the label settings requires advanced effects such as blend modes, which require output in raster formats to be fully respected.

Added in version 3.20.

Return type:

bool

ct

dataDefinedProperties(self) → QgsPropertyCollection

Returns a reference to the label’s property collection, used for data defined overrides.

See also

setDataDefinedProperties()

Return type:

QgsPropertyCollection

decimals: int

Number of decimal places to show for numeric labels. formatNumbers must be True for this setting to have an effect.

See also

formatNumbers()

property displayAll

dist: float

Distance from feature to the label. Units are specified via distUnits.

See also

distUnits()

See also

distMapUnitScale()

distMapUnitScale: QgsMapUnitScale

Map unit scale for label feature distance.

See also

dist()

See also

distUnits()

distUnits: Qgis.RenderUnit

Units the distance from feature to the label.

See also

dist()

See also

distMapUnitScale()

drawLabels: bool

Whether to draw labels for this layer. For some layers it may be desirable to register their features as obstacles for other labels without requiring labels to be drawn for the layer itself. In this case drawLabels can be set to False and obstacle set to True, which will result in the layer acting as an obstacle but having no labels of its own.

extentGeom

fieldIndex

fieldName: str

Name of field (or an expression) to use for label text. If fieldName is an expression, then isExpression should be set to True.

See also

isExpression()

fitInPolygonOnly: bool

True if only labels which completely fit within a polygon are allowed.

fontLimitPixelSize: bool

True if label sizes should be limited by pixel size.

See also

fontMinPixelSize()

See also

fontMaxPixelSize()

fontMaxPixelSize: int

Maximum pixel size for showing rendered map unit labels (1 - 10000).

See also

fontLimitPixelSize()

See also

fontMinPixelSize()

fontMinPixelSize: int

Minimum pixel size for showing rendered map unit labels (1 - 1000).

See also

fontLimitPixelSize()

See also

fontMaxPixelSize()

format(self) → QgsTextFormat

Returns the label text formatting settings, e.g., font settings, buffer settings, etc.

See also

setFormat()

Return type:

QgsTextFormat

formatNumbers: bool

Set to True to format numeric label text as numbers (e.g. inserting thousand separators and fixed number of decimal places).

See also

decimals()

See also

plusSign()

geometryGenerator: str

The geometry generator expression. Null if disabled.

geometryGeneratorEnabled: bool

Defines if the geometry generator is enabled or not. If disabled, the standard geometry will be taken.

geometryGeneratorType: Qgis.GeometryType

The type of the result geometry of the geometry generator.

getLabelExpression(self) → QgsExpression | None

Returns the QgsExpression for this label settings. May be None if isExpression is False.

Return type:

Optional[QgsExpression]

isExpression: bool

True if this label is made from a expression string, e.g., FieldName || ‘mm’

See also

fieldName()

labelOffsetMapUnitScale: QgsMapUnitScale

Map unit scale for label offset.

See also

xOffset()

See also

yOffset()

See also

offsetUnits()

labelPerPart: bool

True if every part of a multi-part feature should be labeled. If False, only the largest part will be labeled.

static labelSettingsPreviewPixmap(settings: QgsPalLayerSettings, size: QSize, previewText: str | None = '', padding: int = 0, screen: QgsScreenProperties = QgsScreenProperties()) → QPixmap

Returns a pixmap preview for label settings.

Parameters:

• settings (QgsPalLayerSettings) – label settings

• size (QSize) – target pixmap size

• previewText (Optional[str] = '') – text to render in preview, or empty for default text

• padding (int = 0) – space between icon edge and color ramp

• screen (QgsScreenProperties = QgsScreenProperties()) – can be used to specify the destination screen properties for the icon. This allows the icon to be generated using the correct DPI and device pixel ratio for the target screen (since QGIS 3.32)

Added in version 3.10.

Return type:

QPixmap

layerType: Qgis.GeometryType

Geometry type of layers associated with these settings.

Added in version 3.10.

property leftDirectionSymbol

legendString(self) → str

legendString(None) → None

Return type:

str

Returns:

the string to show in the legend and in the preview icon

property limitNumLabels

lineSettings(self) → QgsLabelLineSettings

Returns the label line settings, which contain settings related to how the label engine places and formats labels for line features (or polygon features which are labeled in a “perimeter” style mode).

See also

setLineSettings()

Added in version 3.16.

Return type:

QgsLabelLineSettings

mCurFeat

mCurFields

mFeatsRegPal

mFeatsSendingToPal

mFeaturesToLabel

maxCurvedCharAngleIn: float

Maximum angle between inside curved label characters (valid range 20.0 to 60.0).

See also

maxCurvedCharAngleOut()

maxCurvedCharAngleOut: float

Maximum angle between outside curved label characters (valid range -20.0 to -95.0)

See also

maxCurvedCharAngleIn()

property maxNumLabels

maximumScale: float

The maximum map scale (i.e. most “zoomed in” scale) at which the labels will be visible. The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map. A scale of 0 indicates no maximum scale visibility.

This setting is only considered if scaleVisibility is True.

See also

minimumScale()

See also

scaleVisibility()

property mergeLines

property minFeatureSize

minimumScale: float

The minimum map scale (i.e. most “zoomed out” scale) at which the labels will be visible. The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map. A scale of 0 indicates no minimum scale visibility.

This setting is only considered if scaleVisibility is True.

See also

maximumScale()

See also

scaleVisibility()

multilineAlign: Qgis.LabelMultiLineAlignment

Horizontal alignment of multi-line labels.

property obstacle

property obstacleFactor

obstacleSettings(self) → QgsLabelObstacleSettings

Returns the label obstacle settings.

See also

setObstacleSettings()

Added in version 3.10.2.

Return type:

QgsLabelObstacleSettings

property obstacleType

offsetType: Qgis.LabelOffsetType

Offset type for layer (only applies in certain placement modes)

offsetUnits: Qgis.RenderUnit

Units for offsets of label.

See also

xOffset()

See also

yOffset()

See also

labelOffsetMapUnitScale()

property overrunDistance

property overrunDistanceMapUnitScale

property overrunDistanceUnit

property placeDirectionSymbol

placement: Qgis.LabelPlacement

Label placement mode

property placementFlags

placementSettings(self) → QgsLabelPlacementSettings

Returns the label placement settings.

See also

setPlacementSettings()

Added in version 3.26.

Return type:

QgsLabelPlacementSettings

plusSign: bool

Whether ‘+’ signs should be prepended to positive numeric labels. formatNumbers must be True for this setting to have an effect.

See also

formatNumbers()

pointSettings(self) → QgsLabelPointSettings

Returns the label point settings, which contain settings related to how the label engine places and formats labels for point features, or polygon features which are labeled in the “around” or “over” centroid placement modes.

See also

setPointSettings()

Added in version 3.38.

Return type:

QgsLabelPointSettings

polygonPlacementFlags(self) → Qgis.LabelPolygonPlacementFlags

Returns the polygon placement flags, which dictate how polygon labels can be placed.

See also

setPolygonPlacementFlags()

Added in version 3.14.

Return type:

Qgis.LabelPolygonPlacementFlags

prepare(self, context: QgsRenderContext, attributeNames: Iterable[str | None], fields: QgsFields, mapSettings: QgsMapSettings, crs: QgsCoordinateReferenceSystem)

Prepare for registration of features. The context, mapSettings and fields parameters give more information about the rendering environment. If target crs is not specified, the targetCrs from mapSettings will be taken. The parameter attributeNames should be updated to contain all the field names which the labeling requires for the rendering.

Added in version 3.8.

Parameters:

• context (QgsRenderContext)

• attributeNames (Iterable[Optional[str]])

• fields (QgsFields)

• mapSettings (QgsMapSettings)

• crs (QgsCoordinateReferenceSystem) -> (bool)

preserveRotation: bool

True if label rotation should be preserved during label pin/unpin operations.

previewBkgrdColor: QColor

Deprecated since version 3.10: Use QgsTextFormat.previewBackgroundColor() instead.

priority: int

Label priority. Valid ranges are from 0 to 10, where 0 = lowest priority and 10 = highest priority.

propertyDefinitions() → Dict[int, QgsPropertyDefinition]

Returns the labeling property definitions.

Return type:

Dict[int, QgsPropertyDefinition]

ptOne

ptZero

property quadOffset

readXml(self, elem: QDomElement, context: QgsReadWriteContext)

Read settings from a DOM element

Parameters:

• elem (QDomElement)

• context (QgsReadWriteContext)

referencedFields(self, context: QgsRenderContext) → Set[str]

Returns all field names referenced by the configuration (e.g. field name or expression, data defined properties).

Added in version 3.14.

Parameters:

context (QgsRenderContext)

Return type:

Set[str]

registerFeature(self, f: QgsFeature, context: QgsRenderContext)

Registers a feature for labeling.

Parameters:

• f (QgsFeature) – feature to label

• context (QgsRenderContext) – render context. The QgsExpressionContext contained within the render context must have already had the feature and fields sets prior to calling this method.

Warning

This method is designed for use by PyQGIS clients only. C++ code should use the variant with additional arguments.

repeatDistance: float

Distance for repeating labels for a single feature.

See also

repeatDistanceUnit()

See also

repeatDistanceMapUnitScale()

repeatDistanceMapUnitScale: QgsMapUnitScale

Map unit scale for repeating labels for a single feature.

See also

repeatDistance()

See also

repeatDistanceUnit()

repeatDistanceUnit: Qgis.RenderUnit

Units for repeating labels for a single feature.

See also

repeatDistance()

See also

repeatDistanceMapUnitScale()

property reverseDirectionSymbol

property rightDirectionSymbol

rotationUnit(self) → Qgis.AngleUnit

Unit for rotation of labels.

See also

setRotationUnit()

Added in version 3.22.

Return type:

Qgis.AngleUnit

scaleVisibility: bool

Set to True to limit label visibility to a range of scales.

See also

maximumScale()

See also

minimumScale()

setCallout(self, callout: QgsCallout | None)

Sets the label callout renderer, responsible for drawing label callouts.

Ownership of callout is transferred to the settings.

See also

callout()

Added in version 3.10.

Parameters:

callout (Optional[QgsCallout])

setDataDefinedProperties(self, collection: QgsPropertyCollection)

Sets the label’s property collection, used for data defined overrides.

Parameters:

collection (QgsPropertyCollection) – property collection. Existing properties will be replaced.

See also

dataDefinedProperties()

See also

Property

setFormat(self, format: QgsTextFormat)

Sets the label text formatting settings, e.g., font settings, buffer settings, etc.

Parameters:

format (QgsTextFormat) – label text format

See also

format()

setLegendString(self, legendString: str | None)

setLegendString(None) → None

Parameters:

legendString (Optional[str]) – the string to show in the legend and preview

setLineSettings(self, settings: QgsLabelLineSettings)

Sets the label line settings, which contain settings related to how the label engine places and formats labels for line features (or polygon features which are labeled in a “perimeter” style mode).

See also

lineSettings()

Added in version 3.16.

Parameters:

settings (QgsLabelLineSettings)

setObstacleSettings(self, settings: QgsLabelObstacleSettings)

Sets the label obstacle settings.

See also

obstacleSettings()

Added in version 3.10.2.

Parameters:

settings (QgsLabelObstacleSettings)

setPlacementSettings(self, settings: QgsLabelPlacementSettings)

Sets the label placement settings.

See also

placementSettings()

Added in version 3.26.

Parameters:

settings (QgsLabelPlacementSettings)

setPointSettings(self, settings: QgsLabelPointSettings)

Sets the label point settings, which contain settings related to how the label engine places and formats labels for point features, or polygon features which are labeled in the “around” or “over” centroid placement modes.

See also

pointSettings()

Added in version 3.38.

Parameters:

settings (QgsLabelPointSettings)

setPolygonPlacementFlags(self, flags: Qgis.LabelPolygonPlacementFlags | Qgis.LabelPolygonPlacementFlag)

Sets the polygon placement flags, which dictate how polygon labels can be placed.

See also

polygonPlacementFlags()

Added in version 3.14.

Parameters:

flags (Union[Qgis.LabelPolygonPlacementFlags, Qgis.LabelPolygonPlacementFlag])

setRotationUnit(self, angleUnit: Qgis.AngleUnit)

Set unit for rotation of labels.

See also

rotationUnit()

Added in version 3.22.

Parameters:

angleUnit (Qgis.AngleUnit)

setThinningSettings(self, settings: QgsLabelThinningSettings)

Sets the label thinning settings.

See also

thinningSettings()

Added in version 3.12.

Parameters:

settings (QgsLabelThinningSettings)

setUnplacedVisibility(self, visibility: Qgis.UnplacedLabelVisibility)

Sets the layer’s unplaced label visibility.

See also

unplacedVisibility()

Added in version 3.20.

Parameters:

visibility (Qgis.UnplacedLabelVisibility)

startRender(self, context: QgsRenderContext)

Prepares the label settings for rendering.

This should be called before rendering any labels, and must be followed by a call to stopRender() in order to gracefully clean up symbols.

Added in version 3.10.

Parameters:

context (QgsRenderContext)

stopRender(self, context: QgsRenderContext)

Finalises the label settings after use.

This must be called after a call to startRender(), in order to gracefully clean up symbols.

Added in version 3.10.

Parameters:

context (QgsRenderContext)

substitutions: QgsStringReplacementCollection

Substitution collection for automatic text substitution with labels

thinningSettings(self) → QgsLabelThinningSettings

Returns the label thinning settings.

See also

setThinningSettings()

Added in version 3.12.

Return type:

QgsLabelThinningSettings

unplacedVisibility(self) → Qgis.UnplacedLabelVisibility

Returns the layer’s unplaced label visibility.

See also

setUnplacedVisibility()

Added in version 3.20.

Return type:

Qgis.UnplacedLabelVisibility

upsidedownLabels: Qgis.UpsideDownLabelHandling

Controls whether upside down labels are displayed and how they are handled.

useMaxLineLengthForAutoWrap: bool

If True, indicates that when auto wrapping label text the autoWrapLength length indicates the maximum ideal length of text lines. If False, then autoWrapLength indicates the ideal minimum length of text lines.

If autoWrapLength is 0 then this value has no effect.

See also

autoWrapLength()

Added in version 3.4.

useSubstitutions: bool

True if substitutions should be applied

wrapChar: str

Wrapping character string. If set, any occurrences of this string in the calculated label text will be replaced with new line characters.

writeXml(self, doc: QDomDocument, context: QgsReadWriteContext) → QDomElement

Write settings into a DOM element

Parameters:

• doc (QDomDocument)

• context (QgsReadWriteContext)

Return type:

QDomElement

xOffset: float

Horizontal offset of label. Units are specified via offsetUnits.

See also

yOffset()

See also

offsetUnits()

See also

labelOffsetMapUnitScale()

xform

yOffset: float

Vertical offset of label. Units are specified via offsetUnits.

See also

xOffset()

See also

offsetUnits()

See also

labelOffsetMapUnitScale()

zIndex: float

Z-Index of label, where labels with a higher z-index are rendered on top of labels with a lower z-index