QGIS API Documentation  3.13.0-Master (7f54853aae)
Public Types | Public Member Functions | Static Public Member Functions | List of all members
QgsTextFormat Class Reference

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

#include <qgstextrenderer.h>

Public Types

enum  TextOrientation { HorizontalOrientation, VerticalOrientation, RotationBasedOrientation }
 Text orientation. More...
 

Public Member Functions

 QgsTextFormat ()
 
 QgsTextFormat (const QgsTextFormat &other)
 Copy constructor. More...
 
 ~QgsTextFormat ()
 
QgsTextBackgroundSettingsbackground ()
 Returns a reference to the text background settings. More...
 
QgsTextBackgroundSettings background () const
 Returns a reference to the text background settings. More...
 
QPainter::CompositionMode blendMode () const
 Returns the blending mode used for drawing the text. More...
 
QgsTextBufferSettingsbuffer ()
 Returns a reference to the text buffer settings. More...
 
QgsTextBufferSettings buffer () const
 Returns a reference to the text buffer settings. More...
 
QColor color () const
 Returns the color that text will be rendered in. More...
 
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. More...
 
QgsPropertyCollectiondataDefinedProperties ()
 Returns a reference to the format's property collection, used for data defined overrides. More...
 
const QgsPropertyCollectiondataDefinedProperties () const
 Returns a reference to the format's property collection, used for data defined overrides. More...
 
QFont font () const
 Returns the font used for rendering text. More...
 
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. More...
 
double lineHeight () const
 Returns the line height for text. More...
 
QgsTextMaskSettingsmask ()
 Returns a reference to the masking settings. More...
 
QgsTextMaskSettings mask () const
 Returns a reference to the masking settings. More...
 
QString namedStyle () const
 Returns the named style for the font used for rendering text (e.g., "bold"). More...
 
double opacity () const
 Returns the text's opacity. More...
 
QgsTextFormatoperator= (const QgsTextFormat &other)
 
TextOrientation orientation () const
 Returns the orientation of the text. More...
 
QColor previewBackgroundColor () const
 Returns the background color for text previews. More...
 
void readFromLayer (QgsVectorLayer *layer)
 Reads settings from a layer's custom properties (for QGIS 2.x projects). More...
 
void readXml (const QDomElement &elem, const QgsReadWriteContext &context)
 Read settings from a DOM element. More...
 
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. More...
 
QFont scaledFont (const QgsRenderContext &context) 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. More...
 
void setBackground (const QgsTextBackgroundSettings &backgroundSettings)
 Sets the text's background settings.q. More...
 
void setBlendMode (QPainter::CompositionMode mode)
 Sets the blending mode used for drawing the text. More...
 
void setBuffer (const QgsTextBufferSettings &bufferSettings)
 Sets the text's buffer settings. More...
 
void setColor (const QColor &color)
 Sets the color that text will be rendered in. More...
 
void setDataDefinedProperties (const QgsPropertyCollection &collection)
 Sets the format's property collection, used for data defined overrides. More...
 
void setFont (const QFont &font)
 Sets the font used for rendering text. More...
 
void setLineHeight (double height)
 Sets the line height for text. More...
 
void setMask (const QgsTextMaskSettings &maskSettings)
 Sets the text's masking settings. More...
 
void setNamedStyle (const QString &style)
 Sets the named style for the font used for rendering text. More...
 
void setOpacity (double opacity)
 Sets the text's opacity. More...
 
void setOrientation (TextOrientation orientation)
 Sets the orientation for the text. More...
 
void setPreviewBackgroundColor (const QColor &color)
 Sets the background color that text will be rendered on for previews. More...
 
void setShadow (const QgsTextShadowSettings &shadowSettings)
 Sets the text's drop shadow settings. More...
 
void setSize (double size)
 Sets the size for rendered text. More...
 
void setSizeMapUnitScale (const QgsMapUnitScale &scale)
 Sets the map unit scale object for the size. More...
 
void setSizeUnit (QgsUnitTypes::RenderUnit unit)
 Sets the units for the size of rendered text. More...
 
QgsTextShadowSettingsshadow ()
 Returns a reference to the text drop shadow settings. More...
 
QgsTextShadowSettings shadow () const
 Returns a reference to the text drop shadow settings. More...
 
double size () const
 Returns the size for rendered text. More...
 
QgsMapUnitScale sizeMapUnitScale () const
 Returns the map unit scale object for the size. More...
 
QgsUnitTypes::RenderUnit sizeUnit () const
 Returns the units for the size of rendered text. More...
 
QMimeData * toMimeData () const
 Returns new mime data representing the text format settings. More...
 
QFont toQFont () const
 Returns a QFont matching the relevant settings from this text format. More...
 
void updateDataDefinedProperties (QgsRenderContext &context)
 Updates the format by evaluating current values of data defined properties. More...
 
QDomElement writeXml (QDomDocument &doc, const QgsReadWriteContext &context) const
 Write settings into a DOM element. More...
 

