QgsAbstractLabelProvider Class Reference

The QgsAbstractLabelProvider class is an interface class. More...

#include <qgslabelingengine.h>

Inheritance diagram for QgsAbstractLabelProvider:

Public Types
enum	Flag { DrawLabels = 1 << 1 , MergeConnectedLines = 1 << 3 , CentroidMustBeInside = 1 << 4 }

Public Member Functions
	QgsAbstractLabelProvider (QgsMapLayer *layer, const QString &providerId=QString())
	Construct the provider with default values. More...
virtual	~QgsAbstractLabelProvider ()=default
virtual void	drawLabel (QgsRenderContext &context, pal::LabelPosition *label) const =0
	Draw this label at the position determined by the labeling engine. More...
virtual void	drawLabelBackground (QgsRenderContext &context, pal::LabelPosition *label) const
	Draw the background for the specified label. More...
virtual void	drawUnplacedLabel (QgsRenderContext &context, pal::LabelPosition *label) const
	Draw an unplaced label. More...
Flags	flags () const
	Flags associated with the provider. More...
virtual QList< QgsLabelFeature * >	labelFeatures (QgsRenderContext &context)=0
	Returns list of label features (they are owned by the provider and thus deleted on its destruction) More...
QgsMapLayer *	layer () const
	Returns the associated layer, or nullptr if no layer is associated with the provider. More...
QgsExpressionContextScope *	layerExpressionContextScope () const
	Returns the expression context scope created from the layer associated with this provider. More...
QString	layerId () const
	Returns ID of associated layer, or empty string if no layer is associated with the provider. More...
double	layerReferenceScale () const
	Returns the symbology reference scale of the layer associated with this provider. More...
QString	name () const
	Name of the layer (for statistics, debugging etc.) - does not need to be unique. More...
QgsLabelObstacleSettings::ObstacleType	obstacleType () const
	How the feature geometries will work as obstacles. More...
Qgis::LabelPlacement	placement () const
	What placement strategy to use for the labels. More...
double	priority () const
	Default priority of labels (may be overridden by individual labels) More...
