Class: QgsTextBlockFormat¶

Stores information relating to individual block formatting.

These options encapsulate formatting options which override the default settings from a QgsTextFormat for individual text blocks.

Warning

This API is not considered stable and may change in future QGIS versions.

Added in version 3.40.

Enums

BooleanValue

Status values for boolean format properties

Methods

`backgroundBrush`	Returns the brush used for rendering the background of the block.
`backgroundImagePath`	Returns the path for the image to be used for rendering the background of the fragment.
`hasBackground`	Returns `True` if the block has a background set.
`hasHorizontalAlignmentSet`	Returns `True` if the format has an explicit horizontal alignment set.
`horizontalAlignment`	Returns the format horizontal alignment.
`lineHeight`	Returns the line height in points, or NaN if the line height is not set and should be auto calculated.
`lineHeightPercentage`	Returns the line height percentage size (as fraction of font size from 0.0 to 1.0), or NaN if the line height percentage is not set.
`margins`	Returns the block margins, in points.
`overrideWith`	Override all the default/unset properties of the current block format with the settings from another format.
`setBackgroundBrush`	Sets the brush used for rendering the background of the block.
`setBackgroundImagePath`	Sets the path for the image to be used for rendering the background of the fragment.
`setHasHorizontalAlignmentSet`	Sets whether the format has an explicit horizontal alignment set.
`setHorizontalAlignment`	Sets the format horizontal alignment.
`setLineHeight`	Sets the font line height, in points.
`setLineHeightPercentage`	Sets the line height percentage height (as fraction of font size from 0.0 to 1.0).
`setMargins`	Sets the block margins, in points.
`updateFontForFormat`	Updates the specified font in place, applying block formatting options which are applicable on a font level when rendered in the given context.

class qgis.core.QgsTextBlockFormat[source]¶

Bases: object

__init__()

__init__(format: QTextBlockFormat)

Constructor for QgsTextBlockFormat, based on the specified QTextBlockFormat format.

Parameters:: format (QTextBlockFormat)

__init__(a0: QgsTextBlockFormat)

Parameters:: a0 (QgsTextBlockFormat)

class BooleanValue(*values)¶

Bases: IntEnum

Status values for boolean format properties

NotSet: Property is not set
SetTrue: Property is set and True
SetFalse: Property is set and False

NotSet = 0¶

SetFalse = 2¶

SetTrue = 1¶

backgroundBrush(self) → QBrush[source]¶

Returns the brush used for rendering the background of the block.

Alternatively, the format may have a backgroundBrush() set.

See also

hasBackground()

See also

setBackgroundBrush()

Added in version 3.42.

Return type:: QBrush

backgroundImagePath(self) → str[source]¶

Returns the path for the image to be used for rendering the background of the fragment.

Alternatively, the format may have a backgroundBrush() set.

See also

hasBackground()

See also

setBackgroundImagePath()

Added in version 3.42.

Return type:: str

hasBackground(self) → bool[source]¶

Returns True if the block has a background set.

See also

backgroundBrush()

Added in version 3.42.

Return type:: bool

hasHorizontalAlignmentSet(self) → bool[source]¶

Returns True if the format has an explicit horizontal alignment set.

If False is returned then the horizontal alignment will be inherited.

See also

setHasHorizontalAlignmentSet()

See also

horizontalAlignment()

Return type:: bool

horizontalAlignment(self) → Qgis.TextHorizontalAlignment[source]¶

Returns the format horizontal alignment.

This property is only respected if hasHorizontalAlignmentSet() is True.

See also

hasHorizontalAlignmentSet()

See also

setHorizontalAlignment()

Return type:: Qgis.TextHorizontalAlignment

lineHeight(self) → float[source]¶

Returns the line height in points, or NaN if the line height is not set and should be auto calculated.

Note

A format should have either lineHeight() or lineHeightPercentage() set, not both.

See also

lineHeightPercentage()

See also

setLineHeight()

Added in version 3.42.

Return type:: float

lineHeightPercentage(self) → float[source]¶

Returns the line height percentage size (as fraction of font size from 0.0 to 1.0), or NaN if the line height percentage is not set.

Note

A format should have either lineHeight() or lineHeightPercentage() set, not both.

See also

lineHeight()

See also

setLineHeightPercentage()

Added in version 3.42.

Return type:: float

margins(self) → QgsMargins[source]¶

Returns the block margins, in points.

See also

setMargins()

Added in version 3.42.

Return type:: QgsMargins

overrideWith(self, other: QgsTextBlockFormat)[source]¶

Override all the default/unset properties of the current block format with the settings from another format.

This will replace any default/unset existing settings with the settings from other.

Any settings which are default/unset in other will be left unchanged.

Parameters:: other (QgsTextBlockFormat) – The format to override with.

setBackgroundBrush(self, brush: QBrush | QColor | Qt.GlobalColor | QGradient)[source]¶

Sets the brush used for rendering the background of the block.

Alternatively, the format may have a backgroundBrush() set.

See also

backgroundBrush()

Added in version 3.42.

Parameters:: brush (Union[QBrush, Union[QColor, Qt.GlobalColor], QGradient])

setBackgroundImagePath(self, path: str | None)[source]¶

Sets the path for the image to be used for rendering the background of the fragment.

Alternatively, the format may have a backgroundBrush() set.

See also

backgroundImagePath()

Added in version 3.42.

Parameters:: path (Optional[str])

setHasHorizontalAlignmentSet(self, set: bool)[source]¶

Sets whether the format has an explicit horizontal alignment set.

If set is False then the horizontal alignment will be inherited.

See also

hasHorizontalAlignmentSet()

See also

setHorizontalAlignment()

Parameters:: set (bool)

setHorizontalAlignment(self, alignment: Qgis.TextHorizontalAlignment)[source]¶

Sets the format horizontal alignment.

This property is only respected if hasHorizontalAlignmentSet() is True.

See also

hasHorizontalAlignmentSet()

See also

horizontalAlignment()

Parameters:: alignment (Qgis.TextHorizontalAlignment)

setLineHeight(self, height: float)[source]¶

Sets the font line height, in points.

Set height to NaN if the line height is not set and should be auto calculated.

Note

A format should have either lineHeight() or lineHeightPercentage() set, not both.

See also

lineHeight()

See also

setLineHeightPercentage()

Added in version 3.42.

Parameters:: height (float)

setLineHeightPercentage(self, height: float)[source]¶

Sets the line height percentage height (as fraction of font size from 0.0 to 1.0).

Set height to NaN if the line height percentange is not set.

Note

A format should have either lineHeight() or lineHeightPercentage() set, not both.

See also

lineHeightPercentage()

See also

setLineHeight()

Added in version 3.42.

Parameters:: height (float)

setMargins(self, margins: QgsMargins)[source]¶

Sets the block margins, in points.

See also

margins()

Added in version 3.42.

Parameters:: margins (QgsMargins)

updateFontForFormat(self, font: QFont, context: QgsRenderContext, scaleFactor: float = 1)[source]¶

Updates the specified font in place, applying block formatting options which are applicable on a font level when rendered in the given context.

The optional scaleFactor parameter can specify a font size scaling factor. It is recommended to set this to QgsTextRenderer.calculateScaleFactorForFormat() and then manually calculations based on the resultant font metrics. Failure to do so will result in poor quality text rendering at small font sizes.

Parameters:

font (QFont)
context (QgsRenderContext)
scaleFactor (float = 1)