Class: QgsTextFormat

class qgis.core.QgsTextFormat

Bases: sip.wrapper

Container for all settings relating to text rendering.

Note

QgsTextFormat objects are implicitly shared.

New in version 3.0.

QgsTextFormat() Default constructor for QgsTextFormat. Creates a text format initially set to an invalid state (see isValid()).

QgsTextFormat(other: QgsTextFormat) Copy constructor.

Parameters:

other –

source QgsTextFormat

Enums

TextOrientation

Bases: enum.IntEnum

Methods

allowHtmlFormatting	Returns True if text should be treated as a HTML document and HTML tags should be used for formatting the rendered text.
background	Returns a reference to the text background settings.
blendMode	Returns the blending mode used for drawing the text.
buffer	Returns a reference to the text buffer settings.
capitalization	Returns the text capitalization style.
color	Returns the color that text will be rendered in.
containsAdvancedEffects	Returns True if any component of the font format requires advanced effects such as blend modes, which require output in raster formats to be fully respected.
dataDefinedProperties	Returns a reference to the format's property collection, used for data defined overrides.
families	Returns the list of font families to use when restoring the text format, in order of precedence.
font	Returns the font used for rendering text.
fontFound	Returns True if the specified font was found on the system, or False if the font was not found and a replacement was used instead.
forcedBold	Returns True if the format is set to force a bold style.
forcedItalic	Returns True if the format is set to force an italic style.
fromMimeData	Attempts to parse the provided mime data as a QgsTextFormat.
fromQFont	Returns a text format matching the settings from an input font.
isValid	Returns True if the format is valid.
lineHeight	Returns the line height for text.
lineHeightUnit	Returns the units for the line height for text.
mask	Returns a reference to the masking settings.
namedStyle	Returns the named style for the font used for rendering text (e.g., "bold").
opacity	Returns the text's opacity.
orientation	Returns the orientation of the text.
previewBackgroundColor	Returns the background color for text previews.
readFromLayer	Reads settings from a layer's custom properties (for QGIS 2.x projects).
readXml	Read settings from a DOM element.
referencedFields	Returns all field names referenced by the configuration (e.g.
resolvedFontFamily	Returns the family for the resolved font, ie if the specified font was not found on the system this will return the name of the replacement font.
scaledFont	Returns a font with the size scaled to match the format's size settings (including units and map unit scale) for a specified render context.
setAllowHtmlFormatting	Sets whether text should be treated as a HTML document and HTML tags should be used for formatting the rendered text.
setBackground	Sets the text's background settings.q
setBlendMode	Sets the blending mode used for drawing the text.
setBuffer	Sets the text's buffer settings.
setCapitalization	Sets the text capitalization style.
setColor	Sets the color that text will be rendered in.
setDataDefinedProperties	Sets the format's property collection, used for data defined overrides.
setFamilies	Sets a list of font families to use for the text format, in order of precedence.
setFont	Sets the font used for rendering text.
setForcedBold	Sets whether the format is set to force a bold style.
setForcedItalic	Sets whether the format is set to force an italic style.
setLineHeight	Sets the line height for text.
setLineHeightUnit	Sets the unit for the line height for text.
setMask	Sets the text's masking settings.
setNamedStyle	Sets the named style for the font used for rendering text.
setOpacity	Sets the text's opacity.
setOrientation	Sets the orientation for the text.
setPreviewBackgroundColor	Sets the background color that text will be rendered on for previews.
setShadow	Sets the text's drop shadow settings.
setSize	Sets the size for rendered text.
setSizeMapUnitScale	Sets the map unit scale object for the size.
setSizeUnit	Sets the units for the size of rendered text.
setStretchFactor	Sets the text's stretch factor.
setValid	Sets the format to a valid state, without changing any of the default format settings.
shadow	Returns a reference to the text drop shadow settings.
size	Returns the size for rendered text.
sizeMapUnitScale	Returns the map unit scale object for the size.
sizeUnit	Returns the units for the size of rendered text.
stretchFactor	Returns the text's stretch factor.
textFormatPreviewPixmap	Returns a pixmap preview for a text format.
toMimeData	Returns new mime data representing the text format settings.
toQFont	Returns a QFont matching the relevant settings from this text format.
updateDataDefinedProperties	Updates the format by evaluating current values of data defined properties.
writeXml	Write settings into a DOM element.

class TextOrientation(value)

Bases: enum.IntEnum

Text orientations.

Note

Prior to QGIS 3.28 this was available as QgsTextFormat.TextOrientation

New in version 3.28.

• HorizontalOrientation: Horizontally oriented text

• VerticalOrientation: Vertically oriented text

• RotationBasedOrientation: Horizontally or vertically oriented text based on rotation (only available for map labeling)

baseClass

alias of Qgis

allowHtmlFormatting(self) → bool

Returns True if text should be treated as a HTML document and HTML tags should be used for formatting the rendered text.

Warning

Only a small subset of HTML formatting is supported. Currently this is restricted to:

• text color formatting

• strikethrough

• underline

• overline

See also

setAllowHtmlFormatting()

New in version 3.14.

Return type:

bool

background(self) → QgsTextBackgroundSettings

Returns a reference to the text background settings.

See also

setBackground()

Return type:

QgsTextBackgroundSettings

blendMode(self) → QPainter.CompositionMode

Returns the blending mode used for drawing the text.

See also

setBlendMode()

Return type:

QPainter.CompositionMode

buffer(self) → QgsTextBufferSettings

Returns a reference to the text buffer settings.

See also

setBuffer()

Return type:

QgsTextBufferSettings

capitalization(self) → Qgis.Capitalization

Returns the text capitalization style.

See also

setCapitalization()

New in version 3.16.

Return type:

Qgis.Capitalization

color(self) → QColor

Returns the color that text will be rendered in.

See also

setColor()

Return type:

QColor

containsAdvancedEffects(self) → bool

Returns True if any component of the font format requires advanced effects such as blend modes, which require output in raster formats to be fully respected.

Return type:

bool

dataDefinedProperties(self) → QgsPropertyCollection

Returns a reference to the format’s property collection, used for data defined overrides.

See also

setDataDefinedProperties()

New in version 3.10.

Return type:

QgsPropertyCollection

families(self) → List[str]

Returns the list of font families to use when restoring the text format, in order of precedence.

Warning

The list of families returned by this method is ONLY used when restoring the text format from serialized versions, and will not affect the current font() familily used by the format.

See also

setFamilies()

New in version 3.20.

Return type:

List[str]

font(self) → QFont

Returns the font used for rendering text. Note that the size of the font is not used, and size() should be called instead to determine the size of rendered text.

See also

scaledFont()

See also

setFont()

See also

namedStyle()

See also

toQFont()

Return type:

QFont

fontFound(self) → bool

Returns True if the specified font was found on the system, or False if the font was not found and a replacement was used instead.

See also

resolvedFontFamily()

Return type:

bool

forcedBold(self) → bool

Returns True if the format is set to force a bold style.

Warning

Unlike setting a font’s style via setNamedStyle(), this will ensure that a font is always rendered in bold regardless of whether the font family actually has a bold variant. A “faux bold” effect will be emulated, which may result in poor quality font rendering. For this reason it is greatly preferred to call setNamedStyle() instead.

See also

setForcedBold()

New in version 3.26.

Return type:

bool

forcedItalic(self) → bool

Returns True if the format is set to force an italic style.

Warning

Unlike setting a font’s style via setNamedStyle(), this will ensure that a font is always rendered in italic regardless of whether the font family actually has an italic variant. A “faux italic” slanted text effect will be emulated, which may result in poor quality font rendering. For this reason it is greatly preferred to call setNamedStyle() instead.

See also

setForcedItalic()

New in version 3.26.

Return type:

bool

fromMimeData(data: QMimeData) → Tuple[QgsTextFormat, bool]

Attempts to parse the provided mime data as a QgsTextFormat. If data can be parsed as a text format, ok will be set to True.

See also

toMimeData()

Parameters:

data (QMimeData) –

Return type:

Tuple[QgsTextFormat, bool]

fromQFont(font: QFont) → QgsTextFormat

Returns a text format matching the settings from an input font. Unlike setFont(), this method also handles the size and size units from font.

See also

toQFont()

New in version 3.2.

Parameters:

font (QFont) –

Return type:

QgsTextFormat

isValid(self) → bool

Returns True if the format is valid.

A default constructed QgsTextFormat is invalid, until at least one or more properties have been set on the format. An invalid state can be used as a representation of a “not set” text format, e.g. for indicating that a default text format should be used.

Note

Calling any setter on a QgsTextFormat object will automatically set the format as valid.

See also

setValid()

New in version 3.16.

Return type:

bool

lineHeight(self) → float

Returns the line height for text.

If lineHeightUnit() is QgsUnitTypes.RenderPercentage (the default), then this is a number representing the leading between lines as a multiplier of line height (where 0 - 1.0 represents 0 to 100% of text line height). Otherwise the line height is an absolute measurement in lineHeightUnit().

See also

setLineHeight()

See also

lineHeightUnit()

Return type:

float

lineHeightUnit(self) → QgsUnitTypes.RenderUnit

Returns the units for the line height for text.

See also

setLineHeightUnit()

See also

lineHeight()

New in version 3.28.

Return type:

QgsUnitTypes.RenderUnit

mask(self) → QgsTextMaskSettings

Returns a reference to the masking settings.

See also

setMask()

Return type:

QgsTextMaskSettings

namedStyle(self) → str

Returns the named style for the font used for rendering text (e.g., “bold”).

See also

setNamedStyle()

See also

font()

Return type:

str

opacity(self) → float

Returns the text’s opacity. The opacity is a double value between 0 (fully transparent) and 1 (totally opaque).

See also

setOpacity()

Return type:

float

orientation(self) → Qgis.TextOrientation

Returns the orientation of the text.

See also

setOrientation()

New in version 3.10.

Return type:

Qgis.TextOrientation

previewBackgroundColor(self) → QColor

Returns the background color for text previews.

See also

setPreviewBackgroundColor()

New in version 3.10.

Return type:

QColor

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:

• 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]

