QGIS API Documentation  3.2.0-Bonn (bc43194)
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 QGSLABELINGENGINEV2_H
17 #define QGSLABELINGENGINEV2_H
18 
19 #define SIP_NO_FILE
20 
21 #include "qgis_core.h"
22 #include "qgsmapsettings.h"
23 
24 #include "qgspallabeling.h"
26 
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  unsigned int linePlacementFlags() const { return mLinePlacementFlags; }
98 
100  double priority() const { return mPriority; }
101 
103  QgsPalLayerSettings::ObstacleType obstacleType() const { return mObstacleType; }
104 
106  QgsPalLayerSettings::UpsideDownLabels upsidedownLabels() const { return mUpsidedownLabels; }
107 
108  protected:
110  const QgsLabelingEngine *mEngine = nullptr;
111 
113  QString mName;
115  QString mLayerId;
119  QString mProviderId;
121  Flags mFlags;
125  unsigned int mLinePlacementFlags;
127  double mPriority;
132 };
133 
134 Q_DECLARE_OPERATORS_FOR_FLAGS( QgsAbstractLabelProvider::Flags )
135 
136 
137 
170 class CORE_EXPORT QgsLabelingEngine
171 {
172  public:
174  QgsLabelingEngine();
176  ~QgsLabelingEngine();
177 
179  QgsLabelingEngine( const QgsLabelingEngine &rh ) = delete;
181  QgsLabelingEngine &operator=( const QgsLabelingEngine &rh ) = delete;
182 
184  void setMapSettings( const QgsMapSettings &mapSettings ) { mMapSettings = mapSettings; }
186  const QgsMapSettings &mapSettings() const { return mMapSettings; }
187 
189  const QgsLabelingEngineSettings &engineSettings() const { return mMapSettings.labelingEngineSettings(); }
190 
195  QList< QgsMapLayer * > participatingLayers() const;
196 
198  void addProvider( QgsAbstractLabelProvider *provider );
199 
201  void removeProvider( QgsAbstractLabelProvider *provider );
202 
204  void run( QgsRenderContext &context );
205 
207  QgsLabelingResults *takeResults();
208 
210  QgsLabelingResults *results() const { return mResults.get(); }
211 
212  protected:
213  void processProvider( QgsAbstractLabelProvider *provider, QgsRenderContext &context, pal::Pal &p );
214 
215  protected:
218 
220  QList<QgsAbstractLabelProvider *> mProviders;
221  QList<QgsAbstractLabelProvider *> mSubProviders;
222 
224  std::unique_ptr< QgsLabelingResults > mResults;
225 
226 };
227 
228 
238 class CORE_EXPORT QgsLabelingUtils
239 {
240  public:
241 
248  static QString encodePredefinedPositionOrder( const QVector< QgsPalLayerSettings::PredefinedPointPosition > &positions );
249 
256  static QVector< QgsPalLayerSettings::PredefinedPointPosition > decodePredefinedPositionOrder( const QString &positionString );
257 
258 };
259 
260 #endif // QGSLABELINGENGINEV2_H
Base class for all map layer types.
Definition: qgsmaplayer.h:61
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
void setMapSettings(const QgsMapSettings &mapSettings)
Associate map settings instance.
QPointer< QgsMapLayer > QgsWeakMapLayerPointer
Weak pointer for QgsMapLayer.
Definition: qgsmaplayer.h:1385
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.
unsigned int linePlacementFlags() const
For layers with linestring geometries - extra placement flags (or-ed combination of QgsPalLayerSettin...
const QgsLabelingEngineSettings & engineSettings() const
Gets associated labeling engine settings.
unsigned int mLinePlacementFlags
Extra placement flags for linestring geometries.
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...