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

#include <qgsexpressionbuilderwidget.h>

Inheritance diagram for QgsExpressionBuilderWidget:

[legend]

Public Types
enum	Flag { LoadNothing = 0 , LoadRecent = 1 << 1 , LoadUserExpressions = 1 << 2 , LoadAll = LoadRecent \| LoadUserExpressions }
	Flag to determine what should be loaded. More...

typedef QFlags< Flag >	Flags

Public Slots
void	autosave ()
	Auto save the current Python function code.

void	editSelectedUserExpression ()
	Edits the selected expression from the stored user expressions, the selected expression must be a user stored expression.

const QList< QgsExpressionItem * >	findExpressions (const QString &label)
	Returns the list of expression items matching a label.

void	loadAllUsedValues ()
	Load all unique values from the set layer into the sample area.

void	loadAllValues ()
	Load all unique values from the set layer into the sample area.

void	loadSampleUsedValues ()
	Load used sample values into the sample value area.

void	loadSampleValues ()
	Load sample values into the sample value area.

void	removeSelectedUserExpression ()
	Removes the selected expression from the stored user expressions, the selected expression must be a user stored expression.

void	setAutoSave (bool enabled)
	Enabled or disable auto saving.

void	storeCurrentUserExpression ()
	Adds the current expressions to the stored user expressions.

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 Member Functions
	QgsExpressionBuilderWidget (QWidget *parent=nullptr)
	Create a new expression builder widget with an optional parent.

	~QgsExpressionBuilderWidget () override

bool	evalError () const
	Will be set to `true` if the current expression text reported an eval error with the context.

QString	expectedOutputFormat ()
	The set expected format string.

QgsExpressionContext	expressionContext () const
	Returns the expression context for the widget.

QString	expressionText ()
	Gets the expression string that has been set in the expression area.

QgsExpressionTreeView *	expressionTree () const
	Returns the expression tree.

void	init (const QgsExpressionContext &context=QgsExpressionContext(), const QString &recentCollection=QStringLiteral("generic"), QgsExpressionBuilderWidget::Flags flags=LoadAll)
	Initialize without any layer.

void	initWithFields (const QgsFields &fields, const QgsExpressionContext &context=QgsExpressionContext(), const QString &recentCollection=QStringLiteral("generic"), QgsExpressionBuilderWidget::Flags flags=LoadAll)
	Initialize with given fields without any layer.

void	initWithLayer (QgsVectorLayer *layer, const QgsExpressionContext &context=QgsExpressionContext(), const QString &recentCollection=QStringLiteral("generic"), QgsExpressionBuilderWidget::Flags flags=LoadAll)
	Initialize with a layer.

bool	isExpressionValid ()
	Returns if the expression is valid.

QgsVectorLayer *	layer () const
	Returns the current layer or a nullptr.

void	loadCodeFromFile (QString path)
	Loads code from the given file into the function editor.

Q_DECL_DEPRECATED void	loadFieldNames ()

Q_DECL_DEPRECATED void	loadFieldNames (const QgsFields &fields)

Q_DECL_DEPRECATED void	loadFieldsAndValues (const QMap< QString, QStringList > &fieldValues)
	Loads field names and values from the specified map.

void	loadFunctionCode (const QString &code)
	Loads code into the function editor.

Q_DECL_DEPRECATED void	loadRecent (const QString &collection=QStringLiteral("generic"))
	Loads the recent expressions from the given collection.

Q_DECL_DEPRECATED void	loadUserExpressions ()
	Loads the user expressions.

Q_DECL_DEPRECATED QStandardItemModel *	model ()
	Returns a pointer to the dialog's function item model.

void	newFunctionFile (const QString &fileName="scratch")
	Creates a new file in the function editor.

bool	parserError () const
	Will be set to `true` if the current expression text reports a parser error with the context.

QgsProject *	project ()
	Returns the project currently associated with the widget.

Q_DECL_DEPRECATED void	removeFromUserExpressions (const QString &label)
	Removes the expression label from the user stored expressions.

void	saveFunctionFile (QString fileName)
	Saves the current function editor text to the given file.

