Class: QgsTextBackgroundSettings¶

class qgis.core.QgsTextBackgroundSettings¶

Bases: sip.wrapper

Container for settings relating to a text background object.

Note

QgsTextBackgroundSettings objects are implicitly shared.

New in version 3.0.

QgsTextBackgroundSettings()

QgsTextBackgroundSettings(other: QgsTextBackgroundSettings) Copy constructor.

Parameters:

other –

source QgsTextBackgroundSettings

Methods

`blendMode`	Returns the blending mode used for drawing the background shape.
`enabled`	Returns whether the background is enabled.
`fillColor`	Returns the color used for filing the background shape.
`fillSymbol`	Returns the fill symbol to be rendered in the background.
`joinStyle`	Returns the join style used for drawing the background shape.
`markerSymbol`	Returns the marker symbol to be rendered in the background.
`offset`	Returns the offset used for drawing the background shape.
`offsetMapUnitScale`	Returns the map unit scale object for the shape offset.
`offsetUnit`	Returns the units used for the shape's offset.
`opacity`	Returns the background shape's opacity.
`paintEffect`	Returns the current paint effect for the background shape.
`radii`	Returns the radii used for rounding the corners of shapes.
`radiiMapUnitScale`	Returns the map unit scale object for the shape radii.
`radiiUnit`	Returns the units used for the shape's radii.
`readFromLayer`	Reads settings from a layer's custom properties (for QGIS 2.x projects).
`readXml`	Read settings from a DOM element.
`referencedFields`	Returns all field names referenced by the configuration (e.g. from data defined properties).
`rotation`	Returns the rotation for the background shape, in degrees clockwise.
`rotationType`	Returns the method used for rotating the background shape.
`setBlendMode`	Sets the blending mode used for drawing the background shape.
`setEnabled`	Sets whether the text background will be drawn.
`setFillColor`	Sets the color used for filing the background shape.
`setFillSymbol`	Sets the current fill `symbol` for the background shape.
`setJoinStyle`	Sets the join style used for drawing the background shape.
`setMarkerSymbol`	Sets the current marker `symbol` for the background shape.
`setOffset`	Sets the offset used for drawing the background shape.
`setOffsetMapUnitScale`	Sets the map unit scale object for the shape offset.
`setOffsetUnit`	Sets the units used for the shape's offset.
`setOpacity`	Sets the background shape's opacity.
`setPaintEffect`	Sets the current paint `effect` for the background shape.
`setRadii`	Sets the radii used for rounding the corners of shapes.
`setRadiiMapUnitScale`	Sets the map unit scale object for the shape radii.
`setRadiiUnit`	Sets the units used for the shape's radii.
`setRotation`	Sets the `rotation` for the background shape, in degrees clockwise.
`setRotationType`	Sets the method used for rotating the background shape.
`setSize`	Sets the size of the background shape.
`setSizeMapUnitScale`	Sets the map unit scale object for the shape size.
`setSizeType`	Sets the method used to determine the size of the background shape (e.g., fixed size or buffer around text).
`setSizeUnit`	Sets the units used for the shape's size.
`setStrokeColor`	Sets the color used for outlining the background shape.
`setStrokeWidth`	Sets the width of the shape's stroke (stroke).
`setStrokeWidthMapUnitScale`	Sets the map unit scale object for the shape stroke width.
`setStrokeWidthUnit`	Sets the units used for the shape's stroke width.
`setSvgFile`	Sets the path to the background SVG file.
`setType`	Sets the type of background shape to draw (e.g., square, ellipse, SVG).
`size`	Returns the size of the background shape.
`sizeMapUnitScale`	Returns the map unit scale object for the shape size.
`sizeType`	Returns the method used to determine the size of the background shape (e.g., fixed size or buffer around text).
`sizeUnit`	Returns the units used for the shape's size.
`strokeColor`	Returns the color used for outlining the background shape.
`strokeWidth`	Returns the width of the shape's stroke (stroke).
`strokeWidthMapUnitScale`	Returns the map unit scale object for the shape stroke width.
`strokeWidthUnit`	Returns the units used for the shape's stroke width.
`svgFile`	Returns the absolute path to the background SVG file, if set.
`type`	Returns the type of background shape (e.g., square, ellipse, SVG).
`updateDataDefinedProperties`	Updates the format by evaluating current values of data defined properties.
`writeXml`	Write settings into a DOM element.

