QGIS API Documentation  3.21.0-Master (56b4176581)
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 class QgsLabelingResults;
30 
31 namespace pal
32 {
33  class Problem;
34 }
35 
48 class CORE_EXPORT QgsAbstractLabelProvider
49 {
50 
51  public:
53  QgsAbstractLabelProvider( QgsMapLayer *layer, const QString &providerId = QString() );
54 
55  virtual ~QgsAbstractLabelProvider() = default;
56 
58  void setEngine( const QgsLabelingEngine *engine ) { mEngine = engine; }
59 
60  enum Flag
61  {
62  DrawLabels = 1 << 1,
63  DrawAllLabels = 1 << 2,
64  MergeConnectedLines = 1 << 3,
65  CentroidMustBeInside = 1 << 4,
66  };
67  Q_DECLARE_FLAGS( Flags, Flag )
68 
69 
70  virtual QList<QgsLabelFeature *> labelFeatures( QgsRenderContext &context ) = 0;
71 
78  virtual void drawLabel( QgsRenderContext &context, pal::LabelPosition *label ) const = 0;
79 
91  virtual void drawUnplacedLabel( QgsRenderContext &context, pal::LabelPosition *label ) const;
92 
105  virtual void drawLabelBackground( QgsRenderContext &context, pal::LabelPosition *label ) const;
106 
112  virtual void startRender( QgsRenderContext &context );
113 
119  virtual void stopRender( QgsRenderContext &context );
120 
122  virtual QList<QgsAbstractLabelProvider *> subProviders() { return QList<QgsAbstractLabelProvider *>(); }
123 
125  QString name() const { return mName; }
126 
128  QString layerId() const { return mLayerId; }
129 
135  QgsMapLayer *layer() const { return mLayer.data(); }
136 
142  QString providerId() const { return mProviderId; }
143 
145  Flags flags() const { return mFlags; }
146 
148  QgsPalLayerSettings::Placement placement() const { return mPlacement; }
149 
151  double priority() const { return mPriority; }
152 
154  QgsLabelObstacleSettings::ObstacleType obstacleType() const { return mObstacleType; }
155 
157  QgsPalLayerSettings::UpsideDownLabels upsidedownLabels() const { return mUpsidedownLabels; }
158 
164  QgsExpressionContextScope *layerExpressionContextScope() const;
165 
171  double layerReferenceScale() const { return mLayerReferenceScale; }
172 
173  protected:
175  const QgsLabelingEngine *mEngine = nullptr;
176 
178  QString mName;
180  QString mLayerId;
184  QString mProviderId;
186  Flags mFlags;
190  double mPriority;
195 
196  private:
197 
198  std::unique_ptr< QgsExpressionContextScope > mLayerExpressionContextScope;
199  double mLayerReferenceScale = -1;
200 };
201 
202 Q_DECLARE_OPERATORS_FOR_FLAGS( QgsAbstractLabelProvider::Flags )
203 
204 
205 
238 class CORE_EXPORT QgsLabelingEngine
239 {
240  public:
244  virtual ~QgsLabelingEngine();
245 
247  QgsLabelingEngine( const QgsLabelingEngine &rh ) = delete;
250 
252  void setMapSettings( const QgsMapSettings &mapSettings );
254  const QgsMapSettings &mapSettings() const { return mMapSettings; }
255 
257  const QgsLabelingEngineSettings &engineSettings() const { return mMapSettings.labelingEngineSettings(); }
258 
263  QList< QgsMapLayer * > participatingLayers() const;
264 
269  QStringList participatingLayerIds() const;
270 
272  void addProvider( QgsAbstractLabelProvider *provider );
273 
275  void removeProvider( QgsAbstractLabelProvider *provider );
276 
284  virtual void run( QgsRenderContext &context ) = 0;
285 
287  QgsLabelingResults *takeResults();
288 
290  QgsLabelingResults *results() const { return mResults.get(); }
291 
292  protected:
293  void processProvider( QgsAbstractLabelProvider *provider, QgsRenderContext &context, pal::Pal &p );
294 
295  protected:
296 
304  void registerLabels( QgsRenderContext &context );
305 
314  void solve( QgsRenderContext &context );
315 
326  void drawLabels( QgsRenderContext &context, const QString &layerId = QString() );
327 
332  void cleanup();
333 
336 
338  QList<QgsAbstractLabelProvider *> mProviders;
339  QList<QgsAbstractLabelProvider *> mSubProviders;
340 
342  std::unique_ptr< QgsLabelingResults > mResults;
343 
344  std::unique_ptr< pal::Pal > mPal;
345  std::unique_ptr< pal::Problem > mProblem;
346  QList<pal::LabelPosition *> mUnlabeled;
347  QList<pal::LabelPosition *> mLabels;
348 
349 };
350 
360 class CORE_EXPORT QgsDefaultLabelingEngine : public QgsLabelingEngine
361 {
362  public:
365 
370 
371  void run( QgsRenderContext &context ) override;
372 
373 };
374 
387 {
388  public:
391 
396 
397  void run( QgsRenderContext &context ) override;
398 
403  void renderLabelsForLayer( QgsRenderContext &context, const QString &layerId );
404 
409  void finalize();
410 };
411 
412 
421 class CORE_EXPORT QgsLabelingUtils
422 {
423  public:
424 
431  static QString encodePredefinedPositionOrder( const QVector< QgsPalLayerSettings::PredefinedPointPosition > &positions );
432 
439  static QVector< QgsPalLayerSettings::PredefinedPointPosition > decodePredefinedPositionOrder( const QString &positionString );
440 
445  static QString encodeLinePlacementFlags( QgsLabeling::LinePlacementFlags flags );
446 
451  static QgsLabeling::LinePlacementFlags decodeLinePlacementFlags( const QString &string );
452 
453 };
454 
455 #endif // QGSLABELINGENGINE_H
The QgsAbstractLabelProvider class is an interface class.
QString mName
Name of the layer.
virtual ~QgsAbstractLabelProvider()=default
QgsMapLayer * layer() const
Returns the associated layer, or nullptr if no layer is associated with the provider.
void setEngine(const QgsLabelingEngine *engine)
Associate provider with a labeling engine (should be only called internally from QgsLabelingEngine)
QString mLayerId
Associated layer's ID, if applicable.
QgsPalLayerSettings::Placement placement() const
What placement strategy to use for the labels.
double priority() const
Default priority of labels (may be overridden by individual labels)
QgsPalLayerSettings::UpsideDownLabels mUpsidedownLabels
How to handle labels that would be upside down.
QString name() const
Name of the layer (for statistics, debugging etc.) - does not need to be unique.
double mPriority
Default priority of labels.
double layerReferenceScale() const
Returns the symbology reference scale of the layer associated with this provider.
Flags mFlags
Flags altering drawing and registration of features.
Flags flags() const
Flags associated with the provider.
QgsLabelObstacleSettings::ObstacleType obstacleType() const
How the feature geometries will work as obstacles.
QgsPalLayerSettings::UpsideDownLabels upsidedownLabels() const
How to handle labels that would be upside down.
QString layerId() const
Returns ID of associated layer, or empty string if no layer is associated with the provider.
QgsWeakMapLayerPointer mLayer
Weak pointer to source layer.
QString providerId() const
Returns provider ID - useful in case there is more than one label provider within a layer (e....
QgsPalLayerSettings::Placement mPlacement
Placement strategy.
QString mProviderId
Associated provider ID (one layer may have multiple providers, e.g. in rule-based labeling)
Default QgsLabelingEngine implementation, which completes the whole labeling operation (including lab...
QgsDefaultLabelingEngine(const QgsDefaultLabelingEngine &rh)=delete
QgsDefaultLabelingEngine cannot be copied.
QgsDefaultLabelingEngine & operator=(const QgsDefaultLabelingEngine &rh)=delete
QgsDefaultLabelingEngine cannot be copied.
Single scope for storing variables and functions for use within a QgsExpressionContext.
The QgsLabelFeature class describes a feature that should be used within the labeling engine.
ObstacleType
Valid obstacle types, which affect how features within the layer will act as obstacles for labels.
Stores global configuration for labeling engine.
The QgsLabelingEngine class provides map labeling functionality.
std::unique_ptr< pal::Pal > mPal
const QgsLabelingEngineSettings & engineSettings() const
Gets associated labeling engine settings.
std::unique_ptr< QgsLabelingResults > mResults
Resulting labeling layout.
QgsMapSettings mMapSettings
Associated map settings instance.
QList< pal::LabelPosition * > mUnlabeled
std::unique_ptr< pal::Problem > mProblem
const QgsMapSettings & mapSettings() const
Gets associated map settings.
QgsLabelingEngine & operator=(const QgsLabelingEngine &rh)=delete
QgsLabelingEngine cannot be copied.
QList< pal::LabelPosition * > mLabels
QList< QgsAbstractLabelProvider * > mSubProviders
virtual void run(QgsRenderContext &context)=0
Runs the labeling job.
QgsLabelingResults * results() const
For internal use by the providers.
QgsLabelingEngine(const QgsLabelingEngine &rh)=delete
QgsLabelingEngine cannot be copied.
QList< QgsAbstractLabelProvider * > mProviders
List of providers (the are owned by the labeling engine)
Class that stores computed placement from labeling engine.
Contains helper utilities for working with QGIS' labeling engine.
Base class for all map layer types.
Definition: qgsmaplayer.h:72
The QgsMapSettings class contains configuration for rendering of the map.
Placement
Placement modes which determine how label candidates are generated for a feature.
Contains information about the context of a rendering operation.
A QgsLabelingEngine implementation, which only calculates the labeling solution during its run() meth...
QgsStagedRenderLabelingEngine & operator=(const QgsStagedRenderLabelingEngine &rh)=delete
QgsStagedRenderLabelingEngine cannot be copied.
QgsStagedRenderLabelingEngine(const QgsStagedRenderLabelingEngine &rh)=delete
QgsStagedRenderLabelingEngine cannot be copied.
Main Pal labeling class.
Definition: pal.h:80
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.
QPointer< QgsMapLayer > QgsWeakMapLayerPointer
Weak pointer for QgsMapLayer.
Definition: qgsmaplayer.h:2128