QGIS API Documentation  2.13.0-Master
Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Static Protected Member Functions | Protected Attributes | Friends | List of all members
QgsPalLabeling Class Reference

#include <qgspallabeling.h>

Inheritance diagram for QgsPalLabeling:
Inheritance graph
[legend]

Public Types

enum  DrawLabelType {
  LabelText = 0, LabelBuffer, LabelShape, LabelSVG,
  LabelShadow
}
 
enum  Search {
  Chain, Popmusic_Tabu, Popmusic_Chain, Popmusic_Tabu_Chain,
  Falp
}
 

Public Member Functions

 QgsPalLabeling ()
 
 ~QgsPalLabeling ()
 
virtual Q_DECL_DEPRECATED int addDiagramLayer (QgsVectorLayer *layer, const QgsDiagramLayerSettings *s) override
 adds a diagram layer to the labeling engine More...
 
Q_DECL_DEPRECATED const QList< QgsLabelCandidate > & candidates ()
 
virtual void clearActiveLayer (const QString &layerID) override
 clears data defined objects from PAL layer settings for a registered layer More...
 
virtual void clearActiveLayers () override
 clears all PAL layer settings for registered layers More...
 
void clearEngineSettings ()
 
virtual QgsPalLabelingclone () override
 called when passing engine among map renderers More...
 
virtual void drawLabeling (QgsRenderContext &context) override
 called when the map is drawn and labels should be placed More...
 
bool drawLabelRectOnly () const
 Returns whether the engine will only draw the outline rectangles of labels, not the label contents themselves. More...
 
virtual void exit () override
 called when we're done with rendering More...
 
virtual Q_DECL_DEPRECATED void init (QgsMapRenderer *mr) override
 called when we're going to start with rendering More...
 
virtual void init (const QgsMapSettings &mapSettings) override
 called when we're going to start with rendering More...
 
bool isDrawingOutlineLabels () const
 
bool isShowingAllLabels () const
 
bool isShowingCandidates () const
 
bool isShowingPartialsLabels () const
 
bool isShowingShadowRectangles () const
 
Q_DECL_DEPRECATED bool isStoredWithProject () const
 
virtual Q_DECL_DEPRECATED QList< QgsLabelPositionlabelsAtPosition (const QgsPoint &p) override
 return infos about labels at a given (map) position More...
 
virtual Q_DECL_DEPRECATED QList< QgsLabelPositionlabelsWithinRect (const QgsRectangle &r) override
 return infos about labels within a given (map) rectangle More...
 
Q_DECL_DEPRECATED QgsPalLayerSettingslayer (const QString &layerName) override
 
void loadEngineSettings ()
 load/save engine settings to project file More...
 
void numCandidatePositions (int &candPoint, int &candLine, int &candPolygon)
 
virtual int prepareDiagramLayer (QgsVectorLayer *layer, QStringList &attrNames, QgsRenderContext &ctx) override
 adds a diagram layer to the labeling engine More...
 
virtual int prepareLayer (QgsVectorLayer *layer, QStringList &attrNames, QgsRenderContext &ctx) override
 hook called when drawing layer before issuing select() More...
 
virtual void registerDiagramFeature (const QString &layerID, QgsFeature &feat, QgsRenderContext &context) override
 called for every diagram feature More...
 
virtual void registerFeature (const QString &layerID, QgsFeature &feat, QgsRenderContext &context, const QString &dxfLayer=QString::null) override
 Register a feature for labelling. More...
 
void saveEngineSettings ()
 
Search searchMethod () const
 
void setDrawingOutlineLabels (bool outline)
 
void setDrawLabelRectOnly (bool drawRect)
 Sets whether the engine should only draw the outline rectangles of labels, not the label contents themselves. More...
 
void setNumCandidatePositions (int candPoint, int candLine, int candPolygon)
 
void setSearchMethod (Search s)
 
void setShowingAllLabels (bool showing)
 
void setShowingCandidates (bool showing)
 
void setShowingPartialsLabels (bool showing)
 
void setShowingShadowRectangles (bool showing)
 
Q_DECL_DEPRECATED void setStoredWithProject (bool store)
 
QgsLabelingResultstakeResults ()
 Return pointer to recently computed results (in drawLabeling()) and pass the ownership of results to the caller. More...
 
virtual bool willUseLayer (QgsVectorLayer *layer) override
 called to find out whether the layer is used for labeling More...
 
- Public Member Functions inherited from QgsLabelingEngineInterface
virtual ~QgsLabelingEngineInterface ()
 

Static Public Member Functions

static void drawLabelBackground (QgsRenderContext &context, QgsLabelComponent component, const QgsPalLayerSettings &tmpLyr)
 
static void drawLabelBuffer (QgsRenderContext &context, const QgsLabelComponent &component, const QgsPalLayerSettings &tmpLyr)
 
static void drawLabelCandidateRect (pal::LabelPosition *lp, QPainter *painter, const QgsMapToPixel *xform, QList< QgsLabelCandidate > *candidates=nullptr)
 
static void drawLabelShadow (QgsRenderContext &context, const QgsLabelComponent &component, const QgsPalLayerSettings &tmpLyr)
 
static bool geometryRequiresPreparation (const QgsGeometry *geometry, QgsRenderContext &context, const QgsCoordinateTransform *ct, QgsGeometry *clipGeometry=nullptr)
 Checks whether a geometry requires preparation before registration with PAL. More...
 
static QgsGeometryprepareGeometry (const QgsGeometry *geometry, QgsRenderContext &context, const QgsCoordinateTransform *ct, QgsGeometry *clipGeometry=nullptr)
 Prepares a geometry for registration with PAL. More...
 
static QStringList splitToGraphemes (const QString &text)
 Splits a text string to a list of graphemes, which are the smallest allowable character divisions in the string. More...
 
static QStringList splitToLines (const QString &text, const QString &wrapCharacter)
 Splits a text string to a list of separate lines, using a specified wrap character. More...
 
static bool staticWillUseLayer (QgsVectorLayer *layer)
 called to find out whether the layer is used for labeling More...
 
static bool staticWillUseLayer (const QString &layerID)
 

Protected Member Functions

void deleteTemporaryData ()
 

Static Protected Member Functions

static bool checkMinimumSizeMM (const QgsRenderContext &context, const QgsGeometry *geom, double minSize)
 Checks whether a geometry exceeds the minimum required size for a geometry to be labeled. More...
 
static void dataDefinedDropShadow (QgsPalLayerSettings &tmpLyr, const QMap< QgsPalLayerSettings::DataDefinedProperties, QVariant > &ddValues)
 
static void dataDefinedShapeBackground (QgsPalLayerSettings &tmpLyr, const QMap< QgsPalLayerSettings::DataDefinedProperties, QVariant > &ddValues)
 
static void dataDefinedTextBuffer (QgsPalLayerSettings &tmpLyr, const QMap< QgsPalLayerSettings::DataDefinedProperties, QVariant > &ddValues)
 
static void dataDefinedTextFormatting (QgsPalLayerSettings &tmpLyr, const QMap< QgsPalLayerSettings::DataDefinedProperties, QVariant > &ddValues)
 
static void dataDefinedTextStyle (QgsPalLayerSettings &tmpLyr, const QMap< QgsPalLayerSettings::DataDefinedProperties, QVariant > &ddValues)
 

Protected Attributes

QList< QgsLabelCandidatemCandidates
 
QHash< QString, QgsVectorLayerDiagramProvider * > mDiagramProviders
 hashtable of diagram providers (key = layer ID) More...
 
QgsLabelingEngineV2mEngine
 New labeling engine to interface with PAL. More...
 
QgsPalLayerSettings mInvalidLayerSettings
 
QHash< QString, QgsVectorLayerLabelProvider * > mLabelProviders
 hashtable of label providers, being filled during labeling (key = layer ID) More...
 

Friends

class QgsPalLayerSettings
 
class QgsVectorLayerLabelProvider
 

Detailed Description

Definition at line 859 of file qgspallabeling.h.

Member Enumeration Documentation

Enumerator
LabelText 
LabelBuffer 
LabelShape 
LabelSVG 
LabelShadow 

Definition at line 862 of file qgspallabeling.h.

Enumerator
Chain 
Popmusic_Tabu 
Popmusic_Chain 
Popmusic_Tabu_Chain 
Falp 

Definition at line 880 of file qgspallabeling.h.

Constructor & Destructor Documentation

QgsPalLabeling::QgsPalLabeling ( )

Definition at line 3712 of file qgspallabeling.cpp.

QgsPalLabeling::~QgsPalLabeling ( )

Definition at line 3717 of file qgspallabeling.cpp.

Member Function Documentation

int QgsPalLabeling::addDiagramLayer ( QgsVectorLayer layer,
const QgsDiagramLayerSettings s 
)
overridevirtual

adds a diagram layer to the labeling engine

Deprecated:
since 2.12 - use prepareDiagramLayer()

Reimplemented from QgsLabelingEngineInterface.

Definition at line 3804 of file qgspallabeling.cpp.

Q_DECL_DEPRECATED const QList<QgsLabelCandidate>& QgsPalLabeling::candidates ( )
inline
Deprecated:
since 2.12

Definition at line 888 of file qgspallabeling.h.

bool QgsPalLabeling::checkMinimumSizeMM ( const QgsRenderContext context,
const QgsGeometry geom,
double  minSize 
)
staticprotected

Checks whether a geometry exceeds the minimum required size for a geometry to be labeled.

Parameters
contextrender context
geomgeometry
minSizeminimum size for geometry
Returns
true if geometry exceeds minimum size
Note
added in QGIS 2.9

Definition at line 3961 of file qgspallabeling.cpp.

void QgsPalLabeling::clearActiveLayer ( const QString layerID)
overridevirtual

clears data defined objects from PAL layer settings for a registered layer

Implements QgsLabelingEngineInterface.

Definition at line 3754 of file qgspallabeling.cpp.

void QgsPalLabeling::clearActiveLayers ( )
overridevirtual

clears all PAL layer settings for registered layers

Implements QgsLabelingEngineInterface.

Definition at line 3750 of file qgspallabeling.cpp.

void QgsPalLabeling::clearEngineSettings ( )

Definition at line 5018 of file qgspallabeling.cpp.

QgsPalLabeling * QgsPalLabeling::clone ( )
overridevirtual

called when passing engine among map renderers

Implements QgsLabelingEngineInterface.

Definition at line 5031 of file qgspallabeling.cpp.

void QgsPalLabeling::dataDefinedDropShadow ( QgsPalLayerSettings tmpLyr,
const QMap< QgsPalLayerSettings::DataDefinedProperties, QVariant > &  ddValues 
)
staticprotected

Definition at line 4275 of file qgspallabeling.cpp.

void QgsPalLabeling::dataDefinedShapeBackground ( QgsPalLayerSettings tmpLyr,
const QMap< QgsPalLayerSettings::DataDefinedProperties, QVariant > &  ddValues 
)
staticprotected

Definition at line 4164 of file qgspallabeling.cpp.

void QgsPalLabeling::dataDefinedTextBuffer ( QgsPalLayerSettings tmpLyr,
const QMap< QgsPalLayerSettings::DataDefinedProperties, QVariant > &  ddValues 
)
staticprotected

Definition at line 4107 of file qgspallabeling.cpp.

void QgsPalLabeling::dataDefinedTextFormatting ( QgsPalLayerSettings tmpLyr,
const QMap< QgsPalLayerSettings::DataDefinedProperties, QVariant > &  ddValues 
)
staticprotected

Definition at line 4054 of file qgspallabeling.cpp.

void QgsPalLabeling::dataDefinedTextStyle ( QgsPalLayerSettings tmpLyr,
const QMap< QgsPalLayerSettings::DataDefinedProperties, QVariant > &  ddValues 
)
staticprotected

Definition at line 4029 of file qgspallabeling.cpp.

void QgsPalLabeling::deleteTemporaryData ( )
protected

Definition at line 4348 of file qgspallabeling.cpp.

void QgsPalLabeling::drawLabelBackground ( QgsRenderContext context,
QgsLabelComponent  component,
const QgsPalLayerSettings tmpLyr 
)
static

Definition at line 4563 of file qgspallabeling.cpp.

void QgsPalLabeling::drawLabelBuffer ( QgsRenderContext context,
const QgsLabelComponent component,
const QgsPalLayerSettings tmpLyr 
)
static

Definition at line 4507 of file qgspallabeling.cpp.

void QgsPalLabeling::drawLabelCandidateRect ( pal::LabelPosition lp,
QPainter painter,
const QgsMapToPixel xform,
QList< QgsLabelCandidate > *  candidates = nullptr 
)
static
Note
not available in python bindings

Definition at line 4447 of file qgspallabeling.cpp.

void QgsPalLabeling::drawLabeling ( QgsRenderContext context)
overridevirtual

called when the map is drawn and labels should be placed

Implements QgsLabelingEngineInterface.

Definition at line 4343 of file qgspallabeling.cpp.

bool QgsPalLabeling::drawLabelRectOnly ( ) const

Returns whether the engine will only draw the outline rectangles of labels, not the label contents themselves.

Used for debugging and testing purposes.

See also
setDrawLabelRectOnly
Note
added in QGIS 2.12

Definition at line 4437 of file qgspallabeling.cpp.

void QgsPalLabeling::drawLabelShadow ( QgsRenderContext context,
const QgsLabelComponent component,
const QgsPalLayerSettings tmpLyr 
)
static

Definition at line 4860 of file qgspallabeling.cpp.

void QgsPalLabeling::exit ( )
overridevirtual

called when we're done with rendering

Implements QgsLabelingEngineInterface.

Definition at line 4017 of file qgspallabeling.cpp.

bool QgsPalLabeling::geometryRequiresPreparation ( const QgsGeometry geometry,
QgsRenderContext context,
const QgsCoordinateTransform ct,
QgsGeometry clipGeometry = nullptr 
)
static

Checks whether a geometry requires preparation before registration with PAL.

Parameters
geometrygeometry to prepare
contextrender context
ctcoordinate transform
clipGeometrygeometry to clip features to, if applicable
Returns
true if geometry requires preparation
Note
added in QGIS 2.9

Definition at line 3819 of file qgspallabeling.cpp.

void QgsPalLabeling::init ( QgsMapRenderer mr)
overridevirtual

called when we're going to start with rendering

Deprecated:
since 2.4 - use override with QgsMapSettings

Implements QgsLabelingEngineInterface.

Definition at line 4006 of file qgspallabeling.cpp.

void QgsPalLabeling::init ( const QgsMapSettings mapSettings)
overridevirtual

called when we're going to start with rendering

Implements QgsLabelingEngineInterface.

Definition at line 4012 of file qgspallabeling.cpp.

bool QgsPalLabeling::isDrawingOutlineLabels ( ) const
Note
added in 2.4

Definition at line 4427 of file qgspallabeling.cpp.

bool QgsPalLabeling::isShowingAllLabels ( ) const

Definition at line 4407 of file qgspallabeling.cpp.

bool QgsPalLabeling::isShowingCandidates ( ) const

Definition at line 4387 of file qgspallabeling.cpp.

bool QgsPalLabeling::isShowingPartialsLabels ( ) const

Definition at line 4417 of file qgspallabeling.cpp.

bool QgsPalLabeling::isShowingShadowRectangles ( ) const

Definition at line 4397 of file qgspallabeling.cpp.

Q_DECL_DEPRECATED bool QgsPalLabeling::isStoredWithProject ( ) const
inline
Deprecated:
since 2.4 - settings are always stored in project