Attributes

`RotationFixed`
`RotationOffset`
`RotationSync`
`ShapeCircle`
`ShapeEllipse`
`ShapeMarkerSymbol`
`ShapeRectangle`
`ShapeSVG`
`ShapeSquare`
`SizeBuffer`
`SizeFixed`
`SizePercent`

RotationFixed = 2¶

RotationOffset = 1¶

RotationSync = 0¶

class RotationType¶: Bases: int

ShapeCircle = 3¶

ShapeEllipse = 2¶

ShapeMarkerSymbol = 5¶

ShapeRectangle = 0¶

ShapeSVG = 4¶

ShapeSquare = 1¶

class ShapeType¶: Bases: int

SizeBuffer = 0¶

SizeFixed = 1¶

SizePercent = 2¶

class SizeType¶: Bases: int

blendMode(self) → QPainter.CompositionMode¶

Returns the blending mode used for drawing the background shape.

See also

setBlendMode()

Return type:: QPainter.CompositionMode

enabled(self) → bool¶

Returns whether the background is enabled.

See also

setEnabled()

Return type:: bool

fillColor(self) → QColor¶

Returns the color used for filing the background shape.

See also

setFillColor()

See also

strokeColor()

Note

As of QGIS 3.20, using this function is only recommended for SVG backgrounds, while other background types should be configured through their symbols.

Return type:: QColor

fillSymbol(self) → QgsFillSymbol¶

Returns the fill symbol to be rendered in the background. Ownership remains with the background settings.

Note

This is only used when the type() is QgsTextBackgroundSettings.ShapeRectangle, QgsTextBackgroundSettings.ShapeSquare, QgsTextBackgroundSettings.ShapeCircle or QgsTextBackgroundSettings.ShapeEllipse

See also

setFillSymbol()

New in version 3.20.

Return type:: QgsFillSymbol

joinStyle(self) → Qt.PenJoinStyle¶

Returns the join style used for drawing the background shape.

See also

setJoinStyle()

Return type:: Qt.PenJoinStyle

markerSymbol(self) → QgsMarkerSymbol¶

Returns the marker symbol to be rendered in the background. Ownership remains with the background settings.

Note

This is only used when the type() is QgsTextBackgroundSettings.ShapeMarkerSymbol.

See also

setMarkerSymbol()

New in version 3.10.

Return type:: QgsMarkerSymbol

offset(self) → QPointF¶

Returns the offset used for drawing the background shape. Units are determined via offsetUnit().

See also

setOffset()

See also

offsetUnit()

Return type:: QPointF

offsetMapUnitScale(self) → QgsMapUnitScale¶

Returns the map unit scale object for the shape offset. This is only used if the offsetUnit() is set to QgsUnitTypes.RenderMapUnit.

See also

setOffsetMapUnitScale()

See also

offsetUnit()

Return type:: QgsMapUnitScale

offsetUnit(self) → Qgis.RenderUnit¶

Returns the units used for the shape’s offset.

See also

setOffsetUnit()

See also

offset()

Return type:: Qgis.RenderUnit

opacity(self) → float¶

Returns the background shape’s opacity. The opacity is a double value between 0 (fully transparent) and 1 (totally opaque).

See also

setOpacity()

Return type:: float

paintEffect(self) → QgsPaintEffect¶

Returns the current paint effect for the background shape.

Return type:: QgsPaintEffect
Returns:: paint effect

See also

setPaintEffect()

radii(self) → QSizeF¶

Returns the radii used for rounding the corners of shapes. Units are retrieved through radiiUnit().

See also

setRadii()

See also

radiiUnit()

Return type:: QSizeF

radiiMapUnitScale(self) → QgsMapUnitScale¶

Returns the map unit scale object for the shape radii. This is only used if the radiiUnit() is set to QgsUnitTypes.RenderMapUnit.

See also

setRadiiMapUnitScale()

See also

radiiUnit()

Return type:: QgsMapUnitScale

radiiUnit(self) → Qgis.RenderUnit¶

