QGIS API Documentation 3.39.0-Master (93ce9bf5c90)
Loading...
Searching...
No Matches
Public Types | Public Member Functions | Static Public Member Functions | Public Attributes | Friends | List of all members
QgsPalLayerSettings Class Reference

Contains settings for how a map layer will be labeled. More...

#include <qgspallabeling.h>

Public Types

enum class  Property : int {
  Size = 0 , Bold = 1 , Italic = 2 , Underline = 3 ,
  Color = 4 , Strikeout = 5 , Family = 6 , FontStyle = 21 ,
  FontSizeUnit = 22 , FontTransp = 18 , FontOpacity = 92 , FontCase = 27 ,
  FontLetterSpacing = 28 , FontWordSpacing = 29 , FontBlendMode = 30 , FontStretchFactor = 113 ,
  MultiLineWrapChar = 31 , AutoWrapLength = 101 , MultiLineHeight = 32 , MultiLineAlignment = 33 ,
  TextOrientation = 110 , TabStopDistance = 120 , DirSymbDraw = 34 , DirSymbLeft = 35 ,
  DirSymbRight = 36 , DirSymbPlacement = 37 , DirSymbReverse = 38 , NumFormat = 39 ,
  NumDecimals = 40 , NumPlusSign = 41 , BufferDraw = 42 , BufferSize = 7 ,
  BufferUnit = 43 , BufferColor = 8 , BufferTransp = 19 , BufferOpacity = 94 ,
  BufferJoinStyle = 44 , BufferBlendMode = 45 , MaskEnabled = 104 , MaskBufferSize = 105 ,
  MaskBufferUnit = 106 , MaskOpacity = 107 , MaskJoinStyle = 108 , ShapeDraw = 46 ,
  ShapeKind = 47 , ShapeSVGFile = 48 , ShapeSizeType = 49 , ShapeSizeX = 50 ,
  ShapeSizeY = 85 , ShapeSizeUnits = 51 , ShapeRotationType = 52 , ShapeRotation = 53 ,
  ShapeOffset = 54 , ShapeOffsetUnits = 55 , ShapeRadii = 56 , ShapeRadiiUnits = 57 ,
  ShapeTransparency = 63 , ShapeOpacity = 93 , ShapeBlendMode = 64 , ShapeFillColor = 58 ,
  ShapeStrokeColor = 59 , ShapeStrokeWidth = 60 , ShapeStrokeWidthUnits = 61 , ShapeJoinStyle = 62 ,
  ShadowDraw = 65 , ShadowUnder = 66 , ShadowOffsetAngle = 67 , ShadowOffsetDist = 68 ,
  ShadowOffsetUnits = 69 , ShadowRadius = 70 , ShadowRadiusUnits = 71 , ShadowTransparency = 72 ,
  ShadowOpacity = 95 , ShadowScale = 73 , ShadowColor = 74 , ShadowBlendMode = 75 ,
  CentroidWhole = 76 , OffsetQuad = 77 , OffsetXY = 78 , OffsetUnits = 80 ,
  LabelDistance = 13 , MaximumDistance = 119 , DistanceUnits = 81 , OffsetRotation = 82 ,
  CurvedCharAngleInOut = 83 , PositionX = 9 , PositionY = 10 , PositionPoint = 114 ,
  Hali = 11 , Vali = 12 , Rotation = 14 , LabelRotation = 96 ,
  RepeatDistance = 84 , RepeatDistanceUnit = 86 , Priority = 87 , PredefinedPositionOrder = 91 ,
  LinePlacementOptions = 99 , OverrunDistance = 102 , LabelAllParts = 103 , PolygonLabelOutside = 109 ,
  LineAnchorPercent = 111 , LineAnchorClipping = 112 , LineAnchorType = 115 , LineAnchorTextPoint = 116 ,
  ScaleVisibility = 23 , MinScale = 16 , MinimumScale = 97 , MaxScale = 17 ,
  MaximumScale = 98 , FontLimitPixel = 24 , FontMinPixel = 25 , FontMaxPixel = 26 ,
  IsObstacle = 88 , ObstacleFactor = 89 , ZIndex = 90 , CalloutDraw = 100 ,
  AllowDegradedPlacement = 117 , OverlapHandling = 118 , Show = 15 , AlwaysShow = 20
}
 Data definable properties. More...
 

Public Member Functions

 QgsPalLayerSettings ()
 
 QgsPalLayerSettings (const QgsPalLayerSettings &s)
 
 ~QgsPalLayerSettings ()
 
void calculateLabelSize (const QFontMetricsF *fm, const QString &text, double &labelX, double &labelY, const QgsFeature *f=nullptr, QgsRenderContext *context=nullptr, double *rotatedLabelX=nullptr, double *rotatedLabelY=nullptr, QgsTextFormat *format=nullptr, QgsTextDocument *document=nullptr, QgsTextDocumentMetrics *documentMetrics=nullptr, QRectF *outerBounds=nullptr)
 Calculates the space required to render the provided text in map units.
 
QgsCalloutcallout () const
 Returns the label callout renderer, responsible for drawing label callouts.
 
bool containsAdvancedEffects () const
 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.
 
QgsPropertyCollectiondataDefinedProperties ()
 Returns a reference to the label's property collection, used for data defined overrides.
 
const QgsPropertyCollectiondataDefinedProperties () const
 Returns a reference to the label's property collection, used for data defined overrides.
 
const QgsTextFormatformat () const
 Returns the label text formatting settings, e.g., font settings, buffer settings, etc.
 
QgsExpressiongetLabelExpression ()
 Returns the QgsExpression for this label settings.
 
QString legendString () const
 legendString
 
QgsLabelLineSettingslineSettings ()
 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).
 
const QgsLabelLineSettingslineSettings () const
 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).
 
QgsLabelObstacleSettingsobstacleSettings ()
 Returns the label obstacle settings.
 
const QgsLabelObstacleSettingsobstacleSettings () const
 Returns the label obstacle settings.
 
QgsPalLayerSettingsoperator= (const QgsPalLayerSettings &s)
 copy operator - only copies the permanent members
 
QgsLabelPlacementSettingsplacementSettings ()
 Returns the label placement settings.
 
const QgsLabelPlacementSettingsplacementSettings () const
 Returns the label placement settings.
 
QgsLabelPointSettingspointSettings ()
 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.
 
const QgsLabelPointSettingspointSettings () const
 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.
 
Qgis::LabelPolygonPlacementFlags polygonPlacementFlags () const
 Returns the polygon placement flags, which dictate how polygon labels can be placed.
 
bool prepare (QgsRenderContext &context, QSet< QString > &attributeNames, const QgsFields &fields, const QgsMapSettings &mapSettings, const QgsCoordinateReferenceSystem &crs)
 Prepare for registration of features.
 
void readXml (const QDomElement &elem, const QgsReadWriteContext &context)
 Read settings from a DOM element.
 
QSet< QString > referencedFields (const QgsRenderContext &context) const
 Returns all field names referenced by the configuration (e.g.
 
void registerFeature (const QgsFeature &f, QgsRenderContext &context)
 Registers a feature for labeling.
 
std::unique_ptr< QgsLabelFeatureregisterFeatureWithDetails (const QgsFeature &feature, QgsRenderContext &context, QgsGeometry obstacleGeometry=QgsGeometry(), const QgsSymbol *symbol=nullptr)
 Registers a feature for labeling.
 
Qgis::AngleUnit rotationUnit () const
 Unit for rotation of labels.
 
void setCallout (QgsCallout *callout)
 Sets the label callout renderer, responsible for drawing label callouts.
 
void setDataDefinedProperties (const QgsPropertyCollection &collection)
 Sets the label's property collection, used for data defined overrides.
 
void setFormat (const QgsTextFormat &format)
 Sets the label text formatting settings, e.g., font settings, buffer settings, etc.
 
void setLegendString (const QString &legendString)
 setLegendString
 
void setLineSettings (const QgsLabelLineSettings &settings)
 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).
 
void setObstacleSettings (const QgsLabelObstacleSettings &settings)
 Sets the label obstacle settings.
 
void setPlacementSettings (const QgsLabelPlacementSettings &settings)
 Sets the label placement settings.
 
void setPointSettings (const QgsLabelPointSettings &settings)
 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.
 
void setPolygonPlacementFlags (Qgis::LabelPolygonPlacementFlags flags)
 Sets the polygon placement flags, which dictate how polygon labels can be placed.
 
void setRotationUnit (Qgis::AngleUnit angleUnit)
 Set unit for rotation of labels.
 
void setThinningSettings (const QgsLabelThinningSettings &settings)
 Sets the label thinning settings.
 
void setUnplacedVisibility (Qgis::UnplacedLabelVisibility visibility)
 Sets the layer's unplaced label visibility.
 
void startRender (QgsRenderContext &context)
 Prepares the label settings for rendering.
 
void stopRender (QgsRenderContext &context)
 Finalises the label settings after use.
 
QgsLabelThinningSettingsthinningSettings ()
 Returns the label thinning settings.
 
const QgsLabelThinningSettingsthinningSettings () const
 Returns the label thinning settings.
 
Qgis::UnplacedLabelVisibility unplacedVisibility () const
 Returns the layer's unplaced label visibility.
 
QDomElement writeXml (QDomDocument &doc, const QgsReadWriteContext &context) const
 Write settings into a DOM element.
 

Static Public Member Functions

static QPixmap labelSettingsPreviewPixmap (const QgsPalLayerSettings &settings, QSize size, const QString &previewText=QString(), int padding=0, const QgsScreenProperties &screen=QgsScreenProperties())
 Returns a pixmap preview for label settings.
 
static const QgsPropertiesDefinitionpropertyDefinitions ()
 Returns the labeling property definitions.
 

Public Attributes

double angleOffset = 0
 Label rotation, in degrees clockwise.
 
int autoWrapLength = 0
 If non-zero, indicates that label text should be automatically wrapped to (ideally) the specified number of characters.
 
bool centroidInside = false
 true if centroid positioned labels must be placed inside their corresponding feature polygon, or false if centroids which fall outside the polygon are permitted.
 
bool centroidWhole = false
 true if feature centroid should be calculated from the whole feature, or false if only the visible part of the feature should be considered.
 
QgsCoordinateTransform ct
 
int decimals = 3
 Number of decimal places to show for numeric labels.
 
double dist = 0
 Distance from feature to the label.
 
QgsMapUnitScale distMapUnitScale
 Map unit scale for label feature distance.
 
Qgis::RenderUnit distUnits = Qgis::RenderUnit::Millimeters
 Units the distance from feature to the label.
 
bool drawLabels = true
 Whether to draw labels for this layer.
 