Q_DECL_DEPRECATED void	saveToRecent (const QString &collection="generic")
	Adds the current expression to the given collection.

Q_DECL_DEPRECATED void	saveToUserExpressions (const QString &label, const QString &expression, const QString &helpText)
	Stores the user expression with given label and helpText.

void	setCustomPreviewGenerator (const QString &label, const QList< QPair< QString, QVariant > > &choices, const std::function< QgsExpressionContext(const QVariant &) > &previewContextGenerator)
	Sets the widget to run using a custom preview generator.

void	setExpectedOutputFormat (const QString &expected)
	The set expected format string.

void	setExpressionContext (const QgsExpressionContext &context)
	Sets the expression context for the widget.

void	setExpressionPreviewVisible (bool isVisible)
	Sets whether the expression preview is visible.

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)
	Updates the list of function files found at the given path.

Protected Member Functions
void	showEvent (QShowEvent *e) override

Detailed Description

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

See QgsExpressionBuilderDialog for example of usage.

Definition at line 42 of file qgsexpressionbuilderwidget.h.

Member Typedef Documentation

◆ Flags

typedef QFlags< Flag > QgsExpressionBuilderWidget::Flags

Definition at line 58 of file qgsexpressionbuilderwidget.h.

Member Enumeration Documentation

◆ Flag

enum QgsExpressionBuilderWidget::Flag

Flag to determine what should be loaded.

Since: QGIS 3.14

Enumerator
LoadNothing	Do not load anything.
LoadRecent	Load recent expressions given the collection key.
LoadUserExpressions	Load user expressions.
LoadAll	Load everything.

Definition at line 51 of file qgsexpressionbuilderwidget.h.

Constructor & Destructor Documentation

◆ QgsExpressionBuilderWidget()

QgsExpressionBuilderWidget::QgsExpressionBuilderWidget ( QWidget * parent = nullptr )

Create a new expression builder widget with an optional parent.

Definition at line 72 of file qgsexpressionbuilderwidget.cpp.

◆ ~QgsExpressionBuilderWidget()

QgsExpressionBuilderWidget::~QgsExpressionBuilderWidget ( )

override

Definition at line 247 of file qgsexpressionbuilderwidget.cpp.

Member Function Documentation

◆ autosave

void QgsExpressionBuilderWidget::autosave ( )

slot

Auto save the current Python function code.

Definition at line 982 of file qgsexpressionbuilderwidget.cpp.

◆ editSelectedUserExpression

void QgsExpressionBuilderWidget::editSelectedUserExpression ( )

slot

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

Since: QGIS 3.14

Definition at line 1015 of file qgsexpressionbuilderwidget.cpp.

◆ evalError()

bool QgsExpressionBuilderWidget::evalError ( ) const

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

Definition at line 715 of file qgsexpressionbuilderwidget.cpp.

◆ evalErrorChanged

void QgsExpressionBuilderWidget::evalErrorChanged ( )

signal

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

◆ expectedOutputFormat()

QString QgsExpressionBuilderWidget::expectedOutputFormat ( )

The set expected format string.

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

Returns: The expected value format.

Definition at line 678 of file qgsexpressionbuilderwidget.cpp.

◆ expressionContext()

QgsExpressionContext QgsExpressionBuilderWidget::expressionContext ( ) const

inline

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

Definition at line 141 of file qgsexpressionbuilderwidget.h.

◆ expressionParsed

void QgsExpressionBuilderWidget::expressionParsed ( bool isValid )

signal

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 Is true if the expression the user has typed is valid.

◆ expressionText()

QString QgsExpressionBuilderWidget::expressionText ( )

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

Returns: The expression as a string.

Definition at line 668 of file qgsexpressionbuilderwidget.cpp.

◆ expressionTree()

QgsExpressionTreeView * QgsExpressionBuilderWidget::expressionTree ( ) const

Returns the expression tree.

Since: QGIS 3.14

Definition at line 641 of file qgsexpressionbuilderwidget.cpp.

◆ findExpressions

const QList< QgsExpressionItem * > QgsExpressionBuilderWidget::findExpressions ( const QString & label )

slot

