Class: QgsTextCharacterFormat¶

Stores information relating to individual character formatting.

These options encapsulate formatting options which override the default settings from a QgsTextFormat for individual characters (or sets of characters).

Warning

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

Added in version 3.14.

Enums

BooleanValue

Status values for boolean format properties

Methods

`backgroundBrush`	Returns the brush used for rendering the background of the fragment.
`backgroundImagePath`	Returns the path for the image to be used for rendering the background of the fragment.
`family`	Returns the font family name, or an empty string if the family is not set and should be inherited.
`fontPercentageSize`	Returns the font percentage size (as fraction of inherited font size), or -1 if the font size percentage is not set.
`fontPointSize`	Returns the font point size, or -1 if the font size is not set and should be inherited.
`fontWeight`	Returns the font weight, or -1 if the font weight is not set and should be inherited.
`hasBackground`	Returns `True` if the fragment has a background set.
`hasVerticalAlignmentSet`	Returns `True` if the format has an explicit vertical alignment set.
`imagePath`	Returns the path to the image to render, if the format applies to a document image fragment.
`imageSize`	Returns the image size, if the format applies to a document image fragment.
`italic`	Returns whether the format has italic enabled.
`overline`	Returns whether the format has overline enabled.
`overrideWith`	Override all the default/unset properties of the current character format with the settings from another format.
`setBackgroundBrush`	Sets the brush used for rendering the background of the fragment.
`setBackgroundImagePath`	Sets the path for the image to be used for rendering the background of the fragment.
`setFamily`	Sets the font family name.
`setFontPercentageSize`	Sets the font percentage size (as fraction of inherited font size).
`setFontPointSize`	Sets the font point size.
`setFontWeight`	Sets the font weight.
`setHasVerticalAlignmentSet`	Sets whether the format has an explicit vertical alignment set.
`setImagePath`	Sets the path to the image to render, if the format applies to a document image fragment.
`setImageSize`	Sets the image size, if the format applies to a document image fragment.
`setItalic`	Sets whether the format has italic enabled.
`setOverline`	Sets whether the format has overline enabled.
`setStrikeOut`	Sets whether the format has strikethrough enabled.
`setTextColor`	Sets the character's text color.
`setUnderline`	Sets whether the format has underline enabled.
`setVerticalAlignment`	Sets the format vertical alignment.
`setWordSpacing`	Sets the font word spacing, in points, or NaN if word spacing is not set and should be inherited.
`strikeOut`	Returns whether the format has strikethrough enabled.
`textColor`	Returns the character's text color, or an invalid color if no color override is set and the default format color should be used.
`underline`	Returns whether the format has underline enabled.
`updateFontForFormat`	Updates the specified font in place, applying character formatting options which are applicable on a font level when rendered in the given context.
`verticalAlignment`	Returns the format vertical alignment.
`wordSpacing`	Returns the font word spacing, in points, or NaN if word spacing is not set and should be inherited.

class qgis.core.QgsTextCharacterFormat[source]¶

Bases: object

__init__()

__init__(format: QTextCharFormat)

Constructor for QgsTextCharacterFormat, based on the specified QTextCharFormat format.

Parameters:: format (QTextCharFormat)

__init__(a0: QgsTextCharacterFormat)

Parameters:: a0 (QgsTextCharacterFormat)

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

Alternatively, the format may have a backgroundImagePath() 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

family(self) → str[source]¶

Returns the font family name, or an empty string if the family is not set and should be inherited.

See also

setFamily()

Added in version 3.28.

Return type:: str

fontPercentageSize(self) → float[source]¶

Returns the font percentage size (as fraction of inherited font size), or -1 if the font size percentage is not set.

Note

A format should have either fontPointSize() or fontPercentageSize() set, not both.

See also

fontPointSize()

See also

setFontPercentageSize()

Added in version 3.40.

Return type:: float

fontPointSize(self) → float[source]¶

Returns the font point size, or -1 if the font size is not set and should be inherited.

Note

A format should have either fontPointSize() or fontPercentageSize() set, not both.

See also

fontPercentageSize()

See also

setFontPointSize()

Added in version 3.28.

Return type:: float

fontWeight(self) → int[source]¶

Returns the font weight, or -1 if the font weight is not set and should be inherited.

See also

setFontWeight()

Added in version 3.28.

Return type:: int

hasBackground(self) → bool[source]¶

Returns True if the fragment has a background set.

See also

backgroundBrush()

Added in version 3.42.

Return type:: bool

hasVerticalAlignmentSet(self) → bool[source]¶

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

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

See also

setHasVerticalAlignmentSet()

See also

verticalAlignment()

Added in version 3.30.

Return type:: bool

imagePath(self) → str[source]¶

Returns the path to the image to render, if the format applies to a document image fragment.

See also

QgsTextFragment.isImage()

See also

imageSize()

See also

setImagePath()

Added in version 3.40.

Return type:: str

imageSize(self) → QSizeF[source]¶

Returns the image size, if the format applies to a document image fragment.

The image size is always considered to be in Qgis.RenderUnit.Points.

See also

QgsTextFragment.isImage()

See also

imagePath()

See also

setImageSize()

Added in version 3.40.

Return type:: QSizeF

italic(self) → QgsTextCharacterFormat.BooleanValue[source]¶

Returns whether the format has italic enabled.

See also

setItalic()

Added in version 3.28.

Return type:: QgsTextCharacterFormat.BooleanValue

overline(self) → QgsTextCharacterFormat.BooleanValue[source]¶

Returns whether the format has overline enabled.

See also

setUnderline()

Return type:: QgsTextCharacterFormat.BooleanValue

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

Override all the default/unset properties of the current character 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 (QgsTextCharacterFormat) – The format to override with.

Added in version 3.36.

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

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

Alternatively, the format may have a backgroundImagePath() 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])

setFamily(self, family: str | None)[source]¶

Sets the font family name.

Set to an empty string if the family should be inherited.

See also

family()

Added in version 3.28.

Parameters:: family (Optional[str])

setFontPercentageSize(self, size: float)[source]¶

Sets the font percentage size (as fraction of inherited font size).

Set size to -1 if the font percentange size is not set.

Note

A format should have either fontPointSize() or fontPercentageSize() set, not both.

See also

fontPercentageSize()

See also

setFontPointSize()

Added in version 3.40.

Parameters:: size (float)

setFontPointSize(self, size: float)[source]¶

Sets the font point size.

Set size to -1 if the font size is not set and should be inherited.

Note

A format should have either fontPointSize() or fontPercentageSize() set, not both.

See also

fontPointSize()

See also

setFontPercentageSize()

Added in version 3.28.

Parameters:: size (float)

setFontWeight(self, fontWeight: int)[source]¶

Sets the font weight.

Set weight to -1 if the font weight is not set and should be inherited.

See also

fontWeight()

Added in version 3.28.

Parameters:: fontWeight (int)

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

Sets whether the format has an explicit vertical alignment set.

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

See also

hasVerticalAlignmentSet()

See also

setVerticalAlignment()

Added in version 3.30.

Parameters:: set (bool)

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

Sets the path to the image to render, if the format applies to a document image fragment.

See also

QgsTextFragment.isImage()

See also

setImageSize()

See also

imagePath()

Added in version 3.40.

Parameters:: path (Optional[str])

setImageSize(self, size: QSizeF)[source]¶

Sets the image size, if the format applies to a document image fragment.

The image size is always considered to be in Qgis.RenderUnit.Points.

See also

QgsTextFragment.isImage()

See also

setImagePath()

See also

imageSize()

Added in version 3.40.

Parameters:: size (QSizeF)

setItalic(self, enabled: QgsTextCharacterFormat.BooleanValue)[source]¶

Sets whether the format has italic enabled.

See also

italic()

Added in version 3.28.

Parameters:: enabled (QgsTextCharacterFormat.BooleanValue)

setOverline(self, enabled: QgsTextCharacterFormat.BooleanValue)[source]¶

Sets whether the format has overline enabled.

See also

overline()

Parameters:: enabled (QgsTextCharacterFormat.BooleanValue)

setStrikeOut(self, enabled: QgsTextCharacterFormat.BooleanValue)[source]¶

Sets whether the format has strikethrough enabled.

See also

strikeOut()

Parameters:: enabled (QgsTextCharacterFormat.BooleanValue)

setTextColor(self, textColor: QColor | Qt.GlobalColor)[source]¶

Sets the character’s text color.

Set color to an invalid color if no color override is desired and the default format color should be used.

See also

textColor()

Parameters:: textColor (Union[QColor, Qt.GlobalColor])

setUnderline(self, enabled: QgsTextCharacterFormat.BooleanValue)[source]¶

Sets whether the format has underline enabled.

See also

underline()

Parameters:: enabled (QgsTextCharacterFormat.BooleanValue)

setVerticalAlignment(self, alignment: Qgis.TextCharacterVerticalAlignment)[source]¶

Sets the format vertical alignment.

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

See also

hasVerticalAlignmentSet()

See also

verticalAlignment()

Added in version 3.30.

Parameters:: alignment (Qgis.TextCharacterVerticalAlignment)

setWordSpacing(self, spacing: float)[source]¶

Sets the font word spacing, in points, or NaN if word spacing is not set and should be inherited.

See also

wordSpacing()

Added in version 3.40.

Parameters:: spacing (float)

strikeOut(self) → QgsTextCharacterFormat.BooleanValue[source]¶

Returns whether the format has strikethrough enabled.

See also

setStrikeOut()

Return type:: QgsTextCharacterFormat.BooleanValue

textColor(self) → QColor[source]¶

Returns the character’s text color, or an invalid color if no color override is set and the default format color should be used.

See also

setTextColor()

Return type:: QColor

underline(self) → QgsTextCharacterFormat.BooleanValue[source]¶

Returns whether the format has underline enabled.

See also

setUnderline()

Return type:: QgsTextCharacterFormat.BooleanValue

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

Updates the specified font in place, applying character 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: