QgsTextBackgroundSettings class

Container for settings relating to a text background object.

Contents

Public types

enum RotationType { RotationSync = 0, RotationOffset, RotationFixed }
Methods for determining the rotation of the background shape.
enum ShapeType { ShapeRectangle = 0, ShapeSquare, ShapeEllipse, ShapeCircle, ShapeSVG }
Background shape types.
enum SizeType { SizeBuffer = 0, SizeFixed, SizePercent }
Methods for determining the background shape size.

Constructors, destructors, conversion operators

QgsTextBackgroundSettings(const QgsTextBackgroundSettings& other)
Copy constructor.

Public functions

auto blendMode() const -> QPainter::CompositionMode
Returns the blending mode used for drawing the background shape.
auto enabled() const -> bool
Returns whether the background is enabled.
auto fillColor() const -> QColor
Returns the color used for filing the background shape.
auto joinStyle() const -> Qt::PenJoinStyle
Returns the join style used for drawing the background shape.
auto offset() const -> QPointF
Returns the offset used for drawing the background shape.
auto offsetMapUnitScale() const -> QgsMapUnitScale
Returns the map unit scale object for the shape offset.
auto offsetUnit() const -> QgsUnitTypes::RenderUnit
Returns the units used for the shape's offset.
auto opacity() const -> double
Returns the background shape's opacity.
auto paintEffect() const -> QgsPaintEffect*
Returns the current paint effect for the background shape.
auto radii() const -> QSizeF
Returns the radii used for rounding the corners of shapes.
auto radiiMapUnitScale() const -> QgsMapUnitScale
Returns the map unit scale object for the shape radii.
auto radiiUnit() const -> QgsUnitTypes::RenderUnit
Returns the units used for the shape's radii.
void readFromLayer(QgsVectorLayer* layer)
Reads settings from a layer's custom properties (for QGIS 2.x projects).
void readXml(const QDomElement& elem, const QgsReadWriteContext& context)
Read settings from a DOM element.
auto rotation() const -> double
Returns the rotation for the background shape, in degrees clockwise.
auto rotationType() const -> RotationType
Returns the method used for rotating the background shape.
void setBlendMode(QPainter::CompositionMode mode)
Sets the blending mode used for drawing the background shape.
void setEnabled(bool enabled)
Sets whether the text background will be drawn.
void setFillColor(const QColor& color)
Sets the color used for filing the background shape.
void setJoinStyle(Qt::PenJoinStyle style)
Sets the join style used for drawing the background shape.
void setOffset(QPointF offset)
Sets the offset used for drawing the background shape.
void setOffsetMapUnitScale(const QgsMapUnitScale& scale)
Sets the map unit scale object for the shape offset.
void setOffsetUnit(QgsUnitTypes::RenderUnit units)
Sets the units used for the shape's offset.
void setOpacity(double opacity)
Sets the background shape's opacity.
void setPaintEffect(QgsPaintEffect* effect)
Sets the current paint effect for the background shape.
void setRadii(QSizeF radii)
Sets the radii used for rounding the corners of shapes.
void setRadiiMapUnitScale(const QgsMapUnitScale& scale)
Sets the map unit scale object for the shape radii.
void setRadiiUnit(QgsUnitTypes::RenderUnit units)
Sets the units used for the shape's radii.
void setRotation(double rotation)
Sets the rotation for the background shape, in degrees clockwise.
void setRotationType(RotationType type)
Sets the method used for rotating the background shape.
void setSize(QSizeF size)
Sets the size of the background shape.
void setSizeMapUnitScale(const QgsMapUnitScale& scale)
Sets the map unit scale object for the shape size.
void setSizeType(SizeType type)
Sets the method used to determine the size of the background shape (e.g., fixed size or buffer around text).
void setSizeUnit(QgsUnitTypes::RenderUnit unit)
Sets the units used for the shape's size.
void setStrokeColor(const QColor& color)
Sets the color used for outlining the background shape.
void setStrokeWidth(double width)
Sets the width of the shape's stroke (stroke).
void setStrokeWidthMapUnitScale(const QgsMapUnitScale& scale)
Sets the map unit scale object for the shape stroke width.
void setStrokeWidthUnit(QgsUnitTypes::RenderUnit units)
Sets the units used for the shape's stroke width.
void setSvgFile(const QString& file)
Sets the path to the background SVG file.
void setType(ShapeType type)
Sets the type of background shape to draw (e.g., square, ellipse, SVG).
auto size() const -> QSizeF
Returns the size of the background shape.
auto sizeMapUnitScale() const -> QgsMapUnitScale
Returns the map unit scale object for the shape size.
auto sizeType() const -> SizeType
Returns the method used to determine the size of the background shape (e.g., fixed size or buffer around text).
auto sizeUnit() const -> QgsUnitTypes::RenderUnit
Returns the units used for the shape's size.
auto strokeColor() const -> QColor
Returns the color used for outlining the background shape.
auto strokeWidth() const -> double
Returns the width of the shape's stroke (stroke).
auto strokeWidthMapUnitScale() const -> QgsMapUnitScale
Returns the map unit scale object for the shape stroke width.
auto strokeWidthUnit() const -> QgsUnitTypes::RenderUnit
Returns the units used for the shape's stroke width.
auto svgFile() const -> QString
Returns the absolute path to the background SVG file, if set.
auto type() const -> ShapeType
Returns the type of background shape (e.g., square, ellipse, SVG).
auto writeXml(QDomDocument& doc, const QgsReadWriteContext& context) const -> QDomElement
Write settings into a DOM element.

