QGIS API Documentation  3.23.0-Master (22c16f2067)
Classes | Public Types | Public Slots | Signals | Public Member Functions | Protected Member Functions | List of all members
QgsExpressionBuilderWidget Class Reference

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

#include <qgsexpressionbuilderwidget.h>

Inheritance diagram for QgsExpressionBuilderWidget:
Inheritance graph
[legend]

Public Types

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

Public Slots

void autosave ()
 Auto save the current Python function code. More...
 
void editSelectedUserExpression ()
 Edits the selected expression from the stored user expressions, the selected expression must be a user stored expression. More...
 
const QList< QgsExpressionItem * > findExpressions (const QString &label)
 Returns the list of expression items matching a label. More...
 
void loadAllUsedValues ()
 Load all unique values from the set layer into the sample area. More...
 
void loadAllValues ()
 Load all unique values from the set layer into the sample area. More...
 
void loadSampleUsedValues ()
 Load used sample values into the sample value area. More...
 
void loadSampleValues ()
 Load sample values into the sample value area. More...
 
void removeSelectedUserExpression ()
 Removes the selected expression from the stored user expressions, the selected expression must be a user stored expression. More...
 
void setAutoSave (bool enabled)
 Enabled or disable auto saving. More...
 
void storeCurrentUserExpression ()
 Adds the current expressions to the stored user expressions. More...
 

Signals

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

Public Member Functions

 QgsExpressionBuilderWidget (QWidget *parent=nullptr)
 Create a new expression builder widget with an optional parent. More...
 
 ~QgsExpressionBuilderWidget () override
 
bool evalError () const
 Will be set to true if the current expression text reported an eval error with the context. More...
 
QString expectedOutputFormat ()
 The set expected format string. More...
 
QgsExpressionContext expressionContext () const
 Returns the expression context for the widget. More...
 
QString expressionText ()
 Gets the expression string that has been set in the expression area. More...
 
QgsExpressionTreeViewexpressionTree () const
 Returns the expression tree. More...
 
void init (const QgsExpressionContext &context=QgsExpressionContext(), const QString &recentCollection=QStringLiteral("generic"), QgsExpressionBuilderWidget::Flags flags=LoadAll)
 Initialize without any layer. More...
 
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. More...
 
void initWithLayer (QgsVectorLayer *layer, const QgsExpressionContext &context=QgsExpressionContext(), const QString &recentCollection=QStringLiteral("generic"), QgsExpressionBuilderWidget::Flags flags=LoadAll)
 Initialize with a layer. More...
 
bool isExpressionValid ()
 Returns if the expression is valid. More...
 
QgsVectorLayerlayer () const
 Returns the current layer or a nullptr. More...
 
void loadCodeFromFile (QString path)
 Loads code from the given file into the function editor. More...
 
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. More...
 
void loadFunctionCode (const QString &code)
 Loads code into the function editor. More...
 
Q_DECL_DEPRECATED void loadRecent (const QString &collection=QStringLiteral("generic"))
 Loads the recent expressions from the given collection. More...
 
Q_DECL_DEPRECATED void loadUserExpressions ()
 Loads the user expressions. More...
 
Q_DECL_DEPRECATED QStandardItemModel * model ()
 Returns a pointer to the dialog's function item model. More...
 
void newFunctionFile (const QString &fileName="scratch")
 Creates a new file in the function editor. More...
 
bool parserError () const
 Will be set to true if the current expression text reports a parser error with the context. More...
 
QgsProjectproject ()
 Returns the project currently associated with the widget. More...
 
Q_DECL_DEPRECATED void removeFromUserExpressions (const QString &label)
 Removes the expression label from the user stored expressions. More...
 
void saveFunctionFile (QString fileName)
 Saves the current function editor text to the given file. More...
 
Q_DECL_DEPRECATED void saveToRecent (const QString &collection="generic")
 Adds the current expression to the given collection. More...
 
Q_DECL_DEPRECATED void saveToUserExpressions (const QString &label, const QString &expression, const QString &helpText)
 Stores the user expression with given label and helpText. More...
 
void setExpectedOutputFormat (const QString &expected)
 The set expected format string. More...
 
void setExpressionContext (const QgsExpressionContext &context)
 Sets the expression context for the widget. More...
 
void setExpressionPreviewVisible (bool isVisible)
 Sets whether the expression preview is visible. More...
 
void setExpressionText (const QString &expression)
 Sets the expression string for the widget. More...
 
void setGeomCalculator (const QgsDistanceArea &da)
 Sets geometry calculator used in distance/area calculations. More...
 