Static Public Member Functions

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

Detailed Description

Container for all settings relating to text rendering.

Note
QgsTextFormat objects are implicitly shared.
Since
QGIS 3.0

Definition at line 1203 of file qgstextrenderer.h.

Member Enumeration Documentation

◆ TextOrientation

Text orientation.

Enumerator
HorizontalOrientation 

Vertically oriented text.

VerticalOrientation 

Horizontally oriented text.

RotationBasedOrientation 

Horizontally or vertically oriented text based on rotation (only available for map labeling)

Definition at line 1208 of file qgstextrenderer.h.

Constructor & Destructor Documentation

◆ QgsTextFormat() [1/2]

QgsTextFormat::QgsTextFormat ( )

Definition at line 1774 of file qgstextrenderer.cpp.

◆ QgsTextFormat() [2/2]

QgsTextFormat::QgsTextFormat ( const QgsTextFormat other)

Copy constructor.

Parameters
othersource QgsTextFormat

Definition at line 1779 of file qgstextrenderer.cpp.

◆ ~QgsTextFormat()

QgsTextFormat::~QgsTextFormat ( )

Definition at line 1803 of file qgstextrenderer.cpp.

Member Function Documentation

◆ background() [1/2]

QgsTextBackgroundSettings& QgsTextFormat::background ( )
inline

Returns a reference to the text background settings.

See also
setBackground()

Definition at line 1250 of file qgstextrenderer.h.

◆ background() [2/2]

QgsTextBackgroundSettings QgsTextFormat::background ( ) const
inline

Returns a reference to the text background settings.

See also
setBackground()

Definition at line 1256 of file qgstextrenderer.h.

◆ blendMode()

QPainter::CompositionMode QgsTextFormat::blendMode ( ) const

Returns the blending mode used for drawing the text.

See also
setBlendMode()

Definition at line 1892 of file qgstextrenderer.cpp.

◆ buffer() [1/2]

QgsTextBufferSettings& QgsTextFormat::buffer ( )
inline

Returns a reference to the text buffer settings.

See also
setBuffer()

Definition at line 1231 of file qgstextrenderer.h.

◆ buffer() [2/2]

QgsTextBufferSettings QgsTextFormat::buffer ( ) const
inline

Returns a reference to the text buffer settings.

See also
setBuffer()

Definition at line 1237 of file qgstextrenderer.h.

◆ color()

QColor QgsTextFormat::color ( ) const

Returns the color that text will be rendered in.

See also
setColor()

Definition at line 1872 of file qgstextrenderer.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 2285 of file qgstextrenderer.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 2302 of file qgstextrenderer.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 2307 of file qgstextrenderer.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 1808 of file qgstextrenderer.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 1549 of file qgstextrenderer.h.

◆ 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 2257 of file qgstextrenderer.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 2208 of file qgstextrenderer.cpp.

◆ lineHeight()

double QgsTextFormat::lineHeight ( ) const

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

Definition at line 1902 of file qgstextrenderer.cpp.

◆ mask() [1/2]

QgsTextMaskSettings& QgsTextFormat::mask ( )
inline

Returns a reference to the masking settings.

See also
setMask()

Definition at line 1288 of file qgstextrenderer.h.

◆ 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 1296 of file qgstextrenderer.h.

◆ 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 1827 of file qgstextrenderer.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 1882 of file qgstextrenderer.cpp.

◆ operator=()

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

Definition at line 1791 of file qgstextrenderer.cpp.

◆ orientation()

QgsTextFormat::TextOrientation QgsTextFormat::orientation ( ) const

Returns the orientation of the text.

See also
setOrientation()
Since
QGIS 3.10

Definition at line 1912 of file qgstextrenderer.cpp.

◆ previewBackgroundColor()

QColor QgsTextFormat::previewBackgroundColor ( ) const

Returns the background color for text previews.

See also
setPreviewBackgroundColor()
Since
QGIS 3.10

Definition at line 1922 of file qgstextrenderer.cpp.

◆ readFromLayer()

void QgsTextFormat::readFromLayer ( QgsVectorLayer layer)

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

Parameters
layersource vector layer

Definition at line 1932 of file qgstextrenderer.cpp.

◆ readXml()

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

Read settings from a DOM element.

See also
writeXml()

Definition at line 2015 of file qgstextrenderer.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 1557 of file qgstextrenderer.h.

◆ scaledFont()

QFont QgsTextFormat::scaledFont ( const QgsRenderContext context) 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
contextdestination render context
Returns
font with scaled size
See also
font()
size()

Definition at line 1813 of file qgstextrenderer.cpp.

◆ setBackground()

void QgsTextFormat::setBackground ( const QgsTextBackgroundSettings backgroundSettings)
inline

Sets the text's background settings.q.

Parameters
backgroundSettingsbackground settings
See also
background()

Definition at line 1263 of file qgstextrenderer.h.

◆ setBlendMode()

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