Enum documentation

enum QgsTextBackgroundSettings::RotationType

Methods for determining the rotation of the background shape.

Enumerators
RotationSync

Shape rotation is synced with text rotation.
RotationOffset

Shape rotation is offset from text rotation.
RotationFixed

Shape rotation is a fixed angle.

enum QgsTextBackgroundSettings::ShapeType

Background shape types.

Enumerators
ShapeRectangle

Rectangle.
ShapeSquare

Square - buffered sizes only.
ShapeEllipse

Ellipse.
ShapeCircle

Circle.
ShapeSVG

SVG file.

enum QgsTextBackgroundSettings::SizeType

Methods for determining the background shape size.

Enumerators
SizeBuffer

Shape size is determined by adding a buffer margin around text.
SizeFixed

Fixed size.
SizePercent

Shape size is determined by percent of text size.

Function documentation

QgsTextBackgroundSettings::QgsTextBackgroundSettings(const QgsTextBackgroundSettings& other)

Copy constructor.

Parameters
other source QgsTextBackgroundSettings

QPainter::CompositionMode QgsTextBackgroundSettings::blendMode() const

Returns the blending mode used for drawing the background shape.

bool QgsTextBackgroundSettings::enabled() const

Returns whether the background is enabled.

QColor QgsTextBackgroundSettings::fillColor() const

Returns the color used for filing the background shape.

Qt::PenJoinStyle QgsTextBackgroundSettings::joinStyle() const

Returns the join style used for drawing the background shape.

QPointF QgsTextBackgroundSettings::offset() const

Returns the offset used for drawing the background shape.

Units are determined via offsetUnit().

QgsMapUnitScale QgsTextBackgroundSettings::offsetMapUnitScale() const

Returns the map unit scale object for the shape offset.

This is only used if the offsetUnit() is set to QgsUnitTypes::RenderMapUnit.

QgsUnitTypes::RenderUnit QgsTextBackgroundSettings::offsetUnit() const

Returns the units used for the shape's offset.

double QgsTextBackgroundSettings::opacity() const

Returns the background shape's opacity.

The opacity is a double value between 0 (fully transparent) and 1 (totally opaque).

QgsPaintEffect* QgsTextBackgroundSettings::paintEffect() const

Returns the current paint effect for the background shape.

Returns paint effect

QSizeF QgsTextBackgroundSettings::radii() const

Returns the radii used for rounding the corners of shapes.

Units are retrieved through radiiUnit().

QgsMapUnitScale QgsTextBackgroundSettings::radiiMapUnitScale() const

Returns the map unit scale object for the shape radii.

This is only used if the radiiUnit() is set to QgsUnitTypes::RenderMapUnit.

QgsUnitTypes::RenderUnit QgsTextBackgroundSettings::radiiUnit() const

Returns the units used for the shape's radii.

void QgsTextBackgroundSettings::readFromLayer(QgsVectorLayer* layer)

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

Parameters
layer source vector layer

void QgsTextBackgroundSettings::readXml(const QDomElement& elem, const QgsReadWriteContext& context)

Read settings from a DOM element.

double QgsTextBackgroundSettings::rotation() const

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

RotationType QgsTextBackgroundSettings::rotationType() const

Returns the method used for rotating the background shape.

void QgsTextBackgroundSettings::setBlendMode(QPainter::CompositionMode mode)

Sets the blending mode used for drawing the background shape.

Parameters
mode blending mode

void QgsTextBackgroundSettings::setEnabled(bool enabled)

Sets whether the text background will be drawn.

Parameters
enabled set to true to draw background

void QgsTextBackgroundSettings::setFillColor(const QColor& color)

Sets the color used for filing the background shape.

Parameters
color background color

void QgsTextBackgroundSettings::setJoinStyle(Qt::PenJoinStyle style)

Sets the join style used for drawing the background shape.

Parameters
style join style

void QgsTextBackgroundSettings::setOffset(QPointF offset)

Sets the offset used for drawing the background shape.

Parameters
offset offset for shape

Units are specified using setOffsetUnit().

void QgsTextBackgroundSettings::setOffsetMapUnitScale(const QgsMapUnitScale& scale)

Sets the map unit scale object for the shape offset.

Parameters
scale scale for shape offset