void setLayer (QgsVectorLayer *layer)
 Sets layer in order to get the fields and values. More...
 
void setProject (QgsProject *project)
 Sets the project currently associated with the widget. More...
 
void updateFunctionFileList (const QString &path)
 Updates the list of function files found at the given path. More...
 

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 Enumeration Documentation

◆ 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 73 of file qgsexpressionbuilderwidget.cpp.

◆ ~QgsExpressionBuilderWidget()

QgsExpressionBuilderWidget::~QgsExpressionBuilderWidget ( )
override

Definition at line 245 of file qgsexpressionbuilderwidget.cpp.

Member Function Documentation

◆ autosave

void QgsExpressionBuilderWidget::autosave ( )
slot

Auto save the current Python function code.

Definition at line 907 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 940 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.

Since
QGIS 3.0

Definition at line 679 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.

Since
QGIS 3.0

◆ 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 642 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
Since
QGIS 2.12

Definition at line 143 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
isValidIs 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 632 of file qgsexpressionbuilderwidget.cpp.

◆ expressionTree()

QgsExpressionTreeView * QgsExpressionBuilderWidget::expressionTree ( ) const

Returns the expression tree.

Since
QGIS 3.14

Definition at line 605 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 1065 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 254 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 271 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 265 of file qgsexpressionbuilderwidget.cpp.

◆ isExpressionValid()

bool QgsExpressionBuilderWidget::isExpressionValid ( )

Returns if the expression is valid.

Definition at line 590 of file qgsexpressionbuilderwidget.cpp.

◆ layer()

QgsVectorLayer * QgsExpressionBuilderWidget::layer ( ) const

Returns the current layer or a nullptr.

Definition at line 301 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 886 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 862 of file qgsexpressionbuilderwidget.cpp.

◆ loadCodeFromFile()

void QgsExpressionBuilderWidget::loadCodeFromFile ( QString  path)

Loads code from the given file into the function editor.

Definition at line 484 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.

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

Definition at line 504 of file qgsexpressionbuilderwidget.cpp.

◆ loadFunctionCode()

void QgsExpressionBuilderWidget::loadFunctionCode ( const QString &  code)

Loads code into the function editor.

Definition at line 492 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 600 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 874 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 850 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 611 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.

Since
QGIS 3.0
Deprecated:
since QGIS 3.14

Definition at line 684 of file qgsexpressionbuilderwidget.cpp.

◆ newFunctionFile()

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

Creates a new file in the function editor.

Definition at line 412 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.

Since
QGIS 3.0

Definition at line 669 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.

Since
QGIS 3.0

◆ project()

QgsProject * QgsExpressionBuilderWidget::project ( )

Returns the project currently associated with the widget.

See also
setProject()
Since
QGIS 3.0

Definition at line 691 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 621 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 969 of file qgsexpressionbuilderwidget.cpp.

◆ saveFunctionFile()

void QgsExpressionBuilderWidget::saveFunctionFile ( QString  fileName)

Saves the current function editor text to the given file.

Definition at line 355 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 595 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 616 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
enabledtrue to enable auto saving.

Definition at line 313 of file qgsexpressionbuilderwidget.h.

◆ 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
expectedThe expected value format for the expression.
Note
Only a UI hint and not used for expression validation.

Definition at line 647 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
contextexpression context
See also
expressionContext
Since
QGIS 2.12

Definition at line 653 of file qgsexpressionbuilderwidget.cpp.

◆ setExpressionPreviewVisible()

void QgsExpressionBuilderWidget::setExpressionPreviewVisible ( bool  isVisible)

Sets whether the expression preview is visible.

Since
QGIS 3.22

Definition at line 674 of file qgsexpressionbuilderwidget.cpp.

◆ setExpressionText()

void QgsExpressionBuilderWidget::setExpressionText ( const QString &  expression)

Sets the expression string for the widget.

Definition at line 637 of file qgsexpressionbuilderwidget.cpp.

◆ setGeomCalculator()

void QgsExpressionBuilderWidget::setGeomCalculator ( const QgsDistanceArea da)

Sets geometry calculator used in distance/area calculations.

Definition at line 627 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 278 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()
Since
QGIS 3.0

Definition at line 696 of file qgsexpressionbuilderwidget.cpp.

◆ showEvent()

void QgsExpressionBuilderWidget::showEvent ( QShowEvent *  e)
overrideprotected

Definition at line 702 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 930 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 382 of file qgsexpressionbuilderwidget.cpp.


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