Class: QgsTextFormat

class qgis.core.QgsTextFormat

Bases: sip.wrapper

QgsTextFormat(other: QgsTextFormat) Copy constructor.

Parameters

other – source QgsTextFormat

Container for all settings relating to text rendering.

Note

QgsTextFormat objects are implicitly shared.

Methods

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.

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.

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.

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.

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.

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.

setColor

Sets the color that text will be rendered in.

setDataDefinedProperties

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

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.

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.

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

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

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

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

Return type

QFont

Returns

font with scaled size

See also

font()

See also

size()

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

setColor(self, color: Union[QColor, Qt.GlobalColor, QGradient])

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.

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, QGradient])

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

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

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