Class: QgsPalLayerSettings¶

Contains settings for how a map layer will be labeled.

class qgis.core.QgsPalLayerSettings[source]¶

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¶

autoWrapLength: int¶

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

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[source]¶

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¶

centroidWhole: bool¶

containsAdvancedEffects(self) → bool[source]¶

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¶

property displayAll¶

dist: float¶

distMapUnitScale: QgsMapUnitScale¶

distUnits: Qgis.RenderUnit¶

drawLabels: bool¶

extentGeom¶

fieldIndex¶

fieldName: str¶

fitInPolygonOnly: bool¶

fontLimitPixelSize: bool¶

fontMaxPixelSize: int¶

fontMinPixelSize: int¶

format(self) → QgsTextFormat¶

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

See also

setFormat()

Return type:: QgsTextFormat

formatNumbers: bool¶

static fromMimeData(data: QMimeData | None)[source]¶

Attempts to parse the provided mime data as a QgsPalLayerSettings. If data can be parsed as a labeling settings, ok will be set to True.

See also

toMimeData()

Added in version 4.0.

Parameters:: data (Optional[QMimeData]) -> (QgsPalLayerSettings)

geometryGenerator: str¶

geometryGeneratorEnabled: bool¶

geometryGeneratorType: Qgis.GeometryType¶

getLabelExpression(self) → QgsExpression | None[source]¶

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

Return type:: Optional[QgsExpression]

isExpression: bool¶

labelOffsetMapUnitScale: QgsMapUnitScale¶

labelPerPart: bool¶

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

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¶

property leftDirectionSymbol¶

legendString(self) → str[source]¶

legendString()

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¶

maxCurvedCharAngleOut: float¶

property maxNumLabels¶

maximumScale: float¶

property mergeLines¶

property minFeatureSize¶

minimumScale: float¶

multilineAlign: Qgis.LabelMultiLineAlignment¶

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¶

offsetUnits: Qgis.RenderUnit¶

property overrunDistance¶

property overrunDistanceMapUnitScale¶

property overrunDistanceUnit¶

property placeDirectionSymbol¶

placement: Qgis.LabelPlacement¶

property placementFlags¶

placementSettings(self) → QgsLabelPlacementSettings¶

Returns the label placement settings.

See also

setPlacementSettings()

Added in version 3.26.

Return type:: QgsLabelPlacementSettings

plusSign: bool¶

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[source]¶

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)[source]¶

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¶

previewBkgrdColor: QColor¶

priority: int¶

propertyDefinitions() → Dict[int, QgsPropertyDefinition]¶

Returns the labeling property definitions.

Return type:: Dict[int, QgsPropertyDefinition]

ptOne¶

ptZero¶

property quadOffset¶

readXml(self, elem: QDomElement, context: QgsReadWriteContext)[source]¶

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)[source]¶

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¶

repeatDistanceMapUnitScale: QgsMapUnitScale¶

repeatDistanceUnit: Qgis.RenderUnit¶

property reverseDirectionSymbol¶

property rightDirectionSymbol¶

rotationUnit(self) → Qgis.AngleUnit[source]¶

Unit for rotation of labels.

See also

setRotationUnit()

Added in version 3.22.

Return type:: Qgis.AngleUnit

scaleVisibility: bool¶

setCallout(self, callout: QgsCallout | None)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

setLegendString()

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

setLineSettings(self, settings: QgsLabelLineSettings)[source]¶

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)[source]¶

Sets the label obstacle settings.

See also

obstacleSettings()

Added in version 3.10.2.

Parameters:: settings (QgsLabelObstacleSettings)

setPlacementSettings(self, settings: QgsLabelPlacementSettings)[source]¶

Sets the label placement settings.

See also

placementSettings()

Added in version 3.26.

Parameters:: settings (QgsLabelPlacementSettings)

setPointSettings(self, settings: QgsLabelPointSettings)[source]¶

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.