QGIS API Documentation  3.37.0-Master (a5b4d9743e8)
Public Member Functions | Static Public Member Functions | Protected Attributes | List of all members
QgsTextLabelFeature Class Reference

Class that adds extra information to QgsLabelFeature for text labels. More...

#include <qgstextlabelfeature.h>

Inheritance diagram for QgsTextLabelFeature:
Inheritance graph
[legend]

Public Member Functions

 QgsTextLabelFeature (QgsFeatureId id, geos::unique_ptr geometry, QSizeF size)
 Construct text label feature. More...
 
 ~QgsTextLabelFeature () override
 Clean up. More...
 
QgsTextCharacterFormat characterFormat (int partId) const
 Returns the character format corresponding to the specified label part. More...
 
const QMap< QgsPalLayerSettings::Property, QVariant > & dataDefinedValues () const
 Gets data-defined values. More...
 
QFont definedFont () const
 Font to be used for rendering. More...
 
QgsTextDocument document () const
 Returns the document for the label. More...
 
QgsTextDocumentMetrics documentMetrics () const
 Returns the document metrics for the label. More...
 
bool hasCharacterFormat (int partId) const
 Returns true if the feature contains specific character formatting for the part with matching ID. More...
 
double maximumCharacterAngleInside () const
 Returns the maximum angle (in radians) between inside curved label characters. More...
 
double maximumCharacterAngleOutside () const
 Returns the maximum angle (in radians) between outside curved label characters. More...
 
void setDataDefinedValues (const QMap< QgsPalLayerSettings::Property, QVariant > &values)
 Sets data-defined values. More...
 
void setDefinedFont (const QFont &f)
 Sets font to be used for rendering. More...
 
void setDocument (const QgsTextDocument &document, const QgsTextDocumentMetrics &metrics)
 Sets the document and document metrics for the label. More...
 
void setMaximumCharacterAngleInside (double angle)
 Sets the maximum angle (in radians) between inside curved label characters. More...
 
void setMaximumCharacterAngleOutside (double angle)
 Sets the maximum angle (in radians) between outside curved label characters. More...
 
void setTextMetrics (const QgsPrecalculatedTextMetrics &metrics)
 Sets additional text metrics required for curved label placement. More...
 
QString text (int partId) const
 Returns the text component corresponding to a specified label part. More...
 
const QgsPrecalculatedTextMetricstextMetrics () const
 Returns additional info required for curved label placement. More...
 
- Public Member Functions inherited from QgsLabelFeature
 QgsLabelFeature (QgsFeatureId id, geos::unique_ptr geometry, QSizeF size)
 Constructor for QgsLabelFeature. More...
 
virtual ~QgsLabelFeature ()
 
bool allowDegradedPlacement () const
 Returns true if the label can be placed in inferior fallback positions if it cannot otherwise be placed. More...
 
bool alwaysShow () const
 Whether label should be always shown (sets very high label priority) More...
 
QgsPointXY anchorPosition () const
 In case of quadrand or aligned positioning, this is set to the anchor point. More...
 
Qgis::LabelLinePlacementFlags arrangementFlags () const
 Returns the feature's arrangement flags. More...
 
double distLabel () const
 Applies to "around point" placement strategy or linestring features. More...
 
QgsFeature feature () const
 Returns the original feature associated with this label. More...
 
double fixedAngle () const
 Angle in radians of the fixed angle (relevant only if hasFixedAngle() returns true) More...
 
QgsPointXY fixedPosition () const
 Coordinates of the fixed position (relevant only if hasFixedPosition() returns true) More...
 
GEOSGeometrygeometry () const
 Gets access to the associated geometry. More...
 
bool hasFixedAngle () const
 Whether the label should use a fixed angle instead of using angle from automatic placement. More...
 
bool hasFixedPosition () const
 Whether the label should use a fixed position instead of being automatically placed. More...
 
bool hasFixedQuadrant () const
 Returns whether the quadrant for the label is fixed. More...
 
QgsFeatureId id () const
 Identifier of the label (unique within the parent label provider) More...
 
bool labelAllParts () const
 Returns true if all parts of the feature should be labeled. More...
 
QString labelText () const
 Text of the label. More...
 
pal::Layerlayer () const
 Gets PAL layer of the label feature. Should be only used internally in PAL. More...
 
double lineAnchorPercent () const
 Returns the percent along the line at which labels should be placed, for line labels only. More...
 
QgsLabelLineSettings::AnchorTextPoint lineAnchorTextPoint () const
 Returns the line anchor text point, which dictates which part of the label text should be placed at the lineAnchorPercent(). More...
 
QgsLabelLineSettings::AnchorType lineAnchorType () const
 Returns the line anchor type, which dictates how the lineAnchorPercent() setting is handled. More...
 
double minimumSize () const
 Returns the minimum size (in map unit) for a feature to be labelled. More...
 
const QgsLabelObstacleSettingsobstacleSettings () const
 Returns the label's obstacle settings. More...
 
Qgis::LabelOffsetType offsetType () const
 Returns the offset type, which determines how offsets and distance to label behaves. More...
 
QgsCoordinateReferenceSystem originalFeatureCrs () const
 Returns the original layer CRS of the feature associated with the label. More...
 
QRectF outerBounds () const
 Returns the extreme outer bounds of the label feature, including any surrounding content like borders or background shapes. More...
 
Qgis::LabelOverlapHandling overlapHandling () const
 Returns the technique to use for handling overlapping labels for the feature. More...
 
double overrunDistance () const
 Returns the permissible distance (in map units) which labels are allowed to overrun the start or end of linear features. More...
 
double overrunSmoothDistance () const
 Returns the distance (in map units) with which the ends of linear features are averaged over when calculating the direction at which to overrun labels. More...
 
QgsGeometry permissibleZone () const
 Returns the label's permissible zone geometry. More...
 
const GEOSPreparedGeometry * permissibleZonePrepared () const
 Returns a GEOS prepared geometry representing the label's permissibleZone(). More...
 
Qgis::LabelPolygonPlacementFlags polygonPlacementFlags () const
 Returns the polygon placement flags, which dictate how polygon labels can be placed. More...
 
QgsPointXY positionOffset () const
 Applies only to "offset from point" placement strategy. More...
 
QVector< Qgis::LabelPredefinedPointPositionpredefinedPositionOrder () const
 Returns the priority ordered list of predefined positions for label candidates. More...
 
double priority () const
 Returns the feature's labeling priority. More...
 
QgsAbstractLabelProviderprovider () const
 Returns provider of this instance. More...
 
QPointF quadOffset () const
 Applies to "offset from point" placement strategy and "around point" (in case hasFixedQuadrant() returns true). More...
 
double repeatDistance () const
 Applies only to linestring features - after what distance (in map units) the labels should be repeated (0 = no repetitions) More...
 
void setAllowDegradedPlacement (bool allow)
 Sets whether the label can be placed in inferior fallback positions if it cannot otherwise be placed. More...
 
void setAlwaysShow (bool enabled)
 Sets whether label should be always shown (sets very high label priority) More...
 
void setAnchorPosition (const QgsPointXY &anchorPosition)
 In case of quadrand or aligned positioning, this is set to the anchor point. More...
 
void setArrangementFlags (Qgis::LabelLinePlacementFlags flags)
 Sets the feature's arrangement flags. More...
 
void setDistLabel (double dist)
 Applies to "around point" placement strategy or linestring features. More...
 
void setFeature (const QgsFeature &feature)
 Sets the original feature associated with this label. More...
 
void setFixedAngle (double angle)
 Sets the angle in radians of the fixed angle (relevant only if hasFixedAngle() returns true). More...
 
void setFixedPosition (const QgsPointXY &point)
 Sets coordinates of the fixed position (relevant only if hasFixedPosition() returns true) More...
 
