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.

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.

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

Register a feature for labeling.

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.

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.

setThinningSettings

Sets the label thinning settings.

startRender

Prepares the label settings for rendering.

stopRender

Finalises the label settings after use.

thinningSettings

Returns the label thinning settings.

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

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

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)

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

  • labelFeature – if using QgsLabelingEngine, this will receive the label feature. Not available in Python bindings.

repeatDistance
repeatDistanceMapUnitScale
repeatDistanceUnit
property reverseDirectionSymbol

_getReverseDirectionSymbol(self) -> bool

Return type

bool

property rightDirectionSymbol

_getRightDirectionSymbol(self) -> str

Return type

str

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.

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: Union[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) –

setThinningSettings(self, settings: QgsLabelThinningSettings)

Sets the label thinning settings.

New in version 3.12.

Parameters

settings (QgsLabelThinningSettings) –

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

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