QGIS API Documentation
3.18.1-Zürich (202f1bf7e5)
|
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 40 of file qgstextformat.h.
Text orientation.
Definition at line 45 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 29 of file qgstextformat.cpp.
QgsTextFormat::QgsTextFormat | ( | const QgsTextFormat & | other | ) |
Copy constructor.
other | source QgsTextFormat |
Definition at line 34 of file qgstextformat.cpp.
QgsTextFormat::~QgsTextFormat | ( | ) |
Definition at line 58 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 301 of file qgstextformat.cpp.
QgsTextBackgroundSettings & QgsTextFormat::background | ( | ) |
Returns a reference to the text background settings.
Definition at line 116 of file qgstextformat.cpp.
|
inline |
Returns a reference to the text background settings.
Definition at line 122 of file qgstextformat.h.
QPainter::CompositionMode QgsTextFormat::blendMode | ( | ) | const |
Returns the blending mode used for drawing the text.
Definition at line 255 of file qgstextformat.cpp.
QgsTextBufferSettings & QgsTextFormat::buffer | ( | ) |
Returns a reference to the text buffer settings.
Definition at line 104 of file qgstextformat.cpp.
|
inline |
Returns a reference to the text buffer settings.
Definition at line 103 of file qgstextformat.h.
QgsStringUtils::Capitalization QgsTextFormat::capitalization | ( | ) | const |
Returns the text capitalization style.
Definition at line 288 of file qgstextformat.cpp.
QColor QgsTextFormat::color | ( | ) | const |
Returns the color that text will be rendered in.
Definition at line 233 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 686 of file qgstextformat.cpp.
QgsPropertyCollection & QgsTextFormat::dataDefinedProperties | ( | ) |
Returns a reference to the format's property collection, used for data defined overrides.
Definition at line 703 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 709 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 152 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 467 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 658 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 609 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 94 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 266 of file qgstextformat.cpp.
QgsTextMaskSettings & QgsTextFormat::mask | ( | ) |
Returns a reference to the masking settings.
Definition at line 140 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 162 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 184 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 244 of file qgstextformat.cpp.
bool QgsTextFormat::operator!= | ( | const QgsTextFormat & | other | ) | const |
Definition at line 89 of file qgstextformat.cpp.
QgsTextFormat & QgsTextFormat::operator= | ( | const QgsTextFormat & | other | ) |
Definition at line 46 of file qgstextformat.cpp.
bool QgsTextFormat::operator== | ( | const QgsTextFormat & | other | ) | const |
Definition at line 63 of file qgstextformat.cpp.
QgsTextFormat::TextOrientation QgsTextFormat::orientation | ( | ) | const |
Returns the orientation of the text.
Definition at line 277 of file qgstextformat.cpp.
QColor QgsTextFormat::previewBackgroundColor | ( | ) | const |
Returns the background color for text previews.
Definition at line 312 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 323 of file qgstextformat.cpp.
void QgsTextFormat::readXml | ( | const QDomElement & | elem, |
const QgsReadWriteContext & | context | ||
) |
Read settings from a DOM element.
Definition at line 407 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 714 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 475 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 157 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 306 of file qgstextformat.cpp.
void QgsTextFormat::setBackground | ( | const QgsTextBackgroundSettings & | backgroundSettings | ) |
Sets the text's background settings.q.
backgroundSettings | background settings |
Definition at line 122 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 260 of file qgstextformat.cpp.
void QgsTextFormat::setBuffer | ( | const QgsTextBufferSettings & | bufferSettings | ) |
Sets the text's buffer settings.
bufferSettings | buffer settings |
Definition at line 110 of file qgstextformat.cpp.
void QgsTextFormat::setCapitalization | ( | QgsStringUtils::Capitalization | capitalization | ) |
Sets the text capitalization style.
Definition at line 294 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 238 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 724 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 178 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 271 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 146 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 193 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 249 of file qgstextformat.cpp.
void QgsTextFormat::setOrientation | ( | TextOrientation | orientation | ) |
Sets the orientation for the text.
Definition at line 282 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 317 of file qgstextformat.cpp.
void QgsTextFormat::setShadow | ( | const QgsTextShadowSettings & | shadowSettings | ) |
Sets the text's drop shadow settings.
shadowSettings | shadow settings |
Definition at line 134 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 227 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 216 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 205 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 99 of file qgstextformat.cpp.
QgsTextShadowSettings & QgsTextFormat::shadow | ( | ) |
Returns a reference to the text drop shadow settings.
Definition at line 128 of file qgstextformat.cpp.
|
inline |
Returns a reference to the text drop shadow settings.
Definition at line 141 of file qgstextformat.h.
double QgsTextFormat::size | ( | ) | const |
Returns the size for rendered text.
Units are retrieved using sizeUnit().
Definition at line 222 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 211 of file qgstextformat.cpp.
QgsUnitTypes::RenderUnit QgsTextFormat::sizeUnit | ( | ) | const |
Returns the units for the size of rendered text.
Definition at line 200 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 913 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 593 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 627 of file qgstextformat.cpp.
void QgsTextFormat::updateDataDefinedProperties | ( | QgsRenderContext & | context | ) |
Updates the format by evaluating current values of data defined properties.
Definition at line 730 of file qgstextformat.cpp.
QDomElement QgsTextFormat::writeXml | ( | QDomDocument & | doc, |
const QgsReadWriteContext & | context | ||
) | const |
Write settings into a DOM element.
Definition at line 556 of file qgstextformat.cpp.