Class: QgsPalLayerSettings

class qgis.core.QgsPalLayerSettings

Bases: sip.wrapper

Contains settings for how a map layer will be labeled.

Enums

MultiLineAlign

alias of LabelMultiLineAlignment

ObstacleType

Bases: enum.IntEnum

OffsetType

alias of LabelOffsetType

Placement

alias of LabelPlacement

PredefinedPointPosition

alias of LabelPredefinedPointPosition

Property

Bases: enum.IntEnum

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.

labelSettingsPreviewPixmap

Returns a pixmap preview for label settings.

legendString

rtype:

str

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

type legendString:

Optional[str]

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

Attributes

AboveLine

BelowLine

MapOrientation

OnLine

SymbolAbove

SymbolBelow

SymbolLeftRight

AboveLine = 2
BelowLine = 4
class DirectionSymbols

Bases: object

SymbolAbove = 1
SymbolBelow = 2
SymbolLeftRight = 0
class LinePlacementFlags

Bases: object

AboveLine = 2
BelowLine = 4
MapOrientation = 8
OnLine = 1
MapOrientation = 8
MultiLineAlign

alias of LabelMultiLineAlignment

class ObstacleType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: enum.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(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: enum.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 (since QGIS 3.14)

  • LineAnchorPercent: Portion along line at which labels should be anchored (since QGIS 3.16)

  • LineAnchorClipping: Clipping mode for line anchor calculation (since QGIS 3.20)

  • LineAnchorType: Line anchor type (since QGIS 3.26)

  • LineAnchorTextPoint: Line anchor text point (since QGIS 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 (since QGIS 3.26)

  • OverlapHandling: Overlap handling technique (since QGIS 3.26)

  • Show:

  • AlwaysShow:

QuadrantPosition

alias of LabelQuadrantPosition

SymbolAbove = 1
SymbolBelow = 2
SymbolLeftRight = 0
UpsideDownLabels

alias of UpsideDownLabelHandling

property addDirectionSymbol
angleOffset
autoWrapLength
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 .

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

Return type:

QgsPropertyCollection

decimals
property displayAll
dist
distMapUnitScale
distUnits
drawLabels
extentGeom
fieldIndex
fieldName
fitInPolygonOnly
fontLimitPixelSize
fontMaxPixelSize
fontMinPixelSize
format(self) QgsTextFormat

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

See also

setFormat()

Return type:

QgsTextFormat

formatNumbers
geometryGenerator
geometryGeneratorEnabled
geometryGeneratorType
getLabelExpression(self) QgsExpression | None

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

Return type:

Optional[QgsExpression]

isExpression
labelOffsetMapUnitScale
labelPerPart
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
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).

Added in version 3.16.

Return type:

QgsLabelLineSettings

mCurFeat
mCurFields
mFeatsRegPal
mFeatsSendingToPal
mFeaturesToLabel
maxCurvedCharAngleIn
maxCurvedCharAngleOut
property maxNumLabels
maximumScale
property mergeLines
property minFeatureSize
minimumScale
multilineAlign
property obstacle
property obstacleFactor
obstacleSettings(self) QgsLabelObstacleSettings

Returns the label obstacle settings.

Added in version 3.10.2.

Return type:

QgsLabelObstacleSettings

property obstacleType
offsetType
offsetUnits
property overrunDistance
property overrunDistanceMapUnitScale
property overrunDistanceUnit
property placeDirectionSymbol
placement
property placementFlags
placementSettings(self) QgsLabelPlacementSettings

Returns the label placement settings.

Added in version 3.26.

Return type:

QgsLabelPlacementSettings

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

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.

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:
preserveRotation
previewBkgrdColor
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:
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:

Warning

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

repeatDistance
repeatDistanceMapUnitScale
repeatDistanceUnit
property reverseDirectionSymbol
property rightDirectionSymbol
rotationUnit(self) Qgis.AngleUnit

Unit for rotation of labels.

Added in version 3.22.

Return type:

Qgis.AngleUnit

scaleVisibility
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

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.

Added in version 3.10.2.

Parameters:

settings (QgsLabelObstacleSettings)

setPlacementSettings(self, settings: QgsLabelPlacementSettings)

Sets the label placement settings.

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.

Added in version 3.14.

Parameters:

flags (Union[Qgis.LabelPolygonPlacementFlags)

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.

Added in version 3.12.

Parameters:

settings (QgsLabelThinningSettings)

setUnplacedVisibility(self, visibility: Qgis.UnplacedLabelVisibility)

Sets the layer’s unplaced label visibility.

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
thinningSettings(self) QgsLabelThinningSettings

Returns the label thinning settings.

Added in version 3.12.

Return type:

QgsLabelThinningSettings

unplacedVisibility(self) Qgis.UnplacedLabelVisibility

Returns the layer’s unplaced label visibility.

Added in version 3.20.

Return type:

Qgis.UnplacedLabelVisibility

upsidedownLabels
useMaxLineLengthForAutoWrap
useSubstitutions
wrapChar
writeXml(self, doc: QDomDocument, context: QgsReadWriteContext) QDomElement

Write settings into a DOM element

Parameters:
Return type:

QDomElement

xOffset
xform
yOffset
zIndex