Class: QgsTextFormat¶
- class qgis.core.QgsTextFormat¶
Bases:
sip.wrapper
Container for all settings relating to text rendering.
Note
QgsTextFormat
objects are implicitly shared.New in version 3.0.
QgsTextFormat() Default constructor for
QgsTextFormat
. Creates a text format initially set to an invalid state (seeisValid()
).QgsTextFormat(other:
QgsTextFormat
) Copy constructor.- Parameters:
other –
source QgsTextFormat
Enums
Bases:
enum.IntEnum
Methods
Returns
True
if text should be treated as a HTML document and HTML tags should be used for formatting the rendered text.Returns a reference to the text background settings.
Returns the blending mode used for drawing the text.
Returns a reference to the text buffer settings.
Returns the text capitalization style.
Returns the color that text will be rendered in.
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.Returns a reference to the format's property collection, used for data defined overrides.
Returns the list of font families to use when restoring the text format, in order of precedence.
Returns the font used for rendering text.
Returns
True
if the specified font was found on the system, orFalse
if the font was not found and a replacement was used instead.Returns
True
if the format is set to force a bold style.Returns
True
if the format is set to force an italic style.Attempts to parse the provided mime
data
as a QgsTextFormat.Returns a text format matching the settings from an input
font
.Returns
True
if the format is valid.Returns the line height for text.
Returns the units for the line height for text.
Returns a reference to the masking settings.
Returns the named style for the font used for rendering text (e.g., "bold").
Returns the text's opacity.
Returns the orientation of the text.
Returns the background color for text previews.
Reads settings from a layer's custom properties (for QGIS 2.x projects).
Read settings from a DOM element.
Returns all field names referenced by the configuration (e.g.
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.
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.
Sets whether text should be treated as a HTML document and HTML tags should be used for formatting the rendered text.
Sets the text's background settings.q
Sets the blending mode used for drawing the text.
Sets the text's buffer settings.
Sets the text
capitalization
style.Sets the color that text will be rendered in.
Sets the format's property collection, used for data defined overrides.
Sets a list of font
families
to use for the text format, in order of precedence.Sets the font used for rendering text.
Sets whether the format is set to force a bold style.
Sets whether the format is set to force an italic style.
Sets the line height for text.
Sets the
unit
for the line height for text.Sets the text's masking settings.
Sets the named style for the font used for rendering text.
Sets the text's opacity.
Sets the
orientation
for the text.Sets the background
color
that text will be rendered on for previews.Sets the text's drop shadow settings.
Sets the size for rendered text.
Sets the map unit scale object for the size.
Sets the units for the size of rendered text.
Sets the text's stretch
factor
.Sets the format to a valid state, without changing any of the default format settings.
Returns a reference to the text drop shadow settings.
Returns the size for rendered text.
Returns the map unit scale object for the size.
Returns the units for the size of rendered text.
Returns the text's stretch factor.
Returns a pixmap preview for a text
format
.Returns new mime data representing the text format settings.
Returns a QFont matching the relevant settings from this text format.
Updates the format by evaluating current values of data defined properties.
Write settings into a DOM element.
- class TextOrientation(value)¶
Bases:
enum.IntEnum
Text orientations.
Note
Prior to QGIS 3.28 this was available as
QgsTextFormat
.TextOrientationNew in version 3.28.
HorizontalOrientation
: Horizontally oriented textVerticalOrientation
: Vertically oriented textRotationBasedOrientation
: Horizontally or vertically oriented text based on rotation (only available for map labeling)
- allowHtmlFormatting(self) bool ¶
Returns
True
if text should be treated as a HTML document and HTML tags should be used for formatting the rendered text.Warning
Only a small subset of HTML formatting is supported. Currently this is restricted to:
text color formatting
strikethrough
underline
overline
See also
New in version 3.14.
- Return type:
bool
- background(self) QgsTextBackgroundSettings ¶
Returns a reference to the text background settings.
See also
- Return type:
- blendMode(self) QPainter.CompositionMode ¶
Returns the blending mode used for drawing the text.
See also
- Return type:
QPainter.CompositionMode
- buffer(self) QgsTextBufferSettings ¶
Returns a reference to the text buffer settings.
See also
- Return type:
- capitalization(self) Qgis.Capitalization ¶
Returns the text capitalization style.
See also
New in version 3.16.
- Return type:
- color(self) QColor ¶
Returns the color that text will be rendered in.
See also
- Return type:
QColor
- containsAdvancedEffects(self) bool ¶
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.- Return type:
bool
- dataDefinedProperties(self) QgsPropertyCollection ¶
Returns a reference to the format’s property collection, used for data defined overrides.
See also
New in version 3.10.
- Return type:
- families(self) List[str] ¶
Returns the list of font families to use when restoring the text format, in order of precedence.
Warning
The list of families returned by this method is ONLY used when restoring the text format from serialized versions, and will not affect the current
font()
familily used by the format.See also
New in version 3.20.
- Return type:
List[str]
- font(self) QFont ¶
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
See also
See also
See also
- Return type:
QFont
- fontFound(self) bool ¶
Returns
True
if the specified font was found on the system, orFalse
if the font was not found and a replacement was used instead.See also
- Return type:
bool
- forcedBold(self) bool ¶
Returns
True
if the format is set to force a bold style.Warning
Unlike setting a font’s style via
setNamedStyle()
, this will ensure that a font is always rendered in bold regardless of whether the font family actually has a bold variant. A “faux bold” effect will be emulated, which may result in poor quality font rendering. For this reason it is greatly preferred to callsetNamedStyle()
instead.See also
New in version 3.26.
- Return type:
bool
- forcedItalic(self) bool ¶
Returns
True
if the format is set to force an italic style.Warning
Unlike setting a font’s style via
setNamedStyle()
, this will ensure that a font is always rendered in italic regardless of whether the font family actually has an italic variant. A “faux italic” slanted text effect will be emulated, which may result in poor quality font rendering. For this reason it is greatly preferred to callsetNamedStyle()
instead.See also
New in version 3.26.
- Return type:
bool
- fromMimeData(data: QMimeData) Tuple[QgsTextFormat, bool] ¶
Attempts to parse the provided mime
data
as a QgsTextFormat. If data can be parsed as a text format,ok
will be set toTrue
.See also
- Parameters:
data (QMimeData) –
- Return type:
Tuple[
QgsTextFormat
, bool]
- fromQFont(font: QFont) QgsTextFormat ¶
Returns a text format matching the settings from an input
font
. UnlikesetFont()
, this method also handles the size and size units fromfont
.See also
New in version 3.2.
- Parameters:
font (QFont) –
- Return type:
- isValid(self) bool ¶
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.Note
Calling any setter on a
QgsTextFormat
object will automatically set the format as valid.See also
New in version 3.16.
- Return type:
bool
- lineHeight(self) float ¶
Returns the line height for text.
If
lineHeightUnit()
isQgsUnitTypes
.RenderPercentage (the default), then this is a number representing the leading between lines as a multiplier of line height (where 0 - 1.0 represents 0 to 100% of text line height). Otherwise the line height is an absolute measurement inlineHeightUnit()
.See also
See also
- Return type:
float
- lineHeightUnit(self) QgsUnitTypes.RenderUnit ¶
Returns the units for the line height for text.
See also
See also
New in version 3.28.
- Return type:
- mask(self) QgsTextMaskSettings ¶
Returns a reference to the masking settings.
See also
- Return type:
- namedStyle(self) str ¶
Returns the named style for the font used for rendering text (e.g., “bold”).
See also
See also
- Return type:
str
- opacity(self) float ¶
Returns the text’s opacity. The opacity is a double value between 0 (fully transparent) and 1 (totally opaque).
See also
- Return type:
float
- orientation(self) Qgis.TextOrientation ¶
Returns the orientation of the text.
See also
New in version 3.10.
- Return type:
- previewBackgroundColor(self) QColor ¶
Returns the background color for text previews.
See also
New in version 3.10.
- Return type:
QColor
- readFromLayer(self, layer: QgsVectorLayer)¶
Reads settings from a layer’s custom properties (for QGIS 2.x projects).
- Parameters:
layer (QgsVectorLayer) – source vector layer
- readXml(self, elem: QDomElement, context: QgsReadWriteContext)¶
Read settings from a DOM element.
See also
- Parameters:
elem (QDomElement) –
context (QgsReadWriteContext) –
- referencedFields(self, context: QgsRenderContext) Set[str] ¶
Returns all field names referenced by the configuration (e.g. from data defined properties).
New in version 3.14.
- Parameters:
context (QgsRenderContext) –
- Return type:
Set[str]
- resolvedFontFamily(self) str ¶
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
- Return type:
str
- scaledFont(self, context: QgsRenderContext, scaleFactor: float = 1) QFont ¶
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:
context (QgsRenderContext) – destination render context
scaleFactor (float = 1) – 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.
- Return type:
QFont
- Returns:
font with scaled size
See also
See also
- setAllowHtmlFormatting(self, allow: bool)¶
Sets whether text should be treated as a HTML document and HTML tags should be used for formatting the rendered text.
Warning
Only a small subset of HTML formatting is supported. Currently this is restricted to:
text color formatting
strikethrough
underline
overline
See also
New in version 3.14.
- Parameters:
allow (bool) –
- setBackground(self, backgroundSettings: QgsTextBackgroundSettings)¶
Sets the text’s background settings.q
- Parameters:
backgroundSettings (QgsTextBackgroundSettings) – background settings
See also
- setBlendMode(self, mode: QPainter.CompositionMode)¶
Sets the blending mode used for drawing the text.
- Parameters:
mode (QPainter.CompositionMode) – blending mode
See also
- setBuffer(self, bufferSettings: QgsTextBufferSettings)¶
Sets the text’s buffer settings.
- Parameters:
bufferSettings (QgsTextBufferSettings) – buffer settings
See also
- setCapitalization(self, capitalization: Qgis.Capitalization)¶
Sets the text
capitalization
style.See also
New in version 3.16.
- Parameters:
capitalization (Qgis.Capitalization) –
- setColor(self, color: QColor | Qt.GlobalColor)¶
Sets the color that text will be rendered in.
- Parameters:
color (Union[QColor) – text color
See also
- setDataDefinedProperties(self, collection: QgsPropertyCollection)¶
Sets the format’s property collection, used for data defined overrides.
- Parameters:
collection (QgsPropertyCollection) – property collection. Existing properties will be replaced.
See also
New in version 3.10.
- setFamilies(self, families: Iterable[str])¶
Sets a list of font
families
to use for the text format, in order of precedence.When restoring serialized versions of the text format then the first matching font family from this list will be used for the text format. This provides a way to specify a list of possible font families which are used as fallbacks if a family isn’t available on a particular QGIS install (CSS style).
Warning
The list of families set by calling this method is ONLY used when restoring the text format from serialized versions, and will not affect the current
font()
familily used by the format.See also
New in version 3.20.
- Parameters:
families (Iterable[str]) –
- setFont(self, font: QFont)¶
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:
font (QFont) – desired font
See also
See also
See also
- setForcedBold(self, forced: bool)¶
Sets whether the format is set to force a bold style.
Warning
Unlike setting a font’s style via
setNamedStyle()
, this will ensure that a font is always rendered in bold regardless of whether the font family actually has a bold variant. A “faux bold” effect will be emulated, which may result in poor quality font rendering. For this reason it is greatly preferred to callsetNamedStyle()
instead.See also
New in version 3.26.
- Parameters:
forced (bool) –
- setForcedItalic(self, forced: bool)¶
Sets whether the format is set to force an italic style.
Warning
Unlike setting a font’s style via
setNamedStyle()
, this will ensure that a font is always rendered in italic regardless of whether the font family actually has an italic variant. A “faux italic” slanted text effect will be emulated, which may result in poor quality font rendering. For this reason it is greatly preferred to callsetNamedStyle()
instead.See also
New in version 3.26.
- Parameters:
forced (bool) –
- setLineHeight(self, height: float)¶
Sets the line height for text.
If
lineHeightUnit()
isQgsUnitTypes
.RenderPercentage (the default), thenheight
is a number representing the leading between lines as a multiplier of line height (where 0 - 1.0 represents 0 to 100% of text line height). Otherwiseheight
is an absolute measurement inlineHeightUnit()
.See also
See also
- Parameters:
height (float) –
- setLineHeightUnit(self, unit: QgsUnitTypes.RenderUnit)¶
Sets the
unit
for the line height for text.See also
See also
New in version 3.28.
- Parameters:
unit (QgsUnitTypes.RenderUnit) –
- setMask(self, maskSettings: QgsTextMaskSettings)¶
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:
maskSettings (QgsTextMaskSettings) – mask settings
See also
New in version 3.12.
- setNamedStyle(self, style: str)¶
Sets the named style for the font used for rendering text.
- Parameters:
style (str) – named style, e.g., “bold”
See also
See also
- setOpacity(self, opacity: float)¶
Sets the text’s opacity.
- Parameters:
opacity (float) – opacity as a double value between 0 (fully transparent) and 1 (totally opaque)
See also
- setOrientation(self, orientation: Qgis.TextOrientation)¶
Sets the
orientation
for the text.See also
New in version 3.10.
- Parameters:
orientation (Qgis.TextOrientation) –
- setPreviewBackgroundColor(self, color: QColor | Qt.GlobalColor)¶
Sets the background
color
that text will be rendered on for previews.See also
New in version 3.10.
- Parameters:
color (Union[QColor) –
- setShadow(self, shadowSettings: QgsTextShadowSettings)¶
Sets the text’s drop shadow settings.
- Parameters:
shadowSettings (QgsTextShadowSettings) – shadow settings
See also
- setSize(self, size: float)¶
Sets the size for rendered text.
- Parameters:
size (float) – size of rendered text. Units are set using
setSizeUnit()
See also
See also
- setSizeMapUnitScale(self, scale: QgsMapUnitScale)¶
Sets the map unit scale object for the size. This is only used if the
sizeUnit()
is set toQgsUnitTypes
.RenderMapUnit.See also
See also
- Parameters:
scale (QgsMapUnitScale) –
- setSizeUnit(self, unit: QgsUnitTypes.RenderUnit)¶
Sets the units for the size of rendered text.
- Parameters:
unit (QgsUnitTypes.RenderUnit) – size units
See also
See also
See also
- setStretchFactor(self, factor: int)¶
Sets the text’s stretch
factor
.The stretch factor matches a condensed or expanded version of the font or applies a stretch transform that changes the width of all characters in the font by factor percent.
For example, setting
factor
to 150 results in all characters in the font being 1.5 times (ie. 150%) wider. The minimum stretch factor is 1, and the maximum stretch factor is 4000.See also
New in version 3.24.
- Parameters:
factor (int) –
- setValid(self)¶
Sets the format to a valid state, without changing any of the default format settings.
See also
New in version 3.16.
- shadow(self) QgsTextShadowSettings ¶
Returns a reference to the text drop shadow settings.
See also
- Return type:
- size(self) float ¶
Returns the size for rendered text. Units are retrieved using
sizeUnit()
.See also
See also
- Return type:
float
- sizeMapUnitScale(self) QgsMapUnitScale ¶
Returns the map unit scale object for the size. This is only used if the
sizeUnit()
is set toQgsUnitTypes
.RenderMapUnit.See also
See also
- Return type:
- sizeUnit(self) QgsUnitTypes.RenderUnit ¶
Returns the units for the size of rendered text.
See also
See also
See also
- Return type:
- stretchFactor(self) int ¶
Returns the text’s stretch factor.
The stretch factor matches a condensed or expanded version of the font or applies a stretch transform that changes the width of all characters in the font by factor percent.
For example, a factor of 150 results in all characters in the font being 1.5 times (ie. 150%) wider. The minimum stretch factor is 1, and the maximum stretch factor is 4000.
See also
New in version 3.24.
- Return type:
int
- textFormatPreviewPixmap(format: QgsTextFormat, size: QSize, previewText: str = '', padding: int = 0) QPixmap ¶
Returns a pixmap preview for a text
format
.- Parameters:
format (QgsTextFormat) – text format
size (QSize) – target pixmap size
previewText (str = '') – text to render in preview, or empty for default text
padding (int = 0) – space between icon edge and color ramp
New in version 3.10.
- Return type:
QPixmap
- toMimeData(self) QMimeData ¶
Returns new mime data representing the text format settings. Caller takes responsibility for deleting the returned object.
See also
- Return type:
QMimeData
- toQFont(self) QFont ¶
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
New in version 3.2.
- Return type:
QFont
- updateDataDefinedProperties(self, context: QgsRenderContext)¶
Updates the format by evaluating current values of data defined properties.
New in version 3.10.
- Parameters:
context (QgsRenderContext) –
- writeXml(self, doc: QDomDocument, context: QgsReadWriteContext) QDomElement ¶
Write settings into a DOM element.
See also
- Parameters:
doc (QDomDocument) –
context (QgsReadWriteContext) –
- Return type:
QDomElement