Stores information relating to individual character formatting. More...

#include <qgstextcharacterformat.h>

Public Types
enum class	BooleanValue { NotSet , SetTrue , SetFalse }
	Status values for boolean format properties. More...

Public Member Functions
	QgsTextCharacterFormat ()=default
	QgsTextCharacterFormat (const QTextCharFormat &format)
	Constructor for QgsTextCharacterFormat, based on the specified QTextCharFormat format.
QBrush	backgroundBrush () const
	Returns the brush used for rendering the background of the fragment.
QString	backgroundImagePath () const
	Returns the path for the image to be used for rendering the background of the fragment.
QString	family () const
	Returns the font family name, or an empty string if the family is not set and should be inherited.
double	fontPercentageSize () const
	Returns the font percentage size (as fraction of inherited font size), or -1 if the font size percentage is not set.
double	fontPointSize () const
	Returns the font point size, or -1 if the font size is not set and should be inherited.
int	fontWeight () const
	Returns the font weight, or -1 if the font weight is not set and should be inherited.
bool	hasBackground () const
	Returns `true` if the fragment has a background set.
bool	hasVerticalAlignmentSet () const
	Returns `true` if the format has an explicit vertical alignment set.
QString	imagePath () const
	Returns the path to the image to render, if the format applies to a document image fragment.
QSizeF	imageSize () const
	Returns the image size, if the format applies to a document image fragment.
BooleanValue	italic () const
	Returns whether the format has italic enabled.
BooleanValue	overline () const
	Returns whether the format has overline enabled.
void	overrideWith (const QgsTextCharacterFormat &other)
	Override all the default/unset properties of the current character format with the settings from another format.
void	setBackgroundBrush (const QBrush &brush)
	Sets the brush used for rendering the background of the fragment.
void	setBackgroundImagePath (const QString &path)
	Sets the path for the image to be used for rendering the background of the fragment.
void	setFamily (const QString &family)
	Sets the font family name.
void	setFontPercentageSize (double size)
	Sets the font percentage size (as fraction of inherited font size).
void	setFontPointSize (double size)
	Sets the font point size.
void	setFontWeight (int fontWeight)
	Sets the font weight.
void	setHasVerticalAlignmentSet (bool set)
	Sets whether the format has an explicit vertical alignment set.
void	setImagePath (const QString &path)
	Sets the path to the image to render, if the format applies to a document image fragment.
void	setImageSize (const QSizeF &size)
	Sets the image size, if the format applies to a document image fragment.
void	setItalic (BooleanValue enabled)
	Sets whether the format has italic enabled.
void	setOverline (BooleanValue enabled)
	Sets whether the format has overline enabled.
void	setStrikeOut (BooleanValue enabled)
	Sets whether the format has strikethrough enabled.
void	setTextColor (const QColor &textColor)
	Sets the character's text color.
void	setUnderline (BooleanValue enabled)
	Sets whether the format has underline enabled.
void	setVerticalAlignment (Qgis::TextCharacterVerticalAlignment alignment)
	Sets the format vertical alignment.
void	setWordSpacing (double spacing)
	Sets the font word spacing, in points, or NaN if word spacing is not set and should be inherited.
BooleanValue	strikeOut () const
	Returns whether the format has strikethrough enabled.
QColor	textColor () const
	Returns the character's text color, or an invalid color if no color override is set and the default format color should be used.
BooleanValue	underline () const
	Returns whether the format has underline enabled.
void	updateFontForFormat (QFont &font, const QgsRenderContext &context, double scaleFactor=1.0) const
	Updates the specified font in place, applying character formatting options which are applicable on a font level when rendered in the given context.
Qgis::TextCharacterVerticalAlignment	verticalAlignment () const
	Returns the format vertical alignment.
double	wordSpacing () const
	Returns the font word spacing, in points, or NaN if word spacing is not set and should be inherited.

Detailed Description

Stores information relating to individual character formatting.

These options encapsulate formatting options which override the default settings from a QgsTextFormat for individual characters (or sets of characters).

Warning: This API is not considered stable and may change in future QGIS versions.

Since: QGIS 3.14

Definition at line 43 of file qgstextcharacterformat.h.

Member Enumeration Documentation

◆ BooleanValue

enum class QgsTextCharacterFormat::BooleanValue

strong

Status values for boolean format properties.

Enumerator
NotSet	Property is not set.
SetTrue	Property is set and `true`.
SetFalse	Property is set and `false`.

Definition at line 55 of file qgstextcharacterformat.h.

Constructor & Destructor Documentation