Returns the list of expression items matching a label.

Since: QGIS 3.12

Deprecated:: since QGIS 3.14 use expressionTree()->findExpressions instead

Definition at line 1143 of file qgsexpressionbuilderwidget.cpp.

◆ init()

void QgsExpressionBuilderWidget::init	(	const QgsExpressionContext &	context = `QgsExpressionContext()`,
		const QString &	recentCollection = `QStringLiteral( "generic" )`,
		QgsExpressionBuilderWidget::Flags	flags = `LoadAll`
	)

Initialize without any layer.

Since: QGIS 3.14

Definition at line 256 of file qgsexpressionbuilderwidget.cpp.

◆ initWithFields()

void QgsExpressionBuilderWidget::initWithFields	(	const QgsFields &	fields,
		const QgsExpressionContext &	context = `QgsExpressionContext()`,
		const QString &	recentCollection = `QStringLiteral( "generic" )`,
		QgsExpressionBuilderWidget::Flags	flags = `LoadAll`
	)

Initialize with given fields without any layer.

Since: QGIS 3.14

Definition at line 273 of file qgsexpressionbuilderwidget.cpp.

◆ initWithLayer()

void QgsExpressionBuilderWidget::initWithLayer	(	QgsVectorLayer *	layer,
		const QgsExpressionContext &	context = `QgsExpressionContext()`,
		const QString &	recentCollection = `QStringLiteral( "generic" )`,
		QgsExpressionBuilderWidget::Flags	flags = `LoadAll`
	)

Initialize with a layer.

Since: QGIS 3.14

Definition at line 267 of file qgsexpressionbuilderwidget.cpp.

◆ isExpressionValid()

bool QgsExpressionBuilderWidget::isExpressionValid ( )

Returns if the expression is valid.

Definition at line 621 of file qgsexpressionbuilderwidget.cpp.

◆ layer()

QgsVectorLayer * QgsExpressionBuilderWidget::layer ( ) const

Returns the current layer or a nullptr.

Definition at line 303 of file qgsexpressionbuilderwidget.cpp.

◆ loadAllUsedValues

void QgsExpressionBuilderWidget::loadAllUsedValues ( )

slot

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

Since: QGIS 3.12

Definition at line 953 of file qgsexpressionbuilderwidget.cpp.

◆ loadAllValues

void QgsExpressionBuilderWidget::loadAllValues ( )

slot

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

Definition at line 913 of file qgsexpressionbuilderwidget.cpp.

◆ loadCodeFromFile()

void QgsExpressionBuilderWidget::loadCodeFromFile ( QString path )

Loads code from the given file into the function editor.

Definition at line 501 of file qgsexpressionbuilderwidget.cpp.

◆ loadFieldNames() [1/2]

Q_DECL_DEPRECATED void QgsExpressionBuilderWidget::loadFieldNames ( )

inline

Deprecated:: since QGIS 3.14 this is now done automatically

Definition at line 98 of file qgsexpressionbuilderwidget.h.

◆ loadFieldNames() [2/2]

Q_DECL_DEPRECATED void QgsExpressionBuilderWidget::loadFieldNames ( const QgsFields & fields )

inline

Deprecated:: since QGIS 3.14 use expressionTree()->loadFieldNames() instead

Definition at line 101 of file qgsexpressionbuilderwidget.h.

◆ loadFieldsAndValues()

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

Loads field names and values from the specified map.

Deprecated:: since QGIS 3.14 this will not do anything, use setLayer() instead

Definition at line 521 of file qgsexpressionbuilderwidget.cpp.

◆ loadFunctionCode()

void QgsExpressionBuilderWidget::loadFunctionCode ( const QString & code )

Loads code into the function editor.

Definition at line 509 of file qgsexpressionbuilderwidget.cpp.

◆ loadRecent()

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

Loads the recent expressions from the given collection.

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

Deprecated:: since QGIS 3.14 use expressionTree()->loadRecent() instead

Definition at line 636 of file qgsexpressionbuilderwidget.cpp.

◆ loadSampleUsedValues

void QgsExpressionBuilderWidget::loadSampleUsedValues ( )

