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
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.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 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 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.
Attributes
- HorizontalOrientation = 0¶
- RotationBasedOrientation = 2¶
- class TextOrientation¶
Bases:
int
- VerticalOrientation = 1¶
- 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
- 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. This is a number between 0.0 and 10.0 representing the leading between lines as a multiplier of line height.
See also
- Return type
float
- 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) QgsTextFormat.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: Union[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
- setLineHeight(self, height: float)¶
Sets the line height for text.
- Parameters
height (float) – a number between 0.0 and 10.0 representing the leading between lines as a multiplier of line height.
See also
- 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: QgsTextFormat.TextOrientation)¶
Sets the
orientation
for the text.See also
New in version 3.10.
- Parameters
orientation (QgsTextFormat.TextOrientation) –
- setPreviewBackgroundColor(self, color: Union[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