resolvedFontFamily(self) → str

Returns the family for the resolved font, ie if the specified font was not found on the system this will return the name of the replacement font.

See also

fontFound()

Return type:

str

scaledFont(self, context: QgsRenderContext, scaleFactor: float = 1) → QFont

Returns a font with the size scaled to match the format’s size settings (including units and map unit scale) for a specified render context.

Parameters:

• context (QgsRenderContext) – destination render context

• scaleFactor (float = 1) – optional font size scaling factor. It is recommended to set this to QgsTextRenderer.FONT_WORKAROUND_SCALE and then manually scale painter devices or calculations based on the resultant font metrics. Failure to do so will result in poor quality text rendering at small font sizes.

Return type:

QFont

Returns:

font with scaled size

See also

font()

See also

size()

setAllowHtmlFormatting(self, allow: bool)

Sets whether text should be treated as a HTML document and HTML tags should be used for formatting the rendered text.

Warning

Only a small subset of HTML formatting is supported. Currently this is restricted to:

• text color formatting

• strikethrough

• underline

• overline

See also

allowHtmlFormatting()

New in version 3.14.

Parameters:

allow (bool) –

setBackground(self, backgroundSettings: QgsTextBackgroundSettings)

Sets the text’s background settings.q

Parameters:

backgroundSettings (QgsTextBackgroundSettings) – background settings

See also

background()

setBlendMode(self, mode: QPainter.CompositionMode)

Sets the blending mode used for drawing the text.

Parameters:

mode (QPainter.CompositionMode) – blending mode

See also

blendMode()

setBuffer(self, bufferSettings: QgsTextBufferSettings)

Sets the text’s buffer settings.

Parameters:

bufferSettings (QgsTextBufferSettings) – buffer settings

See also

buffer()

setCapitalization(self, capitalization: Qgis.Capitalization)

Sets the text capitalization style.

See also

capitalization()

New in version 3.16.

Parameters:

capitalization (Qgis.Capitalization) –

setColor(self, color: QColor | Qt.GlobalColor)

Sets the color that text will be rendered in.

Parameters:

color (Union[QColor) – text color

See also

color()

setDataDefinedProperties(self, collection: QgsPropertyCollection)

Sets the format’s property collection, used for data defined overrides.

Parameters:

collection (QgsPropertyCollection) – property collection. Existing properties will be replaced.

See also

dataDefinedProperties()

New in version 3.10.

setFamilies(self, families: Iterable[str])

Sets a list of font families to use for the text format, in order of precedence.

When restoring serialized versions of the text format then the first matching font family from this list will be used for the text format. This provides a way to specify a list of possible font families which are used as fallbacks if a family isn’t available on a particular QGIS install (CSS style).

Warning

The list of families set by calling this method is ONLY used when restoring the text format from serialized versions, and will not affect the current font() familily used by the format.

See also

families()

New in version 3.20.

Parameters:

families (Iterable[str]) –

setFont(self, font: QFont)

Sets the font used for rendering text. Note that the size of the font is not used, and setSize() should be called instead to explicitly set the size of rendered text.

Parameters:

font (QFont) – desired font

See also

font()

See also

setNamedStyle()

See also

fromQFont()

setForcedBold(self, forced: bool)

Sets whether the format is set to force a bold style.

Warning

Unlike setting a font’s style via setNamedStyle(), this will ensure that a font is always rendered in bold regardless of whether the font family actually has a bold variant. A “faux bold” effect will be emulated, which may result in poor quality font rendering. For this reason it is greatly preferred to call setNamedStyle() instead.

See also

forcedBold()

New in version 3.26.

Parameters:

forced (bool) –

setForcedItalic(self, forced: bool)

Sets whether the format is set to force an italic style.

Warning

Unlike setting a font’s style via setNamedStyle(), this will ensure that a font is always rendered in italic regardless of whether the font family actually has an italic variant. A “faux italic” slanted text effect will be emulated, which may result in poor quality font rendering. For this reason it is greatly preferred to call setNamedStyle() instead.

See also

forcedItalic()

New in version 3.26.

Parameters:

forced (bool) –

setLineHeight(self, height: float)

Sets the line height for text.

If lineHeightUnit() is QgsUnitTypes.RenderPercentage (the default), then height is a number representing the leading between lines as a multiplier of line height (where 0 - 1.0 represents 0 to 100% of text line height). Otherwise height is an absolute measurement in lineHeightUnit().

See also

lineHeight()

See also

setLineHeightUnit()

Parameters:

height (float) –

setLineHeightUnit(self, unit: QgsUnitTypes.RenderUnit)

Sets the unit for the line height for text.

See also

lineHeightUnit()

See also

setLineHeight()

New in version 3.28.

Parameters:

unit (QgsUnitTypes.RenderUnit) –

setMask(self, maskSettings: QgsTextMaskSettings)

Sets the text’s masking settings. Masks may be defined in contexts where the text is rendered over some map layers, for labeling especially.

Parameters:

maskSettings (QgsTextMaskSettings) – mask settings

See also

mask()

New in version 3.12.

setNamedStyle(self, style: str)

Sets the named style for the font used for rendering text.

Parameters:

style (str) – named style, e.g., “bold”

See also

namedStyle()

See also

setFont()

setOpacity(self, opacity: float)

Sets the text’s opacity.

Parameters:

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

See also

opacity()

setOrientation(self, orientation: Qgis.TextOrientation)

Sets the orientation for the text.

See also

orientation()

New in version 3.10.

Parameters:

orientation (Qgis.TextOrientation) –

setPreviewBackgroundColor(self, color: QColor | Qt.GlobalColor)

Sets the background color that text will be rendered on for previews.

See also

previewBackgroundColor()

New in version 3.10.

Parameters:

color (Union[QColor) –

setShadow(self, shadowSettings: QgsTextShadowSettings)

Sets the text’s drop shadow settings.

Parameters:

shadowSettings (QgsTextShadowSettings) – shadow settings

See also

shadow()

setSize(self, size: float)

Sets the size for rendered text.

Parameters:

size (float) – size of rendered text. Units are set using setSizeUnit()

See also

size()

See also

setSizeUnit()

setSizeMapUnitScale(self, scale: QgsMapUnitScale)

Sets the map unit scale object for the size. This is only used if the sizeUnit() is set to QgsUnitTypes.RenderMapUnit.

See also

sizeMapUnitScale()

See also

setSizeUnit()

Parameters:

scale (QgsMapUnitScale) –

setSizeUnit(self, unit: QgsUnitTypes.RenderUnit)

Sets the units for the size of rendered text.

Parameters:

unit (QgsUnitTypes.RenderUnit) – size units

See also

setSize()

See also

sizeUnit()

See also

setSizeMapUnitScale()

setStretchFactor(self, factor: int)

Sets the text’s stretch factor.

The stretch factor matches a condensed or expanded version of the font or applies a stretch transform that changes the width of all characters in the font by factor percent.

For example, setting factor to 150 results in all characters in the font being 1.5 times (ie. 150%) wider. The minimum stretch factor is 1, and the maximum stretch factor is 4000.

See also

stretchFactor()

New in version 3.24.

Parameters:

factor (int) –

setValid(self)

Sets the format to a valid state, without changing any of the default format settings.

See also

isValid()

New in version 3.16.

shadow(self) → QgsTextShadowSettings

Returns a reference to the text drop shadow settings.

See also

setShadow()

Return type:

QgsTextShadowSettings

size(self) → float

Returns the size for rendered text. Units are retrieved using sizeUnit().

See also

setSize()

See also

sizeUnit()

Return type:

float

sizeMapUnitScale(self) → QgsMapUnitScale

Returns the map unit scale object for the size. This is only used if the sizeUnit() is set to QgsUnitTypes.RenderMapUnit.

See also

setSizeMapUnitScale()

See also

sizeUnit()

Return type:

QgsMapUnitScale

sizeUnit(self) → QgsUnitTypes.RenderUnit

Returns the units for the size of rendered text.

See also

size()

See also

setSizeUnit()

See also

sizeMapUnitScale()

Return type:

QgsUnitTypes.RenderUnit

stretchFactor(self) → int

Returns the text’s stretch factor.

The stretch factor matches a condensed or expanded version of the font or applies a stretch transform that changes the width of all characters in the font by factor percent.

For example, a factor of 150 results in all characters in the font being 1.5 times (ie. 150%) wider. The minimum stretch factor is 1, and the maximum stretch factor is 4000.

See also

setStretchFactor()

New in version 3.24.

Return type:

int

textFormatPreviewPixmap(format: QgsTextFormat, size: QSize, previewText: str = '', padding: int = 0) → QPixmap

Returns a pixmap preview for a text format.

Parameters:

• format (QgsTextFormat) – text format

• size (QSize) – target pixmap size

• previewText (str = '') – text to render in preview, or empty for default text

• padding (int = 0) – space between icon edge and color ramp

New in version 3.10.

Return type:

QPixmap

toMimeData(self) → QMimeData

Returns new mime data representing the text format settings. Caller takes responsibility for deleting the returned object.

See also

fromMimeData()

Return type:

QMimeData

toQFont(self) → QFont

Returns a QFont matching the relevant settings from this text format. Unlike font(), this method also handles the size and size units from the text format.

See also

fromQFont()

New in version 3.2.

Return type:

QFont

updateDataDefinedProperties(self, context: QgsRenderContext)

Updates the format by evaluating current values of data defined properties.

New in version 3.10.

Parameters:

context (QgsRenderContext) –

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

Write settings into a DOM element.

See also

readXml()

Parameters:

• doc (QDomDocument) –

• context (QgsReadWriteContext) –

Return type:

QDomElement