QGIS API Documentation 3.41.0-Master (3440c17df1d)
Loading...
Searching...
No Matches
Public Types | Public Member Functions | List of all members
QgsTextCharacterFormat Class Reference

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

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 45 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 306 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 261 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 143 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 133 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 123 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 281 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 301 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 183 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 193 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 271 of file qgstextcharacterformat.cpp.

◆ overline()

QgsTextCharacterFormat::BooleanValue QgsTextCharacterFormat::overline ( ) const

Returns whether the format has overline enabled.

See also
setUnderline()

Definition at line 173 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
otherThe format to override with.
Since
QGIS 3.36

Definition at line 78 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 311 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 266 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 148 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 138 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 128 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 286 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 188 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 198 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 276 of file qgstextcharacterformat.cpp.

◆ setOverline()

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

Sets whether the format has overline enabled.

See also
overline()

Definition at line 178 of file qgstextcharacterformat.cpp.

◆ setStrikeOut()

void QgsTextCharacterFormat::setStrikeOut ( BooleanValue  enabled)

Sets whether the format has strikethrough enabled.

See also
strikeOut()

Definition at line 158 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 118 of file qgstextcharacterformat.cpp.

◆ setUnderline()

void QgsTextCharacterFormat::setUnderline ( BooleanValue  enabled)

Sets whether the format has underline enabled.

See also
underline()

Definition at line 168 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 296 of file qgstextcharacterformat.cpp.

◆ strikeOut()

QgsTextCharacterFormat::BooleanValue QgsTextCharacterFormat::strikeOut ( ) const

Returns whether the format has strikethrough enabled.

See also
setStrikeOut()

Definition at line 153 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 113 of file qgstextcharacterformat.cpp.

◆ underline()

QgsTextCharacterFormat::BooleanValue QgsTextCharacterFormat::underline ( ) const

Returns whether the format has underline enabled.

See also
setUnderline()

Definition at line 163 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 203 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 291 of file qgstextcharacterformat.cpp.


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