QString	providerId () const
	Returns provider ID - useful in case there is more than one label provider within a layer (e.g. More...
void	setEngine (const QgsLabelingEngine *engine)
	Associate provider with a labeling engine (should be only called internally from QgsLabelingEngine) More...
virtual void	startRender (QgsRenderContext &context)
	To be called before rendering of labels begins. More...
virtual void	stopRender (QgsRenderContext &context)
	To be called after rendering is complete. More...
virtual QList< QgsAbstractLabelProvider * >	subProviders ()
	Returns list of child providers - useful if the provider needs to put labels into more layers with different configuration. More...
Qgis::UpsideDownLabelHandling	upsidedownLabels () const
	How to handle labels that would be upside down. More...

Protected Attributes
const QgsLabelingEngine *	mEngine = nullptr
	Associated labeling engine. More...
Flags	mFlags = DrawLabels
	Flags altering drawing and registration of features. More...
QgsWeakMapLayerPointer	mLayer
	Weak pointer to source layer. More...
QString	mLayerId
	Associated layer's ID, if applicable. More...
QString	mName
	Name of the layer. More...
QgsLabelObstacleSettings::ObstacleType	mObstacleType = QgsLabelObstacleSettings::PolygonBoundary
	Type of the obstacle of feature geometries. More...
Qgis::LabelPlacement	mPlacement = Qgis::LabelPlacement::AroundPoint
	Placement strategy. More...
double	mPriority = 0.5
	Default priority of labels. More...
QString	mProviderId
	Associated provider ID (one layer may have multiple providers, e.g. in rule-based labeling) More...
Qgis::UpsideDownLabelHandling	mUpsidedownLabels = Qgis::UpsideDownLabelHandling::FlipUpsideDownLabels
	How to handle labels that would be upside down. More...

Detailed Description

The QgsAbstractLabelProvider class is an interface class.

Implementations return list of labels and their associated geometries - these are used by QgsLabelingEngine to compute the final layout of labels.

Implementations also take care of drawing the returned final label positions.

Note

this class is not a part of public API yet. See notes in QgsLabelingEngine

not available in Python bindings

Since

QGIS 2.12

Definition at line 52 of file qgslabelingengine.h.

Member Enumeration Documentation

Flag

enum QgsAbstractLabelProvider::Flag

Enumerator
DrawLabels	Whether the labels should be rendered.
MergeConnectedLines	Whether adjacent lines (with the same label text) should be merged.
CentroidMustBeInside	Whether location of centroid must be inside of polygons.

Definition at line 64 of file qgslabelingengine.h.

Constructor & Destructor Documentation

QgsAbstractLabelProvider()

QgsAbstractLabelProvider::QgsAbstractLabelProvider	(	QgsMapLayer *	layer,
		const QString &	providerId = QString()
	)

Construct the provider with default values.

Definition at line 631 of file qgslabelingengine.cpp.

~QgsAbstractLabelProvider()

virtual QgsAbstractLabelProvider::~QgsAbstractLabelProvider ( )

virtualdefault

Member Function Documentation

drawLabel()

virtual void QgsAbstractLabelProvider::drawLabel ( QgsRenderContext &  context, pal::LabelPosition *  label  ) const

pure virtual

Draw this label at the position determined by the labeling engine.

Before any calls to drawLabel(), a provider should be prepared for rendering by a call to startRender() and a corresponding call to stopRender().

Implemented in QgsLabelSinkProvider, QgsRuleBasedLabelSinkProvider, QgsVectorLayerLabelProvider, and QgsVectorLayerDiagramProvider.

drawLabelBackground()

void QgsAbstractLabelProvider::drawLabelBackground ( QgsRenderContext &  context, pal::LabelPosition *  label  ) const

virtual

Draw the background for the specified label.

This is called in turn for each label provider before any actual labels are rendered, and allows the provider to render content which should be drawn below ALL map labels (such as background rectangles or callout lines).

Before any calls to drawLabelBackground(), a provider should be prepared for rendering by a call to startRender() and a corresponding call to stopRender().

Since

QGIS 3.10

Reimplemented in QgsVectorLayerLabelProvider.

Definition at line 649 of file qgslabelingengine.cpp.

drawUnplacedLabel()

void QgsAbstractLabelProvider::drawUnplacedLabel ( QgsRenderContext &  context, pal::LabelPosition *  label  ) const

virtual

Draw an unplaced label.

These correspond to features which were registered for labeling, but which could not be labeled (e.g. due to conflicting labels).

The default behavior is to draw nothing for these labels.

Note

This method is only used if the QgsLabelingEngineSettings::DrawUnplacedLabels flag is set on the labeling engine.

Since

QGIS 3.10

Reimplemented in QgsLabelSinkProvider, QgsRuleBasedLabelSinkProvider, and QgsVectorLayerLabelProvider.

Definition at line 644 of file qgslabelingengine.cpp.

flags()

Flags QgsAbstractLabelProvider::flags ( ) const

inline

Flags associated with the provider.

Definition at line 148 of file qgslabelingengine.h.

labelFeatures()

virtual QList< QgsLabelFeature * > QgsAbstractLabelProvider::labelFeatures ( QgsRenderContext &  context )

pure virtual

Returns list of label features (they are owned by the provider and thus deleted on its destruction)

Implemented in QgsVectorLayerLabelProvider, and QgsVectorLayerDiagramProvider.

layer()

QgsMapLayer * QgsAbstractLabelProvider::layer ( ) const

inline

Returns the associated layer, or nullptr if no layer is associated with the provider.

Warning

Accessing the layer is not thread safe, and this should never be called while the labeling engine is running from a background thread!

Definition at line 138 of file qgslabelingengine.h.

layerExpressionContextScope()

QgsExpressionContextScope * QgsAbstractLabelProvider::layerExpressionContextScope

(

)

const

Returns the expression context scope created from the layer associated with this provider.

Since

QGIS 3.22

Definition at line 672 of file qgslabelingengine.cpp.

layerId()

QString QgsAbstractLabelProvider::layerId ( ) const

inline

Returns ID of associated layer, or empty string if no layer is associated with the provider.

Definition at line 131 of file qgslabelingengine.h.

layerReferenceScale()

double QgsAbstractLabelProvider::layerReferenceScale ( ) const

inline

Returns the symbology reference scale of the layer associated with this provider.

Since

QGIS 3.22

Definition at line 174 of file qgslabelingengine.h.

name()

QString QgsAbstractLabelProvider::name ( ) const

inline

Name of the layer (for statistics, debugging etc.) - does not need to be unique.

Definition at line 128 of file qgslabelingengine.h.

obstacleType()

QgsLabelObstacleSettings::ObstacleType QgsAbstractLabelProvider::obstacleType ( ) const

inline

How the feature geometries will work as obstacles.

Definition at line 157 of file qgslabelingengine.h.

placement()

Qgis::LabelPlacement QgsAbstractLabelProvider::placement ( ) const

inline

What placement strategy to use for the labels.

Definition at line 151 of file qgslabelingengine.h.

priority()

double QgsAbstractLabelProvider::priority ( ) const

inline

Default priority of labels (may be overridden by individual labels)

Definition at line 154 of file qgslabelingengine.h.

providerId()

QString QgsAbstractLabelProvider::providerId ( ) const

inline

Returns provider ID - useful in case there is more than one label provider within a layer (e.g.

in case of rule-based labeling - provider ID = rule's key). May be empty string if layer ID is sufficient for identification of provider's configuration.

Definition at line 145 of file qgslabelingengine.h.

setEngine()

void QgsAbstractLabelProvider::setEngine ( const QgsLabelingEngine *  engine )

inline

Associate provider with a labeling engine (should be only called internally from QgsLabelingEngine)

Definition at line 62 of file qgslabelingengine.h.

startRender()

void QgsAbstractLabelProvider::startRender ( QgsRenderContext &  context )

virtual

To be called before rendering of labels begins.

Must be accompanied by a corresponding call to stopRender()

Since

QGIS 3.10

Reimplemented in QgsVectorLayerLabelProvider.

Definition at line 654 of file qgslabelingengine.cpp.

stopRender()

void QgsAbstractLabelProvider::stopRender ( QgsRenderContext &  context )

virtual

To be called after rendering is complete.

See also

startRender()

Since

QGIS 3.10

Reimplemented in QgsVectorLayerLabelProvider.

Definition at line 663 of file qgslabelingengine.cpp.

subProviders()

virtual QList< QgsAbstractLabelProvider * > QgsAbstractLabelProvider::subProviders ( )

inlinevirtual

Returns list of child providers - useful if the provider needs to put labels into more layers with different configuration.

Reimplemented in QgsRuleBasedLabelProvider, and QgsVectorTileBasicLabelProvider.

Definition at line 125 of file qgslabelingengine.h.

upsidedownLabels()

Qgis::UpsideDownLabelHandling QgsAbstractLabelProvider::upsidedownLabels ( ) const

inline

How to handle labels that would be upside down.

Definition at line 160 of file qgslabelingengine.h.

Member Data Documentation

mEngine

const QgsLabelingEngine* QgsAbstractLabelProvider::mEngine = nullptr

protected

Associated labeling engine.

Definition at line 178 of file qgslabelingengine.h.

mFlags

Flags QgsAbstractLabelProvider::mFlags = DrawLabels

protected

Flags altering drawing and registration of features.

Definition at line 189 of file qgslabelingengine.h.

mLayer

QgsWeakMapLayerPointer QgsAbstractLabelProvider::mLayer

protected

Weak pointer to source layer.

Definition at line 185 of file qgslabelingengine.h.

mLayerId

QString QgsAbstractLabelProvider::mLayerId

protected

Associated layer's ID, if applicable.

Definition at line 183 of file qgslabelingengine.h.

mName

QString QgsAbstractLabelProvider::mName

protected

Name of the layer.

Definition at line 181 of file qgslabelingengine.h.

mObstacleType

QgsLabelObstacleSettings::ObstacleType QgsAbstractLabelProvider::mObstacleType = QgsLabelObstacleSettings::PolygonBoundary

protected

Type of the obstacle of feature geometries.

Definition at line 195 of file qgslabelingengine.h.

mPlacement

Qgis::LabelPlacement QgsAbstractLabelProvider::mPlacement = Qgis::LabelPlacement::AroundPoint

protected

Placement strategy.

Definition at line 191 of file qgslabelingengine.h.

mPriority

double QgsAbstractLabelProvider::mPriority = 0.5

protected

Default priority of labels.

Definition at line 193 of file qgslabelingengine.h.

mProviderId

QString QgsAbstractLabelProvider::mProviderId

protected

Associated provider ID (one layer may have multiple providers, e.g. in rule-based labeling)

Definition at line 187 of file qgslabelingengine.h.

mUpsidedownLabels

Qgis::UpsideDownLabelHandling QgsAbstractLabelProvider::mUpsidedownLabels = Qgis::UpsideDownLabelHandling::FlipUpsideDownLabels

protected

How to handle labels that would be upside down.

Definition at line 197 of file qgslabelingengine.h.

---

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

• /build/qgis-3.28.0+99sid/src/core/labeling/qgslabelingengine.h
• /build/qgis-3.28.0+99sid/src/core/labeling/qgslabelingengine.cpp