This is only used if the offsetUnit() is set to QgsUnitTypes::RenderMapUnit.

void QgsTextBackgroundSettings::setOffsetUnit(QgsUnitTypes::RenderUnit units)

Sets the units used for the shape's offset.

Parameters
units offset units

void QgsTextBackgroundSettings::setOpacity(double opacity)

Sets the background shape's opacity.

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

void QgsTextBackgroundSettings::setPaintEffect(QgsPaintEffect* effect)

Sets the current paint effect for the background shape.

Parameters
effect paint effect. Ownership is transferred to the background settings.

void QgsTextBackgroundSettings::setRadii(QSizeF radii)

Sets the radii used for rounding the corners of shapes.

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

This is only used if type() is set to QgsTextBackgroundSettings::ShapeRectangle or QgsTextBackgroundSettings::ShapeSquare.

void QgsTextBackgroundSettings::setRadiiMapUnitScale(const QgsMapUnitScale& scale)

Sets the map unit scale object for the shape radii.

Parameters
scale scale for shape radii

This is only used if the radiiUnit() is set to QgsUnitTypes::RenderMapUnit.

void QgsTextBackgroundSettings::setRadiiUnit(QgsUnitTypes::RenderUnit units)

Sets the units used for the shape's radii.

Parameters
units radii units

void QgsTextBackgroundSettings::setRotation(double rotation)

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

void QgsTextBackgroundSettings::setRotationType(RotationType type)

Sets the method used for rotating the background shape.

Parameters
type rotation method

void QgsTextBackgroundSettings::setSize(QSizeF size)

Sets the size of the background shape.

Parameters
size QSizeF representing horizontal and vertical size components for 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.

void QgsTextBackgroundSettings::setSizeMapUnitScale(const QgsMapUnitScale& scale)

Sets the map unit scale object for the shape size.

Parameters
scale scale for shape size

This is only used if the sizeUnit() is set to QgsUnitTypes::RenderMapUnit.

void QgsTextBackgroundSettings::setSizeType(SizeType type)

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

Parameters
type size method

void QgsTextBackgroundSettings::setSizeUnit(QgsUnitTypes::RenderUnit unit)

Sets the units used for the shape's size.

Parameters
unit size units

This value has no meaning if the sizeType() is set to QgsTextBackgroundSettings::SizePercent.

void QgsTextBackgroundSettings::setStrokeColor(const QColor& color)

Sets the color used for outlining the background shape.

Parameters
color stroke color

void QgsTextBackgroundSettings::setStrokeWidth(double width)

Sets the width of the shape's stroke (stroke).

Units are specified through setStrokeWidthUnit().

void QgsTextBackgroundSettings::setStrokeWidthMapUnitScale(const QgsMapUnitScale& scale)

Sets the map unit scale object for the shape stroke width.

Parameters
scale scale for shape stroke width

This is only used if the strokeWidthUnit() is set to QgsUnitTypes::RenderMapUnit.

void QgsTextBackgroundSettings::setStrokeWidthUnit(QgsUnitTypes::RenderUnit units)

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

Parameters
units stroke width units

void QgsTextBackgroundSettings::setSvgFile(const QString& file)

Sets the path to the background SVG file.

Parameters
file Absolute SVG file path

This is only used if type() is set to QgsTextBackgroundSettings::ShapeSVG. The path must be absolute.

void QgsTextBackgroundSettings::setType(ShapeType type)

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

Parameters
type shape type

QSizeF QgsTextBackgroundSettings::size() const

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.

QgsMapUnitScale QgsTextBackgroundSettings::sizeMapUnitScale() const

Returns the map unit scale object for the shape size.

This is only used if the sizeUnit() is set to QgsUnitTypes::RenderMapUnit.

SizeType QgsTextBackgroundSettings::sizeType() const

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

QgsUnitTypes::RenderUnit QgsTextBackgroundSettings::sizeUnit() const

Returns the units used for the shape's size.

This value has no meaning if the sizeType() is set to QgsTextBackgroundSettings::SizePercent.

QColor QgsTextBackgroundSettings::strokeColor() const

Returns the color used for outlining the background shape.

double QgsTextBackgroundSettings::strokeWidth() const

Returns the width of the shape's stroke (stroke).

Units are retrieved through strokeWidthUnit().

QgsMapUnitScale QgsTextBackgroundSettings::strokeWidthMapUnitScale() const

Returns the map unit scale object for the shape stroke width.

This is only used if the strokeWidthUnit() is set to QgsUnitTypes::RenderMapUnit.

QgsUnitTypes::RenderUnit QgsTextBackgroundSettings::strokeWidthUnit() const

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

QString QgsTextBackgroundSettings::svgFile() const

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

ShapeType QgsTextBackgroundSettings::type() const

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

QDomElement QgsTextBackgroundSettings::writeXml(QDomDocument& doc, const QgsReadWriteContext& context) const

Write settings into a DOM element.