QGIS API Documentation  3.37.0-Master (a5b4d9743e8)
Public Types | Public Member Functions | Protected Attributes | List of all members
QgsAbstractLabelProvider Class Referenceabstract

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

#include <qgslabelingengine.h>

Inheritance diagram for QgsAbstractLabelProvider:
Inheritance graph
[legend]

Public Types

enum  Flag { DrawLabels = 1 << 1 , MergeConnectedLines = 1 << 3 , CentroidMustBeInside = 1 << 4 }
 
typedef QFlags< FlagFlags
 

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...
 
QgsMapLayerlayer () const
 Returns the associated layer, or nullptr if no layer is associated with the provider. More...
 
QgsExpressionContextScopelayerExpressionContextScope () 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 QgsLabelingEnginemEngine = 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::ObstacleType::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

Definition at line 50 of file qgslabelingengine.h.

Member Typedef Documentation

◆ Flags

Definition at line 68 of file qgslabelingengine.h.

Member Enumeration Documentation

◆ 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 62 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 649 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 QgsVectorLayerDiagramProvider, QgsMeshLayerLabelProvider, QgsVectorLayerLabelProvider, QgsRuleBasedLabelSinkProvider, and QgsLabelSinkProvider.

◆ 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 667 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 Qgis::Qgis::LabelingFlag::DrawUnplacedLabels flag is set on the labeling engine.
Since
QGIS 3.10

Reimplemented in QgsVectorLayerLabelProvider, QgsRuleBasedLabelSinkProvider, and QgsLabelSinkProvider.

Definition at line 662 of file qgslabelingengine.cpp.

◆ flags()

Flags QgsAbstractLabelProvider::flags ( ) const
inline

Flags associated with the provider.

Definition at line 146 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 QgsVectorLayerDiagramProvider, QgsMeshLayerLabelProvider, and QgsVectorLayerLabelProvider.

◆ 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 136 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 690 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 129 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 172 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 126 of file qgslabelingengine.h.

◆ obstacleType()

QgsLabelObstacleSettings::ObstacleType QgsAbstractLabelProvider::obstacleType ( ) const
inline

How the feature geometries will work as obstacles.

Definition at line 155 of file qgslabelingengine.h.

◆ placement()

Qgis::LabelPlacement QgsAbstractLabelProvider::placement ( ) const
inline

What placement strategy to use for the labels.

Definition at line 149 of file qgslabelingengine.h.

◆ priority()

double QgsAbstractLabelProvider::priority ( ) const
inline

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

Definition at line 152 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 143 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 60 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 QgsMeshLayerLabelProvider, and QgsVectorLayerLabelProvider.

Definition at line 672 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 QgsMeshLayerLabelProvider, and QgsVectorLayerLabelProvider.

Definition at line 681 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 QgsVectorTileBasicLabelProvider, and QgsRuleBasedLabelProvider.

Definition at line 123 of file qgslabelingengine.h.

◆ upsidedownLabels()

Qgis::UpsideDownLabelHandling QgsAbstractLabelProvider::upsidedownLabels ( ) const
inline

How to handle labels that would be upside down.

Definition at line 158 of file qgslabelingengine.h.

Member Data Documentation

◆ mEngine

const QgsLabelingEngine* QgsAbstractLabelProvider::mEngine = nullptr
protected

Associated labeling engine.

Definition at line 176 of file qgslabelingengine.h.

◆ mFlags

Flags QgsAbstractLabelProvider::mFlags = DrawLabels
protected

Flags altering drawing and registration of features.

Definition at line 187 of file qgslabelingengine.h.

◆ mLayer

QgsWeakMapLayerPointer QgsAbstractLabelProvider::mLayer
protected

Weak pointer to source layer.

Definition at line 183 of file qgslabelingengine.h.

◆ mLayerId

QString QgsAbstractLabelProvider::mLayerId
protected

Associated layer's ID, if applicable.

Definition at line 181 of file qgslabelingengine.h.

◆ mName

QString QgsAbstractLabelProvider::mName
protected

Name of the layer.

Definition at line 179 of file qgslabelingengine.h.

◆ mObstacleType

Type of the obstacle of feature geometries.

Definition at line 193 of file qgslabelingengine.h.

◆ mPlacement

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

Placement strategy.

Definition at line 189 of file qgslabelingengine.h.

◆ mPriority

double QgsAbstractLabelProvider::mPriority = 0.5
protected

Default priority of labels.

Definition at line 191 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 185 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 195 of file qgslabelingengine.h.


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