QGIS API Documentation  3.8.0-Zanzibar (11aff65)
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  LabelPerFeaturePart = 1 << 6,
62  };
63  Q_DECLARE_FLAGS( Flags, Flag )
64 
65 
66  virtual QList<QgsLabelFeature *> labelFeatures( QgsRenderContext &context ) = 0;
67 
69  virtual void drawLabel( QgsRenderContext &context, pal::LabelPosition *label ) const = 0;
70 
72  virtual QList<QgsAbstractLabelProvider *> subProviders() { return QList<QgsAbstractLabelProvider *>(); }
73 
75  QString name() const { return mName; }
76 
78  QString layerId() const { return mLayerId; }
79 
81  QgsMapLayer *layer() const { return mLayer.data(); }
82 
88  QString providerId() const { return mProviderId; }
89 
91  Flags flags() const { return mFlags; }
92 
94  QgsPalLayerSettings::Placement placement() const { return mPlacement; }
95 
97  double priority() const { return mPriority; }
98 
100  QgsPalLayerSettings::ObstacleType obstacleType() const { return mObstacleType; }
101 
103  QgsPalLayerSettings::UpsideDownLabels upsidedownLabels() const { return mUpsidedownLabels; }
104 
105  protected:
107  const QgsLabelingEngine *mEngine = nullptr;
108 
110  QString mName;
112  QString mLayerId;
116  QString mProviderId;
118  Flags mFlags;
122  double mPriority;
127 };
128 
129 Q_DECLARE_OPERATORS_FOR_FLAGS( QgsAbstractLabelProvider::Flags )
130 
131 
132 
165 class CORE_EXPORT QgsLabelingEngine
166 {
167  public:
169  QgsLabelingEngine();
171  ~QgsLabelingEngine();
172 
174  QgsLabelingEngine( const QgsLabelingEngine &rh ) = delete;
176  QgsLabelingEngine &operator=( const QgsLabelingEngine &rh ) = delete;
177 
179  void setMapSettings( const QgsMapSettings &mapSettings );
181  const QgsMapSettings &mapSettings() const { return mMapSettings; }
182 
184  const QgsLabelingEngineSettings &engineSettings() const { return mMapSettings.labelingEngineSettings(); }
185 
190  QList< QgsMapLayer * > participatingLayers() const;
191 
193  void addProvider( QgsAbstractLabelProvider *provider );
194 
196  void removeProvider( QgsAbstractLabelProvider *provider );
197 
199  void run( QgsRenderContext &context );
200 
202  QgsLabelingResults *takeResults();
203 
205  QgsLabelingResults *results() const { return mResults.get(); }
206 
207  protected:
208  void processProvider( QgsAbstractLabelProvider *provider, QgsRenderContext &context, pal::Pal &p );
209 
210  protected:
213 
215  QList<QgsAbstractLabelProvider *> mProviders;
216  QList<QgsAbstractLabelProvider *> mSubProviders;
217 
219  std::unique_ptr< QgsLabelingResults > mResults;
220 
221 };
222 
223 
233 class CORE_EXPORT QgsLabelingUtils
234 {
235  public:
236 
243  static QString encodePredefinedPositionOrder( const QVector< QgsPalLayerSettings::PredefinedPointPosition > &positions );
244 
251  static QVector< QgsPalLayerSettings::PredefinedPointPosition > decodePredefinedPositionOrder( const QString &positionString );
252 
257  static QString encodeLinePlacementFlags( pal::LineArrangementFlags flags );
258 
263  static pal::LineArrangementFlags decodeLinePlacementFlags( const QString &string );
264 
265 };
266 
267 #endif // QGSLABELINGENGINE_H
Base class for all map layer types.
Definition: qgsmaplayer.h:78
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
QPointer< QgsMapLayer > QgsWeakMapLayerPointer
Weak pointer for QgsMapLayer.
Definition: qgsmaplayer.h:1576
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.
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.
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.
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...
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...