Class: QgsPalLayerSettings

class qgis.core.QgsPalLayerSettings

Bases: sip.wrapper

Contains settings for how a map layer will be labeled.

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.

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.

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:

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.

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

AlwaysShow

AroundPoint

AutoWrapLength

BelowLine

Bold

BottomLeft

BottomMiddle

BottomRight

BottomSlightlyLeft

BottomSlightlyRight

BufferBlendMode

BufferColor

BufferDraw

BufferJoinStyle

BufferOpacity

BufferSize

BufferTransp

BufferUnit

CalloutDraw

CentroidWhole

Color

Curved

CurvedCharAngleInOut

DirSymbDraw

DirSymbLeft

DirSymbPlacement

DirSymbReverse

DirSymbRight

DistanceUnits

Family

FontBlendMode

FontCase

FontLetterSpacing

FontLimitPixel

FontMaxPixel

FontMinPixel

FontOpacity

FontSizeUnit

FontStyle

FontTransp

FontWordSpacing

Free

FromPoint

FromSymbolBounds

Hali

Horizontal

IsObstacle

Italic

LabelAllParts

LabelDistance

LabelRotation

Line

LineAnchorClipping

LineAnchorPercent

LinePlacementOptions

MapOrientation

MaskBufferSize

MaskBufferUnit

MaskEnabled

MaskJoinStyle

MaskOpacity

MaxScale

MaximumScale

MiddleLeft

MiddleRight

MinScale

MinimumScale

MultiCenter

MultiFollowPlacement

MultiJustify

MultiLeft

MultiLineAlignment

MultiLineHeight

MultiLineWrapChar

MultiRight

NumDecimals

NumFormat

NumPlusSign

ObstacleFactor

OffsetQuad

OffsetRotation

OffsetUnits

OffsetXY

OnLine

OrderedPositionsAroundPoint

OutsidePolygons

OverPoint

OverrunDistance

PerimeterCurved

PolygonBoundary

PolygonInterior

PolygonLabelOutside

PolygonWhole

PositionX

PositionY

PredefinedPositionOrder

Priority

QuadrantAbove

QuadrantAboveLeft

QuadrantAboveRight

QuadrantBelow

QuadrantBelowLeft

QuadrantBelowRight

QuadrantLeft

QuadrantOver

QuadrantRight

RepeatDistance

RepeatDistanceUnit

Rotation

ScaleVisibility

ShadowBlendMode

ShadowColor

ShadowDraw

ShadowOffsetAngle

ShadowOffsetDist

ShadowOffsetUnits

ShadowOpacity

ShadowRadius

ShadowRadiusUnits

ShadowScale

ShadowTransparency

ShadowUnder

ShapeBlendMode

ShapeDraw

ShapeFillColor

ShapeJoinStyle

ShapeKind

ShapeOffset

ShapeOffsetUnits

ShapeOpacity

ShapeRadii

ShapeRadiiUnits

ShapeRotation

ShapeRotationType

ShapeSVGFile

ShapeSizeType

ShapeSizeUnits

ShapeSizeX

ShapeSizeY

ShapeStrokeColor

ShapeStrokeWidth

ShapeStrokeWidthUnits

ShapeTransparency

Show

ShowAll

ShowDefined

Size

Strikeout

SymbolAbove

SymbolBelow

SymbolLeftRight

TextOrientation

TopLeft

TopMiddle

TopRight

TopSlightlyLeft

TopSlightlyRight

Underline

Upright

Vali

ZIndex

AboveLine = 2
AlwaysShow = 20
AroundPoint = 0
AutoWrapLength = 101
BelowLine = 4
Bold = 1
BottomLeft = 7
BottomMiddle = 9
BottomRight = 11
BottomSlightlyLeft = 8
BottomSlightlyRight = 10
BufferBlendMode = 45
BufferColor = 8
BufferDraw = 42
BufferJoinStyle = 44
BufferOpacity = 94
BufferSize = 7
BufferTransp = 19
BufferUnit = 43
CalloutDraw = 100
CentroidWhole = 76
Color = 4
Curved = 3
CurvedCharAngleInOut = 83
DirSymbDraw = 34
DirSymbLeft = 35
DirSymbPlacement = 37
DirSymbReverse = 38
DirSymbRight = 36
class DirectionSymbols

Bases: int

DistanceUnits = 81
Family = 6
FontBlendMode = 30
FontCase = 27
FontLetterSpacing = 28
FontLimitPixel = 24
FontMaxPixel = 26
FontMinPixel = 25
FontOpacity = 92
FontSizeUnit = 22
FontStyle = 21
FontTransp = 18
FontWordSpacing = 29
Free = 5
FromPoint = 0
FromSymbolBounds = 1
Hali = 11
Horizontal = 4
IsObstacle = 88
Italic = 2
LabelAllParts = 103
LabelDistance = 13
LabelRotation = 96
Line = 2
LineAnchorClipping = 112
LineAnchorPercent = 111
class LinePlacementFlags

