QGIS API Documentation
3.16.0-Hannover (43b64b13f3)
|
Container for all settings relating to text rendering. More...
#include <qgstextformat.h>
Public Types | |
enum | TextOrientation { HorizontalOrientation, VerticalOrientation, RotationBasedOrientation } |
Text orientation. More... | |
Public Member Functions | |
QgsTextFormat () | |
Default constructor for QgsTextFormat. More... | |
QgsTextFormat (const QgsTextFormat &other) | |
Copy constructor. More... | |
~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. More... | |
QgsTextBackgroundSettings & | background () |
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... | |
QgsTextBufferSettings & | buffer () |
Returns a reference to the text buffer settings. More... | |
QgsTextBufferSettings | buffer () const |
Returns a reference to the text buffer settings. More... | |
QgsStringUtils::Capitalization | capitalization () const |
Returns the text capitalization style. 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... | |
QgsPropertyCollection & | dataDefinedProperties () |
Returns a reference to the format's property collection, used for data defined overrides. More... | |
const QgsPropertyCollection & | dataDefinedProperties () 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... | |
bool | isValid () const |
Returns true if the format is valid. More... | |
double | lineHeight () const |
Returns the line height for text. More... | |
QgsTextMaskSettings & | mask () |
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... | |
bool | operator!= (const QgsTextFormat &other) const |
QgsTextFormat & | operator= (const QgsTextFormat &other) |
bool | operator== (const QgsTextFormat &other) const |
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... | |
QSet< QString > | referencedFields (const QgsRenderContext &context) const |
Returns all field names referenced by the configuration (e.g. 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, double scaleFactor=1.0) 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 | setAllowHtmlFormatting (bool allow) |
Sets whether text should be treated as a HTML document and HTML tags should be used for formatting the rendered text. 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 | setCapitalization (QgsStringUtils::Capitalization capitalization) |
Sets the text capitalization style. 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... | |
void | setValid () |
Sets the format to a valid state, without changing any of the default format settings. More... | |
QgsTextShadowSettings & | shadow () |
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... | |
Container for all settings relating to text rendering.
Definition at line 39 of file qgstextformat.h.
Text orientation.
Definition at line 44 of file qgstextformat.h.
QgsTextFormat::QgsTextFormat | ( | ) |
Default constructor for QgsTextFormat.
Creates a text format initially set to an invalid state (see isValid()).
Definition at line 28 of file qgstextformat.cpp.
QgsTextFormat::QgsTextFormat | ( | const QgsTextFormat & | other | ) |
Copy constructor.
other | source QgsTextFormat |
Definition at line 33 of file qgstextformat.cpp.
QgsTextFormat::~QgsTextFormat | ( | ) |
Definition at line 57 of file qgstextformat.cpp.
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.
Definition at line 300 of file qgstextformat.cpp.
QgsTextBackgroundSettings & QgsTextFormat::background | ( | ) |
Returns a reference to the text background settings.
Definition at line 115 of file qgstextformat.cpp.
|
inline |
Returns a reference to the text background settings.
Definition at line 121 of file qgstextformat.h.
QPainter::CompositionMode QgsTextFormat::blendMode | ( | ) | const |
Returns the blending mode used for drawing the text.
Definition at line 254 of file qgstextformat.cpp.
QgsTextBufferSettings & QgsTextFormat::buffer | ( | ) |
Returns a reference to the text buffer settings.
Definition at line 103 of file qgstextformat.cpp.
|
inline |
Returns a reference to the text buffer settings.
Definition at line 102 of file qgstextformat.h.
QgsStringUtils::Capitalization QgsTextFormat::capitalization | ( | ) | const |
Returns the text capitalization style.
Definition at line 287 of file qgstextformat.cpp.
QColor QgsTextFormat::color | ( | ) | const |
Returns the color that text will be rendered in.
Definition at line 232 of file qgstextformat.cpp.
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 684 of file qgstextformat.cpp.
QgsPropertyCollection & QgsTextFormat::dataDefinedProperties | ( | ) |
Returns a reference to the format's property collection, used for data defined overrides.
Definition at line 701 of file qgstextformat.cpp.
const QgsPropertyCollection & QgsTextFormat::dataDefinedProperties | ( | ) | const |
Returns a reference to the format's property collection, used for data defined overrides.
Definition at line 707 of file qgstextformat.cpp.
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.
Definition at line 151 of file qgstextformat.cpp.
|
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.
Definition at line 466 of file qgstextformat.h.
|
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
.
Definition at line 656 of file qgstextformat.cpp.
|
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.
Definition at line 607 of file qgstextformat.cpp.
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.
Definition at line 93 of file qgstextformat.cpp.
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.
Definition at line 265 of file qgstextformat.cpp.
QgsTextMaskSettings & QgsTextFormat::mask | ( | ) |
Returns a reference to the masking settings.
Definition at line 139 of file qgstextformat.cpp.
|
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.
Definition at line 161 of file qgstextformat.h.
QString QgsTextFormat::namedStyle | ( | ) | const |
Returns the named style for the font used for rendering text (e.g., "bold").
Definition at line 183 of file qgstextformat.cpp.
double QgsTextFormat::opacity | ( | ) | const |
Returns the text's opacity.
The opacity is a double value between 0 (fully transparent) and 1 (totally opaque).
Definition at line 243 of file qgstextformat.cpp.
bool QgsTextFormat::operator!= | ( | const QgsTextFormat & | other | ) | const |
Definition at line 88 of file qgstextformat.cpp.
QgsTextFormat & QgsTextFormat::operator= | ( | const QgsTextFormat & | other | ) |
Definition at line 45 of file qgstextformat.cpp.
bool QgsTextFormat::operator== | ( | const QgsTextFormat & | other | ) | const |
Definition at line 62 of file qgstextformat.cpp.
QgsTextFormat::TextOrientation QgsTextFormat::orientation | ( | ) | const |
Returns the orientation of the text.
Definition at line 276 of file qgstextformat.cpp.
QColor QgsTextFormat::previewBackgroundColor | ( | ) | const |
Returns the background color for text previews.
Definition at line 311 of file qgstextformat.cpp.
void QgsTextFormat::readFromLayer | ( | QgsVectorLayer * | layer | ) |
Reads settings from a layer's custom properties (for QGIS 2.x projects).
layer | source vector layer |
Definition at line 322 of file qgstextformat.cpp.
void QgsTextFormat::readXml | ( | const QDomElement & | elem, |
const QgsReadWriteContext & | context | ||
) |
Read settings from a DOM element.
Definition at line 406 of file qgstextformat.cpp.
QSet< QString > QgsTextFormat::referencedFields | ( | const QgsRenderContext & | context | ) | const |
Returns all field names referenced by the configuration (e.g.
from data defined properties).
Definition at line 712 of file qgstextformat.cpp.
|
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.
Definition at line 474 of file qgstextformat.h.
QFont QgsTextFormat::scaledFont | ( | const QgsRenderContext & | context, |
double | scaleFactor = 1.0 |
||
) | 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.
context | destination render context |
scaleFactor | optional font size scaling factor. It is recommended to set this to QgsTextRenderer::FONT_WORKAROUND_SCALE 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. |
Definition at line 156 of file qgstextformat.cpp.
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.
Definition at line 305 of file qgstextformat.cpp.
void QgsTextFormat::setBackground | ( | const QgsTextBackgroundSettings & | backgroundSettings | ) |
Sets the text's background settings.q.
backgroundSettings | background settings |
Definition at line 121 of file qgstextformat.cpp.
void QgsTextFormat::setBlendMode | ( | QPainter::CompositionMode | mode | ) |
Sets the blending mode used for drawing the text.
mode | blending mode |
Definition at line 259 of file qgstextformat.cpp.
void QgsTextFormat::setBuffer | ( | const QgsTextBufferSettings & | bufferSettings | ) |
Sets the text's buffer settings.
bufferSettings | buffer settings |
Definition at line 109 of file qgstextformat.cpp.
void QgsTextFormat::setCapitalization | ( | QgsStringUtils::Capitalization | capitalization | ) |
Sets the text capitalization style.
Definition at line 293 of file qgstextformat.cpp.
void QgsTextFormat::setColor | ( | const QColor & | color | ) |
Sets the color that text will be rendered in.
color | text color |
Definition at line 237 of file qgstextformat.cpp.
void QgsTextFormat::setDataDefinedProperties | ( | const QgsPropertyCollection & | collection | ) |
Sets the format's property collection, used for data defined overrides.
collection | property collection. Existing properties will be replaced. |
Definition at line 722 of file qgstextformat.cpp.
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.
font | desired font |
Definition at line 177 of file qgstextformat.cpp.
void QgsTextFormat::setLineHeight | ( | double | height | ) |
Sets the line height for text.
height | a number between 0.0 and 10.0 representing the leading between lines as a multiplier of line height. |
Definition at line 270 of file qgstextformat.cpp.
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.
maskSettings | mask settings |
Definition at line 145 of file qgstextformat.cpp.
void QgsTextFormat::setNamedStyle | ( | const QString & | style | ) |
Sets the named style for the font used for rendering text.
style | named style, e.g., "bold" |
Definition at line 192 of file qgstextformat.cpp.
void QgsTextFormat::setOpacity | ( | double | opacity | ) |
Sets the text's opacity.
opacity | opacity as a double value between 0 (fully transparent) and 1 (totally opaque) |
Definition at line 248 of file qgstextformat.cpp.
void QgsTextFormat::setOrientation | ( | TextOrientation | orientation | ) |
Sets the orientation for the text.
Definition at line 281 of file qgstextformat.cpp.
void QgsTextFormat::setPreviewBackgroundColor | ( | const QColor & | color | ) |
Sets the background color that text will be rendered on for previews.
Definition at line 316 of file qgstextformat.cpp.
void QgsTextFormat::setShadow | ( | const QgsTextShadowSettings & | shadowSettings | ) |
Sets the text's drop shadow settings.
shadowSettings | shadow settings |
Definition at line 133 of file qgstextformat.cpp.
void QgsTextFormat::setSize | ( | double | size | ) |
Sets the size for rendered text.
size | size of rendered text. Units are set using setSizeUnit() |
Definition at line 226 of file qgstextformat.cpp.
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.
Definition at line 215 of file qgstextformat.cpp.
void QgsTextFormat::setSizeUnit | ( | QgsUnitTypes::RenderUnit | unit | ) |
Sets the units for the size of rendered text.
unit | size units |
Definition at line 204 of file qgstextformat.cpp.
void QgsTextFormat::setValid | ( | ) |
Sets the format to a valid state, without changing any of the default format settings.
Definition at line 98 of file qgstextformat.cpp.
QgsTextShadowSettings & QgsTextFormat::shadow | ( | ) |
Returns a reference to the text drop shadow settings.
Definition at line 127 of file qgstextformat.cpp.
|
inline |
Returns a reference to the text drop shadow settings.
Definition at line 140 of file qgstextformat.h.
double QgsTextFormat::size | ( | ) | const |
Returns the size for rendered text.
Units are retrieved using sizeUnit().
Definition at line 221 of file qgstextformat.cpp.
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.
Definition at line 210 of file qgstextformat.cpp.
QgsUnitTypes::RenderUnit QgsTextFormat::sizeUnit | ( | ) | const |
Returns the units for the size of rendered text.
Definition at line 199 of file qgstextformat.cpp.
|
static |
Returns a pixmap preview for a text format.
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 |
Definition at line 911 of file qgstextformat.cpp.
QMimeData * QgsTextFormat::toMimeData | ( | ) | const |
Returns new mime data representing the text format settings.
Caller takes responsibility for deleting the returned object.
Definition at line 592 of file qgstextformat.cpp.
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.
Definition at line 625 of file qgstextformat.cpp.
void QgsTextFormat::updateDataDefinedProperties | ( | QgsRenderContext & | context | ) |
Updates the format by evaluating current values of data defined properties.
Definition at line 728 of file qgstextformat.cpp.
QDomElement QgsTextFormat::writeXml | ( | QDomDocument & | doc, |
const QgsReadWriteContext & | context | ||
) | const |
Write settings into a DOM element.
Definition at line 555 of file qgstextformat.cpp.