Main Pal labeling class. More...

#include <pal.h>

Public Types
typedef bool(*	FnIsCanceled) (void *ctx)

Public Member Functions
	Pal ()

	Pal (const Pal &other)=delete

	~Pal ()

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

bool	candidatesAreConflicting (const LabelPosition lp1, const LabelPosition lp2) const
	Returns `true` if a labelling candidate lp1 conflicts with lp2.

std::unique_ptr< Problem >	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.

int	globalCandidatesLimitLine () const
	Returns the global candidates limit for line features, or 0 if no global limit is in effect.

int	globalCandidatesLimitPoint () const
	Returns the global candidates limit for point features, or 0 if no global limit is in effect.

int	globalCandidatesLimitPolygon () const
	Returns the global candidates limit for polygon features, or 0 if no global limit is in effect.

bool	isCanceled ()
	Check whether the job has been canceled.

double	maximumLineCandidatesPerMapUnit () const
	Returns the maximum number of line label candidate positions per map unit.

double	maximumPolygonCandidatesPerMapUnitSquared () const
	Returns the maximum number of polygon label candidate positions per map unit squared.

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

Qgis::LabelPlacementEngineVersion	placementVersion () const
	Returns the placement engine version, which dictates how the label placement problem is solved.

void	registerCancellationCallback (FnIsCanceled fnCanceled, void *context)
	Register a function that returns whether this job has been canceled - PAL calls it during the computation.

void	removeLayer (Layer *layer)
	remove a layer

QList< QgsAbstractLabelingEngineRule * >	rules () const
	Returns the rules which the labeling solution must satisify.

void	setMaximumLineCandidatesPerMapUnit (double candidates)
	Sets the maximum number of line label candidates per map unit.

void	setMaximumPolygonCandidatesPerMapUnitSquared (double candidates)
	Sets the maximum number of polygon label candidates per map unit squared.

void	setPlacementVersion (Qgis::LabelPlacementEngineVersion placementVersion)
	Sets the placement engine version, which dictates how the label placement problem is solved.

void	setRules (const QList< QgsAbstractLabelingEngineRule * > &rules)
	Sets rules which the labeling solution must satisfy.

void	setShowPartialLabels (bool show)
	Sets whether partial labels show be allowed.

bool	showPartialLabels () const
	Returns whether partial labels should be allowed.

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.

Static Public Attributes
static const QgsSettingsEntryInteger *	settingsRenderingLabelCandidatesLimitLines = new QgsSettingsEntryInteger( QStringLiteral( "label-candidates-limit-lines" ), sTreePal, 0 )

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

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

static QgsSettingsTreeNode *	sTreePal = 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 122 of file pal.h.

Constructor & Destructor Documentation

◆ Pal() [1/2]

Pal::Pal ( )

Definition at line 60 of file pal.cpp.

◆ ~Pal()

Pal::~Pal ( )

default

◆ Pal() [2/2]

pal::Pal::Pal ( const Pal & other )

delete

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

provider	Provider associated with the layer
layerName	layer's name
arrangement	Howto place candidates
defaultPriority	layer's priority (0 is the best, 1 the worst)
active	is the layer is active (currently displayed)
toLabel	the 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 752 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.

This method:

preprocesses features, eg merging connected lines, chopping features at repeat distances
creates label candidates for every feature
purges candidates outside the map extent (respecting whether partial labels should be shown at the map boundary)
creates default fallback candidates for features with no valid candidates
collects obstacles
calculates candidate costs
calculates overlaps/conflicts
eliminates hard conflicts (forbidden placement)

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 242 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 230 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 254 of file pal.h.

◆ isCanceled()

bool pal::Pal::isCanceled ( )

inline

Check whether the job has been canceled.

Definition at line 128 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 183 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 197 of file pal.h.

◆ operator=()

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

delete

◆ 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 742 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 643 of file pal.cpp.

◆ removeLayer()

void Pal::removeLayer ( Layer * layer )

remove a layer

Parameters

layer layer to remove

Definition at line 69 of file pal.cpp.

◆ rules()

QList< QgsAbstractLabelingEngineRule * > pal::Pal::rules ( ) const

inline

Returns the rules which the labeling solution must satisify.

See also: setRules()

Since: QGIS 3.40

Definition at line 278 of file pal.h.

◆ 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 190 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 204 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 747 of file pal.cpp.

◆ setRules()

void Pal::setRules ( const QList< QgsAbstractLabelingEngineRule * > & rules )

Sets rules which the labeling solution must satisfy.

Ownership of the rules are not transferred to the engine, and it is the caller's responsibility to ensure that the lifetime of the rules exceeds that of the pal job.

See also: rules()

Since: QGIS 3.40

Definition at line 782 of file pal.cpp.

◆ setShowPartialLabels()

void Pal::setShowPartialLabels ( bool show )

Sets whether partial labels show be allowed.

See also: showPartialLabels()

Definition at line 737 of file pal.cpp.

◆ showPartialLabels()

bool Pal::showPartialLabels ( ) const

Returns whether partial labels should be allowed.

See also: setShowPartialLabels()

Definition at line 797 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 650 of file pal.cpp.

Friends And Related Symbol 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:

/build/qgis-3.41.0+git20241214+cea29feecf2+99sid/src/core/pal/pal.h
/build/qgis-3.41.0+git20241214+cea29feecf2+99sid/src/core/pal/pal.cpp

Public Types

Public Member Functions

Static Public Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ FnIsCanceled

Constructor & Destructor Documentation

◆ Pal() [1/2]

◆ ~Pal()

◆ Pal() [2/2]

Member Function Documentation

◆ addLayer()

◆ candidatesAreConflicting()

◆ extractProblem()

◆ globalCandidatesLimitLine()

◆ globalCandidatesLimitPoint()

◆ globalCandidatesLimitPolygon()

◆ isCanceled()

◆ maximumLineCandidatesPerMapUnit()

◆ maximumPolygonCandidatesPerMapUnitSquared()

◆ operator=()

◆ placementVersion()

◆ registerCancellationCallback()

◆ removeLayer()

◆ rules()

◆ setMaximumLineCandidatesPerMapUnit()

◆ setMaximumPolygonCandidatesPerMapUnitSquared()

◆ setPlacementVersion()

◆ setRules()

◆ setShowPartialLabels()

◆ showPartialLabels()

◆ solveProblem()

Friends And Related Symbol Documentation

◆ FeaturePart

◆ Layer

◆ Problem

Member Data Documentation

◆ settingsRenderingLabelCandidatesLimitLines

◆ settingsRenderingLabelCandidatesLimitPoints

◆ settingsRenderingLabelCandidatesLimitPolygons

◆ sTreePal