QGIS API Documentation  3.9.0-Master (224899f119)
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 "pal.h"
27 
28 class QgsLabelingEngine;
29 
30 
43 class CORE_EXPORT QgsAbstractLabelProvider
44 {
45 
46  public:
48  QgsAbstractLabelProvider( QgsMapLayer *layer, const QString &providerId = QString() );
49 
50  virtual ~QgsAbstractLabelProvider() = default;
51 
53  void setEngine( const QgsLabelingEngine *engine ) { mEngine = engine; }
54 
55  enum Flag
56  {
57  DrawLabels = 1 << 1,
58  DrawAllLabels = 1 << 2,
59  MergeConnectedLines = 1 << 3,
60  CentroidMustBeInside = 1 << 4,
61  };
62  Q_DECLARE_FLAGS( Flags, Flag )
63 
64 
65  virtual QList<QgsLabelFeature *> labelFeatures( QgsRenderContext &context ) = 0;
66 
73  virtual void drawLabel( QgsRenderContext &context, pal::LabelPosition *label ) const = 0;
74 
86  virtual void drawUnplacedLabel( QgsRenderContext &context, pal::LabelPosition *label ) const;
87 
100  virtual void drawLabelBackground( QgsRenderContext &context, pal::LabelPosition *label ) const;
101 
107  virtual void startRender( QgsRenderContext &context );
108 
114  virtual void stopRender( QgsRenderContext &context );
115 
117  virtual QList<QgsAbstractLabelProvider *> subProviders() { return QList<QgsAbstractLabelProvider *>(); }
118 
120  QString name() const { return mName; }
121 
123  QString layerId() const { return mLayerId; }
124 
126  QgsMapLayer *layer() const { return mLayer.data(); }
127 
133  QString providerId() const { return mProviderId; }
134 
136  Flags flags() const { return mFlags; }
137 
139  QgsPalLayerSettings::Placement placement() const { return mPlacement; }
140 
142  double priority() const { return mPriority; }
143 
145  QgsPalLayerSettings::ObstacleType obstacleType() const { return mObstacleType; }
146 
148  QgsPalLayerSettings::UpsideDownLabels upsidedownLabels() const { return mUpsidedownLabels; }
149 
150  protected:
152  const QgsLabelingEngine *mEngine = nullptr;
153 
155  QString mName;
157  QString mLayerId;
161  QString mProviderId;
163  Flags mFlags;
167  double mPriority;
172 };
173 
174 Q_DECLARE_OPERATORS_FOR_FLAGS( QgsAbstractLabelProvider::Flags )
175 
176 
177 
210 class CORE_EXPORT QgsLabelingEngine
211 {
212  public:
214  QgsLabelingEngine();
216  virtual ~QgsLabelingEngine();
217 
219  QgsLabelingEngine( const QgsLabelingEngine &rh ) = delete;
221  QgsLabelingEngine &operator=( const QgsLabelingEngine &rh ) = delete;
222 
224  void setMapSettings( const QgsMapSettings &mapSettings );
226  const QgsMapSettings &mapSettings() const { return mMapSettings; }
227 
229  const QgsLabelingEngineSettings &engineSettings() const { return mMapSettings.labelingEngineSettings(); }
230 
235  QList< QgsMapLayer * > participatingLayers() const;
236 
241  QStringList participatingLayerIds() const;
242 
244  void addProvider( QgsAbstractLabelProvider *provider );
245 
247  void removeProvider( QgsAbstractLabelProvider *provider );
248 
256  virtual void run( QgsRenderContext &context ) = 0;
257 
259  QgsLabelingResults *takeResults();
260 
262  QgsLabelingResults *results() const { return mResults.get(); }
263 
264  protected:
265  void processProvider( QgsAbstractLabelProvider *provider, QgsRenderContext &context, pal::Pal &p );
266 
267  protected:
268 
276  void registerLabels( QgsRenderContext &context );
277 
286  void solve( QgsRenderContext &context );
287 
298  void drawLabels( QgsRenderContext &context, const QString &layerId = QString() );
299 
304  void cleanup();
305 
308 
310  QList<QgsAbstractLabelProvider *> mProviders;
311  QList<QgsAbstractLabelProvider *> mSubProviders;
312 
314  std::unique_ptr< QgsLabelingResults > mResults;
315 
316  std::unique_ptr< pal::Pal > mPal;
317  std::unique_ptr< pal::Problem > mProblem;
318  QList<pal::LabelPosition *> mUnlabeled;
319  QList<pal::LabelPosition *> mLabels;
320 
321 };
322 
332 class CORE_EXPORT QgsDefaultLabelingEngine : public QgsLabelingEngine
333 {
334  public:
337 
342 
343  void run( QgsRenderContext &context ) override;
344 
345 };
346 
359 {
360  public:
363 
368 
369  void run( QgsRenderContext &context ) override;
370 
375  void renderLabelsForLayer( QgsRenderContext &context, const QString &layerId );
376 
381  void finalize();
382 };
383 
384 
393 class CORE_EXPORT QgsLabelingUtils
394 {
395  public:
396 
403  static QString encodePredefinedPositionOrder( const QVector< QgsPalLayerSettings::PredefinedPointPosition > &positions );
404 
411  static QVector< QgsPalLayerSettings::PredefinedPointPosition > decodePredefinedPositionOrder( const QString &positionString );
412 
417  static QString encodeLinePlacementFlags( pal::LineArrangementFlags flags );
418 
423  static pal::LineArrangementFlags decodeLinePlacementFlags( const QString &string );
424 
425 };
426 
427 #endif // QGSLABELINGENGINE_H
QList< pal::LabelPosition * > mLabels
std::unique_ptr< pal::Pal > mPal
Base class for all map layer types.
Definition: qgsmaplayer.h:79
QgsWeakMapLayerPointer mLayer
Weak pointer to source layer.
QgsPalLayerSettings::Placement mPlacement
Placement strategy.
QList< QgsAbstractLabelProvider * > mProviders
List of providers (the are owned by the labeling engine)
double mPriority
Default priority of labels.
Contains helper utilities for working with QGIS&#39; labeling engine.
QgsPalLayerSettings::ObstacleType obstacleType() const
How the feature geometries will work as obstacles.
QList< QgsAbstractLabelProvider * > mSubProviders
Main Pal labeling class.
Definition: pal.h:87
Default QgsLabelingEngine implementation, which completes the whole labeling operation (including lab...
QList< pal::LabelPosition * > mUnlabeled
QPointer< QgsMapLayer > QgsWeakMapLayerPointer
Weak pointer for QgsMapLayer.
Definition: qgsmaplayer.h:1617
The QgsMapSettings class contains configuration for rendering of the map.
QgsMapLayer * layer() const
Returns the associated layer, or nullptr if no layer is associated with the provider.
const QgsLabelingEngineSettings & engineSettings() const
Gets associated labeling engine settings.
virtual void run(QgsRenderContext &context)=0
Runs the labeling job.
Flags mFlags
Flags altering drawing and registration of features.
QgsLabelingEngine & operator=(const QgsLabelingEngine &rh)=delete
QgsLabelingEngine cannot be copied.
QgsPalLayerSettings::Placement placement() const
What placement strategy to use for the labels.
The QgsAbstractLabelProvider class is an interface class.
QString layerId() const
Returns ID of associated layer, or empty string if no layer is associated with the provider...
QgsPalLayerSettings::UpsideDownLabels upsidedownLabels() const
How to handle labels that would be upside down.
Flags flags() const
Flags associated with the provider.
Placement
Placement modes which determine how label candidates are generated for a feature. ...
The QgsLabelingEngine class provides map labeling functionality.
virtual QList< QgsAbstractLabelProvider * > subProviders()
Returns list of child providers - useful if the provider needs to put labels into more layers with di...
Contains information about the context of a rendering operation.
std::unique_ptr< pal::Problem > mProblem
QString name() const
Name of the layer (for statistics, debugging etc.) - does not need to be unique.
std::unique_ptr< QgsLabelingResults > mResults
Resulting labeling layout.
QString mName
Name of the layer.
QgsMapSettings mMapSettings
Associated map settings instance.
Stores global configuration for labeling engine.
const QgsMapSettings & mapSettings() const
Gets associated map settings.
double priority() const
Default priority of labels (may be overridden by individual labels)
QgsLabelingResults * results() const
For internal use by the providers.
QString mProviderId
Associated provider ID (one layer may have multiple providers, e.g. in rule-based labeling) ...
LabelPosition is a candidate feature label position.
Definition: labelposition.h:55
QgsPalLayerSettings::ObstacleType mObstacleType
Type of the obstacle of feature geometries.
QgsPalLayerSettings::UpsideDownLabels mUpsidedownLabels
How to handle labels that would be upside down.
QString providerId() const
Returns provider ID - useful in case there is more than one label provider within a layer (e...
A QgsLabelingEngine implementation, which only calculates the labeling solution during its run() meth...
Class that stores computed placement from labeling engine.
QString mLayerId
Associated layer&#39;s ID, if applicable.
void setEngine(const QgsLabelingEngine *engine)
Associate provider with a labeling engine (should be only called internally from QgsLabelingEngine) ...
ObstacleType
Valid obstacle types, which affect how features within the layer will act as obstacles for labels...