void setHasFixedAngle (bool enabled)
 Sets whether the label should use a fixed angle instead of using angle from automatic placement. More...
 
void setHasFixedPosition (bool enabled)
 Sets whether the label should use a fixed position instead of being automatically placed. More...
 
void setHasFixedQuadrant (bool enabled)
 Sets whether the quadrant for the label must be respected. More...
 
void setLabelAllParts (bool labelAllParts)
 Sets whether all parts of the feature should be labeled. More...
 
void setLabelText (const QString &text)
 Sets text of the label. More...
 
void setLayer (pal::Layer *layer)
 Assign PAL layer to the label feature. Should be only used internally in PAL. More...
 
void setLineAnchorPercent (double percent)
 Sets the percent along the line at which labels should be placed, for line labels only. More...
 
void setLineAnchorTextPoint (QgsLabelLineSettings::AnchorTextPoint point)
 Sets the line anchor text point, which dictates which part of the label text should be placed at the lineAnchorPercent(). More...
 
void setLineAnchorType (QgsLabelLineSettings::AnchorType type)
 Sets the line anchor type, which dictates how the lineAnchorPercent() setting is handled. More...
 
void setMinimumSize (double size)
 Sets the minimum size (in map unit) for a feature to be labelled. More...
 
void setObstacleSettings (const QgsLabelObstacleSettings &settings)
 Sets the label's obstacle settings. More...
 
void setOffsetType (Qgis::LabelOffsetType type)
 Sets the offset type, which determines how offsets and distance to label behaves. More...
 
void setOriginalFeatureCrs (const QgsCoordinateReferenceSystem &crs)
 Sets the original layer crs of the feature associated with the label. More...
 
void setOuterBounds (const QRectF &bounds)
 Sets the extreme outer bounds of the label feature, including any surrounding content like borders or background shapes. More...
 
void setOverlapHandling (Qgis::LabelOverlapHandling handling)
 Sets the technique to use for handling overlapping labels for the feature. More...
 
void setOverrunDistance (double distance)
 Sets the permissible distance (in map units) which labels are allowed to overrun the start or end of linear features. More...
 
void setOverrunSmoothDistance (double distance)
 Sets the distance (in map units) with which the ends of linear features are averaged over when calculating the direction at which to overrun labels. More...
 
void setPermissibleZone (const QgsGeometry &geometry)
 Sets the label's permissible zone geometry. More...
 
void setPolygonPlacementFlags (Qgis::LabelPolygonPlacementFlags flags)
 Sets the polygon placement flags, which dictate how polygon labels can be placed. More...
 
void setPositionOffset (const QgsPointXY &offset)
 Applies only to "offset from point" placement strategy. More...
 
void setPredefinedPositionOrder (const QVector< Qgis::LabelPredefinedPointPosition > &order)
 Sets the priority ordered list of predefined positions for label candidates. More...
 
void setPriority (double priority)
 Sets the priority for labeling the feature. More...
 
void setQuadOffset (QPointF quadOffset)
 Set which side of the point to use. More...
 
void setRepeatDistance (double dist)
 Applies only to linestring features - set after what distance (in map units) the labels should be repeated (0 = no repetitions) More...
 
void setRotatedSize (QSizeF size)
 Sets an alternate label size to be used when a label rotation angle is between 45 to 135 and 235 to 313 degrees and the text rotation mode is set to rotation-based. More...
 
void setSymbol (const QgsSymbol *symbol)
 Sets the feature symbol associated with this label. More...
 
void setSymbolSize (QSizeF size)
 Sets the size of the rendered symbol associated with this feature. More...
 
void setVisualMargin (const QgsMargins &margin)
 Sets the visual margin for the label feature. More...
 
void setZIndex (double zIndex)
 Sets the label's z-index. More...
 
QSizeF size (double angle=0.0) const
 Size of the label (in map units). More...
 