slot

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

Since: QGIS 3.12

Definition at line 933 of file qgsexpressionbuilderwidget.cpp.

◆ loadSampleValues

void QgsExpressionBuilderWidget::loadSampleValues ( )

slot

Load sample values into the sample value area.

Including available values, in case the formatter can provide them (eg. RelationReference).

Definition at line 893 of file qgsexpressionbuilderwidget.cpp.

◆ loadUserExpressions()

void QgsExpressionBuilderWidget::loadUserExpressions ( )

Loads the user expressions.

Deprecated:: since QGIS 3.14 use expressionTree()->loadUserExpressions() instead

Since: QGIS 3.12

Definition at line 647 of file qgsexpressionbuilderwidget.cpp.

◆ model()

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.

Deprecated:: since QGIS 3.14

Definition at line 720 of file qgsexpressionbuilderwidget.cpp.

◆ newFunctionFile()

void QgsExpressionBuilderWidget::newFunctionFile ( const QString & fileName = "scratch" )

Creates a new file in the function editor.

Definition at line 428 of file qgsexpressionbuilderwidget.cpp.

◆ parserError()

bool QgsExpressionBuilderWidget::parserError ( ) const

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

Definition at line 705 of file qgsexpressionbuilderwidget.cpp.

◆ parserErrorChanged

void QgsExpressionBuilderWidget::parserErrorChanged ( )

signal

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

◆ project()

QgsProject * QgsExpressionBuilderWidget::project ( )

Returns the project currently associated with the widget.

See also: setProject()

Definition at line 727 of file qgsexpressionbuilderwidget.cpp.

◆ removeFromUserExpressions()

void QgsExpressionBuilderWidget::removeFromUserExpressions ( const QString & label )

Removes the expression label from the user stored expressions.

Deprecated:: since QGIS 3.14 use expressionTree()->removeFromUserExpressions() instead

Since: QGIS 3.12

Definition at line 657 of file qgsexpressionbuilderwidget.cpp.

◆ removeSelectedUserExpression

void QgsExpressionBuilderWidget::removeSelectedUserExpression ( )

slot

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

Since: QGIS 3.12

Definition at line 1044 of file qgsexpressionbuilderwidget.cpp.

◆ saveFunctionFile()

void QgsExpressionBuilderWidget::saveFunctionFile ( QString fileName )

Saves the current function editor text to the given file.

Definition at line 372 of file qgsexpressionbuilderwidget.cpp.

◆ saveToRecent()

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

Adds the current expression to the given collection.

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

Deprecated:: since QGIS 3.14 use expressionTree()->saveRecent() instead

Definition at line 631 of file qgsexpressionbuilderwidget.cpp.

◆ saveToUserExpressions()

void QgsExpressionBuilderWidget::saveToUserExpressions	(	const QString &	label,
		const QString &	expression,
		const QString &	helpText
	)

Stores the user expression with given label and helpText.

Deprecated:: since QGIS 3.14 use expressionTree()->saveToUserExpressions() instead

Since: QGIS 3.12

Definition at line 652 of file qgsexpressionbuilderwidget.cpp.

◆ setAutoSave

void QgsExpressionBuilderWidget::setAutoSave ( bool enabled )

inlineslot

Enabled or disable auto saving.

When enabled Python scripts will be auto saved when text changes.

Parameters

enabled true to enable auto saving.

Definition at line 362 of file qgsexpressionbuilderwidget.h.

◆ setCustomPreviewGenerator()

void QgsExpressionBuilderWidget::setCustomPreviewGenerator	(	const QString &	label,
		const QList< QPair< QString, QVariant > > &	choices,
		const std::function< QgsExpressionContext(const QVariant &) > &	previewContextGenerator
	)

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	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	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.

Since: QGIS 3.38

Definition at line 626 of file qgsexpressionbuilderwidget.cpp.

◆ setExpectedOutputFormat()

void QgsExpressionBuilderWidget::setExpectedOutputFormat ( const QString & expected )

The set expected format string.

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

Parameters

expected The expected value format for the expression.

Note: Only a UI hint and not used for expression validation.

