Class: QgsPalLayerSettings¶
- class qgis.core.QgsPalLayerSettings¶
Bases:
sip.wrapper
Contains settings for how a map layer will be labeled.
Enums
alias of
LabelMultiLineAlignment
alias of
LabelOffsetType
alias of
LabelPlacement
alias of
LabelPredefinedPointPosition
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.
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¶
- 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 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
New in version 3.0.
- Return type:
- 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
New in version 3.0.
- 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) 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
New in version 3.16.
- Return type:
- 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
New in version 3.10.2.
- Return type:
- property obstacleType¶
_getObstacleType(self) -> QgsPalLayerSettings.ObstacleType
- Return type:
- offsetType¶
- offsetUnits¶
- property overrunDistance¶
_getOverrunDistance(self) -> float
- Return type:
float
- property overrunDistanceMapUnitScale¶
_getOverrunDistanceMapUnitScale(self) -> QgsMapUnitScale
- Return type:
- property overrunDistanceUnit¶
_getOverrunDistanceUnit(self) -> QgsUnitTypes.RenderUnit
- Return type:
- property placeDirectionSymbol¶
_getPlaceDirectionSymbol(self) -> QgsPalLayerSettings.DirectionSymbols
- Return type:
- placement¶
- property placementFlags¶
_getLinePlacementFlags(self) -> int
- Return type:
int
- placementSettings(self) QgsLabelPlacementSettings ¶
Returns the label placement settings.
See also
New in version 3.26.
- Return type:
- plusSign¶
- polygonPlacementFlags(self) QgsLabeling.PolygonPlacementFlags ¶
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.
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
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
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
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
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: QgsLabeling.PolygonPlacementFlags | QgsLabeling.PolygonPlacementFlag)¶
Sets the polygon placement
flags
, which dictate how polygon labels can be placed.See also
New in version 3.14.
- Parameters:
flags (Union[QgsLabeling.PolygonPlacementFlags) –
- setRotationUnit(self, angleUnit: QgsUnitTypes.AngleUnit)¶
Set unit for rotation of labels.
See also
New in version 3.22.
- Parameters:
angleUnit (QgsUnitTypes.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
New in version 2.12.
- Parameters:
doc (QDomDocument) –
context (QgsReadWriteContext) –
- Return type:
QDomElement
- xOffset¶
- xform¶
- yOffset¶
- zIndex¶