QgsLabelingEngine class

The QgsLabelingEngine class provides map labeling functionality.

Reference

The input for the engine is a list of label provider objects and map settings. Based on the input, the engine computes layout of labels for the given map view with no collisions between the labels. Drawing of resulting labels is done again by label providers.

The labeling engine is used for the map rendering in QgsMapRendererJob instances, individual map layer renderers may add label providers - for example, QgsVectorLayerRenderer may add text label provider and diagram provider (if labeling / diagrams were configured for such vector layer).

The labeling engine may also be used independently from map rendering loop:

QgsLabelingEngine engine;
engine.setMapSettings( mapSettings );
// add one or more providers
engine.addProvider( ... );
// compute the labeling and draw labels (using painter from the context)
engine.run( context );

Constructors, destructors, conversion operators

QgsLabelingEngine(): Construct the labeling engine with default settings.
QgsLabelingEngine(const QgsLabelingEngine& rh) deleted: QgsLabelingEngine cannot be copied.
~QgsLabelingEngine(): Clean up everything (especially the registered providers)

Public functions

void addProvider(QgsAbstractLabelProvider* provider): Add provider of label features. Takes ownership of the provider.
auto engineSettings() const -> const QgsLabelingEngineSettings&: Gets associated labeling engine settings.
auto mapSettings() const -> const QgsMapSettings&: Gets associated map settings.
auto operator=(const QgsLabelingEngine& rh) -> QgsLabelingEngine& deleted: QgsLabelingEngine cannot be copied.
auto participatingLayers() const -> QList<QgsMapLayer*>: Returns a list of layers with providers in the engine.
void removeProvider(QgsAbstractLabelProvider* provider): Remove provider if the provider's initialization failed. Provider instance is deleted.
auto results() const -> QgsLabelingResults*: For internal use by the providers.
void run(QgsRenderContext& context): compute the labeling with given map settings and providers
void setMapSettings(const QgsMapSettings& mapSettings): Associate map settings instance.
auto takeResults() -> QgsLabelingResults*: Returns pointer to recently computed results and pass the ownership of results to the caller.

Protected variables

QgsMapSettings mMapSettings: Associated map settings instance.
QList<QgsAbstractLabelProvider*> mProviders: List of providers (the are owned by the labeling engine)
std::unique_ptr<QgsLabelingResults> mResults: Resulting labeling layout.

Function documentation

QList<QgsMapLayer*> QgsLabelingEngine::participatingLayers() const