Definition at line 995 of file qgspallabeling.h.

QList< QgsLabelPosition > QgsPalLabeling::labelsAtPosition ( const QgsPoint p)
overridevirtual

return infos about labels at a given (map) position

Deprecated:
since 2.4 - use takeResults() and methods of QgsLabelingResults

Implements QgsLabelingEngineInterface.

Definition at line 4352 of file qgspallabeling.cpp.

QList< QgsLabelPosition > QgsPalLabeling::labelsWithinRect ( const QgsRectangle r)
overridevirtual

return infos about labels within a given (map) rectangle

Deprecated:
since 2.4 - use takeResults() and methods of QgsLabelingResults

Implements QgsLabelingEngineInterface.

Definition at line 4357 of file qgspallabeling.cpp.

QgsPalLayerSettings & QgsPalLabeling::layer ( const QString layerName)
overridevirtual
Deprecated:
since 2.12 - if direct access to QgsPalLayerSettings is necessary, use QgsPalLayerSettings::fromLayer()

Implements QgsLabelingEngineInterface.

Definition at line 4023 of file qgspallabeling.cpp.

void QgsPalLabeling::loadEngineSettings ( )

load/save engine settings to project file

Definition at line 5008 of file qgspallabeling.cpp.

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

Definition at line 4367 of file qgspallabeling.cpp.

int QgsPalLabeling::prepareDiagramLayer ( QgsVectorLayer layer,
QStringList attrNames,
QgsRenderContext ctx 
)
overridevirtual

adds a diagram layer to the labeling engine

Note
added in QGIS 2.12

Reimplemented from QgsLabelingEngineInterface.

Definition at line 3788 of file qgspallabeling.cpp.

QgsGeometry * QgsPalLabeling::prepareGeometry ( const QgsGeometry geometry,
QgsRenderContext context,
const QgsCoordinateTransform ct,
QgsGeometry clipGeometry = nullptr 
)
static

Prepares a geometry for registration with PAL.

Handles reprojection, rotation, clipping, etc.

Parameters
geometrygeometry to prepare
contextrender context
ctcoordinate transform
clipGeometrygeometry to clip features to, if applicable
Returns
prepared geometry, the caller takes ownership
Note
added in QGIS 2.9

Definition at line 3879 of file qgspallabeling.cpp.

int QgsPalLabeling::prepareLayer ( QgsVectorLayer layer,
QStringList attrNames,
QgsRenderContext ctx 
)
overridevirtual

hook called when drawing layer before issuing select()

Implements QgsLabelingEngineInterface.

Definition at line 3760 of file qgspallabeling.cpp.

void QgsPalLabeling::registerDiagramFeature ( const QString layerID,
QgsFeature feat,
QgsRenderContext context 
)
overridevirtual

called for every diagram feature

Reimplemented from QgsLabelingEngineInterface.

Definition at line 3999 of file qgspallabeling.cpp.

void QgsPalLabeling::registerFeature ( const QString layerID,
QgsFeature feat,
QgsRenderContext context,
const QString dxfLayer = QString::null 
)
overridevirtual

Register a feature for labelling.

Parameters
layerIDstring identifying layer associated with label
featfeature to label
contextrender context. The QgsExpressionContext contained within the render context must have already had the feature and fields sets prior to calling this method.
dxfLayerdxfLayer name

Implements QgsLabelingEngineInterface.

Definition at line 3812 of file qgspallabeling.cpp.

void QgsPalLabeling::saveEngineSettings ( )

Definition at line 5013 of file qgspallabeling.cpp.

QgsPalLabeling::Search QgsPalLabeling::searchMethod ( ) const

Definition at line 4382 of file qgspallabeling.cpp.

void QgsPalLabeling::setDrawingOutlineLabels ( bool  outline)

Definition at line 4432 of file qgspallabeling.cpp.

void QgsPalLabeling::setDrawLabelRectOnly ( bool  drawRect)

Sets whether the engine should only draw the outline rectangles of labels, not the label contents themselves.

