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

#include <qgslabelingengine.h>

Inheritance diagram for QgsLabelingEngine:

[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 QgsLabelingEngineSettings &	engineSettings () const
	Gets associated labeling engine settings.

const QgsMapSettings &	mapSettings () const
	Gets associated map settings.

QgsLabelingEngine &	operator= (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.

QgsAbstractLabelProvider *	providerById (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.

QgsLabelingResults *	results () 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.

QgsLabelingResults *	takeResults ()
	Returns pointer to recently computed results and pass the ownership of results to the caller.

Static Public Member Functions
static void	drawLabelCandidateRect (pal::LabelPosition lp, QgsRenderContext &context, const QgsMapToPixel xform, QList< QgsLabelCandidate > *candidates=nullptr)
	Draws label candidate rectangles.

static void	drawLabelMetrics (pal::LabelPosition *label, const QgsMapToPixel &xform, QgsRenderContext &context, const QPointF &renderPoint)
	Draws label metrics.

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::Pal >	mPal

std::unique_ptr< pal::Problem >	mProblem

QList< QgsAbstractLabelProvider * >	mProviders
	List of providers (the are owned by the labeling engine)

QHash< QString, QgsAbstractLabelProvider * >	mProvidersById

std::unique_ptr< QgsLabelingResults >	mResults
	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:

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 );

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 360 of file qgslabelingengine.h.

Constructor & Destructor Documentation

◆ QgsLabelingEngine() [1/2]

QgsLabelingEngine::QgsLabelingEngine ( )

Construct the labeling engine with default settings.

Definition at line 90 of file qgslabelingengine.cpp.

◆ ~QgsLabelingEngine()

QgsLabelingEngine::~QgsLabelingEngine ( )

virtual

Clean up everything (especially the registered providers)

Definition at line 94 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 216 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 674 of file qgslabelingengine.cpp.

◆ drawLabelCandidateRect()

void QgsLabelingEngine::drawLabelCandidateRect	(	pal::LabelPosition *	lp,
		QgsRenderContext &	context,
		const QgsMapToPixel *	xform,
		QList< QgsLabelCandidate > *	candidates = `nullptr`
	)

static

Draws label candidate rectangles.

See also: drawLabelMetrics()

Definition at line 687 of file qgslabelingengine.cpp.

◆ drawLabelMetrics()

void QgsLabelingEngine::drawLabelMetrics	(	pal::LabelPosition *	label,
		const QgsMapToPixel &	xform,
		QgsRenderContext &	context,
		const QPointF &	renderPoint
	)

static

Draws label metrics.

See also: drawLabelCandidateRect()

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

◆ engineSettings()

const QgsLabelingEngineSettings & QgsLabelingEngine::engineSettings ( ) const

inline

Gets associated labeling engine settings.

Definition at line 377 of file qgslabelingengine.h.

◆ mapSettings()

const QgsMapSettings & QgsLabelingEngine::mapSettings ( ) const

inline

Gets associated map settings.

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

◆ participatingLayers()

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

Returns a list of layers with providers in the engine.

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

◆ processProvider()

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

protected

Definition at line 240 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 225 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 289 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 230 of file qgslabelingengine.cpp.

◆ results()

QgsLabelingResults * QgsLabelingEngine::results ( ) const

inline

For internal use by the providers.

Definition at line 432 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 100 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 344 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 682 of file qgslabelingengine.cpp.

Member Data Documentation

◆ mEngineRules

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

protected

Definition at line 498 of file qgslabelingengine.h.

◆ mLabels

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

protected

Definition at line 506 of file qgslabelingengine.h.

◆ mMapSettings

QgsMapSettings QgsLabelingEngine::mMapSettings

protected

Associated map settings instance.

Definition at line 490 of file qgslabelingengine.h.

◆ mPal

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

protected

Definition at line 503 of file qgslabelingengine.h.

◆ mProblem

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

protected

Definition at line 504 of file qgslabelingengine.h.

◆ mProviders

QList<QgsAbstractLabelProvider *> QgsLabelingEngine::mProviders

protected

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

Definition at line 493 of file qgslabelingengine.h.

◆ mProvidersById

QHash<QString, QgsAbstractLabelProvider *> QgsLabelingEngine::mProvidersById

protected

Definition at line 494 of file qgslabelingengine.h.

◆ mResults

std::unique_ptr< QgsLabelingResults > QgsLabelingEngine::mResults

protected

Resulting labeling layout.

Definition at line 501 of file qgslabelingengine.h.

◆ mSubProviders

QList<QgsAbstractLabelProvider *> QgsLabelingEngine::mSubProviders

protected

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

Definition at line 495 of file qgslabelingengine.h.

◆ mUnlabeled

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

protected

Definition at line 505 of file qgslabelingengine.h.

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

/build/qgis-3.41.0+git20241225+af5edcb665c+99sid/src/core/labeling/qgslabelingengine.h
/build/qgis-3.41.0+git20241225+af5edcb665c+99sid/src/core/labeling/qgslabelingengine.cpp

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ QgsLabelingEngine() [1/2]

◆ ~QgsLabelingEngine()

◆ QgsLabelingEngine() [2/2]

Member Function Documentation

◆ addProvider()

◆ cleanup()

◆ drawLabelCandidateRect()

◆ drawLabelMetrics()

◆ drawLabels()

◆ engineSettings()

◆ mapSettings()

◆ operator=()

◆ participatingLayerIds()

◆ participatingLayers()

◆ prepare()

◆ processProvider()

◆ providerById()

◆ registerLabels()

◆ removeProvider()

◆ results()

◆ run()

◆ setMapSettings()

◆ solve()

◆ takeResults()

Member Data Documentation

◆ mEngineRules

◆ mLabels

◆ mMapSettings

◆ mPal

◆ mProblem

◆ mProviders

◆ mProvidersById

◆ mResults

◆ mSubProviders

◆ mUnlabeled