Abstract base class for labeling engine rules. More...

#include <qgslabelingenginerule.h>

Inheritance diagram for QgsAbstractLabelingEngineRule:

[legend]

Public Member Functions
virtual	~QgsAbstractLabelingEngineRule ()

bool	active () const
	Returns `true` if the rule is active.

virtual void	alterCandidateCost (pal::LabelPosition *candidate, QgsLabelingEngineContext &context) const
	Provides an opportunity for the rule to alter the cost for a candidate.

virtual bool	candidateIsIllegal (const pal::LabelPosition *candidate, QgsLabelingEngineContext &context) const
	Returns `true` if a labeling candidate violates the rule and should be eliminated.

virtual bool	candidatesAreConflicting (const pal::LabelPosition lp1, const pal::LabelPosition lp2) const
	Returns `true` if a labeling candidate lp1 conflicts with lp2 after applying the rule.

virtual QgsAbstractLabelingEngineRule *	clone () const =0
	Creates a clone of this rule.

virtual QString	description () const
	Returns a user-friendly description of the rule.

virtual QString	displayType () const =0
	Returns a user-friendly, translated string representing the rule type.

virtual QString	id () const =0
	Returns a string uniquely identifying the rule subclass.

virtual bool	isAvailable () const
	Returns `true` if the rule is available for use within the current QGIS environment.

virtual QgsRectangle	modifyCandidateConflictSearchBoundingBox (const QgsRectangle &candidateBounds) const
	Returns a (possibly expanded) bounding box to use when searching for conflicts for a candidate.

QString	name () const
	Returns the name for this instance of the rule.

virtual bool	prepare (QgsRenderContext &context)=0
	Prepares the rule.

virtual void	readXml (const QDomElement &element, const QgsReadWriteContext &context)=0
	Reads the rule properties from an XML element.

virtual void	resolveReferences (const QgsProject *project)
	Resolves reference to layers from stored layer ID.

void	setActive (bool active)
	Sets whether the rule is active.

void	setName (const QString &name)
	Sets the name for this instance of the rule.

virtual void	writeXml (QDomDocument &doc, QDomElement &element, const QgsReadWriteContext &context) const =0
	Writes the rule properties to an XML element.

Protected Member Functions
virtual void	copyCommonProperties (QgsAbstractLabelingEngineRule *other) const
	Copies common properties from this object to an other.

Detailed Description

Abstract base class for labeling engine rules.

Labeling engine rules implement custom logic to modify the labeling solution for a map render, e.g. by preventing labels being placed which violate custom constraints.

Note: QgsAbstractLabelingEngineRule cannot be subclassed in Python. Use one of the existing implementations of this class instead.

Since: QGIS 3.40

Definition at line 132 of file qgslabelingenginerule.h.

Constructor & Destructor Documentation

◆ ~QgsAbstractLabelingEngineRule()

QgsAbstractLabelingEngineRule::~QgsAbstractLabelingEngineRule ( )

virtualdefault

Member Function Documentation

◆ active()

bool QgsAbstractLabelingEngineRule::active ( ) const

Returns true if the rule is active.

See also: setActive()

Definition at line 96 of file qgslabelingenginerule.cpp.

◆ alterCandidateCost()

void QgsAbstractLabelingEngineRule::alterCandidateCost	(	pal::LabelPosition *	candidate,
		QgsLabelingEngineContext &	context
	)		const

virtual

Provides an opportunity for the rule to alter the cost for a candidate.

The default implementation does nothing.

Reimplemented in QgsAbstractLabelingEngineRuleDistanceFromFeature.

Definition at line 75 of file qgslabelingenginerule.cpp.

◆ candidateIsIllegal()

bool QgsAbstractLabelingEngineRule::candidateIsIllegal	(	const pal::LabelPosition *	candidate,
		QgsLabelingEngineContext &	context
	)		const

virtual

Returns true if a labeling candidate violates the rule and should be eliminated.

The default implementation returns false.

Reimplemented in QgsAbstractLabelingEngineRuleDistanceFromFeature, and QgsLabelingEngineRuleAvoidLabelOverlapWithFeature.

Definition at line 70 of file qgslabelingenginerule.cpp.

◆ candidatesAreConflicting()

bool QgsAbstractLabelingEngineRule::candidatesAreConflicting	(	const pal::LabelPosition *	lp1,
		const pal::LabelPosition *	lp2
	)		const

virtual

Returns true if a labeling candidate lp1 conflicts with lp2 after applying the rule.

The default implementation returns false.

Reimplemented in QgsLabelingEngineRuleMinimumDistanceLabelToLabel.

Definition at line 60 of file qgslabelingenginerule.cpp.

◆ clone()

virtual QgsAbstractLabelingEngineRule * QgsAbstractLabelingEngineRule::clone ( ) const

pure virtual

Creates a clone of this rule.

The caller takes ownership of the returned object.

Implemented in QgsLabelingEngineRuleMinimumDistanceLabelToFeature, QgsLabelingEngineRuleMaximumDistanceLabelToFeature, QgsLabelingEngineRuleMinimumDistanceLabelToLabel, and QgsLabelingEngineRuleAvoidLabelOverlapWithFeature.

◆ copyCommonProperties()

void QgsAbstractLabelingEngineRule::copyCommonProperties ( QgsAbstractLabelingEngineRule * other ) const

protectedvirtual

Copies common properties from this object to an other.

Reimplemented in QgsAbstractLabelingEngineRuleDistanceFromFeature.

Definition at line 80 of file qgslabelingenginerule.cpp.

◆ description()

QString QgsAbstractLabelingEngineRule::description ( ) const

virtual

Returns a user-friendly description of the rule.

This should include the rule name() if set, and other useful details for users to quickly identify the rule's purpose when shown in a tooltip.

The returned string may contain HTML formatting.

Reimplemented in QgsLabelingEngineRuleMinimumDistanceLabelToFeature, QgsLabelingEngineRuleMaximumDistanceLabelToFeature, QgsLabelingEngineRuleMinimumDistanceLabelToLabel, and QgsLabelingEngineRuleAvoidLabelOverlapWithFeature.

Definition at line 91 of file qgslabelingenginerule.cpp.

◆ displayType()

virtual QString QgsAbstractLabelingEngineRule::displayType ( ) const

pure virtual

Returns a user-friendly, translated string representing the rule type.

Implemented in QgsLabelingEngineRuleMinimumDistanceLabelToFeature, QgsLabelingEngineRuleMaximumDistanceLabelToFeature, QgsLabelingEngineRuleMinimumDistanceLabelToLabel, and QgsLabelingEngineRuleAvoidLabelOverlapWithFeature.

◆ id()

virtual QString QgsAbstractLabelingEngineRule::id ( ) const

pure virtual

Returns a string uniquely identifying the rule subclass.

Implemented in QgsLabelingEngineRuleMinimumDistanceLabelToFeature, QgsLabelingEngineRuleMaximumDistanceLabelToFeature, QgsLabelingEngineRuleMinimumDistanceLabelToLabel, and QgsLabelingEngineRuleAvoidLabelOverlapWithFeature.

◆ isAvailable()

bool QgsAbstractLabelingEngineRule::isAvailable ( ) const

virtual

Returns true if the rule is available for use within the current QGIS environment.

The base class method returns true.

Rules can return false if required dependencies are not available, e.g. if a library version is too old for the rule.

Reimplemented in QgsAbstractLabelingEngineRuleDistanceFromFeature, and QgsLabelingEngineRuleMinimumDistanceLabelToLabel.

Definition at line 86 of file qgslabelingenginerule.cpp.

◆ modifyCandidateConflictSearchBoundingBox()

QgsRectangle QgsAbstractLabelingEngineRule::modifyCandidateConflictSearchBoundingBox ( const QgsRectangle & candidateBounds ) const

virtual

Returns a (possibly expanded) bounding box to use when searching for conflicts for a candidate.

The return value is permitted to grow the bounding box, but may NOT shrink it.

The default implementation returns the same bounds.

Reimplemented in QgsLabelingEngineRuleMinimumDistanceLabelToLabel.

Definition at line 65 of file qgslabelingenginerule.cpp.

◆ name()

QString QgsAbstractLabelingEngineRule::name ( ) const

inline

Returns the name for this instance of the rule.

The name is a user-configurable value which helps them identify and describe the rule within their projects.

See also: setName()

Definition at line 209 of file qgslabelingenginerule.h.

◆ prepare()

virtual bool QgsAbstractLabelingEngineRule::prepare ( QgsRenderContext & context )

pure virtual

Prepares the rule.

This must be called on the main render thread, prior to commencing the render operation. Thread sensitive logic (such as creation of feature sources) can be performed in this method.

Implemented in QgsAbstractLabelingEngineRuleDistanceFromFeature, QgsLabelingEngineRuleMinimumDistanceLabelToLabel, and QgsLabelingEngineRuleAvoidLabelOverlapWithFeature.

◆ readXml()

virtual void QgsAbstractLabelingEngineRule::readXml	(	const QDomElement &	element,
		const QgsReadWriteContext &	context
	)

pure virtual

Reads the rule properties from an XML element.

See also: resolveReferences(); writeXml()

Implemented in QgsAbstractLabelingEngineRuleDistanceFromFeature, QgsLabelingEngineRuleMinimumDistanceLabelToLabel, and QgsLabelingEngineRuleAvoidLabelOverlapWithFeature.

◆ resolveReferences()

void QgsAbstractLabelingEngineRule::resolveReferences ( const QgsProject * project )

virtual

Resolves reference to layers from stored layer ID.

Should be called following a call readXml().

Reimplemented in QgsAbstractLabelingEngineRuleDistanceFromFeature, QgsLabelingEngineRuleMinimumDistanceLabelToLabel, and QgsLabelingEngineRuleAvoidLabelOverlapWithFeature.

Definition at line 55 of file qgslabelingenginerule.cpp.

◆ setActive()

void QgsAbstractLabelingEngineRule::setActive ( bool active )

Sets whether the rule is active.

See also: active()

Definition at line 101 of file qgslabelingenginerule.cpp.

◆ setName()

void QgsAbstractLabelingEngineRule::setName ( const QString & name )

inline

Sets the name for this instance of the rule.

The name is a user-configurable value which helps them identify and describe the rule within their projects.

See also: name()

Definition at line 219 of file qgslabelingenginerule.h.

◆ writeXml()

virtual void QgsAbstractLabelingEngineRule::writeXml	(	QDomDocument &	doc,
		QDomElement &	element,
		const QgsReadWriteContext &	context
	)		const

pure virtual

Writes the rule properties to an XML element.

See also: readXml()

Implemented in QgsAbstractLabelingEngineRuleDistanceFromFeature, QgsLabelingEngineRuleMinimumDistanceLabelToLabel, and QgsLabelingEngineRuleAvoidLabelOverlapWithFeature.

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

/build/qgis-3.39.0+git20240920+d85f3c2a281+99sid/src/core/labeling/rules/qgslabelingenginerule.h
/build/qgis-3.39.0+git20240920+d85f3c2a281+99sid/src/core/labeling/rules/qgslabelingenginerule.cpp

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~QgsAbstractLabelingEngineRule()

Member Function Documentation

◆ active()

◆ alterCandidateCost()

◆ candidateIsIllegal()

◆ candidatesAreConflicting()

◆ clone()

◆ copyCommonProperties()

◆ description()

◆ displayType()

◆ id()

◆ isAvailable()

◆ modifyCandidateConflictSearchBoundingBox()

◆ name()

◆ prepare()

◆ readXml()

◆ resolveReferences()

◆ setActive()

◆ setName()

◆ writeXml()