QGIS API Documentation  3.27.0-Master (0e23467727)
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 
25 #include "qgslabeling.h"
26 #include "qgsfeedback.h"
28 
29 class QgsLabelingEngine;
30 class QgsLabelingResults;
31 class QgsLabelFeature;
32 
33 namespace pal
34 {
35  class Problem;
36  class Pal;
37  class LabelPosition;
38 }
39 
52 class CORE_EXPORT QgsAbstractLabelProvider
53 {
54 
55  public:
57  QgsAbstractLabelProvider( QgsMapLayer *layer, const QString &providerId = QString() );
58 
59  virtual ~QgsAbstractLabelProvider() = default;
60 
62  void setEngine( const QgsLabelingEngine *engine ) { mEngine = engine; }
63 
64  enum Flag
65  {
66  DrawLabels = 1 << 1,
67  MergeConnectedLines = 1 << 3,
68  CentroidMustBeInside = 1 << 4,
69  };
70  Q_DECLARE_FLAGS( Flags, Flag )
71 
72 
73  virtual QList<QgsLabelFeature *> labelFeatures( QgsRenderContext &context ) = 0;
74 
81  virtual void drawLabel( QgsRenderContext &context, pal::LabelPosition *label ) const = 0;
82 
94  virtual void drawUnplacedLabel( QgsRenderContext &context, pal::LabelPosition *label ) const;
95 
108  virtual void drawLabelBackground( QgsRenderContext &context, pal::LabelPosition *label ) const;
109 
115  virtual void startRender( QgsRenderContext &context );
116 
122  virtual void stopRender( QgsRenderContext &context );
123 
125  virtual QList<QgsAbstractLabelProvider *> subProviders() { return QList<QgsAbstractLabelProvider *>(); }
126 
128  QString name() const { return mName; }
129 
131  QString layerId() const { return mLayerId; }
132 
138  QgsMapLayer *layer() const { return mLayer.data(); }
139 
145  QString providerId() const { return mProviderId; }
146 
148  Flags flags() const { return mFlags; }
149 
151  Qgis::LabelPlacement placement() const { return mPlacement; }
152 
154  double priority() const { return mPriority; }
155 
157  QgsLabelObstacleSettings::ObstacleType obstacleType() const { return mObstacleType; }
158 
160  Qgis::UpsideDownLabelHandling upsidedownLabels() const { return mUpsidedownLabels; }
161 
167  QgsExpressionContextScope *layerExpressionContextScope() const;
168 
174  double layerReferenceScale() const { return mLayerReferenceScale; }
175 
176  protected:
178  const QgsLabelingEngine *mEngine = nullptr;
179 
181  QString mName;
183  QString mLayerId;
187  QString mProviderId;
189  Flags mFlags = DrawLabels;
193  double mPriority = 0.5;
197  Qgis::UpsideDownLabelHandling mUpsidedownLabels = Qgis::UpsideDownLabelHandling::FlipUpsideDownLabels;
198 
199  private:
200 
201  std::unique_ptr< QgsExpressionContextScope > mLayerExpressionContextScope;
202  double mLayerReferenceScale = -1;
203 };
204 
205 Q_DECLARE_OPERATORS_FOR_FLAGS( QgsAbstractLabelProvider::Flags )
206 
207 
208 
214 class CORE_EXPORT QgsLabelingEngineFeedback : public QgsFeedback
215 {
216  Q_OBJECT
217 
218  public:
219 
223  QgsLabelingEngineFeedback( QObject *parent SIP_TRANSFERTHIS = nullptr )
224  : QgsFeedback( parent )
225  {}
226 
227  signals:
228 
233 
238 
243 
248 
253 
258 
263 
268 
273 
278 
283 
288 
293 
298 
303 
308 };
309 
343 class CORE_EXPORT QgsLabelingEngine
344 {
345  public:
349  virtual ~QgsLabelingEngine();
350 
352  QgsLabelingEngine( const QgsLabelingEngine &rh ) = delete;
355 
357  void setMapSettings( const QgsMapSettings &mapSettings );
359  const QgsMapSettings &mapSettings() const { return mMapSettings; }
360 
362  const QgsLabelingEngineSettings &engineSettings() const { return mMapSettings.labelingEngineSettings(); }
363 
368  QList< QgsMapLayer * > participatingLayers() const;
369 
374  QStringList participatingLayerIds() const;
375 
377  void addProvider( QgsAbstractLabelProvider *provider );
378 
380  void removeProvider( QgsAbstractLabelProvider *provider );
381 
389  virtual void run( QgsRenderContext &context ) = 0;
390 
392  QgsLabelingResults *takeResults();
393 
395  QgsLabelingResults *results() const { return mResults.get(); }
396 
397  protected:
398  void processProvider( QgsAbstractLabelProvider *provider, QgsRenderContext &context, pal::Pal &p );
399 
400  protected:
401 
408  void registerLabels( QgsRenderContext &context );
409 
418  void solve( QgsRenderContext &context );
419 
430  void drawLabels( QgsRenderContext &context, const QString &layerId = QString() );
431 
436  void cleanup();
437 
440 
442  QList<QgsAbstractLabelProvider *> mProviders;
443  QList<QgsAbstractLabelProvider *> mSubProviders;
444 
446  std::unique_ptr< QgsLabelingResults > mResults;
447 
448  std::unique_ptr< pal::Pal > mPal;
449  std::unique_ptr< pal::Problem > mProblem;
450  QList<pal::LabelPosition *> mUnlabeled;
451  QList<pal::LabelPosition *> mLabels;
452 
453 };
454 
464 class CORE_EXPORT QgsDefaultLabelingEngine : public QgsLabelingEngine
465 {
466  public:
469 
474 
475  void run( QgsRenderContext &context ) override;
476 
477 };
478 
491 {
492  public:
495 
500 
501  void run( QgsRenderContext &context ) override;
502 
507  void renderLabelsForLayer( QgsRenderContext &context, const QString &layerId );
508 
513  void finalize();
514 };
515 
516 
525 class CORE_EXPORT QgsLabelingUtils
526 {
527  public:
528 
535  static QString encodePredefinedPositionOrder( const QVector< Qgis::LabelPredefinedPointPosition > &positions );
536 
543  static QVector< Qgis::LabelPredefinedPointPosition > decodePredefinedPositionOrder( const QString &positionString );
544 
549  static QString encodeLinePlacementFlags( QgsLabeling::LinePlacementFlags flags );
550 
555  static QgsLabeling::LinePlacementFlags decodeLinePlacementFlags( const QString &string );
556 
557 };
558 
559 #endif // QGSLABELINGENGINE_H
LabelPlacement
Placement modes which determine how label candidates are generated for a feature.
Definition: qgis.h:561
@ AroundPoint
Arranges candidates in a circle around a point (or centroid of a polygon). Applies to point or polygo...
UpsideDownLabelHandling
Handling techniques for upside down labels.
Definition: qgis.h:643
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.
Qgis::LabelPlacement placement() const
What placement strategy to use for the labels.
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.
double priority() const
Default priority of labels (may be overridden by individual labels)
QString name() const
Name of the layer (for statistics, debugging etc.) - does not need to be unique.
double layerReferenceScale() const
Returns the symbology reference scale of the layer associated with this provider.
Flags flags() const
Flags associated with the provider.
QgsLabelObstacleSettings::ObstacleType obstacleType() const
How the feature geometries will work as obstacles.
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....
Qgis::UpsideDownLabelHandling upsidedownLabels() const
How to handle labels that would be upside down.
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.
Base class for feedback objects to be used for cancellation of something running in a worker thread.
Definition: qgsfeedback.h:45
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.
QgsFeedback subclass for granular reporting of labeling engine progress.
void obstacleCostingAboutToBegin()
Emitted when the obstacle costing is about to begin.
void solvingPlacementAboutToBegin()
Emitted when the problem solving step is about to begin.
void calculatingConflictsAboutToBegin()
Emitted when the conflict handling step is about to begin.
QgsLabelingEngineFeedback(QObject *parent=nullptr)
Constructor for QgsLabelingEngineFeedback, with the specified parent object.
void reductionAboutToBegin()
Emitted when the candidate reduction step is about to begin.
void finalizingCandidatesFinished()
Emitted when the label candidates are finalized.
void labelRegistrationAboutToBegin()
Emitted when the label registration is about to begin.
void labelRegistrationFinished()
Emitted when the label registration has completed for all providers.
void solvingPlacementFinished()
Emitted when the problem solving step is finished.
void finalizingCandidatesAboutToBegin()
Emitted when the label candidates are about to be finalized.
void obstacleCostingFinished()
Emitted when the obstacle costing has completed.
void reductionFinished()
Emitted when the candidate reduction step is finished.
void calculatingConflictsFinished()
Emitted when the conflict handling step has completed.
void candidateCreationFinished(QgsAbstractLabelProvider *provider)
Emitted when the label candidate creation has completed for a provider.
void candidateCreationAboutToBegin(QgsAbstractLabelProvider *provider)
Emitted when the label candidate creation is about to begin for a provider.
void providerRegistrationFinished(QgsAbstractLabelProvider *provider)
Emitted when the label registration has completed for a provider.
void providerRegistrationAboutToBegin(QgsAbstractLabelProvider *provider)
Emitted when the label registration is about to begin for a provider.
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:73
The QgsMapSettings class contains configuration for rendering of the map.
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
#define SIP_TRANSFERTHIS
Definition: qgis_sip.h:53
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:2146