QGIS API Documentation  2.18.21-Las Palmas (9fba24a)
Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
QgsLabelingEngineV2 Class Reference

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 QgsMapSettingsmapSettings () 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...
 
QgsLabelingResultsresults () 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...
 
QgsLabelingResultstakeResults ()
 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...
 
QgsLabelingResultsmResults
 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:

// 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

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: