Class: QgsLabelingEngineSettings

Stores global configuration for labeling engine.

class qgis.core.QgsLabelingEngineSettings[source]

Bases: object

Chain = 0
Falp = 4
Flag

alias of LabelingFlag

Flags

alias of LabelingFlags

PlacementEngineVersion

alias of LabelPlacementEngineVersion

Popmusic_Chain = 2
Popmusic_Tabu = 1
Popmusic_Tabu_Chain = 3
class Search

Bases: int

addRule(self, rule: QgsAbstractLabelingEngineRule | None)[source]

Adds a labeling engine rule which must be satisfied while placing labels.

Ownership of the rule is transferred to the settings.

See also

rules()

See also

setRules()

Added in version 3.40.

Parameters:

rule (Optional[QgsAbstractLabelingEngineRule])

clear(self)[source]

Returns the configuration to the defaults

defaultTextRenderFormat(self) → Qgis.TextRenderFormat[source]

Returns the default text rendering format for the labels.

See also

setDefaultTextRenderFormat()

Added in version 3.4.3.

Return type:

Qgis.TextRenderFormat

flags(self) → Qgis.LabelingFlags[source]

Gets flags of the labeling engine

Return type:

Qgis.LabelingFlags

maximumLineCandidatesPerCm(self) → float[source]

Returns the maximum number of line label candidate positions per centimeter.

See also

setMaximumLineCandidatesPerCm()

Added in version 3.12.

Return type:

float

maximumPolygonCandidatesPerCmSquared(self) → float[source]

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

See also

setMaximumPolygonCandidatesPerCmSquared()

Added in version 3.12.

Return type:

float

numCandidatePositions(self)[source]

Gets number of candidate positions that will be generated for each label feature.

Deprecated since version 3.12: Use maximumPolygonCandidatesPerCmSquared() and maximumLineCandidatesPerCm() instead.

placementVersion(self) → Qgis.LabelPlacementEngineVersion[source]

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

See also

setPlacementVersion()

Added in version 3.10.2.

Return type:

Qgis.LabelPlacementEngineVersion

readSettingsFromProject(self, project: QgsProject | None)[source]

Read configuration of the labeling engine from a project

Note

Both this method and readXml() must be called to completely restore the object’s state from a project.

Parameters:

project (Optional[QgsProject])

readXml(self, element: QDomElement, context: QgsReadWriteContext)[source]

Reads the label engine settings from an XML element.

Note

Both this method and readSettingsFromProject() must be called to completely restore the object’s state from a project.

Note

resolveReferences() must be called following this method.

See also

writeXml()

See also

readSettingsFromProject()

Added in version 3.40.

Parameters:
resolveReferences(self, project: QgsProject | None)[source]

Resolves reference to layers from stored layer ID.

Should be called following a call readXml().

Added in version 3.40.

Parameters:

project (Optional[QgsProject])

rules(self) → List[QgsAbstractLabelingEngineRule]

Returns a list of labeling engine rules which must be satisfied while placing labels.

See also

addRule()

See also

setRules()

Added in version 3.40.

Return type:

List[QgsAbstractLabelingEngineRule]

searchMethod(self) → QgsLabelingEngineSettings.Search[source]

Which search method to use for removal collisions between labels

Deprecated since version 3.10: Chain is always used.

Return type:

QgsLabelingEngineSettings.Search

setDefaultTextRenderFormat(self, format: Qgis.TextRenderFormat)[source]

Sets the default text rendering format for the labels.

See also

defaultTextRenderFormat()

Added in version 3.4.3.

Parameters:

format (Qgis.TextRenderFormat)

setFlag(self, f: Qgis.LabelingFlag, enabled: bool = True)[source]

Sets whether a particual flag is enabled

Parameters:
setFlags(self, flags: Qgis.LabelingFlags | Qgis.LabelingFlag)[source]

Sets flags of the labeling engine

Parameters:

flags (Union[Qgis.LabelingFlags, Qgis.LabelingFlag])

setMaximumLineCandidatesPerCm(self, candidates: float)[source]

Sets the maximum number of line label candidates per centimeter.

See also

maximumLineCandidatesPerCm()

Added in version 3.12.

Parameters:

candidates (float)

setMaximumPolygonCandidatesPerCmSquared(self, candidates: float)[source]

Sets the maximum number of polygon label candidates per centimeter squared.

See also

maximumPolygonCandidatesPerCmSquared()

Added in version 3.12.

Parameters:

candidates (float)

setNumCandidatePositions(self, candPoint: int, candLine: int, candPolygon: int)[source]

Sets the number of candidate positions that will be generated for each label feature.

Deprecated since version 3.12: Use setMaximumPolygonCandidatesPerCmSquared() and setMaximumLineCandidatesPerCm() instead.

Parameters:

  • candPoint (int)

  • candLine (int)

  • candPolygon (int)

setPlacementVersion(self, version: Qgis.LabelPlacementEngineVersion)[source]

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

See also

placementVersion()

Added in version 3.10.2.

Parameters:

version (Qgis.LabelPlacementEngineVersion)

setRules(self, rules: Iterable[QgsAbstractLabelingEngineRule])[source]

Sets the labeling engine rules which must be satisfied while placing labels.

Ownership of the rules are transferred to the settings.

See also

addRule()

See also

rules()

Added in version 3.40.

Parameters:

rules (Iterable[QgsAbstractLabelingEngineRule])

setSearchMethod(self, s: QgsLabelingEngineSettings.Search)[source]

Used to set which search method to use for removal collisions between labels

Deprecated since version 3.10: Chain is always used.

Parameters:

s (QgsLabelingEngineSettings.Search)

setUnplacedLabelColor(self, color: QColor | Qt.GlobalColor)[source]

Sets the color to use when rendering unplaced labels.

See also

unplacedLabelColor()

Added in version 3.10.

Parameters:

color (Union[QColor, Qt.GlobalColor])

testFlag(self, f: Qgis.LabelingFlag) → bool[source]

Test whether a particular flag is enabled

Parameters:

f (Qgis.LabelingFlag)

Return type:

bool

unplacedLabelColor(self) → QColor[source]

Returns the color to use when rendering unplaced labels.

See also

setUnplacedLabelColor()

Added in version 3.10.

Return type:

QColor

writeSettingsToProject(self, project: QgsProject | None)[source]

Write configuration of the labeling engine to a project.

Note

Both this method and writeXml() must be called to completely store the object’s state in a project.

Parameters:

project (Optional[QgsProject])

writeXml(self, doc: QDomDocument, element: QDomElement, context: QgsReadWriteContext)[source]

Writes the label engine settings to an XML element.

Note

Both this method and writeSettingsToProject() must be called to completely store the object’s state in a project.

See also

readXml()

See also

writeSettingsToProject()

Added in version 3.40.

Parameters: