QGIS API Documentation 3.34.0-Prizren (ffbdd678812)
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
51class CORE_EXPORT QgsAbstractLabelProvider
52{
53
54 public:
56 QgsAbstractLabelProvider( QgsMapLayer *layer, const QString &providerId = QString() );
57
58 virtual ~QgsAbstractLabelProvider() = default;
59
61 void setEngine( const QgsLabelingEngine *engine ) { mEngine = engine; }
62
63 enum Flag
64 {
65 DrawLabels = 1 << 1,
66 MergeConnectedLines = 1 << 3,
67 CentroidMustBeInside = 1 << 4,
68 };
69 Q_DECLARE_FLAGS( Flags, Flag )
70
71
72 virtual QList<QgsLabelFeature *> labelFeatures( QgsRenderContext &context ) = 0;
73
80 virtual void drawLabel( QgsRenderContext &context, pal::LabelPosition *label ) const = 0;
81
93 virtual void drawUnplacedLabel( QgsRenderContext &context, pal::LabelPosition *label ) const;
94
107 virtual void drawLabelBackground( QgsRenderContext &context, pal::LabelPosition *label ) const;
108
114 virtual void startRender( QgsRenderContext &context );
115
121 virtual void stopRender( QgsRenderContext &context );
122
124 virtual QList<QgsAbstractLabelProvider *> subProviders() { return QList<QgsAbstractLabelProvider *>(); }
125
127 QString name() const { return mName; }
128
130 QString layerId() const { return mLayerId; }
131
137 QgsMapLayer *layer() const { return mLayer.data(); }
138
144 QString providerId() const { return mProviderId; }
145
147 Flags flags() const { return mFlags; }
148
150 Qgis::LabelPlacement placement() const { return mPlacement; }
151
153 double priority() const { return mPriority; }
154
156 QgsLabelObstacleSettings::ObstacleType obstacleType() const { return mObstacleType; }
157
159 Qgis::UpsideDownLabelHandling upsidedownLabels() const { return mUpsidedownLabels; }
160
166 QgsExpressionContextScope *layerExpressionContextScope() const;
167
173 double layerReferenceScale() const { return mLayerReferenceScale; }
174
175 protected:
177 const QgsLabelingEngine *mEngine = nullptr;
178
180 QString mName;
182 QString mLayerId;
186 QString mProviderId;
188 Flags mFlags = DrawLabels;
192 double mPriority = 0.5;
197
198 private:
199
200 std::unique_ptr< QgsExpressionContextScope > mLayerExpressionContextScope;
201 double mLayerReferenceScale = -1;
202};
203
204Q_DECLARE_OPERATORS_FOR_FLAGS( QgsAbstractLabelProvider::Flags )
205
206
207
308
342class CORE_EXPORT QgsLabelingEngine
343{
344 public:
348 virtual ~QgsLabelingEngine();
349
354
356 void setMapSettings( const QgsMapSettings &mapSettings );
358 const QgsMapSettings &mapSettings() const { return mMapSettings; }
359
361 const QgsLabelingEngineSettings &engineSettings() const { return mMapSettings.labelingEngineSettings(); }
362
367 QList< QgsMapLayer * > participatingLayers() const;
368
373 QStringList participatingLayerIds() const;
374
376 void addProvider( QgsAbstractLabelProvider *provider );
377
379 void removeProvider( QgsAbstractLabelProvider *provider );
380
388 virtual void run( QgsRenderContext &context ) = 0;
389
391 QgsLabelingResults *takeResults();
392
394 QgsLabelingResults *results() const { return mResults.get(); }
395
396 protected:
397 void processProvider( QgsAbstractLabelProvider *provider, QgsRenderContext &context, pal::Pal &p );
398
399 protected:
400
407 void registerLabels( QgsRenderContext &context );
408
417 void solve( QgsRenderContext &context );
418
429 void drawLabels( QgsRenderContext &context, const QString &layerId = QString() );
430
435 void cleanup();
436
439
441 QList<QgsAbstractLabelProvider *> mProviders;
442 QList<QgsAbstractLabelProvider *> mSubProviders;
443
445 std::unique_ptr< QgsLabelingResults > mResults;
446
447 std::unique_ptr< pal::Pal > mPal;
448 std::unique_ptr< pal::Problem > mProblem;
449 QList<pal::LabelPosition *> mUnlabeled;
450 QList<pal::LabelPosition *> mLabels;
451
452 private:
453
454 QStringList mLayerRenderingOrderIds;
455
456};
457
468{
469 public:
472
477
478 void run( QgsRenderContext &context ) override;
479
480};
481
494{
495 public:
498
503
504 void run( QgsRenderContext &context ) override;
505
510 void renderLabelsForLayer( QgsRenderContext &context, const QString &layerId );
511
516 void finalize();
517};
518
519
528class CORE_EXPORT QgsLabelingUtils
529{
530 public:
531
538 static QString encodePredefinedPositionOrder( const QVector< Qgis::LabelPredefinedPointPosition > &positions );
539
546 static QVector< Qgis::LabelPredefinedPointPosition > decodePredefinedPositionOrder( const QString &positionString );
547
552 static QString encodeLinePlacementFlags( Qgis::LabelLinePlacementFlags flags );
553
558 static Qgis::LabelLinePlacementFlags decodeLinePlacementFlags( const QString &string );
559
560};
561
562#endif // QGSLABELINGENGINE_H
LabelPlacement
Placement modes which determine how label candidates are generated for a feature.
Definition qgis.h:838
@ AroundPoint
Arranges candidates in a circle around a point (or centroid of a polygon). Applies to point or polygo...
UpsideDownLabelHandling
Polygon placement flags, which control how candidates are generated for a polygon feature.
Definition qgis.h:966
@ 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: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:74
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)