QGIS API Documentation  3.14.0-Pi (9f7028fd23)
qgslabelingengine.h
Go to the documentation of this file.
1 /***************************************************************************
2  qgslabelingengine.h
3  --------------------------------------
4  Date : September 2015
5  Copyright : (C) 2015 by Martin Dobias
6  Email : wonder dot sk at gmail dot com
7  ***************************************************************************
8  * *
9  * This program is free software; you can redistribute it and/or modify *
10  * it under the terms of the GNU General Public License as published by *
11  * the Free Software Foundation; either version 2 of the License, or *
12  * (at your option) any later version. *
13  * *
14  ***************************************************************************/
15 
16 #ifndef QGSLABELINGENGINE_H
17 #define QGSLABELINGENGINE_H
18 
19 #define SIP_NO_FILE
20 
21 #include "qgis_core.h"
22 #include "qgsmapsettings.h"
23 
24 #include "qgspallabeling.h"
26 #include "qgslabeling.h"
27 
28 class QgsLabelingEngine;
29 
30 namespace pal
31 {
32  class Problem;
33 }
34 
47 class CORE_EXPORT QgsAbstractLabelProvider
48 {
49 
50  public:
52  QgsAbstractLabelProvider( QgsMapLayer *layer, const QString &providerId = QString() );
53 
54  virtual ~QgsAbstractLabelProvider() = default;
55 
57  void setEngine( const QgsLabelingEngine *engine ) { mEngine = engine; }
58 
59  enum Flag
60  {
61  DrawLabels = 1 << 1,
62  DrawAllLabels = 1 << 2,
63  MergeConnectedLines = 1 << 3,
64  CentroidMustBeInside = 1 << 4,
65  };
66  Q_DECLARE_FLAGS( Flags, Flag )
67 
68 
69  virtual QList<QgsLabelFeature *> labelFeatures( QgsRenderContext &context ) = 0;
70 
77  virtual void drawLabel( QgsRenderContext &context, pal::LabelPosition *label ) const = 0;
78 
90  virtual void drawUnplacedLabel( QgsRenderContext &context, pal::LabelPosition *label ) const;
91 
104  virtual void drawLabelBackground( QgsRenderContext &context, pal::LabelPosition *label ) const;
105 
111  virtual void startRender( QgsRenderContext &context );
112 
118  virtual void stopRender( QgsRenderContext &context );
119 
121  virtual QList<QgsAbstractLabelProvider *> subProviders() { return QList<QgsAbstractLabelProvider *>(); }
122 
124  QString name() const { return mName; }
125 
127  QString layerId() const { return mLayerId; }
128 
130  QgsMapLayer *layer() const { return mLayer.data(); }
131 
137  QString providerId() const { return mProviderId; }
138 
140  Flags flags() const { return mFlags; }
141 
143  QgsPalLayerSettings::Placement placement() const { return mPlacement; }
144 
146  double priority() const { return mPriority; }
147 
149  QgsLabelObstacleSettings::ObstacleType obstacleType() const { return mObstacleType; }
150 
152  QgsPalLayerSettings::UpsideDownLabels upsidedownLabels() const { return mUpsidedownLabels; }
153 
154  protected:
156  const QgsLabelingEngine *mEngine = nullptr;
157 
159  QString mName;
161  QString mLayerId;
165  QString mProviderId;
167  Flags mFlags;
171  double mPriority;
176 };
177 
178 Q_DECLARE_OPERATORS_FOR_FLAGS( QgsAbstractLabelProvider::Flags )
179 
180 
181 
214 class CORE_EXPORT QgsLabelingEngine
215 {
216  public:
220  virtual ~QgsLabelingEngine();
221 
223  QgsLabelingEngine( const QgsLabelingEngine &rh ) = delete;
225  QgsLabelingEngine &operator=( const QgsLabelingEngine &rh ) = delete;
226 
228  void setMapSettings( const QgsMapSettings &mapSettings );
230  const QgsMapSettings &mapSettings() const { return mMapSettings; }
231 
233  const QgsLabelingEngineSettings &engineSettings() const { return mMapSettings.labelingEngineSettings(); }
234 
239  QList< QgsMapLayer * > participatingLayers() const;
240 
245  QStringList participatingLayerIds() const;
246 
248  void addProvider( QgsAbstractLabelProvider *provider );
249 
251  void removeProvider( QgsAbstractLabelProvider *provider );
252 
260  virtual void run( QgsRenderContext &context ) = 0;
261 
263  QgsLabelingResults *takeResults();
264 
266  QgsLabelingResults *results() const { return mResults.get(); }
267 
268  protected:
269  void processProvider( QgsAbstractLabelProvider *provider, QgsRenderContext &context, pal::Pal &p );
270 
271  protected:
272 
280  void registerLabels( QgsRenderContext &context );
281 
290  void solve( QgsRenderContext &context );
291 
302  void drawLabels( QgsRenderContext &context, const QString &layerId = QString() );
303 
308  void cleanup();
309 
312 
314  QList<QgsAbstractLabelProvider *> mProviders;
315  QList<QgsAbstractLabelProvider *> mSubProviders;
316 
318  std::unique_ptr< QgsLabelingResults > mResults;
319 
320  std::unique_ptr< pal::Pal > mPal;
321  std::unique_ptr< pal::Problem > mProblem;
322  QList<pal::LabelPosition *> mUnlabeled;
323  QList<pal::LabelPosition *> mLabels;
324 
325 };
326 
336 class CORE_EXPORT QgsDefaultLabelingEngine : public QgsLabelingEngine
337 {
338  public:
341 
346 
347  void run( QgsRenderContext &context ) override;
348 
349 };
350 
363 {
364  public:
367 
372 
373  void run( QgsRenderContext &context ) override;
374 
379  void renderLabelsForLayer( QgsRenderContext &context, const QString &layerId );
380 
385  void finalize();
386 };
387 
388 
397 class CORE_EXPORT QgsLabelingUtils
398 {
399  public:
400 
407  static QString encodePredefinedPositionOrder( const QVector< QgsPalLayerSettings::PredefinedPointPosition > &positions );
408 
415  static QVector< QgsPalLayerSettings::PredefinedPointPosition > decodePredefinedPositionOrder( const QString &positionString );
416 
421  static QString encodeLinePlacementFlags( QgsLabeling::LinePlacementFlags flags );
422 
427  static QgsLabeling::LinePlacementFlags decodeLinePlacementFlags( const QString &string );
428 
429 };
430 
431 #endif // QGSLABELINGENGINE_H
QgsLabelingUtils
Contains helper utilities for working with QGIS' labeling engine.
Definition: qgslabelingengine.h:397
QgsAbstractLabelProvider::mFlags
Flags mFlags
Flags altering drawing and registration of features.
Definition: qgslabelingengine.h:167
qgspallabeling.h
QgsAbstractLabelProvider::layerId
QString layerId() const
Returns ID of associated layer, or empty string if no layer is associated with the provider.
Definition: qgslabelingengine.h:127
QgsLabelingEngine::mPal
std::unique_ptr< pal::Pal > mPal
Definition: qgslabelingengine.h:320
QgsAbstractLabelProvider::upsidedownLabels
QgsPalLayerSettings::UpsideDownLabels upsidedownLabels() const
How to handle labels that would be upside down.
Definition: qgslabelingengine.h:152
qgslabelingenginesettings.h
QgsLabelingEngine::mProviders
QList< QgsAbstractLabelProvider * > mProviders
List of providers (the are owned by the labeling engine)
Definition: qgslabelingengine.h:314
QgsStagedRenderLabelingEngine
A QgsLabelingEngine implementation, which only calculates the labeling solution during its run() meth...
Definition: qgslabelingengine.h:362
QgsAbstractLabelProvider::mName
QString mName
Name of the layer.
Definition: qgslabelingengine.h:159
pal::LabelPosition
LabelPosition is a candidate feature label position.
Definition: labelposition.h:55
QgsLabelingResults
Definition: qgspallabeling.h:1224
QgsAbstractLabelProvider::obstacleType
QgsLabelObstacleSettings::ObstacleType obstacleType() const
How the feature geometries will work as obstacles.
Definition: qgslabelingengine.h:149
QgsLabelingEngine::mUnlabeled
QList< pal::LabelPosition * > mUnlabeled
Definition: qgslabelingengine.h:322
QgsAbstractLabelProvider::Flag
Flag
Definition: qgslabelingengine.h:59
QgsRenderContext
Definition: qgsrendercontext.h:57
QgsDefaultLabelingEngine
Default QgsLabelingEngine implementation, which completes the whole labeling operation (including lab...
Definition: qgslabelingengine.h:336
QgsLabelingEngine::mSubProviders
QList< QgsAbstractLabelProvider * > mSubProviders
Definition: qgslabelingengine.h:315
qgsmapsettings.h
QgsAbstractLabelProvider::priority
double priority() const
Default priority of labels (may be overridden by individual labels)
Definition: qgslabelingengine.h:146
QgsAbstractLabelProvider::mProviderId
QString mProviderId
Associated provider ID (one layer may have multiple providers, e.g. in rule-based labeling)
Definition: qgslabelingengine.h:165
pal
Definition: qgsdiagramrenderer.h:49
QgsAbstractLabelProvider::placement
QgsPalLayerSettings::Placement placement() const
What placement strategy to use for the labels.
Definition: qgslabelingengine.h:143
QgsLabelingEngine::engineSettings
const QgsLabelingEngineSettings & engineSettings() const
Gets associated labeling engine settings.
Definition: qgslabelingengine.h:233
QgsAbstractLabelProvider::mUpsidedownLabels
QgsPalLayerSettings::UpsideDownLabels mUpsidedownLabels
How to handle labels that would be upside down.
Definition: qgslabelingengine.h:175
QgsPalLayerSettings::Placement
Placement
Placement modes which determine how label candidates are generated for a feature.
Definition: qgspallabeling.h:220
QgsAbstractLabelProvider::mLayerId
QString mLayerId
Associated layer's ID, if applicable.
Definition: qgslabelingengine.h:161
QgsAbstractLabelProvider
The QgsAbstractLabelProvider class is an interface class. Implementations return list of labels and t...
Definition: qgslabelingengine.h:47
QgsLabelingEngineSettings
Definition: qgslabelingenginesettings.h:30
QgsAbstractLabelProvider::setEngine
void setEngine(const QgsLabelingEngine *engine)
Associate provider with a labeling engine (should be only called internally from QgsLabelingEngine)
Definition: qgslabelingengine.h:57
QgsAbstractLabelProvider::name
QString name() const
Name of the layer (for statistics, debugging etc.) - does not need to be unique.
Definition: qgslabelingengine.h:124
QgsLabelingEngine::run
virtual void run(QgsRenderContext &context)=0
Runs the labeling job.
QgsAbstractLabelProvider::subProviders
virtual QList< QgsAbstractLabelProvider * > subProviders()
Returns list of child providers - useful if the provider needs to put labels into more layers with di...
Definition: qgslabelingengine.h:121
QgsLabelingEngine::operator=
QgsLabelingEngine & operator=(const QgsLabelingEngine &rh)=delete
QgsLabelingEngine cannot be copied.
QgsWeakMapLayerPointer
QPointer< QgsMapLayer > QgsWeakMapLayerPointer
Weak pointer for QgsMapLayer.
Definition: qgsmaplayer.h:1670
QgsPalLayerSettings::UpsideDownLabels
UpsideDownLabels
Definition: qgspallabeling.h:295
QgsAbstractLabelProvider::providerId
QString providerId() const
Returns provider ID - useful in case there is more than one label provider within a layer (e....
Definition: qgslabelingengine.h:137
QgsAbstractLabelProvider::mLayer
QgsWeakMapLayerPointer mLayer
Weak pointer to source layer.
Definition: qgslabelingengine.h:163
QgsLabelingEngine::mProblem
std::unique_ptr< pal::Problem > mProblem
Definition: qgslabelingengine.h:321
QgsLabelingEngine
The QgsLabelingEngine class provides map labeling functionality. The input for the engine is a list o...
Definition: qgslabelingengine.h:214
qgslabeling.h
QgsLabelingEngine::mapSettings
const QgsMapSettings & mapSettings() const
Gets associated map settings.
Definition: qgslabelingengine.h:230
QgsLabelingEngine::results
QgsLabelingResults * results() const
For internal use by the providers.
Definition: qgslabelingengine.h:266
QgsMapLayer
Definition: qgsmaplayer.h:81
QgsLabelObstacleSettings::PolygonBoundary
@ PolygonBoundary
Definition: qgslabelobstaclesettings.h:46
pal::Pal
Main Pal labeling class.
Definition: pal.h:79
QgsLabelingEngine::mResults
std::unique_ptr< QgsLabelingResults > mResults
Resulting labeling layout.
Definition: qgslabelingengine.h:318
QgsLabelingEngine::mMapSettings
QgsMapSettings mMapSettings
Associated map settings instance.
Definition: qgslabelingengine.h:311
QgsAbstractLabelProvider::layer
QgsMapLayer * layer() const
Returns the associated layer, or nullptr if no layer is associated with the provider.
Definition: qgslabelingengine.h:130
QgsAbstractLabelProvider::flags
Flags flags() const
Flags associated with the provider.
Definition: qgslabelingengine.h:140
QgsLabelObstacleSettings::ObstacleType
ObstacleType
Valid obstacle types, which affect how features within the layer will act as obstacles for labels.
Definition: qgslabelobstaclesettings.h:42
QgsMapSettings
Definition: qgsmapsettings.h:86
QgsAbstractLabelProvider::mPlacement
QgsPalLayerSettings::Placement mPlacement
Placement strategy.
Definition: qgslabelingengine.h:169
QgsAbstractLabelProvider::mPriority
double mPriority
Default priority of labels.
Definition: qgslabelingengine.h:171
QgsLabelingEngine::mLabels
QList< pal::LabelPosition * > mLabels
Definition: qgslabelingengine.h:323