Class: QgsFieldExpressionWidget

A widget for selection of layer fields or expression creation.

It contains a combo box to display the fields and expression and a button to open the expression dialog. The combo box is editable, allowing expressions to be edited inline.

The validity of the expression is checked live on key press, invalid expressions are displayed in red. The expression will be added to the model (and the fieldChanged signals emitted) only when editing in the line edit is finished (focus lost, enter key pressed).

Class Hierarchy

Base classes

QWidget
QObject
QPaintDevice

Methods

allowEmptyFieldName	Returns True if the combo box allows the empty field ("not set") choice.
allowEvalErrors	Allow accepting expressions with evaluation errors.
appendScope	Appends a scope to the current expression context.
asExpression	Returns the currently selected field or expression.
buttonVisible	Returns the visibility of the button
currentField	currentField returns the currently selected field or expression if allowed
currentFieldChanged
currentText	Returns the current text that is set in the expression area
editExpression	open the expression dialog to edit the current or add a new expression
expression	Returns the currently selected field or expression.
expressionDialogTitle	Returns the title used for the expression dialog
expressionEdited	when expression is edited by the user in the line edit, it will be checked for validity
expressionEditingFinished	when expression has been edited (finished) it will be added to the model
filters	currently used filter on list of fields
isExpression	If the content is not just a simple field this method will return True.
isExpressionValid
isValidExpression	Returns True if the current expression is valid
layer	Returns the layer currently associated with the widget.
registerExpressionContextGenerator	Register an expression context generator class that will be used to retrieve an expression context for the widget.
setAllowEmptyFieldName	Sets whether an optional empty field ("not set") option is shown in the combo box.
setAllowEvalErrors	Allow accepting expressions with evaluation errors.
setButtonVisible	Set the visibility of the button
setCustomPreviewGenerator	Sets the widget to run using a custom preview generator.
setExpression	Sets the current expression text and if applicable also the field.
setExpressionDialogTitle	define the title used in the expression dialog
setField	sets the current field or expression in the widget
setFields	Sets the fields used in the widget to fields, this allows the widget to work without a layer.
setFilters	setFilters allows filtering according to the type of field
setGeomCalculator	Sets the geometry calculator used in the expression dialog
setLayer	Sets the layer used to display the fields and expression.
setLeftHandButtonStyle
setRow	sets the current row in the widget
updateLineEditStyle	updateLineEditStyle will re-style (color/font) the line edit depending on content and status

Signals

allowEvalErrorsChanged	Allow accepting expressions with evaluation errors.
buttonVisibleChanged	Emitted when the button visibility changes
fieldChanged	fieldChanged signal with indication of the validity of the expression

class qgis.gui.QgsFieldExpressionWidget

Bases: QWidget

__init__(parent: QWidget | None = None)

QgsFieldExpressionWidget creates a widget with a combo box to display the fields and expression and a button to open the expression dialog

Parameters:

parent (Optional[QWidget] = None)

allowEmptyFieldName(self) → bool

Returns True if the combo box allows the empty field (“not set”) choice.

See also

setAllowEmptyFieldName()

Added in version 3.4.6.

Return type:

bool

allowEvalErrors(self) → bool

Allow accepting expressions with evaluation errors. This can be useful when we are not able to provide an expression context of which we are sure it’s completely populated.

Return type:

bool

signal allowEvalErrorsChanged

Allow accepting expressions with evaluation errors. This can be useful when we are not able to provide an expression context of which we are sure it’s completely populated.

appendScope(self, scope: QgsExpressionContextScope | None)

Appends a scope to the current expression context.

Parameters:

scope (Optional[QgsExpressionContextScope]) – The scope to add.

Added in version 3.2.

asExpression(self) → str

Returns the currently selected field or expression. If a field is currently selected, the returned value will be converted to a valid expression referencing this field (ie enclosing the field name with appropriate quotations).

Return type:

str

buttonVisible(self) → bool

Returns the visibility of the button

If button is hidden, the widget essentially becomes an editable combo box

Added in version 3.36.

Return type:

bool

signal buttonVisibleChanged

Emitted when the button visibility changes

Added in version 3.36.

currentField(self)

currentField returns the currently selected field or expression if allowed

Parameters:

• isExpression – determines if the string returned is the name of a field or an expression

• isValid – determines if the expression (or field) returned is valid

currentFieldChanged(self)

currentText(self) → str

Returns the current text that is set in the expression area

Return type:

str

editExpression(self)

open the expression dialog to edit the current or add a new expression

expression(self) → str

Returns the currently selected field or expression. If a field is currently selected, the returned value will be converted to a valid expression referencing this field (ie enclosing the field name with appropriate quotations).

Alias for asExpression()

Return type:

str

expressionDialogTitle(self) → str

Returns the title used for the expression dialog

Return type:

str

expressionEdited(self, expression: str | None)

when expression is edited by the user in the line edit, it will be checked for validity

Parameters:

expression (Optional[str])

expressionEditingFinished(self)

when expression has been edited (finished) it will be added to the model

signal fieldChanged(fieldName: str, isValid: bool)

fieldChanged signal with indication of the validity of the expression

Parameters:

• fieldName (str)

• isValid (bool)

filters(self) → QgsFieldProxyModel.Filters

currently used filter on list of fields

Return type:

QgsFieldProxyModel.Filters

isExpression(self) → bool

If the content is not just a simple field this method will return True.

Return type:

bool

isExpressionValid(self, expressionStr: str | None) → bool

Parameters:

expressionStr (Optional[str])

Return type:

bool

isValidExpression(self, expressionError: str | None | None = '') → bool

Returns True if the current expression is valid

Parameters:

expressionError (Optional[Optional[str]] = '')

Return type:

bool

layer(self) → QgsVectorLayer | None

Returns the layer currently associated with the widget.

See also

setLayer()

Return type:

Optional[QgsVectorLayer]

registerExpressionContextGenerator(self, generator: QgsExpressionContextGenerator | None)

Register an expression context generator class that will be used to retrieve an expression context for the widget.

Parameters:

generator (Optional[QgsExpressionContextGenerator]) – A QgsExpressionContextGenerator class that will be used to create an expression context when required.

setAllowEmptyFieldName(self, allowEmpty: bool)

Sets whether an optional empty field (“not set”) option is shown in the combo box.

See also

allowEmptyFieldName()

Added in version 3.4.6.

Parameters:

allowEmpty (bool)

setAllowEvalErrors(self, allowEvalErrors: bool)

Allow accepting expressions with evaluation errors. This can be useful when we are not able to provide an expression context of which we are sure it’s completely populated.

Parameters:

allowEvalErrors (bool)

setButtonVisible(self, visible: bool)

Set the visibility of the button

If button is hidden, the widget essentially becomes an editable combo box

Added in version 3.36.

Parameters:

visible (bool)

setCustomPreviewGenerator(self, label: str | None, choices: Iterable[Tuple[str | None, Any]], a2: Callable[..., None])

Sets the widget to run using a custom preview generator.

In this mode, the widget will call a callback function to generate a new QgsExpressionContext as the previewed object changes. This can be used to provide custom preview values for different objects (i.e. for objects which aren’t vector layer features).

Parameters:

• label (Optional[str]) – The label to display for the combo box presenting choices of objects. This should be a representative name, eg “Band” if the widget is showing choices of raster layer bands

• choices (Iterable[Tuple[Optional[str], Any]]) – A list of choices to present to the user. Each choice is a pair of a human-readable label and a QVariant representing the object to preview.

• previewContextGenerator – A function which takes a QVariant representing the object to preview, and returns a QgsExpressionContext to use for previewing the object.

Added in version 3.38.

Parameters:

a2 (Callable[..., None])

setExpression(self, expression: str | None)

Sets the current expression text and if applicable also the field. Alias for setField.

Parameters:

expression (Optional[str])

setExpressionDialogTitle(self, title: str | None)

define the title used in the expression dialog

Parameters:

title (Optional[str])

setField(self, fieldName: str | None)

sets the current field or expression in the widget

Parameters:

fieldName (Optional[str])

setFields(self, fields: QgsFields)

Sets the fields used in the widget to fields, this allows the widget to work without a layer.

Added in version 3.14.

Parameters:

fields (QgsFields)

setFilters(self, filters: QgsFieldProxyModel.Filters | QgsFieldProxyModel.Filter)

setFilters allows filtering according to the type of field

Parameters:

filters (Union[QgsFieldProxyModel.Filters, QgsFieldProxyModel.Filter])

setGeomCalculator(self, da: QgsDistanceArea)

Sets the geometry calculator used in the expression dialog

Parameters:

da (QgsDistanceArea)

setLayer(self, layer: QgsMapLayer | None)

Sets the layer used to display the fields and expression.

See also

layer()

Parameters:

layer (Optional[QgsMapLayer])

setLeftHandButtonStyle(self, isLeft: bool)

Parameters:

isLeft (bool)

setRow(self, row: int)

sets the current row in the widget

Parameters:

row (int)

updateLineEditStyle(self, expression: str | None = '')

updateLineEditStyle will re-style (color/font) the line edit depending on content and status

Parameters:

expression (Optional[str] = '') – if expression is given it will be evaluated for the given string, otherwise it takes current expression from the model