Class: QgsPalLayerSettings¶
- class qgis.core.QgsPalLayerSettings¶
Bases:
sip.wrapper
Contains settings for how a map layer will be labeled.
Enums
alias of
LabelMultiLineAlignment
Bases:
enum.IntEnum
alias of
LabelOffsetType
alias of
LabelPlacement
alias of
LabelPredefinedPointPosition
Bases:
enum.IntEnum
alias of
LabelQuadrantPosition
alias of
UpsideDownLabelHandling
Methods
Calculates the space required to render the provided
text
in map units.Returns the label callout renderer, responsible for drawing label callouts.
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.Returns a reference to the label's property collection, used for data defined overrides.
Returns the label text formatting settings, e.g., font settings, buffer settings, etc.
Returns the
QgsExpression
for this label settings.Returns a pixmap preview for label
settings
.- rtype:
str
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).
Returns the label obstacle settings.
Returns the label placement settings.
Returns the polygon placement flags, which dictate how polygon labels can be placed.
Prepare for registration of features.
Returns the labeling property definitions.
Read settings from a DOM element
Returns all field names referenced by the configuration (e.g. field name or expression, data defined properties).
Registers a feature for labeling.
Unit for rotation of labels.
Sets the label
callout
renderer, responsible for drawing label callouts.Sets the label's property collection, used for data defined overrides.
Sets the label text formatting settings, e.g., font settings, buffer settings, etc.
- type legendString:
str
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).Sets the label obstacle
settings
.Sets the label placement
settings
.Sets the polygon placement
flags
, which dictate how polygon labels can be placed.Set unit for rotation of labels.
Sets the label thinning
settings
.Sets the layer's unplaced label
visibility
.Prepares the label settings for rendering.
Finalises the label settings after use.
Returns the label thinning settings.
Returns the layer's unplaced label visibility.
Write settings into a DOM element
Attributes
- AboveLine = 2¶
- BelowLine = 4¶
- class LinePlacementFlags¶
Bases:
object
- AboveLine = 2¶
- BelowLine = 4¶
- MapOrientation = 8¶
- OnLine = 1¶
- MapOrientation = 8¶
- MultiLineAlign¶
alias of
LabelMultiLineAlignment
- class ObstacleType(value)¶
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)¶
Bases:
enum.IntEnum
Data definable properties.
Size
: Label sizeBold
: Use bold styleItalic
: Use italic styleUnderline
: Use underlineColor
: Text colorStrikeout
: Use strikeoutFamily
: Font familyFontStyle
: Font style nameFontSizeUnit
: Font size unitsFontTransp
: Text transparency (deprecated)FontOpacity
: Text opacityFontCase
: Label text caseFontLetterSpacing
: Letter spacingFontWordSpacing
: Word spacingFontBlendMode
: Text blend modeFontStretchFactor
: Font stretch factor, since QGIS 3.24MultiLineWrapChar
:AutoWrapLength
:MultiLineHeight
:MultiLineAlignment
:TextOrientation
:DirSymbDraw
:DirSymbLeft
:DirSymbRight
:DirSymbPlacement
:DirSymbReverse
:NumFormat
:NumDecimals
:NumPlusSign
:BufferDraw
:BufferSize
:BufferUnit
:BufferColor
:BufferTransp
: Buffer transparency (deprecated)BufferOpacity
: Buffer opacityBufferJoinStyle
:BufferBlendMode
:MaskEnabled
: Whether the mask is enabledMaskBufferSize
: Mask buffer sizeMaskBufferUnit
: Mask buffer size unitMaskOpacity
: Mask opacityMaskJoinStyle
: Mask join styleShapeDraw
:ShapeKind
:ShapeSVGFile
:ShapeSizeType
:ShapeSizeX
:ShapeSizeY
:ShapeSizeUnits
:ShapeRotationType
:ShapeRotation
:ShapeOffset
:ShapeOffsetUnits
:ShapeRadii
:ShapeRadiiUnits
:ShapeTransparency
: Shape transparency (deprecated)ShapeOpacity
: Shape opacityShapeBlendMode
:ShapeFillColor
:ShapeStrokeColor
:ShapeStrokeWidth
:ShapeStrokeWidthUnits
:ShapeJoinStyle
:ShadowDraw
:ShadowUnder
:ShadowOffsetAngle
:ShadowOffsetDist
:ShadowOffsetUnits
:ShadowRadius
:ShadowRadiusUnits
:ShadowTransparency
: Shadow transparency (deprecated)ShadowOpacity
: Shadow opacityShadowScale
:ShadowColor
:ShadowBlendMode
:CentroidWhole
:OffsetQuad
:OffsetXY
:OffsetUnits
:LabelDistance
:DistanceUnits
:OffsetRotation
:CurvedCharAngleInOut
:PositionX
: X-coordinate data defined label positionPositionY
: Y-coordinate data defined label positionPositionPoint
: Point-coordinate data defined label positionHali
: 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 rotationRepeatDistance
:RepeatDistanceUnit
:Priority
:PredefinedPositionOrder
:LinePlacementOptions
: Line placement flagsOverrunDistance
: Distance which labels can extend past either end of linear featuresLabelAllParts
: Whether all parts of multi-part features should be labeledPolygonLabelOutside
: 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 calloutAllowDegradedPlacement
: 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, 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 tolabelX
andlabelY
. If the text orientation is set to rotation-based, the spaced taken to render vertically oriented text will be written torotatedLabelX
androtatedLabelY
.- 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
New in version 3.10.
- Return type:
- 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
- Return type:
- 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
- Return type:
- formatNumbers¶
- geometryGenerator¶
- geometryGeneratorEnabled¶
- geometryGeneratorType¶
- getLabelExpression(self) QgsExpression ¶
Returns the
QgsExpression
for this label settings. May beNone
if isExpression isFalse
.- Return type:
- isExpression¶
- labelOffsetMapUnitScale¶
- labelPerPart¶
- labelSettingsPreviewPixmap(settings: QgsPalLayerSettings, size: QSize, previewText: str = '', 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 (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)
New 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).
See also
New in version 3.16.
- Return type:
- 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.
See also
New in version 3.10.2.
- Return type:
- property obstacleType¶
- offsetType¶
- offsetUnits¶
- property overrunDistance¶
- property overrunDistanceMapUnitScale¶
- property overrunDistanceUnit¶
- property placeDirectionSymbol¶
- placement¶
- property placementFlags¶
- placementSettings(self) QgsLabelPlacementSettings ¶
Returns the label placement settings.
See also
New in version 3.26.
- Return type:
- plusSign¶
- polygonPlacementFlags(self) Qgis.LabelPolygonPlacementFlags ¶
Returns the polygon placement flags, which dictate how polygon labels can be placed.
See also
New in version 3.14.
- Return type:
- 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
andfields
parameters give more information about the rendering environment. If targetcrs
is not specified, the targetCrs frommapSettings
will be taken. The parameterattributeNames
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.
- Return type:
Dict[int, QgsPropertyDefinition]
- ptOne¶
- ptZero¶
- quadOffset¶
- readXml(self, elem: QDomElement, context: QgsReadWriteContext)¶
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).
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¶
- property rightDirectionSymbol¶
- rotationUnit(self) Qgis.AngleUnit ¶
Unit for rotation of labels.
See also
New in version 3.22.
- Return type:
- 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
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
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
- 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
New in version 3.16.
- Parameters:
settings (QgsLabelLineSettings) –
- setObstacleSettings(self, settings: QgsLabelObstacleSettings)¶
Sets the label obstacle
settings
.See also
New in version 3.10.2.
- Parameters:
settings (QgsLabelObstacleSettings) –
- setPlacementSettings(self, settings: QgsLabelPlacementSettings)¶
Sets the label placement
settings
.See also
New in version 3.26.
- Parameters:
settings (QgsLabelPlacementSettings) –
- setPolygonPlacementFlags(self, flags: Qgis.LabelPolygonPlacementFlags | Qgis.LabelPolygonPlacementFlag)¶
Sets the polygon placement
flags
, which dictate how polygon labels can be placed.See also
New in version 3.14.
- Parameters:
flags (Union[Qgis.LabelPolygonPlacementFlags) –
- setRotationUnit(self, angleUnit: Qgis.AngleUnit)¶
Set unit for rotation of labels.
See also
New in version 3.22.
- Parameters:
angleUnit (Qgis.AngleUnit) –
- setThinningSettings(self, settings: QgsLabelThinningSettings)¶
Sets the label thinning
settings
.See also
New in version 3.12.
- Parameters:
settings (QgsLabelThinningSettings) –
- setUnplacedVisibility(self, visibility: Qgis.UnplacedLabelVisibility)¶
Sets the layer’s unplaced label
visibility
.See also
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
New in version 3.12.
- Return type:
- unplacedVisibility(self) Qgis.UnplacedLabelVisibility ¶
Returns the layer’s unplaced label visibility.
See also
New in version 3.20.
- Return type:
- upsidedownLabels¶
- useMaxLineLengthForAutoWrap¶
- useSubstitutions¶
- wrapChar¶
- writeXml(self, doc: QDomDocument, context: QgsReadWriteContext) QDomElement ¶
Write settings into a DOM element
- Parameters:
doc (QDomDocument) –
context (QgsReadWriteContext) –
- Return type:
QDomElement
- xOffset¶
- xform¶
- yOffset¶
- zIndex¶