Definition at line 683 of file qgsexpressionbuilderwidget.cpp.

◆ setExpressionContext()

void QgsExpressionBuilderWidget::setExpressionContext ( const QgsExpressionContext & context )

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 expression context

See also: expressionContext

Definition at line 689 of file qgsexpressionbuilderwidget.cpp.

◆ setExpressionPreviewVisible()

void QgsExpressionBuilderWidget::setExpressionPreviewVisible ( bool isVisible )

Sets whether the expression preview is visible.

Since: QGIS 3.22

Definition at line 710 of file qgsexpressionbuilderwidget.cpp.

◆ setExpressionText()

void QgsExpressionBuilderWidget::setExpressionText ( const QString & expression )

Sets the expression string for the widget.

Definition at line 673 of file qgsexpressionbuilderwidget.cpp.

◆ setGeomCalculator()

void QgsExpressionBuilderWidget::setGeomCalculator ( const QgsDistanceArea & da )

Sets geometry calculator used in distance/area calculations.

Definition at line 663 of file qgsexpressionbuilderwidget.cpp.

◆ setLayer()

void QgsExpressionBuilderWidget::setLayer ( QgsVectorLayer * layer )

Sets layer in order to get the fields and values.

Note: this needs to be called before calling loadFieldNames().

Definition at line 280 of file qgsexpressionbuilderwidget.cpp.

◆ setProject()

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.

See also: project()

Definition at line 732 of file qgsexpressionbuilderwidget.cpp.

◆ showEvent()

void QgsExpressionBuilderWidget::showEvent ( QShowEvent * e )

overrideprotected

Definition at line 738 of file qgsexpressionbuilderwidget.cpp.

◆ storeCurrentUserExpression

void QgsExpressionBuilderWidget::storeCurrentUserExpression ( )

slot

Adds the current expressions to the stored user expressions.

Since: QGIS 3.12

Definition at line 1005 of file qgsexpressionbuilderwidget.cpp.

◆ updateFunctionFileList()

void QgsExpressionBuilderWidget::updateFunctionFileList ( const QString & path )

Updates the list of function files found at the given path.

Definition at line 398 of file qgsexpressionbuilderwidget.cpp.

The documentation for this class was generated from the following files:

/home/fischer/src/qgis-3.38/src/gui/qgsexpressionbuilderwidget.h
/home/fischer/src/qgis-3.38/src/gui/qgsexpressionbuilderwidget.cpp

Public Types

Public Slots

Signals

Public Member Functions

Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ Flags

Member Enumeration Documentation

◆ Flag

Constructor & Destructor Documentation

◆ QgsExpressionBuilderWidget()

◆ ~QgsExpressionBuilderWidget()

Member Function Documentation

◆ autosave

◆ editSelectedUserExpression

◆ evalError()

◆ evalErrorChanged

◆ expectedOutputFormat()

◆ expressionContext()

◆ expressionParsed

◆ expressionText()

◆ expressionTree()

◆ findExpressions

◆ init()

◆ initWithFields()

◆ initWithLayer()

◆ isExpressionValid()

◆ layer()

◆ loadAllUsedValues

◆ loadAllValues

◆ loadCodeFromFile()

◆ loadFieldNames() [1/2]

◆ loadFieldNames() [2/2]

◆ loadFieldsAndValues()

◆ loadFunctionCode()

◆ loadRecent()

◆ loadSampleUsedValues

◆ loadSampleValues

◆ loadUserExpressions()

◆ model()

◆ newFunctionFile()

◆ parserError()

◆ parserErrorChanged

◆ project()

◆ removeFromUserExpressions()

◆ removeSelectedUserExpression

◆ saveFunctionFile()

◆ saveToRecent()

◆ saveToUserExpressions()

◆ setAutoSave

◆ setCustomPreviewGenerator()

◆ setExpectedOutputFormat()

◆ setExpressionContext()

◆ setExpressionPreviewVisible()

◆ setExpressionText()

◆ setGeomCalculator()

◆ setLayer()

◆ setProject()

◆ showEvent()

◆ storeCurrentUserExpression

◆ updateFunctionFileList()