QGIS API Documentation  3.23.0-Master (7c4a6de034)
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 #include "qgsfeedback.h"
28 
29 class QgsLabelingEngine;
30 class QgsLabelingResults;
31 
32 namespace pal
33 {
34  class Problem;
35 }
36 
49 class CORE_EXPORT QgsAbstractLabelProvider
50 {
51 
52  public:
54  QgsAbstractLabelProvider( QgsMapLayer *layer, const QString &providerId = QString() );
55 
56  virtual ~QgsAbstractLabelProvider() = default;
57 
59  void setEngine( const QgsLabelingEngine *engine ) { mEngine = engine; }
60 
61  enum Flag
62  {
63  DrawLabels = 1 << 1,
64  DrawAllLabels = 1 << 2,
65  MergeConnectedLines = 1 << 3,
66  CentroidMustBeInside = 1 << 4,
67  };
68  Q_DECLARE_FLAGS( Flags, Flag )
69 
70 
71  virtual QList<QgsLabelFeature *> labelFeatures( QgsRenderContext &context ) = 0;
72 
79  virtual void drawLabel( QgsRenderContext &context, pal::LabelPosition *label ) const = 0;
80 
92  virtual void drawUnplacedLabel( QgsRenderContext &context, pal::LabelPosition *label ) const;
93 
106  virtual void drawLabelBackground( QgsRenderContext &context, pal::LabelPosition *label ) const;
107 
113  virtual void startRender( QgsRenderContext &context );
114 
120  virtual void stopRender( QgsRenderContext &context );
121 
123  virtual QList<QgsAbstractLabelProvider *> subProviders() { return QList<QgsAbstractLabelProvider *>(); }
124 
126  QString name() const { return mName; }
127 
129  QString layerId() const { return mLayerId; }
130 
136  QgsMapLayer *layer() const { return mLayer.data(); }
137 
143  QString providerId() const { return mProviderId; }
144 
146  Flags flags() const { return mFlags; }
147 
149  QgsPalLayerSettings::Placement placement() const { return mPlacement; }
150 
152  double priority() const { return mPriority; }
153 
155  QgsLabelObstacleSettings::ObstacleType obstacleType() const { return mObstacleType; }
156 
158  QgsPalLayerSettings::UpsideDownLabels upsidedownLabels() const { return mUpsidedownLabels; }
159 
165  QgsExpressionContextScope *layerExpressionContextScope() const;
166 
172  double layerReferenceScale() const { return mLayerReferenceScale; }
173 
174  protected:
176  const QgsLabelingEngine *mEngine = nullptr;
177 
179  QString mName;
181  QString mLayerId;
185  QString mProviderId;
187  Flags mFlags;
191  double mPriority;
196 
197  private:
198 
199  std::unique_ptr< QgsExpressionContextScope > mLayerExpressionContextScope;
200  double mLayerReferenceScale = -1;
201 };
202 
203 Q_DECLARE_OPERATORS_FOR_FLAGS( QgsAbstractLabelProvider::Flags )
204 
205 
206 
212 class CORE_EXPORT QgsLabelingEngineFeedback : public QgsFeedback
213 {
214  Q_OBJECT
215 
216  public:
217 
221  QgsLabelingEngineFeedback( QObject *parent SIP_TRANSFERTHIS = nullptr )
222  : QgsFeedback( parent )
223  {}
224 
225  signals:
226 
231 
236 
241 
246 
251 
256 
261 
266 
271 
276 
281 
286 
291 
296 
301 
306 };
307 
341 class CORE_EXPORT QgsLabelingEngine
342 {
343  public:
347  virtual ~QgsLabelingEngine();
348 
350  QgsLabelingEngine( const QgsLabelingEngine &rh ) = delete;
353 
355  void setMapSettings( const QgsMapSettings &mapSettings );
357  const QgsMapSettings &mapSettings() const { return mMapSettings; }
358 
360  const QgsLabelingEngineSettings &engineSettings() const { return mMapSettings.labelingEngineSettings(); }
361 
366  QList< QgsMapLayer * > participatingLayers() const;
367 
372  QStringList participatingLayerIds() const;
373 
375  void addProvider( QgsAbstractLabelProvider *provider );
376 
378  void removeProvider( QgsAbstractLabelProvider *provider );
379 
387  virtual void run( QgsRenderContext &context ) = 0;
388 
390  QgsLabelingResults *takeResults();
391 
393  QgsLabelingResults *results() const { return mResults.get(); }
394 
395  protected:
396  void processProvider( QgsAbstractLabelProvider *provider, QgsRenderContext &context, pal::Pal &p );
397 
398  protected:
399 
406  void registerLabels( QgsRenderContext &context );
407 
416  void solve( QgsRenderContext &context );
417 
428  void drawLabels( QgsRenderContext &context, const QString &layerId = QString() );
429 
434  void cleanup();
435 
438 
440  QList<QgsAbstractLabelProvider *> mProviders;
441  QList<QgsAbstractLabelProvider *> mSubProviders;
442 
444  std::unique_ptr< QgsLabelingResults > mResults;
445 
446  std::unique_ptr< pal::Pal > mPal;
447  std::unique_ptr< pal::Problem > mProblem;
448  QList<pal::LabelPosition *> mUnlabeled;
449  QList<pal::LabelPosition *> mLabels;
450 
451 };
452 
462 class CORE_EXPORT QgsDefaultLabelingEngine : public QgsLabelingEngine
463 {
464  public:
467 
472 
473  void run( QgsRenderContext &context ) override;
474 
475 };
476 
489 {
490  public:
493 
498 
499  void run( QgsRenderContext &context ) override;
500 
505  void renderLabelsForLayer( QgsRenderContext &context, const QString &layerId );
506 
511  void finalize();
512 };
513 
514 
523 class CORE_EXPORT QgsLabelingUtils
524 {
525  public:
526 
533  static QString encodePredefinedPositionOrder( const QVector< QgsPalLayerSettings::PredefinedPointPosition > &positions );
534 
541  static QVector< QgsPalLayerSettings::PredefinedPointPosition > decodePredefinedPositionOrder( const QString &positionString );
542 
547  static QString encodeLinePlacementFlags( QgsLabeling::LinePlacementFlags flags );
548 
553  static QgsLabeling::LinePlacementFlags decodeLinePlacementFlags( const QString &string );
554 
555 };
556 
557 #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.
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.
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
#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:2133