Class: QgsExpressionBuilderWidget

A reusable widget that can be used to build an expression string.

See also

QgsExpressionBuilderDialog for example of usage.

Class Hierarchy

Base classes

QWidget
QObject
QPaintDevice

Methods

autosave	Auto save the current Python function code.
editSelectedUserExpression	Edits the selected expression from the stored user expressions, the selected expression must be a user stored expression.
evalError	Will be set to True if the current expression text reported an eval error with the context.
expectedOutputFormat	The set expected format string.
expressionContext	Returns the expression context for the widget.
expressionText	Gets the expression string that has been set in the expression area.
expressionTree	Returns the expression tree
findExpressions	Returns the list of expression items matching a label.
init	Initialize without any layer
initWithFields	Initialize with given fields without any layer
initWithLayer	Initialize with a layer
isExpressionValid	Returns if the expression is valid
layer	Returns the current layer or a None.
loadAllUsedValues	Load all unique values from the set layer into the sample area.
loadAllValues	Load all unique values from the set layer into the sample area.
loadCodeFromFile	Loads code from the given file into the function editor
loadCodeFromProjectFunctions	Loads code from the project into the function editor
loadFieldNames
loadFieldsAndValues	Loads field names and values from the specified map.
loadFunctionCode	Loads code into the function editor
loadRecent	Loads the recent expressions from the given collection.
loadSampleUsedValues	Load used sample values into the sample value area.
loadSampleValues	Load sample values into the sample value area.
loadUserExpressions	Loads the user expressions.
model	Returns a pointer to the dialog's function item model.
newFunctionFile	Creates a new file in the function editor
parserError	Will be set to True if the current expression text reports a parser error with the context.
project	Returns the project currently associated with the widget.
removeFromUserExpressions	Removes the expression label from the user stored expressions.
removeSelectedUserExpression	Removes the selected expression from the stored user expressions, the selected expression must be a user stored expression.
saveFunctionFile	Saves the current function editor text to the given file.
saveProjectFunctionsEntry	Saves the current function editor text to a project entry.
saveToRecent	Adds the current expression to the given collection.
saveToUserExpressions	Stores the user expression with given label and helpText.
setAutoSave	Enabled or disable auto saving.
setCustomPreviewGenerator	Sets the widget to run using a custom preview generator.
setExpectedOutputFormat	The set expected format string.
setExpressionContext	Sets the expression context for the widget.
setExpressionPreviewVisible	Sets whether the expression preview is visible.
setExpressionText	Sets the expression string for the widget
setGeomCalculator	Sets geometry calculator used in distance/area calculations.
setLayer	Sets layer in order to get the fields and values
setProject	Sets the project currently associated with the widget.
storeCurrentUserExpression	Adds the current expressions to the stored user expressions.
updateFunctionFileList	Updates the list of function files found at the given path

Signals

evalErrorChanged	Will be set to True if the current expression text reported an eval error with the context.
expressionParsed	Emitted when the user changes the expression in the widget.
parserErrorChanged	Will be set to True if the current expression text reported a parser error with the context.

Attributes

LoadAll
LoadNothing
LoadRecent
LoadUserExpressions

class qgis.gui.QgsExpressionBuilderWidget

Bases: QWidget

__init__(parent: QWidget | None = None)

Create a new expression builder widget with an optional parent.

Parameters:

parent (Optional[QWidget] = None)

class Flag

Bases: int

class Flags

class Flags(f: QgsExpressionBuilderWidget.Flags | QgsExpressionBuilderWidget.Flag)

class Flags(a0: QgsExpressionBuilderWidget.Flags)

Bases: object

LoadAll = 6

LoadNothing = 0

LoadRecent = 2

LoadUserExpressions = 4

autosave(self)

Auto save the current Python function code.

editSelectedUserExpression(self)

Edits the selected expression from the stored user expressions, the selected expression must be a user stored expression.

Added in version 3.14.

evalError(self) → bool

Will be set to True if the current expression text reported an eval error with the context.

Return type:

bool

signal evalErrorChanged

Will be set to True if the current expression text reported an eval error with the context.

expectedOutputFormat(self) → str

The set expected format string. This is pure text format and no expression validation is done against it.

Return type:

str

Returns:

The expected value format.

expressionContext(self) → QgsExpressionContext

Returns the expression context for the widget. The context is used for the expression preview result and for populating the list of available functions and variables.

See also

setExpressionContext()

Return type:

