QGIS API Documentation  3.1.0-Master (cd495fb)
Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
QgsLabelingEngine Class Reference

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

#include <qgslabelingengine.h>

Public Member Functions

 QgsLabelingEngine ()
 Construct the labeling engine with default settings. More...
 
 QgsLabelingEngine (const QgsLabelingEngine &rh)=delete
 QgsLabelingEngine cannot be copied. More...
 
 ~QgsLabelingEngine ()
 Clean up everything (especially the registered providers) More...
 
void addProvider (QgsAbstractLabelProvider *provider)
 Add provider of label features. Takes ownership of the provider. More...
 
const QgsLabelingEngineSettingsengineSettings () const
 Gets associated labeling engine settings. More...
 
const QgsMapSettingsmapSettings () const
 Gets associated map settings. More...
 
QgsLabelingEngineoperator= (const QgsLabelingEngine &rh)=delete
 QgsLabelingEngine cannot be copied. More...
 
QList< QgsMapLayer *> participatingLayers () const
 Returns a list of layers with providers in the engine. More...
 
void removeProvider (QgsAbstractLabelProvider *provider)
 Remove provider if the provider's initialization failed. Provider instance is deleted. More...
 
QgsLabelingResultsresults () const
 For internal use by the providers. More...
 
void run (QgsRenderContext &context)
 compute the labeling with given map settings and providers More...
 
void setMapSettings (const QgsMapSettings &mapSettings)
 Associate map settings instance. More...
 
QgsLabelingResultstakeResults ()
 Returns pointer to recently computed results and pass the ownership of results to the caller. More...
 

Protected Member Functions

void processProvider (QgsAbstractLabelProvider *provider, QgsRenderContext &context, pal::Pal &p)
 

Protected Attributes

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

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 );
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
Since
QGIS 2.12

Definition at line 170 of file qgslabelingengine.h.

Constructor & Destructor Documentation

◆ QgsLabelingEngine() [1/2]

QgsLabelingEngine::QgsLabelingEngine ( )

Construct the labeling engine with default settings.

Definition at line 74 of file qgslabelingengine.cpp.

◆ ~QgsLabelingEngine()

QgsLabelingEngine::~QgsLabelingEngine ( )

Clean up everything (especially the registered providers)

Definition at line 78 of file qgslabelingengine.cpp.

◆ QgsLabelingEngine() [2/2]

QgsLabelingEngine::QgsLabelingEngine ( const QgsLabelingEngine rh)
delete

QgsLabelingEngine cannot be copied.

Member Function Documentation

◆ addProvider()

void QgsLabelingEngine::addProvider ( QgsAbstractLabelProvider provider)

Add provider of label features. Takes ownership of the provider.

Definition at line 100 of file qgslabelingengine.cpp.

◆ engineSettings()

const QgsLabelingEngineSettings& QgsLabelingEngine::engineSettings ( ) const
inline

Gets associated labeling engine settings.

Definition at line 189 of file qgslabelingengine.h.

◆ mapSettings()

const QgsMapSettings& QgsLabelingEngine::mapSettings ( ) const
inline

Gets associated map settings.

Definition at line 186 of file qgslabelingengine.h.

◆ operator=()

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

QgsLabelingEngine cannot be copied.

◆ participatingLayers()

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

Returns a list of layers with providers in the engine.

Since
QGIS 3.0

Definition at line 84 of file qgslabelingengine.cpp.

◆ processProvider()

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

Definition at line 115 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 106 of file qgslabelingengine.cpp.

◆ results()

QgsLabelingResults* QgsLabelingEngine::results ( ) const
inline

For internal use by the providers.

Definition at line 210 of file qgslabelingengine.h.

◆ run()

void QgsLabelingEngine::run ( QgsRenderContext context)

compute the labeling with given map settings and providers

Definition at line 188 of file qgslabelingengine.cpp.

◆ setMapSettings()

void QgsLabelingEngine::setMapSettings ( const QgsMapSettings mapSettings)
inline

Associate map settings instance.

Definition at line 184 of file qgslabelingengine.h.

◆ takeResults()

QgsLabelingResults * QgsLabelingEngine::takeResults ( )

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

Definition at line 348 of file qgslabelingengine.cpp.

Member Data Documentation

◆ mMapSettings

QgsMapSettings QgsLabelingEngine::mMapSettings
protected

Associated map settings instance.

Definition at line 217 of file qgslabelingengine.h.

◆ mProviders

QList<QgsAbstractLabelProvider *> QgsLabelingEngine::mProviders
protected

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

Definition at line 220 of file qgslabelingengine.h.

◆ mResults

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

Resulting labeling layout.

Definition at line 224 of file qgslabelingengine.h.

◆ mSubProviders

QList<QgsAbstractLabelProvider *> QgsLabelingEngine::mSubProviders
protected

Definition at line 221 of file qgslabelingengine.h.


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