QGIS API Documentation 3.39.0-Master (f549811d78c)
Loading...
Searching...
No Matches
Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
QgsLabelingEngine Class Referenceabstract

The QgsLabelingEngine class provides map labeling functionality. More...

#include <qgslabelingengine.h>

Inheritance diagram for QgsLabelingEngine:
Inheritance graph
[legend]

Public Member Functions

 QgsLabelingEngine ()
 Construct the labeling engine with default settings.
 
 QgsLabelingEngine (const QgsLabelingEngine &rh)=delete
 
virtual ~QgsLabelingEngine ()
 Clean up everything (especially the registered providers)
 
QString addProvider (QgsAbstractLabelProvider *provider)
 Adds a provider of label features.
 
const QgsLabelingEngineSettingsengineSettings () const
 Gets associated labeling engine settings.
 
const QgsMapSettingsmapSettings () const
 Gets associated map settings.
 
QgsLabelingEngineoperator= (const QgsLabelingEngine &rh)=delete
 
QStringList participatingLayerIds () const
 Returns a list of layer IDs for layers with providers in the engine.
 
QList< QgsMapLayer * > participatingLayers () const
 Returns a list of layers with providers in the engine.
 
bool prepare (QgsRenderContext &context)
 Prepares the engine for rendering in the specified context.
 
QgsAbstractLabelProviderproviderById (const QString &id)
 Returns the provider with matching id, where id corresponds to the value returned by the addProvider() call.
 
void removeProvider (QgsAbstractLabelProvider *provider)
 Remove provider if the provider's initialization failed. Provider instance is deleted.
 
QgsLabelingResultsresults () const
 For internal use by the providers.
 
virtual void run (QgsRenderContext &context)=0
 Runs the labeling job.
 
void setMapSettings (const QgsMapSettings &mapSettings)
 Associate map settings instance.
 
QgsLabelingResultstakeResults ()
 Returns pointer to recently computed results and pass the ownership of results to the caller.
 

Protected Member Functions

void cleanup ()
 Cleans up the engine following a call to registerLabels() or solve().
 
void drawLabels (QgsRenderContext &context, const QString &layerId=QString())
 Draws labels to the specified render context.
 
void processProvider (QgsAbstractLabelProvider *provider, QgsRenderContext &context, pal::Pal &p)
 
void registerLabels (QgsRenderContext &context)
 Runs the label registration step.
 
void solve (QgsRenderContext &context)
 Solves the label problem.
 

Protected Attributes

std::vector< std::unique_ptr< QgsAbstractLabelingEngineRule > > mEngineRules
 
QList< pal::LabelPosition * > mLabels
 
QgsMapSettings mMapSettings
 Associated map settings instance.
 
std::unique_ptr< pal::PalmPal
 
std::unique_ptr< pal::ProblemmProblem
 
QList< QgsAbstractLabelProvider * > mProviders
 List of providers (the are owned by the labeling engine)
 
QHash< QString, QgsAbstractLabelProvider * > mProvidersById
 
std::unique_ptr< QgsLabelingResultsmResults
 Resulting labeling layout.
 
QList< QgsAbstractLabelProvider * > mSubProviders
 List of labeling engine rules (owned by the labeling engine)
 
QList< pal::LabelPosition * > mUnlabeled
 

Detailed Description

The QgsLabelingEngine class provides map labeling functionality.

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:

// add one or more providers
engine.addProvider( ... );
// compute the labeling and draw labels (using painter from the context)
engine.run( context );
The QgsLabelingEngine class provides map labeling functionality.
QString addProvider(QgsAbstractLabelProvider *provider)
Adds a provider of label features.
const QgsMapSettings & mapSettings() const
Gets associated map settings.
void setMapSettings(const QgsMapSettings &mapSettings)
Associate map settings instance.
virtual void run(QgsRenderContext &context)=0
Runs the labeling job.
Note
this class is not a part of public API yet. The provider's interface still uses pal::LabelPosition as an argument in drawLabels() method - this should be sorted out first (a class common to API and pal?). Also, the API may need more polishing to be easy to use - e.g. use concept of labeling layers in API (equivalent of pal::Layer) instead of subProviders(), label providers integrated into feature loop vs providers with independent feature loop), split labeling computation from drawing of labels, improved results class with label iterator).
not available in Python bindings

Definition at line 340 of file qgslabelingengine.h.

Constructor & Destructor Documentation

◆ QgsLabelingEngine() [1/2]

QgsLabelingEngine::QgsLabelingEngine ( )

Construct the labeling engine with default settings.

Definition at line 88 of file qgslabelingengine.cpp.

◆ ~QgsLabelingEngine()

QgsLabelingEngine::~QgsLabelingEngine ( )
virtual

Clean up everything (especially the registered providers)

Definition at line 92 of file qgslabelingengine.cpp.

◆ QgsLabelingEngine() [2/2]

QgsLabelingEngine::QgsLabelingEngine ( const QgsLabelingEngine rh)
delete

Member Function Documentation

◆ addProvider()

QString QgsLabelingEngine::addProvider ( QgsAbstractLabelProvider provider)

Adds a provider of label features.

Takes ownership of the provider.

Returns a generated string uniqueuly identifying the provider, which can be used with the providerById() method to retrieve the provider at a later stage.

Definition at line 214 of file qgslabelingengine.cpp.

◆ cleanup()

void QgsLabelingEngine::cleanup ( )
protected

Cleans up the engine following a call to registerLabels() or solve().

Since
QGIS 3.10

Definition at line 593 of file qgslabelingengine.cpp.

◆ drawLabels()

void QgsLabelingEngine::drawLabels ( QgsRenderContext context,
const QString &  layerId = QString() 
)
protected

Draws labels to the specified render context.

If layerId is specified, only labels from the matching layer will be rendered.

Must be preceded by a call to registerLabels() and solve()

Since
QGIS 3.10

Definition at line 458 of file qgslabelingengine.cpp.

◆ engineSettings()

const QgsLabelingEngineSettings & QgsLabelingEngine::engineSettings ( ) const
inline

Gets associated labeling engine settings.

Definition at line 357 of file qgslabelingengine.h.

◆ mapSettings()

const QgsMapSettings & QgsLabelingEngine::mapSettings ( ) const
inline

Gets associated map settings.

Definition at line 354 of file qgslabelingengine.h.

◆ operator=()

QgsLabelingEngine & QgsLabelingEngine::operator= ( const QgsLabelingEngine rh)
delete

◆ participatingLayerIds()

QStringList QgsLabelingEngine::participatingLayerIds ( ) const

Returns a list of layer IDs for layers with providers in the engine.

Since
QGIS 3.10

Definition at line 168 of file qgslabelingengine.cpp.

◆ participatingLayers()

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

Returns a list of layers with providers in the engine.

Definition at line 122 of file qgslabelingengine.cpp.

◆ prepare()

bool QgsLabelingEngine::prepare ( QgsRenderContext context)

Prepares the engine for rendering in the specified context.

Warning
This method must be called in advanced on the main rendering thread, not a background thread.
Since
QGIS 3.40

Definition at line 106 of file qgslabelingengine.cpp.

◆ processProvider()

void QgsLabelingEngine::processProvider ( QgsAbstractLabelProvider provider,
QgsRenderContext context,
pal::Pal p 
)
protected

Definition at line 238 of file qgslabelingengine.cpp.

◆ providerById()

QgsAbstractLabelProvider * QgsLabelingEngine::providerById ( const QString &  id)

Returns the provider with matching id, where id corresponds to the value returned by the addProvider() call.

Returns nullptr if no matching provider is found.

Definition at line 223 of file qgslabelingengine.cpp.

◆ registerLabels()

void QgsLabelingEngine::registerLabels ( QgsRenderContext context)
protected

Runs the label registration step.

Must be called by subclasses prior to solve() and drawLabels()

Since
QGIS 3.10

Definition at line 287 of file qgslabelingengine.cpp.

◆ removeProvider()

void QgsLabelingEngine::removeProvider ( QgsAbstractLabelProvider provider)

Remove provider if the provider's initialization failed. Provider instance is deleted.

Definition at line 228 of file qgslabelingengine.cpp.

◆ results()

QgsLabelingResults * QgsLabelingEngine::results ( ) const
inline

For internal use by the providers.

Definition at line 412 of file qgslabelingengine.h.

◆ run()

virtual void QgsLabelingEngine::run ( QgsRenderContext context)
pure virtual

Runs the labeling job.

Depending on the concrete labeling engine class, this will either run the whole labeling job, including rendering the labels themselves, OR possibly just run the labeling job but leave the rendering to a future, deferred stage.

Implemented in QgsDefaultLabelingEngine, and QgsStagedRenderLabelingEngine.

◆ setMapSettings()

void QgsLabelingEngine::setMapSettings ( const QgsMapSettings mapSettings)

Associate map settings instance.

Definition at line 98 of file qgslabelingengine.cpp.

◆ solve()

void QgsLabelingEngine::solve ( QgsRenderContext context)
protected

Solves the label problem.

Must be called by subclasses prior to drawLabels(), and must be preceded by a call to registerLabels()

Since
QGIS 3.10

Definition at line 342 of file qgslabelingengine.cpp.

◆ takeResults()

QgsLabelingResults * QgsLabelingEngine::takeResults ( )

Returns pointer to recently computed results and pass the ownership of results to the caller.

Definition at line 601 of file qgslabelingengine.cpp.

Member Data Documentation

◆ mEngineRules

std::vector< std::unique_ptr< QgsAbstractLabelingEngineRule > > QgsLabelingEngine::mEngineRules
protected

Definition at line 464 of file qgslabelingengine.h.

◆ mLabels

QList<pal::LabelPosition *> QgsLabelingEngine::mLabels
protected

Definition at line 472 of file qgslabelingengine.h.

◆ mMapSettings

QgsMapSettings QgsLabelingEngine::mMapSettings
protected

Associated map settings instance.

Definition at line 456 of file qgslabelingengine.h.

◆ mPal

std::unique_ptr< pal::Pal > QgsLabelingEngine::mPal
protected

Definition at line 469 of file qgslabelingengine.h.

◆ mProblem

std::unique_ptr< pal::Problem > QgsLabelingEngine::mProblem
protected

Definition at line 470 of file qgslabelingengine.h.

◆ mProviders

QList<QgsAbstractLabelProvider *> QgsLabelingEngine::mProviders
protected

List of providers (the are owned by the labeling engine)

Definition at line 459 of file qgslabelingengine.h.

◆ mProvidersById

QHash<QString, QgsAbstractLabelProvider *> QgsLabelingEngine::mProvidersById
protected

Definition at line 460 of file qgslabelingengine.h.

◆ mResults

std::unique_ptr< QgsLabelingResults > QgsLabelingEngine::mResults
protected

Resulting labeling layout.

Definition at line 467 of file qgslabelingengine.h.

◆ mSubProviders

QList<QgsAbstractLabelProvider *> QgsLabelingEngine::mSubProviders
protected

List of labeling engine rules (owned by the labeling engine)

Definition at line 461 of file qgslabelingengine.h.

◆ mUnlabeled

QList<pal::LabelPosition *> QgsLabelingEngine::mUnlabeled
protected

Definition at line 471 of file qgslabelingengine.h.


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