const QgsSymbolsymbol () const
 Returns the feature symbol associated with this label. More...
 
const QSizeF & symbolSize () const
 Returns the size of the rendered symbol associated with this feature, if applicable. More...
 
const QgsMarginsvisualMargin () const
 Returns the visual margin for the label feature. More...
 
double zIndex () const
 Returns the label's z-index. More...
 

Static Public Member Functions

static QgsPrecalculatedTextMetrics calculateTextMetrics (const QgsMapToPixel *xform, const QgsRenderContext &context, const QFont &baseFont, const QFontMetricsF &fontMetrics, double letterSpacing, double wordSpacing, const QString &text=QString(), QgsTextDocument *document=nullptr, QgsTextDocumentMetrics *metrics=nullptr)
 Calculate text metrics for later retrieval via textMetrics(). More...
 

Protected Attributes

QMap< QgsPalLayerSettings::Property, QVariant > mDataDefinedValues
 Stores attribute values for data defined properties. More...
 
QFont mDefinedFont
 Font for rendering. More...
 
QgsTextDocument mDocument
 
QgsTextDocumentMetrics mDocumentMetrics
 
double mMaximumCharacterAngleInside = 0
 
double mMaximumCharacterAngleOutside = 0
 
std::optional< QgsPrecalculatedTextMetricsmTextMetrics
 
- Protected Attributes inherited from QgsLabelFeature
bool mAlwaysShow = false
 whether to always show label - even in case of collisions More...
 
Qgis::LabelLinePlacementFlags mArrangementFlags = Qgis::LabelLinePlacementFlags()
 
double mDistLabel = 0
 distance of label from the feature (only for "around point" placement or linestrings) More...
 
double mFixedAngle = 0
 fixed rotation for the label (instead of automatic choice) More...
 
QgsPointXY mFixedPosition
 fixed position for the label (instead of automatic placement) More...
 
geos::unique_ptr mGeometry
 Geometry of the feature to be labelled. More...
 
bool mHasFixedAngle = false
 whether mFixedAngle should be respected More...
 
bool mHasFixedPosition = false
 whether mFixedPosition should be respected More...
 
bool mHasFixedQuadrant = false
 whether mQuadOffset should be respected (only for "around point" placement) More...
 
QgsFeatureId mId
 Associated ID unique within the parent label provider. More...
 
QString mLabelText
 text of the label More...
 
pal::LayermLayer = nullptr
 Pointer to PAL layer (assigned when registered to PAL) More...
 
Qgis::LabelOffsetType mOffsetType = Qgis::LabelOffsetType::FromPoint
 Offset type for certain placement modes. More...
 
QRectF mOuterBounds
 Extreme outer bounds of the label feature, including any surrounding content like borders or background shapes. More...
 
double mOverrunDistance = 0
 Distance to allow label to overrun linear features. More...
 
double mOverrunSmoothDistance = 0
 Distance to smooth angle of line start and end when calculating overruns. More...
 
QgsGeometry mPermissibleZone
 Optional geometry to use for label's permissible zone. More...
 
Qgis::LabelPolygonPlacementFlags mPolygonPlacementFlags = Qgis::LabelPolygonPlacementFlag::AllowPlacementInsideOfPolygon
 
QgsPointXY mPositionOffset
 offset of label from the feature (only for "offset from point" placement) More...
 
QVector< Qgis::LabelPredefinedPointPositionmPredefinedPositionOrder
 Ordered list of predefined positions for label (only for OrderedPositionsAroundPoint placement) More...
 
double mPriority = -1
 Priority of the label. More...
 
QPointF mQuadOffset
 whether the side of the label is fixed (only for "around point" placement) More...
 
double mRepeatDistance = 0
 distance after which label should be repeated (only for linestrings) More...
 
QSizeF mRotatedSize
 Width and height of the label when rotated between 45 to 135 and 235 to 315 degrees;. More...
 
QSizeF mSize
 Width and height of the label. More...
 
QSizeF mSymbolSize
 Size of associated rendered symbol, if applicable. More...
 
QgsMargins mVisualMargin
 Visual margin of label contents. More...
 
double mZIndex = 0
 Z-index of label (higher z-index labels are rendered on top of lower z-index labels) More...
 

Detailed Description

Class that adds extra information to QgsLabelFeature for text labels.

Note
not part of public API

Definition at line 35 of file qgstextlabelfeature.h.

Constructor & Destructor Documentation

◆ QgsTextLabelFeature()

QgsTextLabelFeature::QgsTextLabelFeature ( QgsFeatureId  id,
geos::unique_ptr  geometry,
QSizeF  size 
)

Construct text label feature.

Definition at line 26 of file qgstextlabelfeature.cpp.

◆ ~QgsTextLabelFeature()

QgsTextLabelFeature::~QgsTextLabelFeature ( )
overridedefault

Clean up.

Member Function Documentation

◆ calculateTextMetrics()

QgsPrecalculatedTextMetrics QgsTextLabelFeature::calculateTextMetrics ( const QgsMapToPixel xform,
const QgsRenderContext context,
const QFont &  baseFont,
const QFontMetricsF &  fontMetrics,
double  letterSpacing,
double  wordSpacing,
const QString &  text = QString(),
QgsTextDocument document = nullptr,
QgsTextDocumentMetrics metrics = nullptr 
)
static

Calculate text metrics for later retrieval via textMetrics().

Since
QGIS 3.20

Definition at line 52 of file qgstextlabelfeature.cpp.

◆ characterFormat()

QgsTextCharacterFormat QgsTextLabelFeature::characterFormat ( int  partId) const

Returns the character format corresponding to the specified label part.

Parameters
partIdSet to the required part index for labels which are broken into parts (curved labels)

This only returns valid formats for curved label placements.

Since
QGIS 3.14

Definition at line 42 of file qgstextlabelfeature.cpp.

◆ dataDefinedValues()

const QMap< QgsPalLayerSettings::Property, QVariant >& QgsTextLabelFeature::dataDefinedValues ( ) const
inline

Gets data-defined values.

Definition at line 69 of file qgstextlabelfeature.h.

◆ definedFont()

QFont QgsTextLabelFeature::definedFont ( ) const
inline

Font to be used for rendering.

Definition at line 76 of file qgstextlabelfeature.h.

◆ document()

QgsTextDocument QgsTextLabelFeature::document ( ) const

Returns the document for the label.

See also
setDocument()
Since
QGIS 3.14

Definition at line 177 of file qgstextlabelfeature.cpp.

◆ documentMetrics()

QgsTextDocumentMetrics QgsTextLabelFeature::documentMetrics ( ) const

Returns the document metrics for the label.

See also
document()
Since
QGIS 3.28

Definition at line 182 of file qgstextlabelfeature.cpp.

◆ hasCharacterFormat()

bool QgsTextLabelFeature::hasCharacterFormat ( int  partId) const

Returns true if the feature contains specific character formatting for the part with matching ID.

Since
QGIS 3.14

Definition at line 47 of file qgstextlabelfeature.cpp.

◆ maximumCharacterAngleInside()

double QgsTextLabelFeature::maximumCharacterAngleInside ( ) const
inline

Returns the maximum angle (in radians) between inside curved label characters.

See also
setMaximumCharacterAngleInside()
maximumCharacterAngleOutside()
Since
QGIS 3.20

Definition at line 141 of file qgstextlabelfeature.h.

◆ maximumCharacterAngleOutside()

double QgsTextLabelFeature::maximumCharacterAngleOutside ( ) const
inline

Returns the maximum angle (in radians) between outside curved label characters.

See also
setMaximumCharacterAngleOutside()
maximumCharacterAngleInside()
Since
QGIS 3.20

Definition at line 157 of file qgstextlabelfeature.h.

