QGIS API Documentation  3.17.0-Master (3b262f2a79)
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:
218  QgsLabelingEngine();
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 
345  QgsDefaultLabelingEngine &operator=( const QgsDefaultLabelingEngine &rh ) = delete;
346 
347  void run( QgsRenderContext &context ) override;
348 
349 };
350 
363 {
364  public:
367 
371  QgsStagedRenderLabelingEngine &operator=( const QgsStagedRenderLabelingEngine &rh ) = delete;
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
QList< pal::LabelPosition * > mLabels
std::unique_ptr< pal::Pal > mPal
Base class for all map layer types.
Definition: qgsmaplayer.h:84
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.
QList< QgsAbstractLabelProvider * > mSubProviders
Q_DECLARE_OPERATORS_FOR_FLAGS(QgsField::ConfigurationFlags) CORE_EXPORT QDataStream &operator<<(QDataStream &out
Writes the field to stream out. QGIS version compatibility is not guaranteed.
Main Pal labeling class.
Definition: pal.h:79
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:1746
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.
ObstacleType
Valid obstacle types, which affect how features within the layer will act as obstacles for labels...
const QgsLabelingEngineSettings & engineSettings() const
Gets associated labeling engine settings.
Flags mFlags
Flags altering drawing and registration of features.
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.
QgsLabelObstacleSettings::ObstacleType obstacleType() const
How the feature geometries will work as obstacles.
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::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) ...