Class: QgsPalLayerSettings

class qgis.core.QgsPalLayerSettings

Bases: sip.wrapper

Contains settings for how a map layer will be labeled.

Enums

MultiLineAlign	alias of LabelMultiLineAlignment
OffsetType	alias of LabelOffsetType
Placement	alias of LabelPlacement
PredefinedPointPosition	alias of LabelPredefinedPointPosition
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.
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.
setPlacementSettings	Sets the label placement 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
AllowDegradedPlacement
AlwaysShow
AutoWrapLength
BelowLine
Bold
BufferBlendMode
BufferColor
BufferDraw
BufferJoinStyle
BufferOpacity
BufferSize
BufferTransp
BufferUnit
CalloutDraw
CentroidWhole
Color
CurvedCharAngleInOut
DirSymbDraw
DirSymbLeft
DirSymbPlacement
DirSymbReverse
DirSymbRight
DistanceUnits
Family
FontBlendMode
FontCase
FontLetterSpacing
FontLimitPixel
FontMaxPixel
FontMinPixel
FontOpacity
FontSizeUnit
FontStretchFactor
FontStyle
FontTransp
FontWordSpacing
Hali
IsObstacle
Italic
LabelAllParts
LabelDistance
LabelRotation
LineAnchorClipping
LineAnchorPercent
LineAnchorTextPoint
LineAnchorType
LinePlacementOptions
MapOrientation
MaskBufferSize
MaskBufferUnit
MaskEnabled
MaskJoinStyle
MaskOpacity
MaxScale
MaximumScale
MinScale
MinimumScale
MultiLineAlignment
MultiLineHeight
MultiLineWrapChar
NumDecimals
NumFormat
NumPlusSign
ObstacleFactor
OffsetQuad
OffsetRotation
OffsetUnits
OffsetXY
OnLine
OverlapHandling
OverrunDistance
PolygonBoundary
PolygonInterior
PolygonLabelOutside
PolygonWhole
PositionPoint
PositionX
PositionY
PredefinedPositionOrder
Priority
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
Size
Strikeout
SymbolAbove
SymbolBelow
SymbolLeftRight
TextOrientation
Underline
Vali
ZIndex

AboveLine = 2

AllowDegradedPlacement = 117

AlwaysShow = 20

AutoWrapLength = 101

BelowLine = 4

Bold = 1

BufferBlendMode = 45

BufferColor = 8

BufferDraw = 42

BufferJoinStyle = 44

BufferOpacity = 94

BufferSize = 7

BufferTransp = 19

BufferUnit = 43

CalloutDraw = 100

CentroidWhole = 76

Color = 4

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

FontStretchFactor = 113

FontStyle = 21

FontTransp = 18

FontWordSpacing = 29

Hali = 11

IsObstacle = 88

Italic = 2

LabelAllParts = 103

LabelDistance = 13

LabelRotation = 96

LineAnchorClipping = 112

LineAnchorPercent = 111

LineAnchorTextPoint = 116

LineAnchorType = 115

class LinePlacementFlags

Bases: int

LinePlacementOptions = 99

MapOrientation = 8

MaskBufferSize = 105

MaskBufferUnit = 106

MaskEnabled = 104

MaskJoinStyle = 108

MaskOpacity = 107

MaxScale = 17

MaximumScale = 98

MinScale = 16

MinimumScale = 97

MultiLineAlign

alias of LabelMultiLineAlignment

MultiLineAlignment = 33

MultiLineHeight = 32

MultiLineWrapChar = 31

NumDecimals = 40

NumFormat = 39

NumPlusSign = 41

ObstacleFactor = 89

class ObstacleType

Bases: int

OffsetQuad = 77

OffsetRotation = 82

OffsetType

alias of LabelOffsetType

OffsetUnits = 80

OffsetXY = 78

OnLine = 1

OverlapHandling = 118

OverrunDistance = 102

Placement

alias of LabelPlacement

PolygonBoundary = 1

PolygonInterior = 0

PolygonLabelOutside = 109

PolygonWhole = 2

PositionPoint = 114

PositionX = 9

PositionY = 10

PredefinedPointPosition

alias of LabelPredefinedPointPosition

PredefinedPositionOrder = 91

Priority = 87

class Property

Bases: int

QuadrantPosition

alias of LabelQuadrantPosition

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

Size = 0

Strikeout = 5

SymbolAbove = 1

SymbolBelow = 2

SymbolLeftRight = 0

TextOrientation = 110

Underline = 3

UpsideDownLabels

alias of UpsideDownLabelHandling

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:

• fm (QFontMetricsF) –

• text (str) –

• f (QgsFeature = None) –

• context (QgsRenderContext = None) –

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.

See also

setDataDefinedProperties()

New in version 3.0.

Return type:

QgsPropertyCollection

decimals

property displayAll

_getDisplayAll(self) -> bool

Return type:

bool

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

See also

setLineSettings()

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.

See also

setObstacleSettings()

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

placementSettings(self) → QgsLabelPlacementSettings

Returns the label placement settings.

See also

setPlacementSettings()

New in version 3.26.

Return type:

QgsLabelPlacementSettings

plusSign

polygonPlacementFlags(self) → QgsLabeling.PolygonPlacementFlags

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

See also

setPolygonPlacementFlags()

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:

• context (QgsRenderContext) –

• attributeNames (Iterable[str]) –

• fields (QgsFields) –

• mapSettings (QgsMapSettings) –

• crs (QgsCoordinateReferenceSystem) –

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:

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

New 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

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.

See also

setRotationUnit()

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

dataDefinedProperties()

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.

See also

obstacleSettings()

New in version 3.10.2.

Parameters:

settings (QgsLabelObstacleSettings) –

setPlacementSettings(self, settings: QgsLabelPlacementSettings)

Sets the label placement settings.

See also

placementSettings()

New in version 3.26.

Parameters:

settings (QgsLabelPlacementSettings) –

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

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

See also

polygonPlacementFlags()

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.

See also

thinningSettings()

New in version 3.12.

Parameters:

settings (QgsLabelThinningSettings) –

setUnplacedVisibility(self, visibility: Qgis.UnplacedLabelVisibility)

Sets the layer’s unplaced label visibility.

See also

unplacedVisibility()

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.

See also

setThinningSettings()

New in version 3.12.

Return type:

QgsLabelThinningSettings

unplacedVisibility(self) → Qgis.UnplacedLabelVisibility

Returns the layer’s unplaced label visibility.

See also

setUnplacedVisibility()

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:

• doc (QDomDocument) –

• context (QgsReadWriteContext) –

Return type:

QDomElement

xOffset

xform

yOffset

zIndex