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
Returns the blending mode used for drawing the background shape.
Returns whether the background is enabled.
Returns the color used for filing the background shape.
Returns the fill symbol to be rendered in the background.
Returns the join style used for drawing the background shape.
Returns the marker symbol to be rendered in the background.
Returns the offset used for drawing the background shape.
Returns the map unit scale object for the shape offset.
Returns the units used for the shape's offset.
Returns the background shape's opacity.
Returns the current paint effect for the background shape.
Returns the radii used for rounding the corners of shapes.
Returns the map unit scale object for the shape radii.
Returns the units used for the shape's radii.
Reads settings from a layer's custom properties (for QGIS 2.x projects).
Read settings from a DOM element.
Returns all field names referenced by the configuration (e.g.
Returns the rotation for the background shape, in degrees clockwise.
Returns the method used for rotating the background shape.
Sets the blending mode used for drawing the background shape.
Sets whether the text background will be drawn.
Sets the color used for filing the background shape.
Sets the current fill
symbol
for the background shape.Sets the join style used for drawing the background shape.
Sets the current marker
symbol
for the background shape.Sets the offset used for drawing the background shape.
Sets the map unit scale object for the shape offset.
Sets the units used for the shape's offset.
Sets the background shape's opacity.
Sets the current paint
effect
for the background shape.Sets the radii used for rounding the corners of shapes.
Sets the map unit scale object for the shape radii.
Sets the units used for the shape's radii.
Sets the
rotation
for the background shape, in degrees clockwise.Sets the method used for rotating the background shape.
Sets the size of the background shape.
Sets the map unit scale object for the shape size.
Sets the method used to determine the size of the background shape (e.g., fixed size or buffer around text).
Sets the units used for the shape's size.
Sets the color used for outlining the background shape.
Sets the width of the shape's stroke (stroke).
Sets the map unit scale object for the shape stroke width.
Sets the units used for the shape's stroke width.
Sets the path to the background SVG file.
Sets the type of background shape to draw (e.g., square, ellipse, SVG).
Returns the size of the background shape.
Returns the map unit scale object for the shape size.
Returns the method used to determine the size of the background shape (e.g., fixed size or buffer around text).
Returns the units used for the shape's size.
Returns the color used for outlining the background shape.
Returns the width of the shape's stroke (stroke).
Returns the map unit scale object for the shape stroke width.
Returns the units used for the shape's stroke width.
Returns the absolute path to the background SVG file, if set.
Returns the type of background shape (e.g., square, ellipse, SVG).
Updates the format by evaluating current values of data defined properties.
Write settings into a DOM element.
Attributes
- 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
- Return type:
QPainter.CompositionMode
- enabled(self) bool ¶
Returns whether the background is enabled.
See also
- Return type:
bool
- fillColor(self) QColor ¶
Returns the color used for filing the background shape.
See also
See also
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.ShapeEllipseSee also
New in version 3.20.
- Return type:
- joinStyle(self) Qt.PenJoinStyle ¶
Returns the join style used for drawing the background shape.
See also
- 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
New in version 3.10.
- Return type:
- offset(self) QPointF ¶
Returns the offset used for drawing the background shape. Units are determined via
offsetUnit()
.See also
See also
- 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 toQgsUnitTypes
.RenderMapUnit.See also
See also
- Return type:
- offsetUnit(self) Qgis.RenderUnit ¶
Returns the units used for the shape’s offset.
See also
See also
- Return type:
- 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
- Return type:
float
- paintEffect(self) QgsPaintEffect ¶
Returns the current paint effect for the background shape.
- Return type:
- Returns:
paint effect
See also
- radii(self) QSizeF ¶
Returns the radii used for rounding the corners of shapes. Units are retrieved through
radiiUnit()
.See also
See also
- 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 toQgsUnitTypes
.RenderMapUnit.See also
See also
- Return type:
- radiiUnit(self) Qgis.RenderUnit ¶
Returns the units used for the shape’s radii.
See also
See also
- Return type:
- 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
- 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
See also
- Return type:
float
- rotationType(self) QgsTextBackgroundSettings.RotationType ¶
Returns the method used for rotating the background shape.
See also
See also
- Return type:
- setBlendMode(self, mode: QPainter.CompositionMode)¶
Sets the blending mode used for drawing the background shape.
- Parameters:
mode (QPainter.CompositionMode) – blending mode
See also
- setEnabled(self, enabled: bool)¶
Sets whether the text background will be drawn.
- Parameters:
enabled (bool) – set to
True
to draw background
See also
- setFillColor(self, color: QColor | Qt.GlobalColor)¶
Sets the color used for filing the background shape.
- Parameters:
color (Union[QColor) – background color
See also
See also
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.ShapeEllipseSee also
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
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
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
See also
- setOffsetMapUnitScale(self, scale: QgsMapUnitScale)¶
Sets the map unit scale object for the shape offset. This is only used if the
offsetUnit()
is set toQgsUnitTypes
.RenderMapUnit.- Parameters:
scale (QgsMapUnitScale) – scale for shape offset
See also
See also
- setOffsetUnit(self, units: Qgis.RenderUnit)¶
Sets the units used for the shape’s offset.
- Parameters:
units (Qgis.RenderUnit) – offset units
See also
See also
- 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
- 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
- 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
See also
- setRadiiMapUnitScale(self, scale: QgsMapUnitScale)¶
Sets the map unit scale object for the shape radii. This is only used if the
radiiUnit()
is set toQgsUnitTypes
.RenderMapUnit.- Parameters:
scale (QgsMapUnitScale) – scale for shape radii
See also
See also
- setRadiiUnit(self, units: Qgis.RenderUnit)¶
Sets the units used for the shape’s radii.
- Parameters:
units (Qgis.RenderUnit) – radii units
See also
See also
- setRotation(self, rotation: float)¶
Sets the
rotation
for the background shape, in degrees clockwise.See also
See also
- 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
See also
- 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
See also
- setSizeMapUnitScale(self, scale: QgsMapUnitScale)¶
Sets the map unit scale object for the shape size. This is only used if the
sizeUnit()
is set toQgsUnitTypes
.RenderMapUnit.- Parameters:
scale (QgsMapUnitScale) – scale for shape size
See also
See also
- 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
See also
- 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
See also
See also
- setStrokeColor(self, color: QColor | Qt.GlobalColor)¶
Sets the color used for outlining the background shape.
- Parameters:
color (Union[QColor) – stroke color
See also
See also
- setStrokeWidth(self, width: float)¶
Sets the width of the shape’s stroke (stroke). Units are specified through
setStrokeWidthUnit()
.See also
See also
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 toQgsUnitTypes
.RenderMapUnit.- Parameters:
scale (QgsMapUnitScale) – scale for shape stroke width
See also
See also
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
See also
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
- 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
- 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
See also
- 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 toQgsUnitTypes
.RenderMapUnit.See also
See also
- Return type:
- 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
See also
- Return type:
- 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
See also
See also
- Return type:
- strokeColor(self) QColor ¶
Returns the color used for outlining the background shape.
See also
See also
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
See also
- 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 toQgsUnitTypes
.RenderMapUnit.See also
See also
- Return type:
- strokeWidthUnit(self) Qgis.RenderUnit ¶
Returns the units used for the shape’s stroke width.
See also
See also
- Return type:
- svgFile(self) str ¶
Returns the absolute path to the background SVG file, if set.
See also
- Return type:
str
- type(self) QgsTextBackgroundSettings.ShapeType ¶
Returns the type of background shape (e.g., square, ellipse, SVG).
See also
- Return type:
- 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
- Parameters:
doc (QDomDocument) –
context (QgsReadWriteContext) –
- Return type:
QDomElement