QgsExpressionContext

signal expressionParsed(isValid: bool)

Emitted when the user changes the expression in the widget. Users of this widget should connect to this signal to decide if to let the user continue.

Parameters:

isValid (bool) – Is True if the expression the user has typed is valid.

expressionText(self) → str

Gets the expression string that has been set in the expression area.

Return type:

str

Returns:

The expression as a string.

expressionTree(self) → QgsExpressionTreeView | None

Returns the expression tree

Added in version 3.14.

Return type:

Optional[QgsExpressionTreeView]

findExpressions(self, label: str | None) → List[QgsExpressionItem]

Returns the list of expression items matching a label.

Added in version 3.12.

Deprecated since version 3.14: Use expressionTree()->findExpressions instead.

Parameters:

label (Optional[str])

Return type:

List[QgsExpressionItem]

init(self, context: QgsExpressionContext = QgsExpressionContext(), recentCollection: str | None = '', flags: QgsExpressionBuilderWidget.Flags | QgsExpressionBuilderWidget.Flag = QgsExpressionBuilderWidget.LoadAll)

Initialize without any layer

Added in version 3.14.

Parameters:

• context (QgsExpressionContext = QgsExpressionContext())

• recentCollection (Optional[str] = '')

• flags (Union[QgsExpressionBuilderWidget.Flags, QgsExpressionBuilderWidget.Flag] = QgsExpressionBuilderWidget.LoadAll)

initWithFields(self, fields: QgsFields, context: QgsExpressionContext = QgsExpressionContext(), recentCollection: str | None = '', flags: QgsExpressionBuilderWidget.Flags | QgsExpressionBuilderWidget.Flag = QgsExpressionBuilderWidget.LoadAll)

Initialize with given fields without any layer

Added in version 3.14.

Parameters:

• fields (QgsFields)

• context (QgsExpressionContext = QgsExpressionContext())

• recentCollection (Optional[str] = '')

• flags (Union[QgsExpressionBuilderWidget.Flags, QgsExpressionBuilderWidget.Flag] = QgsExpressionBuilderWidget.LoadAll)

initWithLayer(self, layer: QgsVectorLayer | None, context: QgsExpressionContext = QgsExpressionContext(), recentCollection: str | None = '', flags: QgsExpressionBuilderWidget.Flags | QgsExpressionBuilderWidget.Flag = QgsExpressionBuilderWidget.LoadAll)

Initialize with a layer

Added in version 3.14.

Parameters:

• layer (Optional[QgsVectorLayer])

• context (QgsExpressionContext = QgsExpressionContext())

• recentCollection (Optional[str] = '')

• flags (Union[QgsExpressionBuilderWidget.Flags, QgsExpressionBuilderWidget.Flag] = QgsExpressionBuilderWidget.LoadAll)

isExpressionValid(self) → bool

Returns if the expression is valid

Return type:

bool

layer(self) → QgsVectorLayer | None

Returns the current layer or a None.

Return type:

Optional[QgsVectorLayer]

loadAllUsedValues(self)

Load all unique values from the set layer into the sample area. Only the used ones. Without available values, even if the formatter can provide them (eg. RelationReference).

Added in version 3.12.

loadAllValues(self)

Load all unique values from the set layer into the sample area. Including all available values, in case the formatter can provide them (eg. RelationReference).

loadCodeFromFile(self, path: str | None)

Loads code from the given file into the function editor

Parameters:

path (Optional[str])

loadCodeFromProjectFunctions(self)

Loads code from the project into the function editor

Added in version 3.40.

loadFieldNames(self)

Deprecated since version 3.14: This is now done automatically.

loadFieldNames(self, fields: QgsFields)

Deprecated since version 3.14: Use expressionTree()->:py:func:~QgsExpressionBuilderWidget.loadFieldNames instead.

Parameters:

fields (QgsFields)

loadFieldsAndValues(self, fieldValues: Dict[str | None, Iterable[str | None]])

Loads field names and values from the specified map.

Deprecated since version 3.14: This will not do anything, use setLayer() instead.

Parameters:

fieldValues (Dict[Optional[str], Iterable[Optional[str]]])

loadFunctionCode(self, code: str | None)

Loads code into the function editor

Parameters:

code (Optional[str])

loadRecent(self, collection: str | None = '')

Loads the recent expressions from the given collection. By default it is loaded from the collection “generic”.

Deprecated since version 3.14: Use expressionTree()->:py:func:~QgsExpressionBuilderWidget.loadRecent instead.

Parameters:

collection (Optional[str] = '')

loadSampleUsedValues(self)

Load used sample values into the sample value area. Only the used ones. Without available values, even if the formatter can provide them (eg. RelationReference).

Added in version 3.12.

loadSampleValues(self)

Load sample values into the sample value area. Including available values, in case the formatter can provide them (eg. RelationReference).

loadUserExpressions(self)

Loads the user expressions.

Deprecated since version 3.14: Use expressionTree()->:py:func:~QgsExpressionBuilderWidget.loadUserExpressions instead.

Added in version 3.12.

model(self) → QStandardItemModel | None

Returns a pointer to the dialog’s function item model. This method is exposed for testing purposes only - it should not be used to modify the model.

Deprecated since version 3.14.

Return type:

Optional[QStandardItemModel]

newFunctionFile(self, fileName: str | None = '')

Creates a new file in the function editor

Parameters:

fileName (Optional[str] = '')

parserError(self) → bool

Will be set to True if the current expression text reports a parser error with the context.

Return type:

bool

signal parserErrorChanged

Will be set to True if the current expression text reported a parser error with the context.

project(self) → QgsProject | None

Returns the project currently associated with the widget.

See also

setProject()

Return type:

Optional[QgsProject]

removeFromUserExpressions(self, label: str | None)

Removes the expression label from the user stored expressions.

Deprecated since version 3.14: Use expressionTree()->:py:func:~QgsExpressionBuilderWidget.removeFromUserExpressions instead.

Added in version 3.12.

Parameters:

label (Optional[str])

removeSelectedUserExpression(self)

Removes the selected expression from the stored user expressions, the selected expression must be a user stored expression.

Added in version 3.12.

saveFunctionFile(self, fileName: str | None)

Saves the current function editor text to the given file.

Parameters:

fileName (Optional[str])

saveProjectFunctionsEntry(self)

Saves the current function editor text to a project entry.

Added in version 3.40.

saveToRecent(self, collection: str | None = '')

Adds the current expression to the given collection. By default it is saved to the collection “generic”.

Deprecated since version 3.14: Use expressionTree()->:py:func:~QgsExpressionBuilderWidget.saveRecent instead.

Parameters:

collection (Optional[str] = '')

saveToUserExpressions(self, label: str | None, expression: str | None, helpText: str | None)

Stores the user expression with given label and helpText.

Deprecated since version 3.14: Use expressionTree()->:py:func:~QgsExpressionBuilderWidget.saveToUserExpressions instead.

Added in version 3.12.

Parameters:

• label (Optional[str])

• expression (Optional[str])

• helpText (Optional[str])

setAutoSave(self, enabled: bool)

Enabled or disable auto saving. When enabled Python scripts will be auto saved when text changes.

Parameters:

enabled (bool) – True to enable auto saving.

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])

setExpectedOutputFormat(self, expected: str | None)

The set expected format string. This is pure text format and no expression validation is done against it.

Parameters:

expected (Optional[str]) – The expected value format for the expression.

Note

Only a UI hint and not used for expression validation.

setExpressionContext(self, context: QgsExpressionContext)

Sets the expression context for the widget. The context is used for the expression preview result and to populate the list of available functions and variables.

Parameters:

context (QgsExpressionContext) – expression context

See also

expressionContext()

setExpressionPreviewVisible(self, isVisible: bool)

Sets whether the expression preview is visible.

Added in version 3.22.

Parameters:

isVisible (bool)

setExpressionText(self, expression: str | None)

Sets the expression string for the widget

Parameters:

expression (Optional[str])

setGeomCalculator(self, da: QgsDistanceArea)

Sets geometry calculator used in distance/area calculations.

Parameters:

da (QgsDistanceArea)

setLayer(self, layer: QgsVectorLayer | None)

Sets layer in order to get the fields and values

Note

this needs to be called before calling loadFieldNames().

Parameters:

layer (Optional[QgsVectorLayer])

setProject(self, project: QgsProject | None)

Sets the project currently associated with the widget. This controls which layers and relations and other project-specific items are shown in the widget.

See also

project()

Parameters:

project (Optional[QgsProject])

storeCurrentUserExpression(self)

Adds the current expressions to the stored user expressions.

Added in version 3.12.

updateFunctionFileList(self, path: str | None)

Updates the list of function files found at the given path

Parameters:

path (Optional[str])