QGIS API Documentation 3.27.0-Master (9c08adf5ef)
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
31class QgsLabelFeature;
32
33namespace pal
34{
35 class Problem;
36 class Pal;
37 class LabelPosition;
38}
39
52class 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
205Q_DECLARE_OPERATORS_FOR_FLAGS( QgsAbstractLabelProvider::Flags )
206
207
208
214class 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
343class CORE_EXPORT QgsLabelingEngine
344{
345 public:
349 virtual ~QgsLabelingEngine();
350
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
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
525class 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
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.
QgsMapLayer * layer() const
Returns the associated layer, or nullptr if no layer is associated with the 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.
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)
QgsLabelingEngine & operator=(const QgsLabelingEngine &rh)=delete
QgsLabelingEngine cannot be copied.
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