◆ QgsTextCharacterFormat() [1/2]

QgsTextCharacterFormat::QgsTextCharacterFormat ( )

default

◆ QgsTextCharacterFormat() [2/2]

QgsTextCharacterFormat::QgsTextCharacterFormat ( const QTextCharFormat & format )

Constructor for QgsTextCharacterFormat, based on the specified QTextCharFormat format.

Definition at line 46 of file qgstextcharacterformat.cpp.

Member Function Documentation

◆ backgroundBrush()

QBrush QgsTextCharacterFormat::backgroundBrush ( ) const

Returns the brush used for rendering the background of the fragment.

Alternatively, the format may have a backgroundImagePath() set.

See also: hasBackground(); setBackgroundBrush()

Since: QGIS 3.42

Definition at line 307 of file qgstextcharacterformat.cpp.

◆ backgroundImagePath()

QString QgsTextCharacterFormat::backgroundImagePath ( ) const

Returns the path for the image to be used for rendering the background of the fragment.

Alternatively, the format may have a backgroundBrush() set.

See also: hasBackground(); setBackgroundImagePath()

Since: QGIS 3.42

Definition at line 262 of file qgstextcharacterformat.cpp.

◆ family()

QString QgsTextCharacterFormat::family ( ) const

Returns the font family name, or an empty string if the family is not set and should be inherited.

See also: setFamily()

Since: QGIS 3.28

Definition at line 144 of file qgstextcharacterformat.cpp.

◆ fontPercentageSize()

double QgsTextCharacterFormat::fontPercentageSize ( ) const

Returns the font percentage size (as fraction of inherited font size), or -1 if the font size percentage is not set.

Note: A format should have either fontPointSize() or fontPercentageSize() set, not both.

See also: fontPointSize(); setFontPercentageSize()

Since: QGIS 3.40

Definition at line 134 of file qgstextcharacterformat.cpp.

◆ fontPointSize()

double QgsTextCharacterFormat::fontPointSize ( ) const

Returns the font point size, or -1 if the font size is not set and should be inherited.

Note: A format should have either fontPointSize() or fontPercentageSize() set, not both.

See also: fontPercentageSize(); setFontPointSize()

Since: QGIS 3.28

Definition at line 124 of file qgstextcharacterformat.cpp.

◆ fontWeight()

int QgsTextCharacterFormat::fontWeight ( ) const

Returns the font weight, or -1 if the font weight is not set and should be inherited.

See also: setFontWeight()

Since: QGIS 3.28

Definition at line 282 of file qgstextcharacterformat.cpp.

◆ hasBackground()

bool QgsTextCharacterFormat::hasBackground ( ) const

Returns true if the fragment has a background set.

See also: backgroundBrush()

Since: QGIS 3.42

Definition at line 302 of file qgstextcharacterformat.cpp.

◆ hasVerticalAlignmentSet()

bool QgsTextCharacterFormat::hasVerticalAlignmentSet ( ) const

inline

Returns true if the format has an explicit vertical alignment set.

If false is returned then the vertical alignment will be inherited.

See also: setHasVerticalAlignmentSet(); verticalAlignment()

Since: QGIS 3.30

Definition at line 316 of file qgstextcharacterformat.h.

◆ imagePath()

QString QgsTextCharacterFormat::imagePath ( ) const

Returns the path to the image to render, if the format applies to a document image fragment.

See also: QgsTextFragment::isImage(); imageSize(); setImagePath()

Since: QGIS 3.40

Definition at line 184 of file qgstextcharacterformat.cpp.

◆ imageSize()

QSizeF QgsTextCharacterFormat::imageSize ( ) const

Returns the image size, if the format applies to a document image fragment.

The image size is always considered to be in Qgis::RenderUnit::Points.

See also: QgsTextFragment::isImage(); imagePath(); setImageSize()

Since: QGIS 3.40

Definition at line 194 of file qgstextcharacterformat.cpp.

◆ italic()

QgsTextCharacterFormat::BooleanValue QgsTextCharacterFormat::italic ( ) const

Returns whether the format has italic enabled.

See also: setItalic()

Since: QGIS 3.28

Definition at line 272 of file qgstextcharacterformat.cpp.

◆ overline()

QgsTextCharacterFormat::BooleanValue QgsTextCharacterFormat::overline ( ) const

Returns whether the format has overline enabled.

See also: setUnderline()

Definition at line 174 of file qgstextcharacterformat.cpp.

◆ overrideWith()

void QgsTextCharacterFormat::overrideWith ( const QgsTextCharacterFormat & other )

Override all the default/unset properties of the current character format with the settings from another format.

This will replace any default/unset existing settings with the settings from other.

Any settings which are default/unset in other will be left unchanged.

Parameters

other The format to override with.

Since: QGIS 3.36

Definition at line 79 of file qgstextcharacterformat.cpp.

◆ setBackgroundBrush()

void QgsTextCharacterFormat::setBackgroundBrush ( const QBrush & brush )

Sets the brush used for rendering the background of the fragment.

Alternatively, the format may have a backgroundImagePath() set.

See also: backgroundBrush()

Since: QGIS 3.42

Definition at line 312 of file qgstextcharacterformat.cpp.

◆ setBackgroundImagePath()

void QgsTextCharacterFormat::setBackgroundImagePath ( const QString & path )

Sets the path for the image to be used for rendering the background of the fragment.

Alternatively, the format may have a backgroundBrush() set.

See also: backgroundImagePath()

Since: QGIS 3.42

Definition at line 267 of file qgstextcharacterformat.cpp.

◆ setFamily()

void QgsTextCharacterFormat::setFamily ( const QString & family )

Sets the font family name.

Set to an empty string if the family should be inherited.

See also: family()

Since: QGIS 3.28

Definition at line 149 of file qgstextcharacterformat.cpp.

◆ setFontPercentageSize()

void QgsTextCharacterFormat::setFontPercentageSize ( double size )

Sets the font percentage size (as fraction of inherited font size).

Set size to -1 if the font percentange size is not set.

Note: A format should have either fontPointSize() or fontPercentageSize() set, not both.

See also: fontPercentageSize(); setFontPointSize()

Since: QGIS 3.40

Definition at line 139 of file qgstextcharacterformat.cpp.

◆ setFontPointSize()

void QgsTextCharacterFormat::setFontPointSize ( double size )

Sets the font point size.

Set size to -1 if the font size is not set and should be inherited.

Note: A format should have either fontPointSize() or fontPercentageSize() set, not both.

See also: fontPointSize(); setFontPercentageSize()

Since: QGIS 3.28

Definition at line 129 of file qgstextcharacterformat.cpp.

◆ setFontWeight()

void QgsTextCharacterFormat::setFontWeight ( int fontWeight )

Sets the font weight.

Set weight to -1 if the font weight is not set and should be inherited.

See also: fontWeight()

Since: QGIS 3.28

Definition at line 287 of file qgstextcharacterformat.cpp.

◆ setHasVerticalAlignmentSet()

void QgsTextCharacterFormat::setHasVerticalAlignmentSet ( bool set )

inline

Sets whether the format has an explicit vertical alignment set.

If set is false then the vertical alignment will be inherited.

See also: hasVerticalAlignmentSet(); setVerticalAlignment()

Since: QGIS 3.30

Definition at line 328 of file qgstextcharacterformat.h.

◆ setImagePath()

void QgsTextCharacterFormat::setImagePath ( const QString & path )

Sets the path to the image to render, if the format applies to a document image fragment.

See also: QgsTextFragment::isImage(); setImageSize(); imagePath()

Since: QGIS 3.40

Definition at line 189 of file qgstextcharacterformat.cpp.

◆ setImageSize()

void QgsTextCharacterFormat::setImageSize ( const QSizeF & size )

Sets the image size, if the format applies to a document image fragment.

The image size is always considered to be in Qgis::RenderUnit::Points.

See also: QgsTextFragment::isImage(); setImagePath(); imageSize()

Since: QGIS 3.40

Definition at line 199 of file qgstextcharacterformat.cpp.

◆ setItalic()

void QgsTextCharacterFormat::setItalic ( QgsTextCharacterFormat::BooleanValue enabled )

Sets whether the format has italic enabled.

See also: italic()

Since: QGIS 3.28

Definition at line 277 of file qgstextcharacterformat.cpp.

◆ setOverline()

void QgsTextCharacterFormat::setOverline ( QgsTextCharacterFormat::BooleanValue enabled )

Sets whether the format has overline enabled.

See also: overline()

Definition at line 179 of file qgstextcharacterformat.cpp.

◆ setStrikeOut()

void QgsTextCharacterFormat::setStrikeOut ( BooleanValue enabled )

Sets whether the format has strikethrough enabled.

See also: strikeOut()

Definition at line 159 of file qgstextcharacterformat.cpp.

◆ setTextColor()

void QgsTextCharacterFormat::setTextColor ( const QColor & textColor )

Sets the character's text color.

Set color to an invalid color if no color override is desired and the default format color should be used.

See also: textColor()

Definition at line 119 of file qgstextcharacterformat.cpp.

◆ setUnderline()

void QgsTextCharacterFormat::setUnderline ( BooleanValue enabled )

Sets whether the format has underline enabled.

See also: underline()

Definition at line 169 of file qgstextcharacterformat.cpp.

◆ setVerticalAlignment()

void QgsTextCharacterFormat::setVerticalAlignment ( Qgis::TextCharacterVerticalAlignment alignment )

inline

Sets the format vertical alignment.

This property is only respected if hasVerticalAlignmentSet() is true.

See also: hasVerticalAlignmentSet(); verticalAlignment()

Since: QGIS 3.30

Definition at line 352 of file qgstextcharacterformat.h.

◆ setWordSpacing()

void QgsTextCharacterFormat::setWordSpacing ( double spacing )

Sets the font word spacing, in points, or NaN if word spacing is not set and should be inherited.

See also: wordSpacing()

Since: QGIS 3.40

Definition at line 297 of file qgstextcharacterformat.cpp.

◆ strikeOut()

QgsTextCharacterFormat::BooleanValue QgsTextCharacterFormat::strikeOut ( ) const

Returns whether the format has strikethrough enabled.

See also: setStrikeOut()

Definition at line 154 of file qgstextcharacterformat.cpp.

◆ textColor()

QColor QgsTextCharacterFormat::textColor ( ) const

Returns the character's text color, or an invalid color if no color override is set and the default format color should be used.

See also: setTextColor()

Definition at line 114 of file qgstextcharacterformat.cpp.

◆ underline()

QgsTextCharacterFormat::BooleanValue QgsTextCharacterFormat::underline ( ) const

Returns whether the format has underline enabled.

See also: setUnderline()

Definition at line 164 of file qgstextcharacterformat.cpp.

◆ updateFontForFormat()

void QgsTextCharacterFormat::updateFontForFormat	(	QFont &	font,
		const QgsRenderContext &	context,
		double	scaleFactor = 1.0 ) const

Updates the specified font in place, applying character formatting options which are applicable on a font level when rendered in the given context.

The optional scaleFactor parameter can specify a font size scaling factor. It is recommended to set this to QgsTextRenderer::calculateScaleFactorForFormat() and then manually calculations based on the resultant font metrics. Failure to do so will result in poor quality text rendering at small font sizes.

Definition at line 204 of file qgstextcharacterformat.cpp.

◆ verticalAlignment()

Qgis::TextCharacterVerticalAlignment QgsTextCharacterFormat::verticalAlignment ( ) const

inline

Returns the format vertical alignment.

This property is only respected if hasVerticalAlignmentSet() is true.

See also: hasVerticalAlignmentSet(); setVerticalAlignment()

Since: QGIS 3.30

Definition at line 340 of file qgstextcharacterformat.h.

◆ wordSpacing()

double QgsTextCharacterFormat::wordSpacing ( ) const

Returns the font word spacing, in points, or NaN if word spacing is not set and should be inherited.

See also: setWordSpacing()

Since: QGIS 3.40

Definition at line 292 of file qgstextcharacterformat.cpp.

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

/build/qgis-3.99.0+git20251205+26c88405ac0+99sid/src/core/textrenderer/qgstextcharacterformat.h
/build/qgis-3.99.0+git20251205+26c88405ac0+99sid/src/core/textrenderer/qgstextcharacterformat.cpp

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ BooleanValue

Constructor & Destructor Documentation

◆ QgsTextCharacterFormat() [1/2]

◆ QgsTextCharacterFormat() [2/2]

Member Function Documentation

◆ backgroundBrush()

◆ backgroundImagePath()

◆ family()

◆ fontPercentageSize()

◆ fontPointSize()

◆ fontWeight()

◆ hasBackground()

◆ hasVerticalAlignmentSet()

◆ imagePath()

◆ imageSize()

◆ italic()

◆ overline()

◆ overrideWith()

◆ setBackgroundBrush()

◆ setBackgroundImagePath()

◆ setFamily()

◆ setFontPercentageSize()

◆ setFontPointSize()

◆ setFontWeight()

◆ setHasVerticalAlignmentSet()

◆ setImagePath()

◆ setImageSize()

◆ setItalic()

◆ setOverline()

◆ setStrikeOut()

◆ setTextColor()

◆ setUnderline()

◆ setVerticalAlignment()

◆ setWordSpacing()

◆ strikeOut()

◆ textColor()

◆ underline()

◆ updateFontForFormat()

◆ verticalAlignment()

◆ wordSpacing()