Returns the units used for the shape’s radii.

See also

setRadiiUnit()

See also

radii()

Return type:: Qgis.RenderUnit

readFromLayer(self, layer: QgsVectorLayer)¶

Reads settings from a layer’s custom properties (for QGIS 2.x projects).

Parameters:: layer (QgsVectorLayer) – source vector layer

readXml(self, elem: QDomElement, context: QgsReadWriteContext)¶

Read settings from a DOM element.

See also

writeXml()

Parameters:

elem (QDomElement) –
context (QgsReadWriteContext) –

referencedFields(self, context: QgsRenderContext) → Set[str]¶

Returns all field names referenced by the configuration (e.g. from data defined properties).

New in version 3.14.

Parameters:: context (QgsRenderContext) –
Return type:: Set[str]

rotation(self) → float¶

Returns the rotation for the background shape, in degrees clockwise.

See also

rotationType()

See also

setRotation()

Return type:: float

rotationType(self) → QgsTextBackgroundSettings.RotationType¶

Returns the method used for rotating the background shape.

See also

setRotationType()

See also

rotation()

Return type:: QgsTextBackgroundSettings.RotationType

setBlendMode(self, mode: QPainter.CompositionMode)¶

Sets the blending mode used for drawing the background shape.

Parameters:: mode (QPainter.CompositionMode) – blending mode

See also

blendMode()

setEnabled(self, enabled: bool)¶

Sets whether the text background will be drawn.

Parameters:: enabled (bool) – set to True to draw background

See also

enabled()

setFillColor(self, color: QColor | Qt.GlobalColor)¶

Sets the color used for filing the background shape.

Parameters:: color (Union[QColor) – background color

See also

fillColor()

See also

setStrokeColor()

Note

As of QGIS 3.20, using this function is only recommended for SVG backgrounds, while other background types should be configured through their symbols.

setFillSymbol(self, symbol: QgsFillSymbol)¶

Sets the current fill symbol for the background shape. Ownership is transferred to the background settings.

Note

This is only used when the type() is QgsTextBackgroundSettings.ShapeRectangle, QgsTextBackgroundSettings.ShapeSquare, QgsTextBackgroundSettings.ShapeCircle or QgsTextBackgroundSettings.ShapeEllipse

See also

fillSymbol()

New in version 3.20.

Parameters:: symbol (QgsFillSymbol) –

setJoinStyle(self, style: Qt.PenJoinStyle)¶

Sets the join style used for drawing the background shape.

Parameters:: style (Qt.PenJoinStyle) – join style

See also

joinStyle()

Note

As of QGIS 3.20, using this function is only recommended for SVG backgrounds, while other background types should be configured through their symbols.

setMarkerSymbol(self, symbol: QgsMarkerSymbol)¶

Sets the current marker symbol for the background shape. Ownership is transferred to the background settings.

Note

This is only used when the type() is QgsTextBackgroundSettings.ShapeMarkerSymbol.

See also

markerSymbol()

New in version 3.10.

Parameters:: symbol (QgsMarkerSymbol) –

setOffset(self, offset: QPointF | QPoint)¶

Sets the offset used for drawing the background shape. Units are specified using setOffsetUnit().

Parameters:: offset (Union[QPointF) – offset for shape

See also

offset()

See also

setOffsetUnit()

setOffsetMapUnitScale(self, scale: QgsMapUnitScale)¶

Sets the map unit scale object for the shape offset. This is only used if the offsetUnit() is set to QgsUnitTypes.RenderMapUnit.

Parameters:: scale (QgsMapUnitScale) – scale for shape offset

See also

offsetMapUnitScale()

See also

setOffsetUnit()

setOffsetUnit(self, units: Qgis.RenderUnit)¶

Sets the units used for the shape’s offset.

Parameters:: units (Qgis.RenderUnit) – offset units

See also

offsetUnit()

See also

setOffset()

setOpacity(self, opacity: float)¶

Sets the background shape’s opacity.

Parameters:: opacity (float) – opacity as a double value between 0 (fully transparent) and 1 (totally opaque)

See also

opacity()

setPaintEffect(self, effect: QgsPaintEffect)¶

Sets the current paint effect for the background shape.

Parameters:: effect (QgsPaintEffect) – paint effect. Ownership is transferred to the background settings.

See also

paintEffect()

setRadii(self, radii: QSizeF)¶

Sets the radii used for rounding the corners of shapes. This is only used if type() is set to QgsTextBackgroundSettings.ShapeRectangle or QgsTextBackgroundSettings.ShapeSquare.

Parameters:: radii (QSizeF) – QSizeF representing horizontal and vertical radii for rounded corners. Units are specified through setRadiiUnit()

See also

radii()

See also

setRadiiUnit()

setRadiiMapUnitScale(self, scale: QgsMapUnitScale)¶

Sets the map unit scale object for the shape radii. This is only used if the radiiUnit() is set to QgsUnitTypes.RenderMapUnit.

Parameters:: scale (QgsMapUnitScale) – scale for shape radii

See also

radiiMapUnitScale()

See also

setRadiiUnit()

setRadiiUnit(self, units: Qgis.RenderUnit)¶

Sets the units used for the shape’s radii.

Parameters:: units (Qgis.RenderUnit) – radii units

See also

radiiUnit()

See also

setRadii()

setRotation(self, rotation: float)¶

Sets the rotation for the background shape, in degrees clockwise.

See also

rotation()

See also

setRotationType()

Parameters:: rotation (float) –

setRotationType(self, type: QgsTextBackgroundSettings.RotationType)¶

Sets the method used for rotating the background shape.

Parameters:: type (QgsTextBackgroundSettings.RotationType) – rotation method

See also

rotationType()

See also

setRotation()

setSize(self, size: QSizeF)¶

Sets the size of the background shape. The meaning of the size depends on the current sizeType(), e.g., for size types of QgsTextBackgroundSettings.SizeFixed the size will represent the actual width and height of the shape, for QgsTextBackgroundSettings.SizeBuffer the size will represent the horizontal and vertical margins to add to the text when calculating the size of the shape.

Parameters:: size (QSizeF) – QSizeF representing horizontal and vertical size components for shape

See also

size()

See also

setSizeType()

setSizeMapUnitScale(self, scale: QgsMapUnitScale)¶

Sets the map unit scale object for the shape size. This is only used if the sizeUnit() is set to QgsUnitTypes.RenderMapUnit.

Parameters:: scale (QgsMapUnitScale) – scale for shape size

See also

sizeMapUnitScale()

See also

setSizeUnit()

setSizeType(self, type: QgsTextBackgroundSettings.SizeType)¶

Sets the method used to determine the size of the background shape (e.g., fixed size or buffer around text).

Parameters:: type (QgsTextBackgroundSettings.SizeType) – size method

See also

sizeType()

See also

setSize()

setSizeUnit(self, unit: Qgis.RenderUnit)¶

Sets the units used for the shape’s size. This value has no meaning if the sizeType() is set to QgsTextBackgroundSettings.SizePercent.

Parameters:: unit (Qgis.RenderUnit) – size units

See also

sizeUnit()

See also

setSizeType()

See also

setSize()

setStrokeColor(self, color: QColor | Qt.GlobalColor)¶

Sets the color used for outlining the background shape.

Parameters:: color (Union[QColor) – stroke color

See also

strokeColor()

See also

setFillColor()

setStrokeWidth(self, width: float)¶

Sets the width of the shape’s stroke (stroke). Units are specified through setStrokeWidthUnit().

See also

strokeWidth()

See also

setStrokeWidthUnit()

Note

As of QGIS 3.20, using this function is only recommended for SVG backgrounds, while other background types should be configured through their symbols.

Parameters:: width (float) –

setStrokeWidthMapUnitScale(self, scale: QgsMapUnitScale)¶

Sets the map unit scale object for the shape stroke width. This is only used if the strokeWidthUnit() is set to QgsUnitTypes.RenderMapUnit.

Parameters:: scale (QgsMapUnitScale) – scale for shape stroke width

See also

strokeWidthMapUnitScale()

See also

setStrokeWidthUnit()

Note

As of QGIS 3.20, using this function is only recommended for SVG backgrounds, while other background types should be configured through their symbols.

setStrokeWidthUnit(self, units: Qgis.RenderUnit)¶

Sets the units used for the shape’s stroke width.

Parameters:: units (Qgis.RenderUnit) – stroke width units

See also

strokeWidthUnit()

See also

setStrokeWidth()

Note

As of QGIS 3.20, using this function is only recommended for SVG backgrounds, while other background types should be configured through their symbols.

setSvgFile(self, file: str)¶

Sets the path to the background SVG file. This is only used if type() is set to QgsTextBackgroundSettings.ShapeSVG. The path must be absolute.

Parameters:: file (str) – Absolute SVG file path

See also

svgFile()

setType(self, type: QgsTextBackgroundSettings.ShapeType)¶

Sets the type of background shape to draw (e.g., square, ellipse, SVG).

Parameters:: type (QgsTextBackgroundSettings.ShapeType) – shape type

See also

type()

size(self) → QSizeF¶

Returns the size of the background shape. The meaning of the size depends on the current sizeType(), e.g., for size types of QgsTextBackgroundSettings.SizeFixed the size will represent the actual width and height of the shape, for QgsTextBackgroundSettings.SizeBuffer the size will represent the horizontal and vertical margins to add to the text when calculating the size of the shape.

See also

setSize()

See also

sizeType()

Return type:: QSizeF

sizeMapUnitScale(self) → QgsMapUnitScale¶

Returns the map unit scale object for the shape size. This is only used if the sizeUnit() is set to QgsUnitTypes.RenderMapUnit.

See also

setSizeMapUnitScale()

See also

sizeUnit()

Return type:: QgsMapUnitScale

sizeType(self) → QgsTextBackgroundSettings.SizeType¶

Returns the method used to determine the size of the background shape (e.g., fixed size or buffer around text).

See also

setSizeType()

See also

size()

Return type:: QgsTextBackgroundSettings.SizeType

sizeUnit(self) → Qgis.RenderUnit¶

Returns the units used for the shape’s size. This value has no meaning if the sizeType() is set to QgsTextBackgroundSettings.SizePercent.

See also

setSizeUnit()

See also

sizeType()

See also

size()

Return type:: Qgis.RenderUnit

strokeColor(self) → QColor¶

Returns the color used for outlining the background shape.

See also

setStrokeColor()

See also

fillColor()

Note

As of QGIS 3.20, using this function is only recommended for SVG backgrounds, while other background types should be configured through their symbols.

Return type:: QColor

strokeWidth(self) → float¶

Returns the width of the shape’s stroke (stroke). Units are retrieved through strokeWidthUnit().

See also

setStrokeWidth()

See also

strokeWidthUnit()

Return type:: float

strokeWidthMapUnitScale(self) → QgsMapUnitScale¶

Returns the map unit scale object for the shape stroke width. This is only used if the strokeWidthUnit() is set to QgsUnitTypes.RenderMapUnit.

See also

setStrokeWidthMapUnitScale()

See also

strokeWidthUnit()

Return type:: QgsMapUnitScale

strokeWidthUnit(self) → Qgis.RenderUnit¶

Returns the units used for the shape’s stroke width.

See also

setStrokeWidthUnit()

See also

strokeWidth()

Return type:: Qgis.RenderUnit

svgFile(self) → str¶

Returns the absolute path to the background SVG file, if set.

See also

setSvgFile()

Return type:: str

type(self) → QgsTextBackgroundSettings.ShapeType¶

Returns the type of background shape (e.g., square, ellipse, SVG).

See also

setType()

Return type:: QgsTextBackgroundSettings.ShapeType

updateDataDefinedProperties(self, context: QgsRenderContext, properties: QgsPropertyCollection)¶

Updates the format by evaluating current values of data defined properties.

Note

Since QGIS 3.20, data defined fill color, stroke color, stroke width, and pen join style will only modify SVG backgrounds. For other background types, the data defined properties within symbols are to be used.

New in version 3.10.

Parameters:

context (QgsRenderContext) –
properties (QgsPropertyCollection) –

writeXml(self, doc: QDomDocument, context: QgsReadWriteContext) → QDomElement¶

Write settings into a DOM element.

See also

readXml()

Parameters:

doc (QDomDocument) –
context (QgsReadWriteContext) –

Return type:

QDomElement