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

#include <qgslabelingenginev2.h>

Public Types
enum	Flag { UseAllLabels = 1 << 1, UsePartialCandidates = 1 << 2, RenderOutlineLabels = 1 << 3, DrawLabelRectOnly = 1 << 4, DrawCandidates = 1 << 5, DrawShadowRects = 1 << 6 }

Public Member Functions
	QgsLabelingEngineV2 ()
	Construct the labeling engine with default settings. More...

	~QgsLabelingEngineV2 ()
	Clean up everything (especially the registered providers) More...

void	addProvider (QgsAbstractLabelProvider *provider)
	Add provider of label features. Takes ownership of the provider. More...

Flags	flags () const
	Get flags of the labeling engine. More...

const QgsMapSettings &	mapSettings () const
	Get associated map settings. More...

void	numCandidatePositions (int &candPoint, int &candLine, int &candPolygon)
	Get number of candidate positions that will be generated for each label feature (default to 8) More...

void	readSettingsFromProject ()
	Read configuration of the labeling engine from the current project file. More...

void	removeProvider (QgsAbstractLabelProvider *provider)
	Remove provider if the provider's initialization failed. Provider instance is deleted. More...

QgsLabelingResults *	results () const
	For internal use by the providers. More...

void	run (QgsRenderContext &context)
	compute the labeling with given map settings and providers More...

QgsPalLabeling::Search	searchMethod () const
	Which search method to use for removal collisions between labels. More...

void	setFlag (Flag f, bool enabled=true)
	Set whether a particual flag is enabled. More...

void	setFlags (const Flags &flags)
	Set flags of the labeling engine. More...

void	setMapSettings (const QgsMapSettings &mapSettings)
	Associate map settings instance. More...

void	setNumCandidatePositions (int candPoint, int candLine, int candPolygon)
	Set number of candidate positions that will be generated for each label feature. More...

void	setSearchMethod (QgsPalLabeling::Search s)
	Set which search method to use for removal collisions between labels. More...

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

bool	testFlag (Flag f) const
	Test whether a particular flag is enabled. More...

void	writeSettingsToProject ()
	Write configuration of the labeling engine to the current project file. More...

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

Protected Attributes
int	mCandLine

int	mCandPoint
	Number of candedate positions that will be generated for features. More...

int	mCandPolygon

Flags	mFlags
	Flags. More...

QgsMapSettings	mMapSettings
	Associated map settings instance. More...

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

QgsLabelingResults *	mResults
	Resulting labeling layout. More...

QgsPalLabeling::Search	mSearchMethod
	search method to use for removal collisions between labels More...

QList< QgsAbstractLabelProvider * >	mSubProviders

Detailed Description

The QgsLabelingEngineV2 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:

QgsLabelingEngineV2 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).; added in QGIS 2.12; not available in Python bindings

Definition at line 162 of file qgslabelingenginev2.h.

Member Enumeration Documentation

◆ Flag

enum QgsLabelingEngineV2::Flag

Enumerator
UseAllLabels	Whether to draw all labels even if there would be collisions.
UsePartialCandidates	Whether to use also label candidates that are partially outside of the map view.
RenderOutlineLabels	Whether to render labels as text or outlines.
DrawLabelRectOnly	Whether to only draw the label rect and not the actual label text (used for unit tests)
DrawCandidates	Whether to draw rectangles of generated candidates (good for debugging)
DrawShadowRects	Whether to show debugging rectangles for drop shadows.

Definition at line 170 of file qgslabelingenginev2.h.

Constructor & Destructor Documentation

◆ QgsLabelingEngineV2()

QgsLabelingEngineV2::QgsLabelingEngineV2 ( )

Construct the labeling engine with default settings.

Definition at line 71 of file qgslabelingenginev2.cpp.

◆ ~QgsLabelingEngineV2()

QgsLabelingEngineV2::~QgsLabelingEngineV2 ( )

Clean up everything (especially the registered providers)

Definition at line 82 of file qgslabelingenginev2.cpp.

Member Function Documentation

◆ addProvider()

void QgsLabelingEngineV2::addProvider ( QgsAbstractLabelProvider * provider )

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

Definition at line 89 of file qgslabelingenginev2.cpp.

◆ flags()

Flags QgsLabelingEngineV2::flags ( ) const

inline

Get flags of the labeling engine.

Definition at line 204 of file qgslabelingenginev2.h.

◆ mapSettings()

const QgsMapSettings& QgsLabelingEngineV2::mapSettings ( ) const

inline

Get associated map settings.

Definition at line 184 of file qgslabelingenginev2.h.

◆ numCandidatePositions()

void QgsLabelingEngineV2::numCandidatePositions	(	int &	candPoint,
		int &	candLine,
		int &	candPolygon
	)

inline

Get number of candidate positions that will be generated for each label feature (default to 8)

Definition at line 211 of file qgslabelingenginev2.h.

◆ processProvider()

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

protected

Definition at line 104 of file qgslabelingenginev2.cpp.

◆ readSettingsFromProject()

void QgsLabelingEngineV2::readSettingsFromProject ( )

Read configuration of the labeling engine from the current project file.

Definition at line 341 of file qgslabelingenginev2.cpp.

◆ removeProvider()