QgsGeometry extentGeom
 
int fieldIndex = 0
 
QString fieldName
 Name of field (or an expression) to use for label text.
 
bool fitInPolygonOnly = false
 true if only labels which completely fit within a polygon are allowed.
 
bool fontLimitPixelSize = false
 true if label sizes should be limited by pixel size.
 
int fontMaxPixelSize = 10000
 Maximum pixel size for showing rendered map unit labels (1 - 10000).
 
int fontMinPixelSize = 0
 Minimum pixel size for showing rendered map unit labels (1 - 1000).
 
bool formatNumbers = false
 Set to true to format numeric label text as numbers (e.g.
 
QString geometryGenerator
 The geometry generator expression. Null if disabled.
 
bool geometryGeneratorEnabled = false
 Defines if the geometry generator is enabled or not. If disabled, the standard geometry will be taken.
 
Qgis::GeometryType geometryGeneratorType = Qgis::GeometryType::Point
 The type of the result geometry of the geometry generator.
 
bool isExpression = false
 true if this label is made from a expression string, e.g., FieldName || 'mm'
 
QgsMapUnitScale labelOffsetMapUnitScale
 Map unit scale for label offset.
 
bool labelPerPart = false
 true if every part of a multi-part feature should be labeled.
 
Qgis::GeometryType layerType = Qgis::GeometryType::Unknown
 Geometry type of layers associated with these settings.
 
double maxCurvedCharAngleIn = 25.0
 Maximum angle between inside curved label characters (valid range 20.0 to 60.0).
 
double maxCurvedCharAngleOut = -25.0
 Maximum angle between outside curved label characters (valid range -20.0 to -95.0)
 
double maximumScale = 0
 The maximum map scale (i.e.
 
const QgsFeaturemCurFeat = nullptr
 
QgsFields mCurFields
 
int mFeatsRegPal = 0
 
int mFeatsSendingToPal = 0
 
int mFeaturesToLabel = 0
 
double minimumScale = 0
 The minimum map scale (i.e.
 
Qgis::LabelMultiLineAlignment multilineAlign = Qgis::LabelMultiLineAlignment::FollowPlacement
 Horizontal alignment of multi-line labels.
 
Qgis::LabelOffsetType offsetType = Qgis::LabelOffsetType::FromPoint
 Offset type for layer (only applies in certain placement modes)
 
Qgis::RenderUnit offsetUnits = Qgis::RenderUnit::Millimeters
 Units for offsets of label.
 
Qgis::LabelPlacement placement = Qgis::LabelPlacement::AroundPoint
 Label placement mode.
 
bool plusSign = false
 Whether '+' signs should be prepended to positive numeric labels.
 
bool preserveRotation = true
 True if label rotation should be preserved during label pin/unpin operations.
 
Q_DECL_DEPRECATED QColor previewBkgrdColor = Qt::white
 
int priority = 5
 Label priority.
 
QgsPointXY ptOne
 
QgsPointXY ptZero
 
double repeatDistance = 0
 Distance for repeating labels for a single feature.
 
QgsMapUnitScale repeatDistanceMapUnitScale
 Map unit scale for repeating labels for a single feature.
 
Qgis::RenderUnit repeatDistanceUnit = Qgis::RenderUnit::Millimeters
 Units for repeating labels for a single feature.
 
bool scaleVisibility = false
 Set to true to limit label visibility to a range of scales.
 
QgsStringReplacementCollection substitutions
 Substitution collection for automatic text substitution with labels.
 
Qgis::UpsideDownLabelHandling upsidedownLabels = Qgis::UpsideDownLabelHandling::FlipUpsideDownLabels
 Controls whether upside down labels are displayed and how they are handled.
 
bool useMaxLineLengthForAutoWrap = true
 If true, indicates that when auto wrapping label text the autoWrapLength length indicates the maximum ideal length of text lines.
 
bool useSubstitutions = false
 True if substitutions should be applied.
 
QString wrapChar
 Wrapping character string.
 
const QgsMapToPixelxform = nullptr
 
double xOffset = 0
 Horizontal offset of label.
 
double yOffset = 0
 Vertical offset of label.
 
double zIndex = 0
 Z-Index of label, where labels with a higher z-index are rendered on top of labels with a lower z-index.
 

Friends

class QgsVectorLayer
 

Detailed Description

Contains settings for how a map layer will be labeled.

Definition at line 87 of file qgspallabeling.h.

Member Enumeration Documentation

◆ Property

enum class QgsPalLayerSettings::Property : int
strong

Data definable properties.

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

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

AllowDegradedPlacement 

Allow degraded label placements.

Since
QGIS 3.26
OverlapHandling 

Overlap handling technique.

Since
QGIS 3.26
Show 
AlwaysShow 

Definition at line 99 of file qgspallabeling.h.

Constructor & Destructor Documentation

◆ QgsPalLayerSettings() [1/2]

Q_NOWARN_DEPRECATED_PUSH QgsPalLayerSettings::QgsPalLayerSettings ( )

Definition at line 262 of file qgspallabeling.cpp.

◆ QgsPalLayerSettings() [2/2]

Q_NOWARN_DEPRECATED_POP Q_NOWARN_DEPRECATED_PUSH QgsPalLayerSettings::QgsPalLayerSettings ( const QgsPalLayerSettings s)

Definition at line 274 of file qgspallabeling.cpp.

◆ ~QgsPalLayerSettings()

QgsPalLayerSettings::~QgsPalLayerSettings ( )

Definition at line 592 of file qgspallabeling.cpp.

Member Function Documentation

◆ calculateLabelSize()

void QgsPalLayerSettings::calculateLabelSize ( const QFontMetricsF *  fm,
const QString &  text,
double &  labelX,
double &  labelY,
const QgsFeature f = nullptr,
QgsRenderContext context = nullptr,
double *  rotatedLabelX = nullptr,
double *  rotatedLabelY = nullptr,
QgsTextFormat format = nullptr,
QgsTextDocument document = nullptr,
QgsTextDocumentMetrics documentMetrics = nullptr,
QRectF *  outerBounds = nullptr 
)

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 .

Definition at line 1545 of file qgspallabeling.cpp.

◆ callout()

QgsCallout * QgsPalLayerSettings::callout ( ) const
inline

Returns the label callout renderer, responsible for drawing label callouts.

Ownership is not transferred.

See also
setCallout()
Since
QGIS 3.10

Definition at line 732 of file qgspallabeling.h.

◆ containsAdvancedEffects()

bool QgsPalLayerSettings::containsAdvancedEffects ( ) const

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.

Since
QGIS 3.20

Definition at line 587 of file qgspallabeling.cpp.

◆ dataDefinedProperties() [1/2]

QgsPropertyCollection & QgsPalLayerSettings::dataDefinedProperties ( )
inline

Returns a reference to the label's property collection, used for data defined overrides.

See also
setDataDefinedProperties()

Definition at line 693 of file qgspallabeling.h.

◆ dataDefinedProperties() [2/2]

const QgsPropertyCollection & QgsPalLayerSettings::dataDefinedProperties ( ) const
inline

Returns a reference to the label's property collection, used for data defined overrides.

See also
setDataDefinedProperties()
Property
Note
not available in Python bindings

Definition at line 701 of file qgspallabeling.h.

◆ format()

const QgsTextFormat & QgsPalLayerSettings::format ( ) const
inline

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

See also
setFormat()

Definition at line 715 of file qgspallabeling.h.

◆ getLabelExpression()

QgsExpression * QgsPalLayerSettings::getLabelExpression ( )

Returns the QgsExpression for this label settings.

May be nullptr if isExpression is false.

Definition at line 611 of file qgspallabeling.cpp.

◆ labelSettingsPreviewPixmap()

QPixmap QgsPalLayerSettings::labelSettingsPreviewPixmap ( const QgsPalLayerSettings settings,
QSize  size,
const QString &  previewText = QString(),
int  padding = 0,
const QgsScreenProperties screen = QgsScreenProperties() 
)
static

Returns a pixmap preview for label settings.

Parameters
settingslabel settings
sizetarget pixmap size
previewTexttext to render in preview, or empty for default text
paddingspace between icon edge and color ramp
screencan 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)
Since
QGIS 3.10

Definition at line 1384 of file qgspallabeling.cpp.

◆ legendString()

QString QgsPalLayerSettings::legendString ( ) const
inline

legendString

Returns
the string to show in the legend and in the preview icon

Definition at line 631 of file qgspallabeling.h.

◆ lineSettings() [1/2]

QgsLabelLineSettings & QgsPalLayerSettings::lineSettings ( )
inline

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()
Since
QGIS 3.16

Definition at line 761 of file qgspallabeling.h.

◆ lineSettings() [2/2]

const QgsLabelLineSettings & QgsPalLayerSettings::lineSettings ( ) const
inline

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()
Note
Not available in Python bindings
Since
QGIS 3.16

Definition at line 752 of file qgspallabeling.h.

◆ obstacleSettings() [1/2]

QgsLabelObstacleSettings & QgsPalLayerSettings::obstacleSettings ( )
inline

Returns the label obstacle settings.

See also
setObstacleSettings()
Since
QGIS 3.10.2

Definition at line 816 of file qgspallabeling.h.

◆ obstacleSettings() [2/2]

const QgsLabelObstacleSettings & QgsPalLayerSettings::obstacleSettings ( ) const
inline

Returns the label obstacle settings.

See also
setObstacleSettings()
Note
Not available in Python bindings
Since
QGIS 3.10.2

Definition at line 809 of file qgspallabeling.h.

◆ operator=()

Q_NOWARN_DEPRECATED_POP QgsPalLayerSettings & QgsPalLayerSettings::operator= ( const QgsPalLayerSettings s)

copy operator - only copies the permanent members

Definition at line 282 of file qgspallabeling.cpp.

◆ placementSettings() [1/2]

QgsLabelPlacementSettings & QgsPalLayerSettings::placementSettings ( )
inline

Returns the label placement settings.

See also
setPlacementSettings()
Since
QGIS 3.26

Definition at line 860 of file qgspallabeling.h.

◆ placementSettings() [2/2]

const QgsLabelPlacementSettings & QgsPalLayerSettings::placementSettings ( ) const
inline

Returns the label placement settings.

See also
setPlacementSettings()
Note
Not available in Python bindings
Since
QGIS 3.26

Definition at line 853 of file qgspallabeling.h.

◆ pointSettings() [1/2]

QgsLabelPointSettings & QgsPalLayerSettings::pointSettings ( )
inline

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()
Since
QGIS 3.38

Definition at line 791 of file qgspallabeling.h.

◆ pointSettings() [2/2]

const QgsLabelPointSettings & QgsPalLayerSettings::pointSettings ( ) const
inline

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()
Note
Not available in Python bindings
Since
QGIS 3.38

Definition at line 781 of file qgspallabeling.h.

◆ polygonPlacementFlags()

Qgis::LabelPolygonPlacementFlags QgsPalLayerSettings::polygonPlacementFlags ( ) const
inline

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

See also
setPolygonPlacementFlags()
Since
QGIS 3.14

Definition at line 397 of file qgspallabeling.h.

◆ prepare()

bool QgsPalLayerSettings::prepare ( QgsRenderContext context,
QSet< QString > &  attributeNames,
const QgsFields fields,
const QgsMapSettings mapSettings,
const QgsCoordinateReferenceSystem crs 
)

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.

Since
QGIS 3.8

Definition at line 368 of file qgspallabeling.cpp.

◆ propertyDefinitions()

const QgsPropertiesDefinition & QgsPalLayerSettings::propertyDefinitions ( )
static

Returns the labeling property definitions.

Definition at line 605 of file qgspallabeling.cpp.

◆ readXml()

void QgsPalLayerSettings::readXml ( const QDomElement &  elem,
const QgsReadWriteContext context 
)

Read settings from a DOM element.

Definition at line 959 of file qgspallabeling.cpp.

◆ referencedFields()

QSet< QString > QgsPalLayerSettings::referencedFields ( const QgsRenderContext context) const

Returns all field names referenced by the configuration (e.g.

field name or expression, data defined properties).

Since
QGIS 3.14

Definition at line 498 of file qgspallabeling.cpp.

◆ registerFeature()

void QgsPalLayerSettings::registerFeature ( const QgsFeature f,
QgsRenderContext context 
)

Registers a feature for labeling.

Parameters
ffeature to label
contextrender 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.

Definition at line 1818 of file qgspallabeling.cpp.

◆ registerFeatureWithDetails()

std::unique_ptr< QgsLabelFeature > QgsPalLayerSettings::registerFeatureWithDetails ( const QgsFeature feature,
QgsRenderContext context,
QgsGeometry  obstacleGeometry = QgsGeometry(),
const QgsSymbol symbol = nullptr 
)

Registers a feature for labeling.

Parameters
featurefeature to label
contextrender context. The QgsExpressionContext contained within the render context must have already had the feature and fields set prior to calling this method.
obstacleGeometryoptional obstacle geometry, if a different geometry to the feature's geometry should be used as an obstacle for labels (e.g., if the feature has been rendered with an offset point symbol, the obstacle geometry should represent the bounds of the offset symbol). If not set, the feature's original geometry will be used as an obstacle for labels.
symbolfeature symbol to label (ownership is not transferred, and symbol must exist until the labeling is complete)
Returns
QgsLabelFeature representing the registered feature, or nullptr if the feature will not be labeled in this context.
Note
Not available in Python bindings

Definition at line 1823 of file qgspallabeling.cpp.

◆ rotationUnit()

Qgis::AngleUnit QgsPalLayerSettings::rotationUnit ( ) const

Unit for rotation of labels.

See also
setRotationUnit()
Since
QGIS 3.22

Definition at line 620 of file qgspallabeling.cpp.

◆ setCallout()

void QgsPalLayerSettings::setCallout ( QgsCallout callout)

Sets the label callout renderer, responsible for drawing label callouts.

Ownership of callout is transferred to the settings.

See also
callout()
Since
QGIS 3.10

Definition at line 1379 of file qgspallabeling.cpp.

◆ setDataDefinedProperties()

void QgsPalLayerSettings::setDataDefinedProperties ( const QgsPropertyCollection collection)
inline

Sets the label's property collection, used for data defined overrides.

Parameters
collectionproperty collection. Existing properties will be replaced.
See also
dataDefinedProperties()
Property

Definition at line 709 of file qgspallabeling.h.

◆ setFormat()

void QgsPalLayerSettings::setFormat ( const QgsTextFormat format)
inline

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

Parameters
formatlabel text format
See also
format()

Definition at line 722 of file qgspallabeling.h.

◆ setLegendString()

void QgsPalLayerSettings::setLegendString ( const QString &  legendString)
inline

setLegendString

Parameters
legendStringthe string to show in the legend and preview

Definition at line 625 of file qgspallabeling.h.

◆ setLineSettings()

void QgsPalLayerSettings::setLineSettings ( const QgsLabelLineSettings settings)
inline

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()
Since
QGIS 3.16

Definition at line 770 of file qgspallabeling.h.

◆ setObstacleSettings()

void QgsPalLayerSettings::setObstacleSettings ( const QgsLabelObstacleSettings settings)
inline

Sets the label obstacle settings.

See also
obstacleSettings()
Since
QGIS 3.10.2

Definition at line 823 of file qgspallabeling.h.

◆ setPlacementSettings()

void QgsPalLayerSettings::setPlacementSettings ( const QgsLabelPlacementSettings settings)
inline

Sets the label placement settings.

See also
placementSettings()
Since
QGIS 3.26

Definition at line 867 of file qgspallabeling.h.

◆ setPointSettings()

void QgsPalLayerSettings::setPointSettings ( const QgsLabelPointSettings settings)
inline

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()
Since
QGIS 3.38

Definition at line 801 of file qgspallabeling.h.

◆ setPolygonPlacementFlags()

void QgsPalLayerSettings::setPolygonPlacementFlags ( Qgis::LabelPolygonPlacementFlags  flags)
inline

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

See also
polygonPlacementFlags()
Since
QGIS 3.14

Definition at line 405 of file qgspallabeling.h.

◆ setRotationUnit()

void QgsPalLayerSettings::setRotationUnit ( Qgis::AngleUnit  angleUnit)

Set unit for rotation of labels.

See also
rotationUnit()
Since
QGIS 3.22

Definition at line 625 of file qgspallabeling.cpp.

◆ setThinningSettings()

void QgsPalLayerSettings::setThinningSettings ( const QgsLabelThinningSettings settings)
inline

Sets the label thinning settings.

See also
thinningSettings()
Since
QGIS 3.12

Definition at line 845 of file qgspallabeling.h.

◆ setUnplacedVisibility()

void QgsPalLayerSettings::setUnplacedVisibility ( Qgis::UnplacedLabelVisibility  visibility)

Sets the layer's unplaced label visibility.

See also
unplacedVisibility()
Since
QGIS 3.20

Definition at line 1535 of file qgspallabeling.cpp.

◆ startRender()

void QgsPalLayerSettings::startRender ( QgsRenderContext context)

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.

Since
QGIS 3.10

Definition at line 534 of file qgspallabeling.cpp.

◆ stopRender()

void QgsPalLayerSettings::stopRender ( QgsRenderContext context)

Finalises the label settings after use.

This must be called after a call to startRender(), in order to gracefully clean up symbols.

Since
QGIS 3.10

Definition at line 571 of file qgspallabeling.cpp.

◆ thinningSettings() [1/2]

QgsLabelThinningSettings & QgsPalLayerSettings::thinningSettings ( )
inline

Returns the label thinning settings.

See also
setThinningSettings()
Since
QGIS 3.12

Definition at line 838 of file qgspallabeling.h.

◆ thinningSettings() [2/2]

const QgsLabelThinningSettings & QgsPalLayerSettings::thinningSettings ( ) const
inline

Returns the label thinning settings.

See also
setThinningSettings()
Note
Not available in Python bindings
Since
QGIS 3.12

Definition at line 831 of file qgspallabeling.h.

◆ unplacedVisibility()

Qgis::UnplacedLabelVisibility QgsPalLayerSettings::unplacedVisibility ( ) const

Returns the layer's unplaced label visibility.

See also
setUnplacedVisibility()
Since
QGIS 3.20

Definition at line 1530 of file qgspallabeling.cpp.

◆ writeXml()

QDomElement QgsPalLayerSettings::writeXml ( QDomDocument &  doc,
const QgsReadWriteContext context 
) const

Write settings into a DOM element.

Definition at line 1257 of file qgspallabeling.cpp.

Friends And Related Symbol Documentation

◆ QgsVectorLayer

friend class QgsVectorLayer
friend

Definition at line 912 of file qgspallabeling.h.

Member Data Documentation

◆ angleOffset

double QgsPalLayerSettings::angleOffset = 0

Label rotation, in degrees clockwise.

Definition at line 503 of file qgspallabeling.h.

◆ autoWrapLength

int QgsPalLayerSettings::autoWrapLength = 0

If non-zero, indicates that label text should be automatically wrapped to (ideally) the specified number of characters.

If zero, auto wrapping is disabled.

See also
useMaxLineLengthForAutoWrap
Since
QGIS 3.4

Definition at line 347 of file qgspallabeling.h.

◆ centroidInside

bool QgsPalLayerSettings::centroidInside = false

true if centroid positioned labels must be placed inside their corresponding feature polygon, or false if centroids which fall outside the polygon are permitted.

Definition at line 418 of file qgspallabeling.h.

◆ centroidWhole

bool QgsPalLayerSettings::centroidWhole = false

true if feature centroid should be calculated from the whole feature, or false if only the visible part of the feature should be considered.

Definition at line 411 of file qgspallabeling.h.

◆ ct

QgsCoordinateTransform QgsPalLayerSettings::ct

Definition at line 901 of file qgspallabeling.h.

◆ decimals

int QgsPalLayerSettings::decimals = 3

Number of decimal places to show for numeric labels.

formatNumbers must be true for this setting to have an effect.

See also
formatNumbers

Definition at line 377 of file qgspallabeling.h.

◆ dist

double QgsPalLayerSettings::dist = 0

Distance from feature to the label.

Units are specified via distUnits.

See also
distUnits
distMapUnitScale

Definition at line 430 of file qgspallabeling.h.

◆ distMapUnitScale

QgsMapUnitScale QgsPalLayerSettings::distMapUnitScale

Map unit scale for label feature distance.

See also
dist
distUnits

Definition at line 444 of file qgspallabeling.h.

◆ distUnits

Qgis::RenderUnit QgsPalLayerSettings::distUnits = Qgis::RenderUnit::Millimeters

Units the distance from feature to the label.

See also
dist
distMapUnitScale

Definition at line 437 of file qgspallabeling.h.

◆ drawLabels

bool QgsPalLayerSettings::drawLabels = true

Whether to draw labels for this layer.

For some layers it may be desirable to register their features as obstacles for other labels without requiring labels to be drawn for the layer itself. In this case drawLabels can be set to false and obstacle set to true, which will result in the layer acting as an obstacle but having no labels of its own.

Definition at line 300 of file qgspallabeling.h.

◆ extentGeom

QgsGeometry QgsPalLayerSettings::extentGeom

Definition at line 905 of file qgspallabeling.h.

◆ fieldIndex

int QgsPalLayerSettings::fieldIndex = 0

Definition at line 899 of file qgspallabeling.h.

◆ fieldName

QString QgsPalLayerSettings::fieldName

Name of field (or an expression) to use for label text.

If fieldName is an expression, then isExpression should be set to true.

See also
isExpression

Definition at line 309 of file qgspallabeling.h.

◆ fitInPolygonOnly

bool QgsPalLayerSettings::fitInPolygonOnly = false

true if only labels which completely fit within a polygon are allowed.

Definition at line 423 of file qgspallabeling.h.

◆ fontLimitPixelSize

bool QgsPalLayerSettings::fontLimitPixelSize = false

true if label sizes should be limited by pixel size.

See also
fontMinPixelSize
fontMaxPixelSize

Definition at line 578 of file qgspallabeling.h.

◆ fontMaxPixelSize

int QgsPalLayerSettings::fontMaxPixelSize = 10000

Maximum pixel size for showing rendered map unit labels (1 - 10000).

See also
fontLimitPixelSize
fontMinPixelSize

Definition at line 592 of file qgspallabeling.h.

◆ fontMinPixelSize

int QgsPalLayerSettings::fontMinPixelSize = 0

Minimum pixel size for showing rendered map unit labels (1 - 1000).

See also
fontLimitPixelSize
fontMaxPixelSize

Definition at line 585 of file qgspallabeling.h.

◆ formatNumbers

bool QgsPalLayerSettings::formatNumbers = false

Set to true to format numeric label text as numbers (e.g.

inserting thousand separators and fixed number of decimal places).

See also
decimals
plusSign

Definition at line 370 of file qgspallabeling.h.

◆ geometryGenerator

QString QgsPalLayerSettings::geometryGenerator

The geometry generator expression. Null if disabled.

Definition at line 607 of file qgspallabeling.h.

◆ geometryGeneratorEnabled

bool QgsPalLayerSettings::geometryGeneratorEnabled = false

Defines if the geometry generator is enabled or not. If disabled, the standard geometry will be taken.

Definition at line 613 of file qgspallabeling.h.

◆ geometryGeneratorType

Qgis::GeometryType QgsPalLayerSettings::geometryGeneratorType = Qgis::GeometryType::Point

The type of the result geometry of the geometry generator.

Definition at line 610 of file qgspallabeling.h.

◆ isExpression

bool QgsPalLayerSettings::isExpression = false

true if this label is made from a expression string, e.g., FieldName || 'mm'

See also
fieldName

Definition at line 315 of file qgspallabeling.h.

◆ labelOffsetMapUnitScale

QgsMapUnitScale QgsPalLayerSettings::labelOffsetMapUnitScale

Map unit scale for label offset.

See also
xOffset
yOffset
offsetUnits

Definition at line 500 of file qgspallabeling.h.

◆ labelPerPart

bool QgsPalLayerSettings::labelPerPart = false

true if every part of a multi-part feature should be labeled.

If false, only the largest part will be labeled.

Definition at line 601 of file qgspallabeling.h.

◆ layerType

Qgis::GeometryType QgsPalLayerSettings::layerType = Qgis::GeometryType::Unknown

Geometry type of layers associated with these settings.

Since
QGIS 3.10

Definition at line 619 of file qgspallabeling.h.

◆ maxCurvedCharAngleIn

double QgsPalLayerSettings::maxCurvedCharAngleIn = 25.0

Maximum angle between inside curved label characters (valid range 20.0 to 60.0).

See also
maxCurvedCharAngleOut

Definition at line 526 of file qgspallabeling.h.

◆ maxCurvedCharAngleOut

double QgsPalLayerSettings::maxCurvedCharAngleOut = -25.0

Maximum angle between outside curved label characters (valid range -20.0 to -95.0)

See also
maxCurvedCharAngleIn

Definition at line 532 of file qgspallabeling.h.

◆ maximumScale

double QgsPalLayerSettings::maximumScale = 0

The maximum map scale (i.e.

most "zoomed in" scale) at which the labels will be visible. The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map. A scale of 0 indicates no maximum scale visibility.

This setting is only considered if scaleVisibility is true.

See also
minimumScale
scaleVisibility

Definition at line 559 of file qgspallabeling.h.

◆ mCurFeat

const QgsFeature* QgsPalLayerSettings::mCurFeat = nullptr

Definition at line 897 of file qgspallabeling.h.

◆ mCurFields

QgsFields QgsPalLayerSettings::mCurFields

Definition at line 898 of file qgspallabeling.h.

◆ mFeatsRegPal

int QgsPalLayerSettings::mFeatsRegPal = 0

Definition at line 908 of file qgspallabeling.h.

◆ mFeatsSendingToPal

int QgsPalLayerSettings::mFeatsSendingToPal = 0

Definition at line 907 of file qgspallabeling.h.

◆ mFeaturesToLabel

int QgsPalLayerSettings::mFeaturesToLabel = 0

Definition at line 906 of file qgspallabeling.h.

◆ minimumScale

double QgsPalLayerSettings::minimumScale = 0

The minimum map scale (i.e.

most "zoomed out" scale) at which the labels will be visible. The scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map. A scale of 0 indicates no minimum scale visibility.

This setting is only considered if scaleVisibility is true.

See also
maximumScale
scaleVisibility

Definition at line 571 of file qgspallabeling.h.

◆ multilineAlign

Horizontal alignment of multi-line labels.

Definition at line 362 of file qgspallabeling.h.

◆ offsetType

Qgis::LabelOffsetType QgsPalLayerSettings::offsetType = Qgis::LabelOffsetType::FromPoint

Offset type for layer (only applies in certain placement modes)

Definition at line 447 of file qgspallabeling.h.

◆ offsetUnits

Qgis::RenderUnit QgsPalLayerSettings::offsetUnits = Qgis::RenderUnit::Millimeters

Units for offsets of label.

See also
xOffset
yOffset
labelOffsetMapUnitScale

Definition at line 492 of file qgspallabeling.h.

◆ placement

Qgis::LabelPlacement QgsPalLayerSettings::placement = Qgis::LabelPlacement::AroundPoint

Label placement mode.

Definition at line 389 of file qgspallabeling.h.

◆ plusSign

bool QgsPalLayerSettings::plusSign = false

Whether '+' signs should be prepended to positive numeric labels.

formatNumbers must be true for this setting to have an effect.

See also
formatNumbers

Definition at line 384 of file qgspallabeling.h.

◆ preserveRotation

bool QgsPalLayerSettings::preserveRotation = true

True if label rotation should be preserved during label pin/unpin operations.

Definition at line 506 of file qgspallabeling.h.

◆ previewBkgrdColor

Q_DECL_DEPRECATED QColor QgsPalLayerSettings::previewBkgrdColor = Qt::white
Deprecated:
QGIS 3.10. Use QgsTextFormat::previewBackgroundColor() instead.

Definition at line 325 of file qgspallabeling.h.

◆ priority

int QgsPalLayerSettings::priority = 5

Label priority.

Valid ranges are from 0 to 10, where 0 = lowest priority and 10 = highest priority.

Definition at line 538 of file qgspallabeling.h.

◆ ptOne

QgsPointXY QgsPalLayerSettings::ptOne

Definition at line 904 of file qgspallabeling.h.

◆ ptZero

QgsPointXY QgsPalLayerSettings::ptZero

Definition at line 903 of file qgspallabeling.h.

◆ repeatDistance

double QgsPalLayerSettings::repeatDistance = 0

Distance for repeating labels for a single feature.

See also
repeatDistanceUnit
repeatDistanceMapUnitScale

Definition at line 454 of file qgspallabeling.h.

◆ repeatDistanceMapUnitScale

QgsMapUnitScale QgsPalLayerSettings::repeatDistanceMapUnitScale

Map unit scale for repeating labels for a single feature.

See also
repeatDistance
repeatDistanceUnit

Definition at line 468 of file qgspallabeling.h.

◆ repeatDistanceUnit

Qgis::RenderUnit QgsPalLayerSettings::repeatDistanceUnit = Qgis::RenderUnit::Millimeters

Units for repeating labels for a single feature.

See also
repeatDistance
repeatDistanceMapUnitScale

Definition at line 461 of file qgspallabeling.h.

◆ scaleVisibility

bool QgsPalLayerSettings::scaleVisibility = false

Set to true to limit label visibility to a range of scales.

See also
maximumScale
minimumScale

Definition at line 547 of file qgspallabeling.h.

◆ substitutions

QgsStringReplacementCollection QgsPalLayerSettings::substitutions

Substitution collection for automatic text substitution with labels.

Definition at line 328 of file qgspallabeling.h.

◆ upsidedownLabels

Controls whether upside down labels are displayed and how they are handled.

Definition at line 595 of file qgspallabeling.h.

◆ useMaxLineLengthForAutoWrap

bool QgsPalLayerSettings::useMaxLineLengthForAutoWrap = true

If true, indicates that when auto wrapping label text the autoWrapLength length indicates the maximum ideal length of text lines.

If false, then autoWrapLength indicates the ideal minimum length of text lines.

If autoWrapLength is 0 then this value has no effect.

See also
autoWrapLength
Since
QGIS 3.4

Definition at line 359 of file qgspallabeling.h.

◆ useSubstitutions

bool QgsPalLayerSettings::useSubstitutions = false

True if substitutions should be applied.

Definition at line 330 of file qgspallabeling.h.

◆ wrapChar

QString QgsPalLayerSettings::wrapChar

Wrapping character string.

If set, any occurrences of this string in the calculated label text will be replaced with new line characters.

Definition at line 338 of file qgspallabeling.h.

◆ xform

const QgsMapToPixel* QgsPalLayerSettings::xform = nullptr

Definition at line 900 of file qgspallabeling.h.

◆ xOffset

double QgsPalLayerSettings::xOffset = 0

Horizontal offset of label.

Units are specified via offsetUnits.

See also
yOffset
offsetUnits
labelOffsetMapUnitScale

Definition at line 476 of file qgspallabeling.h.

◆ yOffset

double QgsPalLayerSettings::yOffset = 0

Vertical offset of label.

Units are specified via offsetUnits.

See also
xOffset
offsetUnits
labelOffsetMapUnitScale

Definition at line 484 of file qgspallabeling.h.

◆ zIndex

double QgsPalLayerSettings::zIndex = 0

Z-Index of label, where labels with a higher z-index are rendered on top of labels with a lower z-index.

Definition at line 604 of file qgspallabeling.h.


The documentation for this class was generated from the following files: