QGIS API Documentation 3.39.0-Master (be2050b798e)
Loading...
Searching...
No Matches
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 "qgsfeedback.h"
26
29class QgsLabelFeature;
31
32namespace pal
33{
34 class Problem;
35 class Pal;
36 class LabelPosition;
37}
38
50class CORE_EXPORT QgsAbstractLabelProvider
51{
52
53 public:
55 QgsAbstractLabelProvider( QgsMapLayer *layer, const QString &providerId = QString() );
56
57 virtual ~QgsAbstractLabelProvider() = default;
58
60 void setEngine( const QgsLabelingEngine *engine ) { mEngine = engine; }
61
62 enum Flag
63 {
64 DrawLabels = 1 << 1,
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 Qgis::LabelPlacement placement() const { return mPlacement; }
150
152 double priority() const { return mPriority; }
153
155 QgsLabelObstacleSettings::ObstacleType obstacleType() const { return mObstacleType; }
156
158 Qgis::UpsideDownLabelHandling 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 = DrawLabels;
191 double mPriority = 0.5;
196
197 private:
198
199 std::unique_ptr< QgsExpressionContextScope > mLayerExpressionContextScope;
200 double mLayerReferenceScale = -1;
201};
202
204
205
206
307
340class CORE_EXPORT QgsLabelingEngine
341{
342 public:
346 virtual ~QgsLabelingEngine();
347
352
354 void setMapSettings( const QgsMapSettings &mapSettings );
356 const QgsMapSettings &mapSettings() const { return mMapSettings; }
357
359 const QgsLabelingEngineSettings &engineSettings() const { return mMapSettings.labelingEngineSettings(); }
360
364 QList< QgsMapLayer * > participatingLayers() const;
365
370 QStringList participatingLayerIds() const;
371
373 void addProvider( QgsAbstractLabelProvider *provider );
374
376 void removeProvider( QgsAbstractLabelProvider *provider );
377
385 virtual void run( QgsRenderContext &context ) = 0;
386
388 QgsLabelingResults *takeResults();
389
391 QgsLabelingResults *results() const { return mResults.get(); }
392
393 protected:
394 void processProvider( QgsAbstractLabelProvider *provider, QgsRenderContext &context, pal::Pal &p );
395
396 protected:
397
404 void registerLabels( QgsRenderContext &context );
405
414 void solve( QgsRenderContext &context );
415
426 void drawLabels( QgsRenderContext &context, const QString &layerId = QString() );
427
432 void cleanup();
433
436
438 QList<QgsAbstractLabelProvider *> mProviders;
439 QList<QgsAbstractLabelProvider *> mSubProviders;
440
442 std::unique_ptr< QgsLabelingResults > mResults;
443
444 std::unique_ptr< pal::Pal > mPal;
445 std::unique_ptr< pal::Problem > mProblem;
446 QList<pal::LabelPosition *> mUnlabeled;
447 QList<pal::LabelPosition *> mLabels;
448
449 private:
450
451 QStringList mLayerRenderingOrderIds;
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
524class CORE_EXPORT QgsLabelingUtils
525{
526 public:
527
534 static QString encodePredefinedPositionOrder( const QVector< Qgis::LabelPredefinedPointPosition > &positions );
535
542 static QVector< Qgis::LabelPredefinedPointPosition > decodePredefinedPositionOrder( const QString &positionString );
543
548 static QString encodeLinePlacementFlags( Qgis::LabelLinePlacementFlags flags );
549
554 static Qgis::LabelLinePlacementFlags decodeLinePlacementFlags( const QString &string );
555
556};
557
558#endif // QGSLABELINGENGINE_H
LabelPlacement
Placement modes which determine how label candidates are generated for a feature.
Definition qgis.h:1028
@ AroundPoint
Arranges candidates in a circle around a point (or centroid of a polygon). Applies to point or polygo...
QFlags< LabelLinePlacementFlag > LabelLinePlacementFlags
Line placement flags, which control how candidates are generated for a linear feature.
Definition qgis.h:1124
UpsideDownLabelHandling
Handling techniques for upside down labels.
Definition qgis.h:1157
@ FlipUpsideDownLabels
Upside-down labels (90 <= angle < 270) are shown upright.
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:44
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.
@ PolygonBoundary
Avoid placing labels over boundary of polygon (prefer placing outside or completely inside polygon)
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:75
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:83
#define SIP_TRANSFERTHIS
Definition qgis_sip.h:53
QPointer< QgsMapLayer > QgsWeakMapLayerPointer
Weak pointer for QgsMapLayer.
Q_DECLARE_OPERATORS_FOR_FLAGS(QgsTextRendererUtils::CurvedTextFlags)