Class: QgsTextFormatWidget

A widget for customizing text formatting settings.

QgsTextFormatWidget provides a widget for controlling the appearance of text rendered using QgsTextRenderer. The widget includes all settings contained within a QgsTextFormat, including shadow, background and buffer.

Additionally, the widget can handle labeling settings due to the large overlap between the text renderer settings and the labeling settings. This mode is possible by subclassing QgsTextFormatWidget and calling the protected constructor with a mode of Labeling.

Class Hierarchy

Inheritance diagram of qgis.gui.QgsTextFormatWidget

Base classes

QWidget

QObject

QPaintDevice

QgsExpressionContextGenerator

Abstract interface for generating an expression context.

Methods

context

Returns the context in which the widget is shown, e.g., the associated map canvas and expression contexts.

deactivateField

Deactivate a field from data defined properties and update the corresponding button.

enableDataDefinedAlignment

Update the enabled state of the data defined alignment buttons.

format

Returns the current formatting settings defined by the widget.

labelGeometryType

Returns the geometry type which will be used by the labeling engine when registering labels for the labeling settings currently defined by the widget.

setDockMode

Sets whether the widget should be shown in a compact dock mode.

setFormat

Sets the current formatting settings

setPreviewBackground

Sets the background color for the text preview widget.

setPropertyOverrideButtonsVisible

Toggles whether data defined buttons should be shown in the widget.

updateLinePlacementOptions

Updates line placement options to reflect current state of widget

updatePlacementWidgets

Updates label placement options to reflect current state of widget

updatePreview

Updates the text preview.

updateWidgetForFormat

Updates the widget's state to reflect the settings in a QgsTextFormat.

Virtual Methods

In PyQGIS, only methods marked as virtual can be safely overridden in a Python subclass of QgsTextFormatWidget. See the FAQ for more details.

saveFormat

Saves the current text settings to a style entry.

setContext

Sets the context in which the widget is shown, e.g., the associated map canvas and expression contexts.

setFormatFromStyle

Sets the current text settings from a style entry.

Signals

auxiliaryFieldCreated

Emitted when an auxiliary field is created in the widget.

widgetChanged

Emitted when the text format defined by the widget changes

Attributes

Labeling

Text

class qgis.gui.QgsTextFormatWidget[source]

Bases: QWidget, QgsExpressionContextGenerator

__init__(format: QgsTextFormat = QgsTextFormat(), mapCanvas: QgsMapCanvas | None = None, parent: QWidget | None = None, layer: QgsMapLayer | None = None)

Constructor for QgsTextFormatWidget.

Parameters:
  • format (QgsTextFormat = QgsTextFormat()) – initial formatting settings to show in widget

  • mapCanvas (Optional[QgsMapCanvas] = None) – associated map canvas

  • parent (Optional[QWidget] = None) – parent widget

  • layer (Optional[QgsMapLayer] = None) – associated layer (vector or mesh)

__init__(mapCanvas: QgsMapCanvas | None, parent: QWidget | None, mode: QgsTextFormatWidget.Mode, layer: QgsMapLayer | None = None)

Constructor for QgsTextFormatWidget.

Parameters:
Labeling = 1
class Mode

Bases: int

Text = 0
signal auxiliaryFieldCreated[source]

Emitted when an auxiliary field is created in the widget.

Added in version 3.10.

context(self) QgsSymbolWidgetContext[source]

Returns the context in which the widget is shown, e.g., the associated map canvas and expression contexts.

See also

setContext()

Added in version 3.10.

Return type:

QgsSymbolWidgetContext

deactivateField(self, key: QgsPalLayerSettings.Property)[source]

Deactivate a field from data defined properties and update the corresponding button.

Parameters:

key (QgsPalLayerSettings.Property) – The property key to deactivate

enableDataDefinedAlignment(self, enable: bool)[source]

Update the enabled state of the data defined alignment buttons.

Deprecated since version 3.24.

Parameters:

enable (bool)

format(self, includeDataDefinedProperties: bool = True) QgsTextFormat[source]

Returns the current formatting settings defined by the widget.

If includateDataDefinedProperties is True, then data defined properties specified in the widget will be included in the format definition.

Parameters:

includeDataDefinedProperties (bool = True)

Return type:

QgsTextFormat

labelGeometryType(self) Qgis.GeometryType[source]

Returns the geometry type which will be used by the labeling engine when registering labels for the labeling settings currently defined by the widget.

Added in version 3.16.

Return type:

Qgis.GeometryType

virtual saveFormat(self)[source]

Saves the current text settings to a style entry.

virtual setContext(self, context: QgsSymbolWidgetContext)[source]

Sets the context in which the widget is shown, e.g., the associated map canvas and expression contexts.

See also

context()

Added in version 3.10.

Parameters:

context (QgsSymbolWidgetContext)

setDockMode(self, enabled: bool)[source]

Sets whether the widget should be shown in a compact dock mode.

Parameters:

enabled (bool) – set to True to show in dock mode.

setFormat(self, format: QgsTextFormat)[source]

Sets the current formatting settings

Added in version 3.2.

Parameters:

format (QgsTextFormat)

virtual setFormatFromStyle(self, name: str | None, type: QgsStyle.StyleEntity, stylePath: str | None)[source]

Sets the current text settings from a style entry.

Added in version 3.10.

Parameters:
setPreviewBackground(self, color: QColor | Qt.GlobalColor)[source]

Sets the background color for the text preview widget.

Parameters:

color (Union[QColor, Qt.GlobalColor]) – background color

setPropertyOverrideButtonsVisible(self, visible: bool)[source]

Toggles whether data defined buttons should be shown in the widget.

Added in version 3.42.

Parameters:

visible (bool)

updateLinePlacementOptions(self)[source]

Updates line placement options to reflect current state of widget

updatePlacementWidgets(self)[source]

Updates label placement options to reflect current state of widget

updatePreview(self)[source]

Updates the text preview.

Added in version 3.10.

updateWidgetForFormat(self, format: QgsTextFormat)[source]

Updates the widget’s state to reflect the settings in a QgsTextFormat.

Parameters:

format (QgsTextFormat) – source format

signal widgetChanged[source]

Emitted when the text format defined by the widget changes