◆ setDataDefinedValues()

void QgsTextLabelFeature::setDataDefinedValues ( const QMap< QgsPalLayerSettings::Property, QVariant > &  values)
inline

Sets data-defined values.

Definition at line 71 of file qgstextlabelfeature.h.

◆ setDefinedFont()

void QgsTextLabelFeature::setDefinedFont ( const QFont &  f)
inline

Sets font to be used for rendering.

Definition at line 74 of file qgstextlabelfeature.h.

◆ setDocument()

void QgsTextLabelFeature::setDocument ( const QgsTextDocument document,
const QgsTextDocumentMetrics metrics 
)

Sets the document and document metrics for the label.

See also
document()
Since
QGIS 3.14

Definition at line 187 of file qgstextlabelfeature.cpp.

◆ setMaximumCharacterAngleInside()

void QgsTextLabelFeature::setMaximumCharacterAngleInside ( double  angle)
inline

Sets the maximum angle (in radians) between inside curved label characters.

See also
maximumCharacterAngleInside()
setMaximumCharacterAngleOutside()
Since
QGIS 3.20

Definition at line 133 of file qgstextlabelfeature.h.

◆ setMaximumCharacterAngleOutside()

void QgsTextLabelFeature::setMaximumCharacterAngleOutside ( double  angle)
inline

Sets the maximum angle (in radians) between outside curved label characters.

See also
maximumCharacterAngleOutside()
setMaximumCharacterAngleInside()
Since
QGIS 3.20

Definition at line 149 of file qgstextlabelfeature.h.

◆ setTextMetrics()

void QgsTextLabelFeature::setTextMetrics ( const QgsPrecalculatedTextMetrics metrics)
inline

Sets additional text metrics required for curved label placement.

See also
textMetrics()
Since
QGIS 3.20

Definition at line 94 of file qgstextlabelfeature.h.

◆ text()

QString QgsTextLabelFeature::text ( int  partId) const

Returns the text component corresponding to a specified label part.

Parameters
partIdSet to -1 for labels which are not broken into parts (e.g., non-curved labels), or the required part index for labels which are broken into parts (curved labels)

Definition at line 34 of file qgstextlabelfeature.cpp.

◆ textMetrics()

const QgsPrecalculatedTextMetrics* QgsTextLabelFeature::textMetrics ( ) const
inline

Returns additional info required for curved label placement.

Returns nullptr if not set.

See also
setTextMetrics()
Since
QGIS 3.20

Definition at line 86 of file qgstextlabelfeature.h.

Member Data Documentation

◆ mDataDefinedValues

QMap< QgsPalLayerSettings::Property, QVariant > QgsTextLabelFeature::mDataDefinedValues
protected

Stores attribute values for data defined properties.

Definition at line 165 of file qgstextlabelfeature.h.

◆ mDefinedFont

QFont QgsTextLabelFeature::mDefinedFont
protected

Font for rendering.

Definition at line 162 of file qgstextlabelfeature.h.

◆ mDocument

QgsTextDocument QgsTextLabelFeature::mDocument
protected

Definition at line 167 of file qgstextlabelfeature.h.

◆ mDocumentMetrics

QgsTextDocumentMetrics QgsTextLabelFeature::mDocumentMetrics
protected

Definition at line 168 of file qgstextlabelfeature.h.

◆ mMaximumCharacterAngleInside

double QgsTextLabelFeature::mMaximumCharacterAngleInside = 0
protected

Definition at line 170 of file qgstextlabelfeature.h.

◆ mMaximumCharacterAngleOutside

double QgsTextLabelFeature::mMaximumCharacterAngleOutside = 0
protected

Definition at line 171 of file qgstextlabelfeature.h.

◆ mTextMetrics

std::optional< QgsPrecalculatedTextMetrics > QgsTextLabelFeature::mTextMetrics
protected

Definition at line 173 of file qgstextlabelfeature.h.


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