QGIS API Documentation 3.39.0-Master (bca3cdb6021)
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
350
352 void setMapSettings( const QgsMapSettings &mapSettings );
354 const QgsMapSettings &mapSettings() const { return mMapSettings; }
355
357 const QgsLabelingEngineSettings &engineSettings() const { return mMapSettings.labelingEngineSettings(); }
358
366 bool prepare( QgsRenderContext &context );
367
371 QList< QgsMapLayer * > participatingLayers() const;
372
377 QStringList participatingLayerIds() const;
378
387 QString addProvider( QgsAbstractLabelProvider *provider );
388
394 QgsAbstractLabelProvider *providerById( const QString &id );
395
397 void removeProvider( QgsAbstractLabelProvider *provider );
398
406 virtual void run( QgsRenderContext &context ) = 0;
407
409 QgsLabelingResults *takeResults();
410
412 QgsLabelingResults *results() const { return mResults.get(); }
413
414 protected:
415 void processProvider( QgsAbstractLabelProvider *provider, QgsRenderContext &context, pal::Pal &p );
416
417 protected:
418
425 void registerLabels( QgsRenderContext &context );
426
435 void solve( QgsRenderContext &context );
436
447 void drawLabels( QgsRenderContext &context, const QString &layerId = QString() );
448
453 void cleanup();
454
457
459 QList<QgsAbstractLabelProvider *> mProviders;
460 QHash<QString, QgsAbstractLabelProvider *> mProvidersById;
461 QList<QgsAbstractLabelProvider *> mSubProviders;
462
464 std::vector< std::unique_ptr< QgsAbstractLabelingEngineRule > > mEngineRules;
465
467 std::unique_ptr< QgsLabelingResults > mResults;
468
469 std::unique_ptr< pal::Pal > mPal;
470 std::unique_ptr< pal::Problem > mProblem;
471 QList<pal::LabelPosition *> mUnlabeled;
472 QList<pal::LabelPosition *> mLabels;
473
474 private:
475
476 QStringList mLayerRenderingOrderIds;
477
478};
479
490{
491 public:
494
497
498 void run( QgsRenderContext &context ) override;
499
500};
501
514{
515 public:
518
521
522 void run( QgsRenderContext &context ) override;
523
528 void renderLabelsForLayer( QgsRenderContext &context, const QString &layerId );
529
534 void finalize();
535};
536
537
545class CORE_EXPORT QgsLabelingUtils
546{
547 public:
548
555 static QString encodePredefinedPositionOrder( const QVector< Qgis::LabelPredefinedPointPosition > &positions );
556
563 static QVector< Qgis::LabelPredefinedPointPosition > decodePredefinedPositionOrder( const QString &positionString );
564
569 static QString encodeLinePlacementFlags( Qgis::LabelLinePlacementFlags flags );
570
575 static Qgis::LabelLinePlacementFlags decodeLinePlacementFlags( const QString &string );
576
577};
578
579#endif // QGSLABELINGENGINE_H
LabelPlacement
Placement modes which determine how label candidates are generated for a feature.
Definition qgis.h:1125
@ 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:1221
UpsideDownLabelHandling
Handling techniques for upside down labels.
Definition qgis.h:1254
@ 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 & operator=(const QgsDefaultLabelingEngine &rh)=delete
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::vector< std::unique_ptr< QgsAbstractLabelingEngineRule > > mEngineRules
std::unique_ptr< pal::Problem > mProblem
const QgsMapSettings & mapSettings() const
Gets associated map settings.
QList< pal::LabelPosition * > mLabels
QList< QgsAbstractLabelProvider * > mSubProviders
List of labeling engine rules (owned by the labeling engine)
virtual void run(QgsRenderContext &context)=0
Runs the labeling job.
QgsLabelingResults * results() const
For internal use by the providers.
QHash< QString, QgsAbstractLabelProvider * > mProvidersById
QgsLabelingEngine(const QgsLabelingEngine &rh)=delete
QList< QgsAbstractLabelProvider * > mProviders
List of providers (the are owned by the labeling engine)
QgsLabelingEngine & operator=(const QgsLabelingEngine &rh)=delete
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:76
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(const QgsStagedRenderLabelingEngine &rh)=delete
Main Pal labeling class.
Definition pal.h:84
#define SIP_TRANSFERTHIS
Definition qgis_sip.h:53
QPointer< QgsMapLayer > QgsWeakMapLayerPointer
Weak pointer for QgsMapLayer.
Q_DECLARE_OPERATORS_FOR_FLAGS(QgsTextRendererUtils::CurvedTextFlags)