Container for all settings relating to text rendering. More...

#include <qgstextformat.h>

Classes
class	Tab
	Defines a tab position for a text format. More...

Public Member Functions
	QgsTextFormat ()
	Default constructor for QgsTextFormat.
	QgsTextFormat (const QgsTextFormat &other)
	QgsTextFormat (QgsTextFormat &&other)
	~QgsTextFormat ()
bool	allowHtmlFormatting () const
	Returns `true` if text should be treated as a HTML document and HTML tags should be used for formatting the rendered text.
QString	asCSS (double pointToPixelMultiplier=1.0) const
	Returns a CSS string representing the specified text format as closely as possible.
QgsTextBackgroundSettings &	background ()
	Returns a reference to the text background settings.
QgsTextBackgroundSettings	background () const
	Returns a reference to the text background settings.
QPainter::CompositionMode	blendMode () const
	Returns the blending mode used for drawing the text.
QgsTextBufferSettings &	buffer ()
	Returns a reference to the text buffer settings.
QgsTextBufferSettings	buffer () const
	Returns a reference to the text buffer settings.
Qgis::Capitalization	capitalization () const
	Returns the text capitalization style.
QColor	color () const
	Returns the color that text will be rendered in.
bool	containsAdvancedEffects () const
	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.
QgsPropertyCollection &	dataDefinedProperties ()
	Returns a reference to the format's property collection, used for data defined overrides.
const QgsPropertyCollection &	dataDefinedProperties () const
	Returns a reference to the format's property collection, used for data defined overrides.
QStringList	families () const
	Returns the list of font families to use when restoring the text format, in order of precedence.
QFont	font () const
	Returns the font used for rendering text.
bool	fontFound () const
	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.
bool	forcedBold () const
	Returns `true` if the format is set to force a bold style.
bool	forcedItalic () const
	Returns `true` if the format is set to force an italic style.
bool	hasNonDefaultCompositionMode () const
	Returns `true` if any component of the font format requires a non-default composition mode.
bool	isValid () const
	Returns `true` if the format is valid.
double	lineHeight () const
	Returns the line height for text.
Qgis::RenderUnit	lineHeightUnit () const
	Returns the units for the line height for text.
QgsTextMaskSettings &	mask ()
	Returns a reference to the masking settings.
QgsTextMaskSettings	mask () const
	Returns a reference to the masking settings.
void	multiplyOpacity (double opacityFactor)
	Multiply opacity by opacityFactor.
QString	namedStyle () const
	Returns the named style for the font used for rendering text (e.g., "bold").
double	opacity () const
	Returns the text's opacity.
bool	operator!= (const QgsTextFormat &other) const
QgsTextFormat &	operator= (const QgsTextFormat &other)
QgsTextFormat &	operator= (QgsTextFormat &&other)
bool	operator== (const QgsTextFormat &other) const
Qgis::TextOrientation	orientation () const
	Returns the orientation of the text.
QColor	previewBackgroundColor () const
	Returns the background color for text previews.
void	readFromLayer (QgsVectorLayer *layer)
	Reads settings from a layer's custom properties (for QGIS 2.x projects).
void	readXml (const QDomElement &elem, const QgsReadWriteContext &context)
	Read settings from a DOM element.
QSet< QString >	referencedFields (const QgsRenderContext &context) const
	Returns all field names referenced by the configuration (e.g.
QString	resolvedFontFamily () const
	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.
QFont	scaledFont (const QgsRenderContext &context, double scaleFactor=1.0, bool *isZeroSize=nullptr) const
	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.
void	setAllowHtmlFormatting (bool allow)
	Sets whether text should be treated as a HTML document and HTML tags should be used for formatting the rendered text.
void	setBackground (const QgsTextBackgroundSettings &backgroundSettings)
	Sets the text's background settings.q.
void	setBlendMode (QPainter::CompositionMode mode)
	Sets the blending mode used for drawing the text.
void	setBuffer (const QgsTextBufferSettings &bufferSettings)
	Sets the text's buffer settings.
void	setCapitalization (Qgis::Capitalization capitalization)
	Sets the text capitalization style.
void	setColor (const QColor &color)
	Sets the color that text will be rendered in.
void	setDataDefinedProperties (const QgsPropertyCollection &collection)
	Sets the format's property collection, used for data defined overrides.
void	setFamilies (const QStringList &families)
	Sets a list of font families to use for the text format, in order of precedence.
void	setFont (const QFont &font)
	Sets the font used for rendering text.
void	setForcedBold (bool forced)
	Sets whether the format is set to force a bold style.
void	setForcedItalic (bool forced)
	Sets whether the format is set to force an italic style.
void	setLineHeight (double height)
	Sets the line height for text.
void	setLineHeightUnit (Qgis::RenderUnit unit)
	Sets the unit for the line height for text.
void	setMask (const QgsTextMaskSettings &maskSettings)
	Sets the text's masking settings.
void	setNamedStyle (const QString &style)
	Sets the named style for the font used for rendering text.
void	setOpacity (double opacity)
	Sets the text's opacity.
void	setOrientation (Qgis::TextOrientation orientation)
	Sets the orientation for the text.
void	setPreviewBackgroundColor (const QColor &color)
	Sets the background color that text will be rendered on for previews.
void	setShadow (const QgsTextShadowSettings &shadowSettings)
	Sets the text's drop shadow settings.
void	setSize (double size)
	Sets the size for rendered text.
void	setSizeMapUnitScale (const QgsMapUnitScale &scale)
	Sets the map unit scale object for the size.
void	setSizeUnit (Qgis::RenderUnit unit)
	Sets the units for the size of rendered text.
void	setStretchFactor (int factor)
	Sets the text's stretch factor.
void	setTabPositions (const QList< QgsTextFormat::Tab > &positions)
	Sets the list of tab positions for tab stops.
void	setTabStopDistance (double distance)
	Sets the distance for tab stops.
void	setTabStopDistanceMapUnitScale (const QgsMapUnitScale &scale)
	Sets the map unit scale object for the tab stop distance.
void	setTabStopDistanceUnit (Qgis::RenderUnit unit)
	Sets the unit used for the tab stop distance.
void	setValid ()
	Sets the format to a valid state, without changing any of the default format settings.
QgsTextShadowSettings &	shadow ()
	Returns a reference to the text drop shadow settings.
QgsTextShadowSettings	shadow () const
	Returns a reference to the text drop shadow settings.
double	size () const
	Returns the size for rendered text.
QgsMapUnitScale	sizeMapUnitScale () const
	Returns the map unit scale object for the size.
Qgis::RenderUnit	sizeUnit () const
	Returns the units for the size of rendered text.
int	stretchFactor () const
	Returns the text's stretch factor.
QList< QgsTextFormat::Tab >	tabPositions () const
	Returns the list of tab positions for tab stops.
double	tabStopDistance () const
	Returns the distance for tab stops.
QgsMapUnitScale	tabStopDistanceMapUnitScale () const
	Returns the map unit scale object for the tab stop distance.
Qgis::RenderUnit	tabStopDistanceUnit () const
	Returns the units for the tab stop distance.
QMimeData *	toMimeData () const
	Returns new mime data representing the text format settings.
QFont	toQFont () const
	Returns a QFont matching the relevant settings from this text format.
void	updateDataDefinedProperties (QgsRenderContext &context)
	Updates the format by evaluating current values of data defined properties.
QDomElement	writeXml (QDomDocument &doc, const QgsReadWriteContext &context) const
	Write settings into a DOM element.

Static Public Member Functions
static QgsTextFormat	fromMimeData (const QMimeData data, bool ok=nullptr)
	Attempts to parse the provided mime data as a QgsTextFormat.
static QgsTextFormat	fromQFont (const QFont &font)
	Returns a text format matching the settings from an input font.
static QPixmap	textFormatPreviewPixmap (const QgsTextFormat &format, QSize size, const QString &previewText=QString(), int padding=0, const QgsScreenProperties &screen=QgsScreenProperties())
	Returns a pixmap preview for a text format.

Detailed Description

Container for all settings relating to text rendering.

Note: QgsTextFormat objects are implicitly shared.

Definition at line 40 of file qgstextformat.h.

Constructor & Destructor Documentation

◆ QgsTextFormat() [1/3]

QgsTextFormat::QgsTextFormat ( )

Default constructor for QgsTextFormat.

Creates a text format initially set to an invalid state (see isValid()).

Definition at line 37 of file qgstextformat.cpp.

◆ QgsTextFormat() [2/3]

QgsTextFormat::QgsTextFormat ( const QgsTextFormat & other )

Definition at line 42 of file qgstextformat.cpp.

◆ QgsTextFormat() [3/3]

QgsTextFormat::QgsTextFormat ( QgsTextFormat && other )

Definition at line 56 of file qgstextformat.cpp.

◆ ~QgsTextFormat()

QgsTextFormat::~QgsTextFormat ( )

Definition at line 100 of file qgstextformat.cpp.

Member Function Documentation

◆ allowHtmlFormatting()

bool QgsTextFormat::allowHtmlFormatting ( ) const

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

Since: QGIS 3.14

Definition at line 491 of file qgstextformat.cpp.

◆ asCSS()

QString QgsTextFormat::asCSS ( double pointToPixelMultiplier = 1.0 ) const

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

Parameters

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

Returns: partial CSS string, e.g., "line-height: 120%;"

Since: QGIS 3.34

Definition at line 1406 of file qgstextformat.cpp.

◆ background() [1/2]

QgsTextBackgroundSettings & QgsTextFormat::background ( )

Returns a reference to the text background settings.

See also: setBackground()

Definition at line 166 of file qgstextformat.cpp.

◆ background() [2/2]

QgsTextBackgroundSettings QgsTextFormat::background ( ) const

inline

Returns a reference to the text background settings.

See also: setBackground()

Definition at line 112 of file qgstextformat.h.

◆ blendMode()

QPainter::CompositionMode QgsTextFormat::blendMode ( ) const

Returns the blending mode used for drawing the text.

See also: setBlendMode()

Definition at line 384 of file qgstextformat.cpp.

◆ buffer() [1/2]

QgsTextBufferSettings & QgsTextFormat::buffer ( )

Returns a reference to the text buffer settings.

See also: setBuffer()

Definition at line 154 of file qgstextformat.cpp.

◆ buffer() [2/2]

QgsTextBufferSettings QgsTextFormat::buffer ( ) const

inline

Returns a reference to the text buffer settings.

See also: setBuffer()

Definition at line 93 of file qgstextformat.h.

◆ capitalization()

Qgis::Capitalization QgsTextFormat::capitalization ( ) const

Returns the text capitalization style.

See also: setCapitalization()

Since: QGIS 3.16

Definition at line 472 of file qgstextformat.cpp.

◆ color()

QColor QgsTextFormat::color ( ) const

Returns the color that text will be rendered in.

See also: setColor()

Definition at line 340 of file qgstextformat.cpp.

◆ containsAdvancedEffects()

bool QgsTextFormat::containsAdvancedEffects ( ) const

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.

Definition at line 975 of file qgstextformat.cpp.

◆ dataDefinedProperties() [1/2]

QgsPropertyCollection & QgsTextFormat::dataDefinedProperties ( )

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

See also: setDataDefinedProperties()

Since: QGIS 3.10

Definition at line 1015 of file qgstextformat.cpp.

◆ dataDefinedProperties() [2/2]

const QgsPropertyCollection & QgsTextFormat::dataDefinedProperties ( ) const

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

See also: setDataDefinedProperties()

Note: not available in Python bindings

Since: QGIS 3.10

Definition at line 1021 of file qgstextformat.cpp.

◆ families()

QStringList QgsTextFormat::families ( ) const

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

Since: QGIS 3.20

Definition at line 296 of file qgstextformat.cpp.

◆ font()

QFont QgsTextFormat::font ( ) const

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(); setFont(); namedStyle(); toQFont()

Definition at line 202 of file qgstextformat.cpp.

◆ fontFound()

bool QgsTextFormat::fontFound ( ) const

inline

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

Definition at line 760 of file qgstextformat.h.

◆ forcedBold()

bool QgsTextFormat::forcedBold ( ) const

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

Since: QGIS 3.26

Definition at line 272 of file qgstextformat.cpp.

◆ forcedItalic()

bool QgsTextFormat::forcedItalic ( ) const

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

Since: QGIS 3.26

Definition at line 284 of file qgstextformat.cpp.

◆ fromMimeData()

QgsTextFormat QgsTextFormat::fromMimeData	(	const QMimeData *	data,
		bool *	ok = nullptr )

static

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

Definition at line 947 of file qgstextformat.cpp.

◆ fromQFont()

QgsTextFormat QgsTextFormat::fromQFont ( const QFont & font )

static

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

Since: QGIS 3.2

Definition at line 898 of file qgstextformat.cpp.

◆ hasNonDefaultCompositionMode()

bool QgsTextFormat::hasNonDefaultCompositionMode ( ) const

Returns true if any component of the font format requires a non-default composition mode.

The default composition mode is QPainter::CompositionMode_SourceOver.

Since: QGIS 3.44

Definition at line 992 of file qgstextformat.cpp.

◆ isValid()

bool QgsTextFormat::isValid ( ) const

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

Since: QGIS 3.16

Definition at line 144 of file qgstextformat.cpp.

◆ lineHeight()

double QgsTextFormat::lineHeight ( ) const

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

Definition at line 395 of file qgstextformat.cpp.

◆ lineHeightUnit()

Qgis::RenderUnit QgsTextFormat::lineHeightUnit ( ) const

Returns the units for the line height for text.

See also: setLineHeightUnit(); lineHeight()

Since: QGIS 3.28

Definition at line 406 of file qgstextformat.cpp.

◆ mask() [1/2]

QgsTextMaskSettings & QgsTextFormat::mask ( )

Returns a reference to the masking settings.

See also: setMask()

Definition at line 190 of file qgstextformat.cpp.

◆ mask() [2/2]

QgsTextMaskSettings QgsTextFormat::mask ( ) const

inline

Returns a reference to the masking settings.

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

See also: setMask()

Since: QGIS 3.12

Definition at line 152 of file qgstextformat.h.

◆ multiplyOpacity()

void QgsTextFormat::multiplyOpacity ( double opacityFactor )

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.

Since: QGIS 3.32

Definition at line 356 of file qgstextformat.cpp.

◆ namedStyle()

QString QgsTextFormat::namedStyle ( ) const

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

See also: setNamedStyle(); font()

Definition at line 256 of file qgstextformat.cpp.

◆ opacity()

double QgsTextFormat::opacity ( ) const

Returns the text's opacity.

The opacity is a double value between 0 (fully transparent) and 1 (totally opaque).

See also: setOpacity()

Definition at line 351 of file qgstextformat.cpp.

◆ operator!=()

bool QgsTextFormat::operator!= ( const QgsTextFormat & other ) const

Definition at line 139 of file qgstextformat.cpp.

◆ operator=() [1/2]

QgsTextFormat & QgsTextFormat::operator= ( const QgsTextFormat & other )

Definition at line 68 of file qgstextformat.cpp.

◆ operator=() [2/2]

QgsTextFormat & QgsTextFormat::operator= ( QgsTextFormat && other )

Definition at line 85 of file qgstextformat.cpp.

◆ operator==()

bool QgsTextFormat::operator== ( const QgsTextFormat & other ) const

Definition at line 105 of file qgstextformat.cpp.

◆ orientation()

Qgis::TextOrientation QgsTextFormat::orientation ( ) const

Returns the orientation of the text.

See also: setOrientation()

Since: QGIS 3.10

Definition at line 461 of file qgstextformat.cpp.

◆ previewBackgroundColor()

QColor QgsTextFormat::previewBackgroundColor ( ) const

Returns the background color for text previews.

See also: setPreviewBackgroundColor()

Since: QGIS 3.10

Definition at line 502 of file qgstextformat.cpp.

◆ readFromLayer()

void QgsTextFormat::readFromLayer ( QgsVectorLayer * layer )

Reads settings from a layer's custom properties (for QGIS 2.x projects).

Parameters

layer source vector layer

Definition at line 513 of file qgstextformat.cpp.

◆ readXml()

void QgsTextFormat::readXml	(	const QDomElement &	elem,
		const QgsReadWriteContext &	context )

Read settings from a DOM element.

See also: writeXml()

Definition at line 598 of file qgstextformat.cpp.

◆ referencedFields()

QSet< QString > QgsTextFormat::referencedFields ( const QgsRenderContext & context ) const

Returns all field names referenced by the configuration (e.g.

from data defined properties).

Since: QGIS 3.14

Definition at line 1026 of file qgstextformat.cpp.

◆ resolvedFontFamily()

QString QgsTextFormat::resolvedFontFamily ( ) const

inline

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

Definition at line 768 of file qgstextformat.h.

◆ scaledFont()

QFont QgsTextFormat::scaledFont	(	const QgsRenderContext &	context,
		double	scaleFactor = 1.0,
		bool *	isZeroSize = nullptr ) const

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	destination render context
scaleFactor	optional font size scaling factor. It is recommended to set this to QgsTextRenderer::calculateScaleFactorForFormat() 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.
isZeroSize	will be set to true if the font is scaled down to a near 0 size, and nothing should be rendered. Not available in Python bindings.

Returns: font with scaled size

See also: font(); size()

Definition at line 207 of file qgstextformat.cpp.

◆ setAllowHtmlFormatting()

void QgsTextFormat::setAllowHtmlFormatting ( bool allow )

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

Since: QGIS 3.14

Definition at line 496 of file qgstextformat.cpp.

◆ setBackground()

void QgsTextFormat::setBackground ( const QgsTextBackgroundSettings & backgroundSettings )

Sets the text's background settings.q.

Parameters

backgroundSettings background settings

See also: background()

Definition at line 172 of file qgstextformat.cpp.

◆ setBlendMode()

void QgsTextFormat::setBlendMode ( QPainter::CompositionMode mode )

Sets the blending mode used for drawing the text.

Parameters

mode	blending mode

See also: blendMode()

Definition at line 389 of file qgstextformat.cpp.

◆ setBuffer()

void QgsTextFormat::setBuffer ( const QgsTextBufferSettings & bufferSettings )

Sets the text's buffer settings.

Parameters

bufferSettings buffer settings

See also: buffer()

Definition at line 160 of file qgstextformat.cpp.

◆ setCapitalization()

void QgsTextFormat::setCapitalization ( Qgis::Capitalization capitalization )

Sets the text capitalization style.

See also: capitalization()

Since: QGIS 3.16

Definition at line 480 of file qgstextformat.cpp.

◆ setColor()

void QgsTextFormat::setColor ( const QColor & color )

Sets the color that text will be rendered in.

Parameters

color text color

See also: color()

Definition at line 345 of file qgstextformat.cpp.

◆ setDataDefinedProperties()

void QgsTextFormat::setDataDefinedProperties ( const QgsPropertyCollection & collection )

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

Parameters

collection property collection. Existing properties will be replaced.

See also: dataDefinedProperties()

Since: QGIS 3.10

Definition at line 1036 of file qgstextformat.cpp.

◆ setFamilies()

void QgsTextFormat::setFamilies ( const QStringList & families )

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

Since: QGIS 3.20

Definition at line 301 of file qgstextformat.cpp.

◆ setFont()

void QgsTextFormat::setFont ( const QFont & font )

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

See also: font(); setNamedStyle(); fromQFont()

Definition at line 249 of file qgstextformat.cpp.

◆ setForcedBold()

void QgsTextFormat::setForcedBold ( bool forced )

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

Since: QGIS 3.26

Definition at line 277 of file qgstextformat.cpp.

◆ setForcedItalic()

void QgsTextFormat::setForcedItalic ( bool forced )

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

Since: QGIS 3.26

Definition at line 289 of file qgstextformat.cpp.

◆ setLineHeight()

void QgsTextFormat::setLineHeight ( double height )

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

Definition at line 400 of file qgstextformat.cpp.

◆ setLineHeightUnit()

void QgsTextFormat::setLineHeightUnit ( Qgis::RenderUnit unit )

Sets the unit for the line height for text.

See also: lineHeightUnit(); setLineHeight()

Since: QGIS 3.28

Definition at line 411 of file qgstextformat.cpp.

◆ setMask()

void QgsTextFormat::setMask ( const QgsTextMaskSettings & maskSettings )

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

See also: mask()

Since: QGIS 3.12

Definition at line 196 of file qgstextformat.cpp.

◆ setNamedStyle()

void QgsTextFormat::setNamedStyle ( const QString & style )

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

Parameters

style named style, e.g., "bold"

See also: namedStyle(); setFont()

Definition at line 265 of file qgstextformat.cpp.

◆ setOpacity()

void QgsTextFormat::setOpacity ( double opacity )

Sets the text's opacity.

Parameters

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

See also: opacity()

Definition at line 367 of file qgstextformat.cpp.

◆ setOrientation()

void QgsTextFormat::setOrientation ( Qgis::TextOrientation orientation )

Sets the orientation for the text.

See also: orientation()

Since: QGIS 3.10

Definition at line 466 of file qgstextformat.cpp.

◆ setPreviewBackgroundColor()

void QgsTextFormat::setPreviewBackgroundColor ( const QColor & color )

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

See also: previewBackgroundColor()

Since: QGIS 3.10

Definition at line 507 of file qgstextformat.cpp.

◆ setShadow()

void QgsTextFormat::setShadow ( const QgsTextShadowSettings & shadowSettings )

Sets the text's drop shadow settings.

Parameters

shadowSettings shadow settings

See also: shadow()

Definition at line 184 of file qgstextformat.cpp.

◆ setSize()

void QgsTextFormat::setSize ( double size )

Sets the size for rendered text.

Parameters

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

See also: size(); setSizeUnit()

Definition at line 334 of file qgstextformat.cpp.

◆ setSizeMapUnitScale()

void QgsTextFormat::setSizeMapUnitScale ( const QgsMapUnitScale & scale )

Sets the map unit scale object for the size.

This is only used if the sizeUnit() is set to QgsUnitTypes::RenderMapUnit.

See also: sizeMapUnitScale(); setSizeUnit()

Definition at line 323 of file qgstextformat.cpp.

◆ setSizeUnit()

void QgsTextFormat::setSizeUnit ( Qgis::RenderUnit unit )

Sets the units for the size of rendered text.

Parameters

unit	size units

See also: setSize(); sizeUnit(); setSizeMapUnitScale()

Definition at line 312 of file qgstextformat.cpp.

◆ setStretchFactor()

void QgsTextFormat::setStretchFactor ( int factor )

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

Since: QGIS 3.24

Definition at line 378 of file qgstextformat.cpp.

◆ setTabPositions()

void QgsTextFormat::setTabPositions ( const QList< QgsTextFormat::Tab > & positions )

Sets the list of tab positions for tab stops.

The units are specified using setTabStopDistanceUnit().

Note: If non-empty, this list overrides any distance defined by setTabStopDistance().

See also: tabPositions(); setTabStopDistance(); setTabStopDistanceUnit()

Since: QGIS 3.42

Definition at line 433 of file qgstextformat.cpp.

◆ setTabStopDistance()

void QgsTextFormat::setTabStopDistance ( double distance )

Sets the distance for tab stops.

The units are specified using setTabStopDistanceUnit().

Note: This value will be ignored if tabPositions() is non-empty.

See also: tabPositions(); tabStopDistance(); setTabStopDistanceUnit()

Since: QGIS 3.38

Definition at line 422 of file qgstextformat.cpp.

◆ setTabStopDistanceMapUnitScale()

void QgsTextFormat::setTabStopDistanceMapUnitScale ( const QgsMapUnitScale & scale )

Sets the map unit scale object for the tab stop distance.

This is only used if the tab stop distance is set to Qgis::RenderUnit::MapUnits.

See also: tabStopDistanceMapUnitScale(); setTabStopDistanceUnit()

Since: QGIS 3.38

Definition at line 455 of file qgstextformat.cpp.

◆ setTabStopDistanceUnit()

void QgsTextFormat::setTabStopDistanceUnit ( Qgis::RenderUnit unit )

Sets the unit used for the tab stop distance.

See also: setTabStopDistance(); setTabPositions(); tabStopDistanceUnit()

Since: QGIS 3.38

Definition at line 444 of file qgstextformat.cpp.

◆ setValid()

void QgsTextFormat::setValid ( )

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

See also: isValid()

Since: QGIS 3.16

Definition at line 149 of file qgstextformat.cpp.

◆ shadow() [1/2]

QgsTextShadowSettings & QgsTextFormat::shadow ( )

Returns a reference to the text drop shadow settings.

See also: setShadow()

Definition at line 178 of file qgstextformat.cpp.

◆ shadow() [2/2]

QgsTextShadowSettings QgsTextFormat::shadow ( ) const

inline

Returns a reference to the text drop shadow settings.

See also: setShadow()

Definition at line 131 of file qgstextformat.h.

◆ size()

double QgsTextFormat::size ( ) const

Returns the size for rendered text.

Units are retrieved using sizeUnit().

See also: setSize(); sizeUnit()

Definition at line 329 of file qgstextformat.cpp.

◆ sizeMapUnitScale()

QgsMapUnitScale QgsTextFormat::sizeMapUnitScale ( ) const

Returns the map unit scale object for the size.

This is only used if the sizeUnit() is set to QgsUnitTypes::RenderMapUnit.

See also: setSizeMapUnitScale(); sizeUnit()

Definition at line 318 of file qgstextformat.cpp.

◆ sizeUnit()

Qgis::RenderUnit QgsTextFormat::sizeUnit ( ) const

Returns the units for the size of rendered text.

See also: size(); setSizeUnit(); sizeMapUnitScale()

Definition at line 307 of file qgstextformat.cpp.

◆ stretchFactor()

int QgsTextFormat::stretchFactor ( ) const

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

Since: QGIS 3.24

Definition at line 373 of file qgstextformat.cpp.

◆ tabPositions()

QList< QgsTextFormat::Tab > QgsTextFormat::tabPositions ( ) const

Returns the list of tab positions for tab stops.

The units are specified using tabStopDistanceUnit().

Note: If non-empty, this list overrides any distance defined by tabStopDistance().

See also: setTabPositions(); tabStopDistance(); tabStopDistanceUnit(); setTabStopDistance()

Since: QGIS 3.42

Definition at line 428 of file qgstextformat.cpp.

◆ tabStopDistance()

double QgsTextFormat::tabStopDistance ( ) const

Returns the distance for tab stops.

Note: This value will be ignored if tabPositions() is non-empty.

See also: tabPositions(); tabStopDistanceUnit(); setTabStopDistance()

Since: QGIS 3.38

Definition at line 417 of file qgstextformat.cpp.

◆ tabStopDistanceMapUnitScale()

QgsMapUnitScale QgsTextFormat::tabStopDistanceMapUnitScale ( ) const

Returns the map unit scale object for the tab stop distance.

This is only used if the tab stop distance is set to Qgis::RenderUnit::MapUnits.

See also: setTabStopDistanceMapUnitScale(); tabStopDistanceUnit()

Since: QGIS 3.38

Definition at line 450 of file qgstextformat.cpp.

◆ tabStopDistanceUnit()

Qgis::RenderUnit QgsTextFormat::tabStopDistanceUnit ( ) const

Returns the units for the tab stop distance.

See also: tabStopDistance(); tabPositions(); setTabStopDistanceUnit()

Since: QGIS 3.38

Definition at line 439 of file qgstextformat.cpp.

◆ textFormatPreviewPixmap()

QPixmap QgsTextFormat::textFormatPreviewPixmap	(	const QgsTextFormat &	format,
		QSize	size,
		const QString &	previewText = QString(),
		int	padding = 0,
		const QgsScreenProperties &	screen = QgsScreenProperties() )

static

Returns a pixmap preview for a text format.

Parameters

format	text format
size	target pixmap size
previewText	text to render in preview, or empty for default text
padding	space between icon edge and color ramp
screen	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)

Since: QGIS 3.10

Definition at line 1284 of file qgstextformat.cpp.

◆ toMimeData()

QMimeData * QgsTextFormat::toMimeData ( ) const

Returns new mime data representing the text format settings.

Caller takes responsibility for deleting the returned object.

See also: fromMimeData()

Definition at line 882 of file qgstextformat.cpp.

◆ toQFont()

QFont QgsTextFormat::toQFont ( ) const

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

Since: QGIS 3.2

Definition at line 916 of file qgstextformat.cpp.

◆ updateDataDefinedProperties()

void QgsTextFormat::updateDataDefinedProperties ( QgsRenderContext & context )

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

Since: QGIS 3.10

Definition at line 1042 of file qgstextformat.cpp.

◆ writeXml()

QDomElement QgsTextFormat::writeXml	(	QDomDocument &	doc,
		const QgsReadWriteContext &	context ) const

Write settings into a DOM element.

See also: readXml()

Definition at line 811 of file qgstextformat.cpp.

The documentation for this class was generated from the following files:

/build/qgis-3.99.0+git20251210+2fe06baccd8+99sid/src/core/textrenderer/qgstextformat.h
/build/qgis-3.99.0+git20251210+2fe06baccd8+99sid/src/core/textrenderer/qgstextformat.cpp

Classes

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ QgsTextFormat() [1/3]

◆ QgsTextFormat() [2/3]

◆ QgsTextFormat() [3/3]

◆ ~QgsTextFormat()

Member Function Documentation

◆ allowHtmlFormatting()

◆ asCSS()

◆ background() [1/2]

◆ background() [2/2]

◆ blendMode()

◆ buffer() [1/2]

◆ buffer() [2/2]

◆ capitalization()

◆ color()

◆ containsAdvancedEffects()

◆ dataDefinedProperties() [1/2]

◆ dataDefinedProperties() [2/2]

◆ families()

◆ font()

◆ fontFound()

◆ forcedBold()

◆ forcedItalic()

◆ fromMimeData()

◆ fromQFont()

◆ hasNonDefaultCompositionMode()

◆ isValid()

◆ lineHeight()

◆ lineHeightUnit()

◆ mask() [1/2]

◆ mask() [2/2]

◆ multiplyOpacity()

◆ namedStyle()

◆ opacity()

◆ operator!=()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ orientation()

◆ previewBackgroundColor()

◆ readFromLayer()

◆ readXml()

◆ referencedFields()

◆ resolvedFontFamily()

◆ scaledFont()

◆ setAllowHtmlFormatting()

◆ setBackground()

◆ setBlendMode()

◆ setBuffer()

◆ setCapitalization()

◆ setColor()

◆ setDataDefinedProperties()

◆ setFamilies()

◆ setFont()

◆ setForcedBold()

◆ setForcedItalic()

◆ setLineHeight()

◆ setLineHeightUnit()

◆ setMask()

◆ setNamedStyle()

◆ setOpacity()

◆ setOrientation()

◆ setPreviewBackgroundColor()

◆ setShadow()

◆ setSize()

◆ setSizeMapUnitScale()

◆ setSizeUnit()

◆ setStretchFactor()

◆ setTabPositions()

◆ setTabStopDistance()

◆ setTabStopDistanceMapUnitScale()

◆ setTabStopDistanceUnit()

◆ setValid()

◆ shadow() [1/2]

◆ shadow() [2/2]

◆ size()