Sets the blending mode used for drawing the text.

Parameters
modeblending mode
See also
blendMode()

Definition at line 1897 of file qgstextrenderer.cpp.

◆ setBuffer()

void QgsTextFormat::setBuffer ( const QgsTextBufferSettings bufferSettings)
inline

Sets the text's buffer settings.

Parameters
bufferSettingsbuffer settings
See also
buffer()

Definition at line 1244 of file qgstextrenderer.h.

◆ setColor()

void QgsTextFormat::setColor ( const QColor &  color)

Sets the color that text will be rendered in.

Parameters
colortext color
See also
color()

Definition at line 1877 of file qgstextrenderer.cpp.

◆ setDataDefinedProperties()

void QgsTextFormat::setDataDefinedProperties ( const QgsPropertyCollection collection)

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

Parameters
collectionproperty collection. Existing properties will be replaced.
See also
dataDefinedProperties()
Since
QGIS 3.10

Definition at line 2312 of file qgstextrenderer.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
fontdesired font
See also
font()
setNamedStyle()
fromQFont()

Definition at line 1822 of file qgstextrenderer.cpp.

◆ setLineHeight()

void QgsTextFormat::setLineHeight ( double  height)

Sets the line height for text.

Parameters
heighta number between 0.0 and 10.0 representing the leading between lines as a multiplier of line height.
See also
lineHeight()

Definition at line 1907 of file qgstextrenderer.cpp.

◆ setMask()

void QgsTextFormat::setMask ( const QgsTextMaskSettings maskSettings)
inline

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
maskSettingsmask settings
See also
mask()
Since
QGIS 3.12

Definition at line 1305 of file qgstextrenderer.h.

◆ setNamedStyle()

void QgsTextFormat::setNamedStyle ( const QString &  style)

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

Parameters
stylenamed style, e.g., "bold"
See also
namedStyle()
setFont()

Definition at line 1836 of file qgstextrenderer.cpp.

◆ setOpacity()

void QgsTextFormat::setOpacity ( double  opacity)

Sets the text's opacity.

Parameters
opacityopacity as a double value between 0 (fully transparent) and 1 (totally opaque)
See also
opacity()

Definition at line 1887 of file qgstextrenderer.cpp.

◆ setOrientation()

void QgsTextFormat::setOrientation ( TextOrientation  orientation)

Sets the orientation for the text.

See also
orientation()
Since
QGIS 3.10

Definition at line 1917 of file qgstextrenderer.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 1927 of file qgstextrenderer.cpp.

◆ setShadow()

void QgsTextFormat::setShadow ( const QgsTextShadowSettings shadowSettings)
inline

Sets the text's drop shadow settings.

Parameters
shadowSettingsshadow settings
See also
shadow()

Definition at line 1282 of file qgstextrenderer.h.

◆ setSize()

void QgsTextFormat::setSize ( double  size)

Sets the size for rendered text.

Parameters
sizesize of rendered text. Units are set using setSizeUnit()
See also
size()
setSizeUnit()

Definition at line 1867 of file qgstextrenderer.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 1857 of file qgstextrenderer.cpp.

◆ setSizeUnit()

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

Sets the units for the size of rendered text.

Parameters
unitsize units
See also
setSize()
sizeUnit()
setSizeMapUnitScale()

Definition at line 1847 of file qgstextrenderer.cpp.

◆ shadow() [1/2]

QgsTextShadowSettings& QgsTextFormat::shadow ( )
inline

Returns a reference to the text drop shadow settings.

See also
setShadow()

Definition at line 1269 of file qgstextrenderer.h.

◆ shadow() [2/2]

QgsTextShadowSettings QgsTextFormat::shadow ( ) const
inline

Returns a reference to the text drop shadow settings.

See also
setShadow()

Definition at line 1275 of file qgstextrenderer.h.

◆ size()

double QgsTextFormat::size ( ) const

Returns the size for rendered text.

Units are retrieved using sizeUnit().

See also
setSize()
sizeUnit()

Definition at line 1862 of file qgstextrenderer.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 1852 of file qgstextrenderer.cpp.

◆ sizeUnit()

QgsUnitTypes::RenderUnit QgsTextFormat::sizeUnit ( ) const

Returns the units for the size of rendered text.

See also
size()
setSizeUnit()
sizeMapUnitScale()

Definition at line 1842 of file qgstextrenderer.cpp.

◆ textFormatPreviewPixmap()

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

Returns a pixmap preview for a text format.

Parameters
formattext format
sizetarget pixmap size
previewTexttext to render in preview, or empty for default text
paddingspace between icon edge and color ramp
Since
QGIS 3.10

Definition at line 2499 of file qgstextrenderer.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 2193 of file qgstextrenderer.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 2226 of file qgstextrenderer.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 2317 of file qgstextrenderer.cpp.

◆ writeXml()

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

Write settings into a DOM element.

See also
readXml()

Definition at line 2157 of file qgstextrenderer.cpp.


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