Class: QgsTextFormatWidget

class qgis.gui.QgsTextFormatWidget

Bases: PyQt5.QtWidgets.QWidget, QgsExpressionContextGenerator

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.

New in version 3.0.

QgsTextFormatWidget(format: QgsTextFormat = QgsTextFormat(), mapCanvas: QgsMapCanvas = None, parent: QWidget = None, layer: QgsVectorLayer = None) Constructor for QgsTextFormatWidget.

  • format – initial formatting settings to show in widget

  • mapCanvas – associated map canvas

  • parent – parent widget

  • layer – associated vector layer

QgsTextFormatWidget(mapCanvas: QgsMapCanvas, parent: QWidget, mode: QgsTextFormatWidget.Mode, layer: QgsVectorLayer = None) Constructor for QgsTextFormatWidget.

Labeling = 1
class Mode

Bases: int

Text = 0
actionEvent(self, QActionEvent)

Emitted when an auxiliary field is created in the widget.

New in version 3.10: [signal]

changeEvent(self, QEvent)
childEvent(self, QChildEvent)
closeEvent(self, QCloseEvent)
connectNotify(self, QMetaMethod)
context(self) QgsSymbolWidgetContext

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

See also


New in version 3.10.

Return type


contextMenuEvent(self, QContextMenuEvent)
create(self, window: sip.voidptr = 0, initializeWindow: bool = True, destroyOldWindow: bool = True)
createExpressionContext(self) QgsExpressionContext
Return type


customEvent(self, QEvent)
deactivateField(self, key: QgsPalLayerSettings.Property)

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


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

New in version 3.0.

destroy(self, destroyWindow: bool = True, destroySubWindows: bool = True)
disconnectNotify(self, QMetaMethod)
dragEnterEvent(self, QDragEnterEvent)
dragLeaveEvent(self, QDragLeaveEvent)
dragMoveEvent(self, QDragMoveEvent)
dropEvent(self, QDropEvent)
enableDataDefinedAlignment(self, enable: bool)

Update the enabled state of the data defined alignment buttons.

Deprecated since version QGIS: 3.24


enable (bool) –

enterEvent(self, QEvent)
event(self, QEvent) bool
focusInEvent(self, QFocusEvent)
focusNextChild(self) bool
focusNextPrevChild(self, bool) bool
focusOutEvent(self, QFocusEvent)
focusPreviousChild(self) bool
format(self, includeDataDefinedProperties: bool = True) QgsTextFormat

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.


includeDataDefinedProperties (bool = True) –

Return type


hideEvent(self, QHideEvent)
initPainter(self, QPainter)
inputMethodEvent(self, QInputMethodEvent)
isSignalConnected(self, QMetaMethod) bool
keyPressEvent(self, QKeyEvent)
keyReleaseEvent(self, QKeyEvent)
labelGeometryType(self) QgsWkbTypes.GeometryType

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

New in version 3.16.

Return type


leaveEvent(self, QEvent)
metric(self, QPaintDevice.PaintDeviceMetric) int
mouseDoubleClickEvent(self, QMouseEvent)
mouseMoveEvent(self, QMouseEvent)
mousePressEvent(self, QMouseEvent)
mouseReleaseEvent(self, QMouseEvent)
moveEvent(self, QMoveEvent)
nativeEvent(self, Union[QByteArray, bytes, bytearray], sip.voidptr) Tuple[bool, int]
paintEvent(self, QPaintEvent)
receivers(self, PYQT_SIGNAL) int
resizeEvent(self, QResizeEvent)

Saves the current text settings to a style entry.

sender(self) QObject
senderSignalIndex(self) int
setContext(self, context: QgsSymbolWidgetContext)

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

See also


New in version 3.10.


context (QgsSymbolWidgetContext) –

setDockMode(self, enabled: bool)

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


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

setFormat(self, format: QgsTextFormat)

Sets the current formatting settings

New in version 3.2.


format (QgsTextFormat) –

setFormatFromStyle(self, name: str, type: QgsStyle.StyleEntity, stylePath: str)

Sets the current text settings from a style entry.

New in version 3.10.

setPreviewBackground(self, color: Union[QColor, Qt.GlobalColor, QGradient])

Sets the background color for the text preview widget.


color (Union[QColor) – background color

sharedPainter(self) QPainter
showEvent(self, QShowEvent)
tabletEvent(self, QTabletEvent)
timerEvent(self, QTimerEvent)

Updates line placement options to reflect current state of widget


Updates label placement options to reflect current state of widget


Updates the text preview.

New in version 3.10.

updateWidgetForFormat(self, format: QgsTextFormat)

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


format (QgsTextFormat) – source format

wheelEvent(self, QWheelEvent)

Emitted when the text format defined by the widget changes [signal]