Used for debugging and testing purposes.

Parameters
drawRectset to true to enable rect drawing only
See also
drawLabelRectOnly
Note
added in QGIS 2.12

Definition at line 4442 of file qgspallabeling.cpp.

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

Definition at line 4372 of file qgspallabeling.cpp.

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

Definition at line 4377 of file qgspallabeling.cpp.

void QgsPalLabeling::setShowingAllLabels ( bool  showing)

Definition at line 4412 of file qgspallabeling.cpp.

void QgsPalLabeling::setShowingCandidates ( bool  showing)

Definition at line 4392 of file qgspallabeling.cpp.

void QgsPalLabeling::setShowingPartialsLabels ( bool  showing)

Definition at line 4422 of file qgspallabeling.cpp.

void QgsPalLabeling::setShowingShadowRectangles ( bool  showing)

Definition at line 4402 of file qgspallabeling.cpp.

Q_DECL_DEPRECATED void QgsPalLabeling::setStoredWithProject ( bool  store)
inline
Deprecated:
since 2.4 - settings are always stored in project

Definition at line 997 of file qgspallabeling.h.

QStringList QgsPalLabeling::splitToGraphemes ( const QString text)
static

Splits a text string to a list of graphemes, which are the smallest allowable character divisions in the string.

This accounts for scripts were individual characters are not allowed to be split apart (eg Arabic and Indic based scripts)

Parameters
textstring to split
Returns
list of graphemes
Note
added in QGIS 2.10

Definition at line 3865 of file qgspallabeling.cpp.

QStringList QgsPalLabeling::splitToLines ( const QString text,
const QString wrapCharacter 
)
static

Splits a text string to a list of separate lines, using a specified wrap character.

The text string will be split on either newline characters or the wrap character.

Parameters
texttext string to split
wrapCharacteradditional character to wrap on
Returns
list of text split to lines
Note
added in QGIS 2.9

Definition at line 3846 of file qgspallabeling.cpp.

bool QgsPalLabeling::staticWillUseLayer ( QgsVectorLayer layer)
static

called to find out whether the layer is used for labeling

Note
added in 2.4

Definition at line 3737 of file qgspallabeling.cpp.

bool QgsPalLabeling::staticWillUseLayer ( const QString layerID)
static

Definition at line 3728 of file qgspallabeling.cpp.

QgsLabelingResults * QgsPalLabeling::takeResults ( )

Return pointer to recently computed results (in drawLabeling()) and pass the ownership of results to the caller.

Note
added in 2.4

Definition at line 4362 of file qgspallabeling.cpp.

bool QgsPalLabeling::willUseLayer ( QgsVectorLayer layer)
overridevirtual

called to find out whether the layer is used for labeling

Implements QgsLabelingEngineInterface.

Definition at line 3723 of file qgspallabeling.cpp.

Friends And Related Function Documentation

friend class QgsPalLayerSettings
friend

Definition at line 1083 of file qgspallabeling.h.

friend class QgsVectorLayerLabelProvider
friend

Definition at line 1058 of file qgspallabeling.h.

Member Data Documentation

QList<QgsLabelCandidate> QgsPalLabeling::mCandidates
protected

Definition at line 1081 of file qgspallabeling.h.

QHash<QString, QgsVectorLayerDiagramProvider*> QgsPalLabeling::mDiagramProviders
protected

hashtable of diagram providers (key = layer ID)

Definition at line 1074 of file qgspallabeling.h.

QgsLabelingEngineV2* QgsPalLabeling::mEngine
protected

New labeling engine to interface with PAL.

Definition at line 1078 of file qgspallabeling.h.

QgsPalLayerSettings QgsPalLabeling::mInvalidLayerSettings
protected

Definition at line 1075 of file qgspallabeling.h.

QHash<QString, QgsVectorLayerLabelProvider*> QgsPalLabeling::mLabelProviders
protected

hashtable of label providers, being filled during labeling (key = layer ID)

Definition at line 1072 of file qgspallabeling.h.


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