Class: QgsTextFormat

class qgis.core.QgsTextFormat

Bases: sip.wrapper

Container for all settings relating to text rendering.

Note

QgsTextFormat objects are implicitly shared.

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.

asCSS

Returns a CSS string representing the specified text format as closely as possible.

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.

multiplyOpacity

Multiply opacity by opacityFactor.

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. from data defined properties).

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

New in version 3.14.

Return type:

bool

asCSS(self, pointToPixelMultiplier: float = 1) str

Returns a CSS string representing the specified text format as closely as possible.

Parameters:

pointToPixelMultiplier (float = 1) – scaling factor to apply to convert point sizes to pixel font sizes. The CSS returned by this function will always use pixels for font sizes, so this parameter should be set to a suitable value to convert point sizes to pixels (e.g., taking into account destination DPI)

Return type:

str

Returns:

partial CSS string, e.g., “line-height: 120%;”

New in version 3.34.

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.

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.

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.

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.

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) Qgis.RenderUnit

Returns the units for the line height for text.

See also

lineHeight()

New in version 3.28.

Return type:

Qgis.RenderUnit

mask(self) QgsTextMaskSettings

Returns a reference to the masking settings.

See also

setMask()

Return type:

QgsTextMaskSettings

multiplyOpacity(self, opacityFactor: float)

Multiply opacity by opacityFactor.

This method multiplies the opacity of all the labeling elements (text, shadow, buffer etc.) by opacityFactor effectively changing the opacity of the whole labeling.

New in version 3.32.

Parameters:

opacityFactor (float) –

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.

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:
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

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.

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()

Parameters:

height (float) –

setLineHeightUnit(self, unit: Qgis.RenderUnit)

Sets the unit for the line height for text.

See also

lineHeightUnit()

See also

setLineHeight()

New in version 3.28.

Parameters:

unit (Qgis.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.

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

setSizeUnit()

Parameters:

scale (QgsMapUnitScale) –

setSizeUnit(self, unit: Qgis.RenderUnit)

Sets the units for the size of rendered text.

Parameters:

unit (Qgis.RenderUnit) – size units

See also

setSize()

See also

sizeUnit()

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

sizeUnit()

Return type:

QgsMapUnitScale

sizeUnit(self) Qgis.RenderUnit

Returns the units for the size of rendered text.

See also

size()

See also

setSizeUnit()

Return type:

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

New in version 3.24.

Return type:

int

textFormatPreviewPixmap(format: QgsTextFormat, size: QSize, previewText: str = '', padding: int = 0, screen: QgsScreenProperties = QgsScreenProperties()) 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

  • screen (QgsScreenProperties = QgsScreenProperties()) – can be used to specify the destination screen properties for the icon. This allows the icon to be generated using the correct DPI and device pixel ratio for the target screen (since QGIS 3.32)

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:
Return type:

QDomElement