QgsLabelFeature class

The QgsLabelFeature class describes a feature that should be used within the labeling engine.

Reference

Those may be the usual textual labels, diagrams, or any other custom type of map annotations (generated by custom label providers).

Instances only contain data relevant to the labeling engine (geometry, label size etc.) necessary for the layout. Rendering of labels is done by label providers.

Individual label providers may create subclasses of QgsLabelFeature in order to add more data to the instances that will be later used for drawing of labels.

Derived classes

class QgsDiagramLabelFeature: Class that adds extra information to QgsLabelFeature for labeling of diagrams.
class QgsTextLabelFeature: Class that adds extra information to QgsLabelFeature for text labels.
class QgsTextLabelFeature: Class that adds extra information to QgsLabelFeature for text labels.

Constructors, destructors, conversion operators

QgsLabelFeature(QgsFeatureId id, geos::unique_ptr geometry, QSizeF size): Create label feature, takes ownership of the geometry instance.
~QgsLabelFeature() virtual: Clean up geometry and curved label info (if present)

Public functions

auto alwaysShow() const -> bool: Whether label should be always shown (sets very high label priority)
auto curvedLabelInfo() const -> pal::LabelInfo*: Gets additional infor required for curved label placement. Returns null if not set.
auto distLabel() const -> double: Applies to "around point" placement strategy or linestring features.
auto fixedAngle() const -> double: Angle in degrees of the fixed angle (relevant only if hasFixedAngle() returns true)
auto fixedPosition() const -> QgsPointXY: Coordinates of the fixed position (relevant only if hasFixedPosition() returns true)
auto geometry() const -> GEOSGeometry*: Gets access to the associated geometry.
auto hasFixedAngle() const -> bool: Whether the label should use a fixed angle instead of using angle from automatic placement.
auto hasFixedPosition() const -> bool: Whether the label should use a fixed position instead of being automatically placed.
auto hasFixedQuadrant() const -> bool: Returns whether the quadrant for the label is fixed.
auto id() const -> QgsFeatureId: Identifier of the label (unique within the parent label provider)
auto isObstacle() const -> bool: Returns whether the feature will act as an obstacle for labels.
auto labelText() const -> QString: Text of the label.
auto layer() const -> pal::Layer*: Gets PAL layer of the label feature. Should be only used internally in PAL.
auto obstacleFactor() const -> double: Returns the obstacle factor for the feature.
auto obstacleGeometry() const -> GEOSGeometry*: Returns the label's obstacle geometry, if different to the feature geometry.
auto offsetType() const -> QgsPalLayerSettings::OffsetType: Returns the offset type, which determines how offsets and distance to label behaves.
auto permissibleZone() const -> QgsGeometry: Returns the label's permissible zone geometry.
auto permissibleZonePrepared() const -> const GEOSPreparedGeometry*: Returns a GEOS prepared geometry representing the label's permissibleZone().
auto positionOffset() const -> QgsPointXY: Applies only to "offset from point" placement strategy.
auto predefinedPositionOrder() const -> QVector<QgsPalLayerSettings::PredefinedPointPosition>: Returns the priority ordered list of predefined positions for label candidates.
auto priority() const -> double: Returns the feature's labeling priority.
auto provider() const -> QgsAbstractLabelProvider*: Returns provider of this instance.
auto quadOffset() const -> QPointF: Applies to "offset from point" placement strategy and "around point" (in case hasFixedQuadrant() returns true).
auto repeatDistance() const -> double: Applies only to linestring features - after what distance (in map units) the labels should be repeated (0 = no repetitions)
void setAlwaysShow(bool enabled): Sets whether label should be always shown (sets very high label priority)
void setCurvedLabelInfo(pal::LabelInfo* info): takes ownership of the instance
void setDistLabel(double dist): Applies to "around point" placement strategy or linestring features.
void setFixedAngle(double angle): Sets angle in degrees of the fixed angle (relevant only if hasFixedAngle() returns true)
void setFixedPosition(const QgsPointXY& point): Sets coordinates of the fixed position (relevant only if hasFixedPosition() returns true)
void setHasFixedAngle(bool enabled): Sets whether the label should use a fixed angle instead of using angle from automatic placement.
void setHasFixedPosition(bool enabled): Sets whether the label should use a fixed position instead of being automatically placed.
void setHasFixedQuadrant(bool enabled): Sets whether the quadrant for the label must be respected.
void setIsObstacle(bool enabled): Sets whether the feature will act as an obstacle for labels.
void setLabelText(const QString& text): Sets text of the label.
void setLayer(pal::Layer* layer): Assign PAL layer to the label feature. Should be only used internally in PAL.
void setObstacleFactor(double factor): Sets the obstacle factor for the feature.
void setObstacleGeometry(geos::unique_ptr obstacleGeom): Sets the label's obstacle geometry, if different to the feature geometry.
void setOffsetType(QgsPalLayerSettings::OffsetType type): Sets the offset type, which determines how offsets and distance to label behaves.
void setPermissibleZone(const QgsGeometry& geometry): Sets the label's permissible zone geometry.
void setPositionOffset(const QgsPointXY& offset): Applies only to "offset from point" placement strategy.
void setPredefinedPositionOrder(const QVector<QgsPalLayerSettings::PredefinedPointPosition>& order): Sets the priority ordered list of predefined positions for label candidates.
void setPriority(double priority): Sets the priority for labeling the feature.
void setQuadOffset(QPointF quadOffset): Set which side of the point to use.
void setRepeatDistance(double dist): Applies only to linestring features - set after what distance (in map units) the labels should be repeated (0 = no repetitions)
void setSymbolSize(QSizeF size): Sets the size of the rendered symbol associated with this feature.
void setVisualMargin(const QgsMargins& margin): Sets the visual margin for the label feature.
void setZIndex(double zIndex): Sets the label's z-index.
auto size() const -> QSizeF: Size of the label (in map units)
auto symbolSize() const -> const QSizeF&: Returns the size of the rendered symbol associated with this feature, if applicable.
auto visualMargin() const -> const QgsMargins&: Returns the visual margin for the label feature.
auto zIndex() const -> double: Returns the label's z-index.

Protected variables

bool mAlwaysShow: whether to always show label - even in case of collisions
double mDistLabel: distance of label from the feature (only for "around point" placement or linestrings)
double mFixedAngle: fixed rotation for the label (instead of automatic choice)
QgsPointXY mFixedPosition: fixed position for the label (instead of automatic placement)
geos::unique_ptr mGeometry: Geometry of the feature to be labelled.
bool mHasFixedAngle: whether mFixedAngle should be respected
bool mHasFixedPosition: whether mFixedPosition should be respected
bool mHasFixedQuadrant: whether mQuadOffset should be respected (only for "around point" placement)
QgsFeatureId mId: Associated ID unique within the parent label provider.
pal::LabelInfo* mInfo: extra information for curved labels (may be null)
bool mIsObstacle: whether the feature geometry acts as an obstacle for labels
QString mLabelText: text of the label
pal::Layer* mLayer: Pointer to PAL layer (assigned when registered to PAL)
double mObstacleFactor: how strong is the geometry acting as obstacle
geos::unique_ptr mObstacleGeometry: Optional geometry to use for label obstacles, if different to mGeometry.
QgsPalLayerSettings::OffsetType mOffsetType: Offset type for certain placement modes.
QgsGeometry mPermissibleZone: Optional geometry to use for label's permissible zone.
QgsPointXY mPositionOffset: offset of label from the feature (only for "offset from point" placement)
QVector<QgsPalLayerSettings::PredefinedPointPosition> mPredefinedPositionOrder: Ordered list of predefined positions for label (only for OrderedPositionsAroundPoint placement)
double mPriority: Priority of the label.
QPointF mQuadOffset: whether the side of the label is fixed (only for "around point" placement)
double mRepeatDistance: distance after which label should be repeated (only for linestrings)
QSizeF mSize: Width and height of the label.
QSizeF mSymbolSize: Size of associated rendered symbol, if applicable.
QgsMargins mVisualMargin: Visual margin of label contents.
double mZIndex: Z-index of label (higher z-index labels are rendered on top of lower z-index labels)

Function documentation

double QgsLabelFeature::distLabel() const

Applies to "around point" placement strategy or linestring features.

Distance of the label from the feature (in map units)

bool QgsLabelFeature::hasFixedQuadrant() const

Returns whether the quadrant for the label is fixed.

Applies to "around point" placement strategy.

bool QgsLabelFeature::isObstacle() const

Returns whether the feature will act as an obstacle for labels.

Returns	true if feature is an obstacle

QString QgsLabelFeature::labelText() const

Text of the label.

Used also if "merge connected lines to avoid duplicate labels" is enabled to identify which features may be merged.

double QgsLabelFeature::obstacleFactor() const

Returns the obstacle factor for the feature.

The factor controls the penalty for labels overlapping this feature.

GEOSGeometry* QgsLabelFeature::obstacleGeometry() const

Returns the label's obstacle geometry, if different to the feature geometry.

QgsPalLayerSettings::OffsetType QgsLabelFeature::offsetType() const

Returns the offset type, which determines how offsets and distance to label behaves.

Support depends on which placement mode is used for generating label candidates.

QgsGeometry QgsLabelFeature::permissibleZone() const

Returns the label's permissible zone geometry.

If a valid geometry is returned, the feature's label MUST be fully contained within this zone, and the feature will not be labeled if no candidates can be generated which are not contained within the zone.

const GEOSPreparedGeometry* QgsLabelFeature::permissibleZonePrepared() const

Returns a GEOS prepared geometry representing the label's permissibleZone().

