Class: QgsTextBackgroundSettings

class qgis.core.QgsTextBackgroundSettings

Bases: sip.wrapper

QgsTextBackgroundSettings(other: QgsTextBackgroundSettings) Copy constructor.

Parameters

other – source QgsTextBackgroundSettings

Container for settings relating to a text background object.

Note

QgsTextBackgroundSettings objects are implicitly shared.

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.

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.

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.

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()

Return type

QColor

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.

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

offsetUnit()

Return type

QgsMapUnitScale

offsetUnit(self) → QgsUnitTypes.RenderUnit

Returns the units used for the shape’s offset.

See also

setOffsetUnit()

See also

offset()

Return type

QgsUnitTypes.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

radiiUnit()

Return type

QgsMapUnitScale

radiiUnit(self) → QgsUnitTypes.RenderUnit

Returns the units used for the shape’s radii.

See also

setRadiiUnit()

See also

radii()

Return type

QgsUnitTypes.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
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

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: Union[QColor, Qt.GlobalColor, QGradient])

Sets the color used for filing the background shape.

Parameters

color (Union[QColor) – background color

See also

fillColor()

See also

setStrokeColor()

setJoinStyle(self, style: Qt.PenJoinStyle)

Sets the join style used for drawing the background shape.

Parameters

style (Qt.PenJoinStyle) – join style

See also

joinStyle()

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: Union[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

setOffsetUnit()

setOffsetUnit(self, units: QgsUnitTypes.RenderUnit)

Sets the units used for the shape’s offset.

Parameters

units (QgsUnitTypes.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

setRadiiUnit()

setRadiiUnit(self, units: QgsUnitTypes.RenderUnit)

Sets the units used for the shape’s radii.

Parameters

units (QgsUnitTypes.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()

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

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: QgsUnitTypes.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 (QgsUnitTypes.RenderUnit) – size units

See also

sizeUnit()

See also

setSizeType()

See also

setSize()

setStrokeColor(self, color: Union[QColor, Qt.GlobalColor, QGradient])

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()

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

setStrokeWidthUnit(self, units: QgsUnitTypes.RenderUnit)

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

Parameters

units (QgsUnitTypes.RenderUnit) – stroke width units

See also

setStrokeWidth()

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

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) → QgsUnitTypes.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

QgsUnitTypes.RenderUnit

strokeColor(self) → QColor

Returns the color used for outlining the background shape.

See also

setStrokeColor()

See also

fillColor()

Return type

QColor

strokeWidth(self) → float

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

See also

setStrokeWidth()

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.

Return type

QgsMapUnitScale

strokeWidthUnit(self) → QgsUnitTypes.RenderUnit

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

See also

strokeWidth()

Return type

QgsUnitTypes.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.

New in version 3.10.

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

Write settings into a DOM element.

See also

readXml()

Parameters
Return type

QDomElement