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

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.

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.

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.

setLineHeight

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

Attributes

HorizontalOrientation

RotationBasedOrientation

VerticalOrientation

HorizontalOrientation = 0
RotationBasedOrientation = 2
class TextOrientation

Bases: int

VerticalOrientation = 1
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

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

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. This is a number between 0.0 and 10.0 representing the leading between lines as a multiplier of line height.

See also

setLineHeight()

Return type

float

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) QgsTextFormat.TextOrientation

Returns the orientation of the text.

See also

setOrientation()

New in version 3.10.

Return type

QgsTextFormat.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: Union[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()

setLineHeight(self, height: float)

Sets the line height for text.

Parameters

height (float) – a number between 0.0 and 10.0 representing the leading between lines as a multiplier of line height.

See also

lineHeight()

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: QgsTextFormat.TextOrientation)

Sets the orientation for the text.

See also

orientation()

New in version 3.10.

Parameters

orientation (QgsTextFormat.TextOrientation) –

setPreviewBackgroundColor(self, color: Union[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: QgsUnitTypes.RenderUnit)

Sets the units for the size of rendered text.

Parameters

unit (QgsUnitTypes.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) QgsUnitTypes.RenderUnit

Returns the units for the size of rendered text.

See also

size()

See also

setSizeUnit()

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.

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

QDomElement