Bases: int

LinePlacementOptions = 99
MapOrientation = 8
MaskBufferSize = 105
MaskBufferUnit = 106
MaskEnabled = 104
MaskJoinStyle = 108
MaskOpacity = 107
MaxScale = 17
MaximumScale = 98
MiddleLeft = 5
MiddleRight = 6
MinScale = 16
MinimumScale = 97
MultiCenter = 1
MultiFollowPlacement = 3
MultiJustify = 4
MultiLeft = 0
class MultiLineAlign

Bases: int

MultiLineAlignment = 33
MultiLineHeight = 32
MultiLineWrapChar = 31
MultiRight = 2
NumDecimals = 40
NumFormat = 39
NumPlusSign = 41
ObstacleFactor = 89
class ObstacleType

Bases: int

OffsetQuad = 77
OffsetRotation = 82
class OffsetType

Bases: int

OffsetUnits = 80
OffsetXY = 78
OnLine = 1
OrderedPositionsAroundPoint = 6
OutsidePolygons = 8
OverPoint = 1
OverrunDistance = 102
PerimeterCurved = 7
class Placement

Bases: int

PolygonBoundary = 1
PolygonInterior = 0
PolygonLabelOutside = 109
PolygonWhole = 2
PositionX = 9
PositionY = 10
class PredefinedPointPosition

Bases: int

PredefinedPositionOrder = 91
Priority = 87
class Property

Bases: int

QuadrantAbove = 1
QuadrantAboveLeft = 0
QuadrantAboveRight = 2
QuadrantBelow = 7
QuadrantBelowLeft = 6
QuadrantBelowRight = 8
QuadrantLeft = 3
QuadrantOver = 4
class QuadrantPosition

Bases: int

QuadrantRight = 5
RepeatDistance = 84
RepeatDistanceUnit = 86
Rotation = 14
ScaleVisibility = 23
ShadowBlendMode = 75
ShadowColor = 74
ShadowDraw = 65
ShadowOffsetAngle = 67
ShadowOffsetDist = 68
ShadowOffsetUnits = 69
ShadowOpacity = 95
ShadowRadius = 70
ShadowRadiusUnits = 71
ShadowScale = 73
ShadowTransparency = 72
ShadowUnder = 66
ShapeBlendMode = 64
ShapeDraw = 46
ShapeFillColor = 58
ShapeJoinStyle = 62
ShapeKind = 47
ShapeOffset = 54
ShapeOffsetUnits = 55
ShapeOpacity = 93
ShapeRadii = 56
ShapeRadiiUnits = 57
ShapeRotation = 53
ShapeRotationType = 52
ShapeSVGFile = 48
ShapeSizeType = 49
ShapeSizeUnits = 51
ShapeSizeX = 50
ShapeSizeY = 85
ShapeStrokeColor = 59
ShapeStrokeWidth = 60
ShapeStrokeWidthUnits = 61
ShapeTransparency = 63
Show = 15
ShowAll = 2
ShowDefined = 1
Size = 0
Strikeout = 5
SymbolAbove = 1
SymbolBelow = 2
SymbolLeftRight = 0
TextOrientation = 110
TopLeft = 0
TopMiddle = 2
TopRight = 4
TopSlightlyLeft = 1
TopSlightlyRight = 3
Underline = 3
Upright = 0
class UpsideDownLabels

Bases: int

Vali = 12
ZIndex = 90
property addDirectionSymbol

_getAddDirectionSymbol(self) -> bool

Return type:

bool

angleOffset
autoWrapLength
calculateLabelSize(self, fm: QFontMetricsF, text: str, f: QgsFeature = None, context: QgsRenderContext = None) Tuple[float, float, float, float]

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:
Return type:

Tuple[float, float, float, float]

callout(self) QgsCallout

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

Ownership is not transferred.

See also

setCallout()

New in version 3.10.

Return type:

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.

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

New in version 3.0.

Return type:

QgsPropertyCollection

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

New in version 3.0.

Return type:

QgsTextFormat

formatNumbers
geometryGenerator
geometryGeneratorEnabled
geometryGeneratorType
getLabelExpression(self) QgsExpression

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

Return type:

QgsExpression

isExpression
labelOffsetMapUnitScale
labelPerPart
labelSettingsPreviewPixmap(settings: QgsPalLayerSettings, size: QSize, previewText: str = '', padding: int = 0) QPixmap

Returns a pixmap preview for label settings.

Parameters:
  • settings (QgsPalLayerSettings) – label settings

  • size (QSize) – target pixmap size

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

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

New in version 3.10.

Return type:

QPixmap

layerType
property leftDirectionSymbol

_getLeftDirectionSymbol(self) -> str

Return type:

str

legendString(self) str
legendString(None) None
Return type:

str

Returns:

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

property limitNumLabels

_limitNumLabels(self) -> bool

Return type:

bool

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

New in version 3.16.

Return type:

QgsLabelLineSettings

mCurFeat
mCurFields
mFeatsRegPal
mFeatsSendingToPal
mFeaturesToLabel
maxCurvedCharAngleIn
maxCurvedCharAngleOut
property maxNumLabels

_maxNumLabels(self) -> int

Return type:

int

maximumScale
property mergeLines

_getMergeLines(self) -> bool

Return type:

bool

property minFeatureSize

_minFeatureSize(self) -> float

Return type:

float

minimumScale
multilineAlign
property obstacle

_getIsObstacle(self) -> bool

Return type:

bool

property obstacleFactor

_getObstacleFactor(self) -> float

Return type:

float

obstacleSettings(self) QgsLabelObstacleSettings

Returns the label obstacle settings.

New in version 3.10.2.

Return type:

QgsLabelObstacleSettings

property obstacleType

_getObstacleType(self) -> QgsPalLayerSettings.ObstacleType

Return type:

QgsPalLayerSettings.ObstacleType

offsetType
offsetUnits
property overrunDistance

_getOverrunDistance(self) -> float

Return type:

float

property overrunDistanceMapUnitScale

_getOverrunDistanceMapUnitScale(self) -> QgsMapUnitScale

Return type:

QgsMapUnitScale

property overrunDistanceUnit

_getOverrunDistanceUnit(self) -> QgsUnitTypes.RenderUnit

Return type:

QgsUnitTypes.RenderUnit

property placeDirectionSymbol

_getPlaceDirectionSymbol(self) -> QgsPalLayerSettings.DirectionSymbols

Return type:

QgsPalLayerSettings.DirectionSymbols

placement
property placementFlags

_getLinePlacementFlags(self) -> int

Return type:

int

plusSign
polygonPlacementFlags(self) QgsLabeling.PolygonPlacementFlags

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

New in version 3.14.

Return type:

QgsLabeling.PolygonPlacementFlags

prepare(self, context: QgsRenderContext, attributeNames: Iterable[str], fields: QgsFields, mapSettings: QgsMapSettings, crs: QgsCoordinateReferenceSystem) Tuple[bool, Set[str]]

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.

New in version 3.8.

Parameters:
Return type:

Tuple[bool, Set[str]]

preserveRotation
previewBkgrdColor
priority
propertyDefinitions() Dict[int, QgsPropertyDefinition]

Returns the labeling property definitions.

New in version 3.0.

Return type:

Dict[int, QgsPropertyDefinition]

ptOne
ptZero
quadOffset
readXml(self, elem: QDomElement, context: QgsReadWriteContext)

Read settings from a DOM element

New in version 2.12.

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

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

New 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

_getReverseDirectionSymbol(self) -> bool

Return type:

bool

property rightDirectionSymbol

_getRightDirectionSymbol(self) -> str

Return type:

str

rotationUnit(self) QgsUnitTypes.AngleUnit

Unit for rotation of labels.

New in version 3.22.

Return type:

QgsUnitTypes.AngleUnit

scaleVisibility
setCallout(self, callout: QgsCallout)

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

Ownership of callout is transferred to the settings.

See also

callout()

New in version 3.10.

Parameters:

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

New in version 3.0.

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

New in version 3.0.

setLegendString(self, legendString: str)
setLegendString(None) None
Parameters:

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

New in version 3.16.

Parameters:

settings (QgsLabelLineSettings) –

setObstacleSettings(self, settings: QgsLabelObstacleSettings)

Sets the label obstacle settings.

New in version 3.10.2.

Parameters:

settings (QgsLabelObstacleSettings) –

setPolygonPlacementFlags(self, flags: QgsLabeling.PolygonPlacementFlags | QgsLabeling.PolygonPlacementFlag)

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

New in version 3.14.

Parameters:

flags (Union[QgsLabeling.PolygonPlacementFlags) –

setRotationUnit(self, angleUnit: QgsUnitTypes.AngleUnit)

Set unit for rotation of labels.

See also

rotationUnit()

New in version 3.22.

Parameters:

angleUnit (QgsUnitTypes.AngleUnit) –

setThinningSettings(self, settings: QgsLabelThinningSettings)

Sets the label thinning settings.

New in version 3.12.

Parameters:

settings (QgsLabelThinningSettings) –

setUnplacedVisibility(self, visibility: Qgis.UnplacedLabelVisibility)

Sets the layer’s unplaced label visibility.

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

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

New in version 3.10.

Parameters:

context (QgsRenderContext) –

substitutions
thinningSettings(self) QgsLabelThinningSettings

Returns the label thinning settings.

New in version 3.12.

Return type:

QgsLabelThinningSettings

unplacedVisibility(self) Qgis.UnplacedLabelVisibility

Returns the layer’s unplaced label visibility.

New 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

New in version 2.12.

Parameters:
Return type:

QDomElement

xOffset
xform
yOffset
zIndex