void QgsLabelingEngineV2::removeProvider ( QgsAbstractLabelProvider * provider )

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

Definition at line 95 of file qgslabelingenginev2.cpp.

◆ results()

QgsLabelingResults* QgsLabelingEngineV2::results ( ) const

inline

For internal use by the providers.

Definition at line 199 of file qgslabelingenginev2.h.

◆ run()

void QgsLabelingEngineV2::run ( QgsRenderContext & context )

compute the labeling with given map settings and providers

Definition at line 177 of file qgslabelingenginev2.cpp.

◆ searchMethod()

QgsPalLabeling::Search QgsLabelingEngineV2::searchMethod ( ) const

inline

Which search method to use for removal collisions between labels.

Definition at line 218 of file qgslabelingenginev2.h.

◆ setFlag()

void QgsLabelingEngineV2::setFlag	(	Flag	f,
		bool	enabled = `true`
	)

inline

Set whether a particual flag is enabled.

Definition at line 208 of file qgslabelingenginev2.h.

◆ setFlags()

void QgsLabelingEngineV2::setFlags ( const Flags & flags )

inline

Set flags of the labeling engine.

Definition at line 202 of file qgslabelingenginev2.h.

◆ setMapSettings()

void QgsLabelingEngineV2::setMapSettings ( const QgsMapSettings & mapSettings )

inline

Associate map settings instance.

Definition at line 182 of file qgslabelingenginev2.h.

◆ setNumCandidatePositions()

void QgsLabelingEngineV2::setNumCandidatePositions	(	int	candPoint,
		int	candLine,
		int	candPolygon
	)

inline

Set number of candidate positions that will be generated for each label feature.

Definition at line 213 of file qgslabelingenginev2.h.

◆ setSearchMethod()

void QgsLabelingEngineV2::setSearchMethod ( QgsPalLabeling::Search s )

inline

Set which search method to use for removal collisions between labels.

Definition at line 216 of file qgslabelingenginev2.h.

◆ takeResults()

QgsLabelingResults * QgsLabelingEngineV2::takeResults ( )

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

Definition at line 333 of file qgslabelingenginev2.cpp.

◆ testFlag()

bool QgsLabelingEngineV2::testFlag ( Flag f ) const

inline

Test whether a particular flag is enabled.

Definition at line 206 of file qgslabelingenginev2.h.

◆ writeSettingsToProject()

void QgsLabelingEngineV2::writeSettingsToProject ( )

Write configuration of the labeling engine to the current project file.

Definition at line 359 of file qgslabelingenginev2.cpp.

Member Data Documentation

◆ mCandLine

int QgsLabelingEngineV2::mCandLine

protected

Definition at line 239 of file qgslabelingenginev2.h.

◆ mCandPoint

int QgsLabelingEngineV2::mCandPoint

protected

Number of candedate positions that will be generated for features.

Definition at line 239 of file qgslabelingenginev2.h.

◆ mCandPolygon

int QgsLabelingEngineV2::mCandPolygon

protected

Definition at line 239 of file qgslabelingenginev2.h.

◆ mFlags

Flags QgsLabelingEngineV2::mFlags

protected

Flags.

Definition at line 235 of file qgslabelingenginev2.h.

◆ mMapSettings

QgsMapSettings QgsLabelingEngineV2::mMapSettings

protected

Associated map settings instance.

Definition at line 230 of file qgslabelingenginev2.h.

◆ mProviders

QList<QgsAbstractLabelProvider*> QgsLabelingEngineV2::mProviders

protected

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

Definition at line 232 of file qgslabelingenginev2.h.

◆ mResults

QgsLabelingResults* QgsLabelingEngineV2::mResults

protected

Resulting labeling layout.

Definition at line 242 of file qgslabelingenginev2.h.

◆ mSearchMethod

QgsPalLabeling::Search QgsLabelingEngineV2::mSearchMethod

protected

search method to use for removal collisions between labels

Definition at line 237 of file qgslabelingenginev2.h.

◆ mSubProviders

QList<QgsAbstractLabelProvider*> QgsLabelingEngineV2::mSubProviders

protected

Definition at line 233 of file qgslabelingenginev2.h.

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

/tmp/buildd/qgis-2.18.21+99unstable/src/core/qgslabelingenginev2.h
/tmp/buildd/qgis-2.18.21+99unstable/src/core/qgslabelingenginev2.cpp

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ Flag

Constructor & Destructor Documentation

◆ QgsLabelingEngineV2()

◆ ~QgsLabelingEngineV2()

Member Function Documentation

◆ addProvider()

◆ flags()

◆ mapSettings()

◆ numCandidatePositions()

◆ processProvider()

◆ readSettingsFromProject()

◆ removeProvider()

◆ results()

◆ run()

◆ searchMethod()

◆ setFlag()

◆ setFlags()

◆ setMapSettings()

◆ setNumCandidatePositions()

◆ setSearchMethod()

◆ takeResults()

◆ testFlag()

◆ writeSettingsToProject()

Member Data Documentation

◆ mCandLine

◆ mCandPoint

◆ mCandPolygon

◆ mFlags

◆ mMapSettings

◆ mProviders

◆ mResults

◆ mSearchMethod

◆ mSubProviders