QgsPointXY QgsLabelFeature::positionOffset() const

Applies only to "offset from point" placement strategy.

What offset (in map units) to use from the point

QVector<QgsPalLayerSettings::PredefinedPointPosition> QgsLabelFeature::predefinedPositionOrder() const

Returns the priority ordered list of predefined positions for label candidates.

This property is only used for OrderedPositionsAroundPoint placements.

double QgsLabelFeature::priority() const

Returns the feature's labeling priority.

Returns	feature's priority, as a value between 0 (highest priority) and 1 (lowest priority). Returns -1.0 if feature will use the layer's default priority.

QPointF QgsLabelFeature::quadOffset() const

Applies to "offset from point" placement strategy and "around point" (in case hasFixedQuadrant() returns true).

Determines which side of the point to use. For X coordinate, values -1, 0, 1 mean left, center, right. For Y coordinate, values -1, 0, 1 mean above, center, below.

void QgsLabelFeature::setDistLabel(double dist)

Applies to "around point" placement strategy or linestring features.

Set distance of the label from the feature (in map units)

void QgsLabelFeature::setHasFixedQuadrant(bool enabled)

Sets whether the quadrant for the label must be respected.

This can be used to fix the quadrant for specific features when using an "around point" placement.

void QgsLabelFeature::setIsObstacle(bool enabled)

Sets whether the feature will act as an obstacle for labels.

Parameters
enabled	whether feature will act as an obstacle

void QgsLabelFeature::setObstacleFactor(double factor)

Sets the obstacle factor for the feature.

Parameters
factor	larger factors ( > 1.0 ) will result in labels which are less likely to cover this feature, smaller factors ( < 1.0 ) mean labels are more likely to cover this feature (where required)

The factor controls the penalty for labels overlapping this feature.

void QgsLabelFeature::setObstacleGeometry(geos::unique_ptr obstacleGeom)

Sets the label's obstacle geometry, if different to the feature geometry.

This can be used to override the shape of the feature for obstacle detection, e.g., to buffer around a point geometry to prevent labels being placed too close to the point itself. It not set, the feature's geometry is used for obstacle detection. Ownership of obstacle geometry is transferred.

void QgsLabelFeature::setOffsetType(QgsPalLayerSettings::OffsetType type)

Sets the offset type, which determines how offsets and distance to label behaves.

Support depends on which placement mode is used for generating label candidates.

void QgsLabelFeature::setPermissibleZone(const QgsGeometry& geometry)

Sets the label's permissible zone geometry.

Parameters
geometry	permissible zone geometry. If an invalid QgsGeometry is passed then no zone limit will be applied to the label candidates (this is the default behavior).

If set, the feature's label MUST be fully contained within this zone, and the feature will not be labeled if no candidates can be generated which are not contained within the zone.

void QgsLabelFeature::setPositionOffset(const QgsPointXY& offset)

Applies only to "offset from point" placement strategy.

Set what offset (in map units) to use from the point

void QgsLabelFeature::setPredefinedPositionOrder(const QVector<QgsPalLayerSettings::PredefinedPointPosition>& order)

Sets the priority ordered list of predefined positions for label candidates.

This property is only used for OrderedPositionsAroundPoint placements.

void QgsLabelFeature::setPriority(double priority)

Sets the priority for labeling the feature.

Parameters
priority	feature's priority, as a value between 0 (highest priority) and 1 (lowest priority). Set to -1.0 to use the layer's default priority for this feature.

void QgsLabelFeature::setQuadOffset(QPointF quadOffset)

Set which side of the point to use.

void QgsLabelFeature::setSymbolSize(QSizeF size)

Sets the size of the rendered symbol associated with this feature.

This size is taken into account in certain label placement modes to avoid placing labels over the rendered symbol for this feature.

void QgsLabelFeature::setVisualMargin(const QgsMargins& margin)

Sets the visual margin for the label feature.

Parameters
margin	visual margins for label

The visual margin represents a margin within the label which should not be considered when calculating the positions of candidates for the label feature. It is used in certain label placement modes to adjust the position of candidates so that they all appear to be at visually equal distances from a point feature. For instance, this can be used to place labels which sit above a point so that their baseline rather then the descender of the label is at a preset distance from the point.

void QgsLabelFeature::setZIndex(double zIndex)

Sets the label's z-index.

Parameters
zIndex	z-index for label

Higher z-index labels are rendered on top of lower z-index labels.

const QSizeF& QgsLabelFeature::symbolSize() const

Returns the size of the rendered symbol associated with this feature, if applicable.

This size is taken into account in certain label placement modes to avoid placing labels over the rendered symbol for this feature. The size will only be set for labels associated with a point feature.

const QgsMargins& QgsLabelFeature::visualMargin() const

Returns the visual margin for the label feature.

double QgsLabelFeature::zIndex() const

Returns the label's z-index.