QgsExpressionBuilderWidget class

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

Reference

See QgsExpressionBuilderDialog for example of usage.

Constructors, destructors, conversion operators

QgsExpressionBuilderWidget(QWidget* parent = nullptr): Create a new expression builder widget with an optional parent.

Public functions

auto evalError() const -> bool: Will be set to true if the current expression text reported an eval error with the context.
auto expectedOutputFormat() -> QString: The set expected format string.
auto expressionContext() const -> QgsExpressionContext: Returns the expression context for the widget.
auto expressionText() -> QString: Gets the expression string that has been set in the expression area.
void loadCodeFromFile(QString path): Load code from the given file into the function editor.
void loadFieldNames(): Loads all the field names from the layer.
void loadFieldsAndValues(const QMap<QString, QStringList>& fieldValues): Loads field names and values from the specified map.
void loadFunctionCode(const QString& code): Load code into the function editor.
void loadRecent(const QString& collection = "generic"): Loads the recent expressions from the given collection.
auto model() -> QStandardItemModel*: Returns a pointer to the dialog's function item model.
void newFunctionFile(const QString& fileName = "scratch"): Create a new file in the function editor.
auto parserError() const -> bool: Will be set to true if the current expression text reports a parser error with the context.
auto project() -> QgsProject*: Returns the project currently associated with the widget.
void registerItem(const QString& group, const QString& label, const QString& expressionText, const QString& helpText = QString(), QgsExpressionItem::ItemType type = QgsExpressionItem::ExpressionNode, bool highlightedItem = false, int sortOrder = 1, QIcon icon = QIcon()): Registers a node item for the expression builder.
void saveFunctionFile(QString fileName): Save the current function editor text to the given file.
void saveToRecent(const QString& collection = "generic"): Adds the current expression to the given collection.
void setExpectedOutputFormat(const QString& expected): The set expected format string.
void setExpressionContext(const QgsExpressionContext& context): Sets the expression context for the widget.
void setExpressionText(const QString& expression): Sets the expression string for the widget.
void setGeomCalculator(const QgsDistanceArea& da): Sets geometry calculator used in distance/area calculations.
void setLayer(QgsVectorLayer* layer): Sets layer in order to get the fields and values.
void setProject(QgsProject* project): Sets the project currently associated with the widget.
void updateFunctionFileList(const QString& path): Update the list of function files found at the given path.

Signals

void evalErrorChanged(): Will be set to true if the current expression text reported an eval error with the context.
void expressionParsed(bool isValid): Emitted when the user changes the expression in the widget.
void parserErrorChanged(): Will be set to true if the current expression text reported a parser error with the context.

Public slots

void autosave(): Auto save the current Python function code.
void loadAllValues(): Load all unique values from the set layer into the sample area.
void loadSampleValues(): Load sample values into the sample value area.
void setAutoSave(bool enabled): Enabled or disable auto saving.

Function documentation

bool QgsExpressionBuilderWidget::evalError() const

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

QString QgsExpressionBuilderWidget::expectedOutputFormat()

The set expected format string.

Returns	The expected value format.

This is pure text format and no expression validation is done against it.

QgsExpressionContext QgsExpressionBuilderWidget::expressionContext() const

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.

QString QgsExpressionBuilderWidget::expressionText()

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

Returns	The expression as a string.

void QgsExpressionBuilderWidget::loadFieldNames()

Loads all the field names from the layer.

void QgsExpressionBuilderWidget::loadFieldsAndValues(const QMap<QString, QStringList>& fieldValues)

Loads field names and values from the specified map.

void QgsExpressionBuilderWidget::loadRecent(const QString& collection = "generic")

Loads the recent expressions from the given collection.

By default it is loaded from the collection "generic".

QStandardItemModel* QgsExpressionBuilderWidget::model()

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.

bool QgsExpressionBuilderWidget::parserError() const

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

QgsProject* QgsExpressionBuilderWidget::project()

Returns the project currently associated with the widget.

void QgsExpressionBuilderWidget::registerItem(const QString& group, const QString& label, const QString& expressionText, const QString& helpText = QString(), QgsExpressionItem::ItemType type = QgsExpressionItem::ExpressionNode, bool highlightedItem = false, int sortOrder = 1, QIcon icon = QIcon())

Registers a node item for the expression builder.

Parameters
group	The group the item will be show in the tree view. If the group doesn't exsit it will be created.
label	The label that is show to the user for the item in the tree.
expressionText	The text that is inserted into the expression area when the user double clicks on the item.
helpText	The help text that the user will see when item is selected.
type	The type of the expression item.
highlightedItem	set to true to make the item highlighted, which inserts a bold copy of the item at the top level
sortOrder	sort ranking for item
icon	custom icon to show for item

void QgsExpressionBuilderWidget::saveToRecent(const QString& collection = "generic")

Adds the current expression to the given collection.

By default it is saved to the collection "generic".

void QgsExpressionBuilderWidget::setExpectedOutputFormat(const QString& expected)

The set expected format string.

Parameters
expected	The expected value format for the expression.

This is pure text format and no expression validation is done against it.

void QgsExpressionBuilderWidget::setExpressionContext(const QgsExpressionContext& context)

Sets the expression context for the widget.

Parameters
context	expression context

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

void QgsExpressionBuilderWidget::setLayer(QgsVectorLayer* layer)

Sets layer in order to get the fields and values.

void QgsExpressionBuilderWidget::setProject(QgsProject* project)

Sets the project currently associated with the widget.

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

void QgsExpressionBuilderWidget::evalErrorChanged() signal