QGIS API Documentation  3.37.0-Master (a5b4d9743e8)
Public Types | Public Member Functions | Static Public Attributes | Friends | List of all members
pal::Pal Class Reference

Main Pal labeling class. More...

#include <pal.h>

Public Types

typedef bool(* FnIsCanceled) (void *ctx)
 

Public Member Functions

 Pal ()
 Create an new pal instance. More...
 
 Pal (const Pal &other)=delete
 Pal cannot be copied. More...
 
 ~Pal ()
 
LayeraddLayer (QgsAbstractLabelProvider *provider, const QString &layerName, Qgis::LabelPlacement arrangement, double defaultPriority, bool active, bool toLabel)
 add a new layer More...
 
bool candidatesAreConflicting (const LabelPosition *lp1, const LabelPosition *lp2) const
 Returns true if a labelling candidate lp1 conflicts with lp2. More...
 
std::unique_ptr< ProblemextractProblem (const QgsRectangle &extent, const QgsGeometry &mapBoundary, QgsRenderContext &context)
 Extracts the labeling problem for the specified map extent - only features within this extent will be considered. More...
 
int globalCandidatesLimitLine () const
 Returns the global candidates limit for line features, or 0 if no global limit is in effect. More...
 
int globalCandidatesLimitPoint () const
 Returns the global candidates limit for point features, or 0 if no global limit is in effect. More...
 
int globalCandidatesLimitPolygon () const
 Returns the global candidates limit for polygon features, or 0 if no global limit is in effect. More...
 
bool isCanceled ()
 Check whether the job has been canceled. More...
 
double maximumLineCandidatesPerMapUnit () const
 Returns the maximum number of line label candidate positions per map unit. More...
 
double maximumPolygonCandidatesPerMapUnitSquared () const
 Returns the maximum number of polygon label candidate positions per map unit squared. More...
 
Paloperator= (const Pal &other)=delete
 Pal cannot be copied. More...
 
Qgis::LabelPlacementEngineVersion placementVersion () const
 Returns the placement engine version, which dictates how the label placement problem is solved. More...
 
void registerCancellationCallback (FnIsCanceled fnCanceled, void *context)
 Register a function that returns whether this job has been canceled - PAL calls it during the computation. More...
 
void removeLayer (Layer *layer)
 remove a layer More...
 
void setMaximumLineCandidatesPerMapUnit (double candidates)
 Sets the maximum number of line label candidates per map unit. More...
 
void setMaximumPolygonCandidatesPerMapUnitSquared (double candidates)
 Sets the maximum number of polygon label candidates per map unit squared. More...
 
void setPlacementVersion (Qgis::LabelPlacementEngineVersion placementVersion)
 Sets the placement engine version, which dictates how the label placement problem is solved. More...
 
void setShowPartialLabels (bool show)
 Sets whether partial labels show be allowed. More...
 
bool showPartialLabels () const
 Returns whether partial labels should be allowed. More...
 
QList< LabelPosition * > solveProblem (Problem *prob, QgsRenderContext &context, bool displayAll, QList< pal::LabelPosition * > *unlabeled=nullptr)
 Solves the labeling problem, selecting the best candidate locations for all labels and returns a list of these calculated label positions. More...
 

Static Public Attributes

static const QgsSettingsEntryIntegersettingsRenderingLabelCandidatesLimitLines = new QgsSettingsEntryInteger( QStringLiteral( "label-candidates-limit-lines" ), sTreePal, 0 )
 
static const QgsSettingsEntryIntegersettingsRenderingLabelCandidatesLimitPoints = new QgsSettingsEntryInteger( QStringLiteral( "label-candidates-limit-points" ), sTreePal, 0 )
 
static const QgsSettingsEntryIntegersettingsRenderingLabelCandidatesLimitPolygons = new QgsSettingsEntryInteger( QStringLiteral( "label-candidates-limit-polygons" ), sTreePal, 0 )
 
static QgsSettingsTreeNodesTreePal = QgsSettingsTree::sTreeRendering->createChildNode( QStringLiteral( "pal" ) )
 

Friends

class FeaturePart
 
class Layer
 
class Problem
 

Detailed Description

Main Pal labeling class.

A pal object will contains layers and global information such as which search method will be used.

Note
not available in Python bindings

Definition at line 82 of file pal.h.

Member Typedef Documentation

◆ FnIsCanceled

typedef bool( * pal::Pal::FnIsCanceled) (void *ctx)

Definition at line 128 of file pal.h.

Constructor & Destructor Documentation

◆ Pal() [1/2]

Pal::Pal ( )

Create an new pal instance.

Definition at line 60 of file pal.cpp.

◆ ~Pal()

Pal::~Pal ( )
default

◆ Pal() [2/2]

pal::Pal::Pal ( const Pal other)
delete

Pal cannot be copied.

Member Function Documentation

◆ addLayer()

Layer * Pal::addLayer ( QgsAbstractLabelProvider provider,
const QString &  layerName,
Qgis::LabelPlacement  arrangement,
double  defaultPriority,
bool  active,
bool  toLabel 
)

add a new layer

Parameters
providerProvider associated with the layer
layerNamelayer's name
arrangementHowto place candidates
defaultPrioritylayer's priority (0 is the best, 1 the worst)
activeis the layer is active (currently displayed)
toLabelthe layer will be labeled only if toLablel is true
Exceptions
PalException::LayerExists

Definition at line 87 of file pal.cpp.

◆ candidatesAreConflicting()

bool Pal::candidatesAreConflicting ( const LabelPosition lp1,
const LabelPosition lp2 
) const

Returns true if a labelling candidate lp1 conflicts with lp2.

Definition at line 724 of file pal.cpp.

◆ extractProblem()

std::unique_ptr< Problem > Pal::extractProblem ( const QgsRectangle extent,
const QgsGeometry mapBoundary,
QgsRenderContext context 
)

Extracts the labeling problem for the specified map extent - only features within this extent will be considered.

The mapBoundary argument specifies the actual geometry of the map boundary, which will be used to detect whether a label is visible (or partially visible) in the rendered map. This may differ from extent in the case of rotated or non-rectangular maps.

Definition at line 102 of file pal.cpp.

◆ globalCandidatesLimitLine()

int pal::Pal::globalCandidatesLimitLine ( ) const
inline

Returns the global candidates limit for line features, or 0 if no global limit is in effect.

This is an installation-wide setting which applies to all projects, and is set via QSettings. It can be used to place global limits on the number of candidates generated for line features in order to optimise map rendering speeds.

See also
globalCandidatesLimitPolygon()
globalCandidatesLimitPoint()

Definition at line 237 of file pal.h.

◆ globalCandidatesLimitPoint()

int pal::Pal::globalCandidatesLimitPoint ( ) const
inline

Returns the global candidates limit for point features, or 0 if no global limit is in effect.

This is an installation-wide setting which applies to all projects, and is set via QSettings. It can be used to place global limits on the number of candidates generated for point features in order to optimise map rendering speeds.

See also
globalCandidatesLimitLine()
globalCandidatesLimitPolygon()

Definition at line 225 of file pal.h.

◆ globalCandidatesLimitPolygon()

int pal::Pal::globalCandidatesLimitPolygon ( ) const
inline

Returns the global candidates limit for polygon features, or 0 if no global limit is in effect.

This is an installation-wide setting which applies to all projects, and is set via QSettings. It can be used to place global limits on the number of candidates generated for polygon features in order to optimise map rendering speeds.

See also
globalCandidatesLimitLine()
globalCandidatesLimitPoint()

Definition at line 249 of file pal.h.

◆ isCanceled()

bool pal::Pal::isCanceled ( )
inline

Check whether the job has been canceled.

Definition at line 134 of file pal.h.

◆ maximumLineCandidatesPerMapUnit()

double pal::Pal::maximumLineCandidatesPerMapUnit ( ) const
inline

Returns the maximum number of line label candidate positions per map unit.

See also
setMaximumLineCandidatesPerMapUnit()

Definition at line 178 of file pal.h.

◆ maximumPolygonCandidatesPerMapUnitSquared()

double pal::Pal::maximumPolygonCandidatesPerMapUnitSquared ( ) const
inline

Returns the maximum number of polygon label candidate positions per map unit squared.

See also
setMaximumPolygonCandidatesPerMapUnitSquared()

Definition at line 192 of file pal.h.

◆ operator=()

Pal& pal::Pal::operator= ( const Pal other)
delete

Pal cannot be copied.

◆ placementVersion()

Qgis::LabelPlacementEngineVersion Pal::placementVersion ( ) const

Returns the placement engine version, which dictates how the label placement problem is solved.

See also
setPlacementVersion()

Definition at line 714 of file pal.cpp.

◆ registerCancellationCallback()

void Pal::registerCancellationCallback ( Pal::FnIsCanceled  fnCanceled,
void *  context 
)

Register a function that returns whether this job has been canceled - PAL calls it during the computation.

Definition at line 614 of file pal.cpp.

◆ removeLayer()

void Pal::removeLayer ( Layer layer)

remove a layer

Parameters
layerlayer to remove

Definition at line 69 of file pal.cpp.

◆ setMaximumLineCandidatesPerMapUnit()

void pal::Pal::setMaximumLineCandidatesPerMapUnit ( double  candidates)
inline

Sets the maximum number of line label candidates per map unit.

See also
maximumLineCandidatesPerMapUnit()

Definition at line 185 of file pal.h.

◆ setMaximumPolygonCandidatesPerMapUnitSquared()

void pal::Pal::setMaximumPolygonCandidatesPerMapUnitSquared ( double  candidates)
inline

Sets the maximum number of polygon label candidates per map unit squared.

See also
maximumPolygonCandidatesPerMapUnitSquared()

Definition at line 199 of file pal.h.

◆ setPlacementVersion()

void Pal::setPlacementVersion ( Qgis::LabelPlacementEngineVersion  placementVersion)

Sets the placement engine version, which dictates how the label placement problem is solved.

See also
placementVersion()

Definition at line 719 of file pal.cpp.

◆ setShowPartialLabels()

void Pal::setShowPartialLabels ( bool  show)

Sets whether partial labels show be allowed.

See also
showPartialLabels()

Definition at line 709 of file pal.cpp.

◆ showPartialLabels()

bool Pal::showPartialLabels ( ) const

Returns whether partial labels should be allowed.

See also
setShowPartialLabels()

Definition at line 750 of file pal.cpp.

◆ solveProblem()

QList< LabelPosition * > Pal::solveProblem ( Problem prob,
QgsRenderContext context,
bool  displayAll,
QList< pal::LabelPosition * > *  unlabeled = nullptr 
)

Solves the labeling problem, selecting the best candidate locations for all labels and returns a list of these calculated label positions.

If displayAll is true, then the best positions for ALL labels will be returned, regardless of whether these labels overlap other labels.

If the optional unlabeled list is specified, it will be filled with a list of all feature labels which could not be placed in the returned solution (e.g. due to overlaps or other constraints).

Ownership of the returned labels is not transferred - it resides with the pal object.

Definition at line 621 of file pal.cpp.

Friends And Related Function Documentation

◆ FeaturePart

friend class FeaturePart
friend

Definition at line 85 of file pal.h.

◆ Layer

friend class Layer
friend

Definition at line 86 of file pal.h.

◆ Problem

friend class Problem
friend

Definition at line 84 of file pal.h.

Member Data Documentation

◆ settingsRenderingLabelCandidatesLimitLines

const QgsSettingsEntryInteger * Pal::settingsRenderingLabelCandidatesLimitLines = new QgsSettingsEntryInteger( QStringLiteral( "label-candidates-limit-lines" ), sTreePal, 0 )
static

Definition at line 92 of file pal.h.

◆ settingsRenderingLabelCandidatesLimitPoints

const QgsSettingsEntryInteger * Pal::settingsRenderingLabelCandidatesLimitPoints = new QgsSettingsEntryInteger( QStringLiteral( "label-candidates-limit-points" ), sTreePal, 0 )
static

Definition at line 91 of file pal.h.

◆ settingsRenderingLabelCandidatesLimitPolygons

const QgsSettingsEntryInteger * Pal::settingsRenderingLabelCandidatesLimitPolygons = new QgsSettingsEntryInteger( QStringLiteral( "label-candidates-limit-polygons" ), sTreePal, 0 )
static

Definition at line 93 of file pal.h.

◆ sTreePal

QgsSettingsTreeNode* pal::Pal::sTreePal = QgsSettingsTree::sTreeRendering->createChildNode( QStringLiteral( "pal" ) )
inlinestatic

Definition at line 89 of file pal.h.


The documentation for this class was generated from the following files: