Merge pull request #6982 from elpaso/currentformfeature-expressions-4

[feature][need-docs] Current feature/current value form context expressions
qgis · May 16, 2018 · a44eeae · a44eeae
2 parents c27ce39 + b2fb029
commit a44eeae
Show file tree

Hide file tree

Showing 33 changed files with 1,064 additions and 90 deletions.
diff --git a/python/core/auto_generated/expression/qgsexpression.sip.in b/python/core/auto_generated/expression/qgsexpression.sip.in
@@ -178,6 +178,14 @@ which is determined at runtime.
 .. versionadded:: 3.0
 %End
 
+    QSet<QString> referencedFunctions() const;
+%Docstring
+Return a list of the names of all functions which are used in this expression.
+
+.. versionadded:: 3.2
+%End
+
+
     QSet<int> referencedAttributeIndexes( const QgsFields &fields ) const;
 %Docstring
 Return a list of field name indexes obtained from the provided fields.

diff --git a/python/core/auto_generated/expression/qgsexpressionnode.sip.in b/python/core/auto_generated/expression/qgsexpressionnode.sip.in
@@ -196,6 +196,11 @@ to evaluate child nodes.
     virtual QSet<QString> referencedVariables() const = 0;
 %Docstring
 Return a set of all variables which are used in this expression.
+%End
+
+    virtual QSet<QString> referencedFunctions() const = 0;
+%Docstring
+Return a set of all functions which are used in this expression.
 %End
 
     virtual bool needsGeometry() const = 0;

diff --git a/python/core/auto_generated/expression/qgsexpressionnodeimpl.sip.in b/python/core/auto_generated/expression/qgsexpressionnodeimpl.sip.in
@@ -55,7 +55,7 @@ Returns the node the operator will operate upon.
 
     virtual QSet<QString> referencedVariables() const;
 
-    virtual bool needsGeometry() const;
+    virtual QSet<QString> referencedFunctions() const;
 
     virtual QgsExpressionNode *clone() const /Factory/;
 
@@ -154,6 +154,8 @@ Returns the node to the right of the operator.
 
     virtual QSet<QString> referencedVariables() const;
 
+    virtual QSet<QString> referencedFunctions() const;
+
     virtual bool needsGeometry() const;
 
     virtual QgsExpressionNode *clone() const /Factory/;
@@ -224,7 +226,7 @@ Returns the list of nodes to search for matching values within.
 
     virtual QSet<QString> referencedVariables() const;
 
-    virtual bool needsGeometry() const;
+    virtual QSet<QString> referencedFunctions() const;
 
     virtual QgsExpressionNode *clone() const /Factory/;
 
@@ -275,7 +277,8 @@ Returns a list of arguments specified for the function.
 
     virtual QSet<QString> referencedVariables() const;
 
-    virtual bool needsGeometry() const;
+    virtual QSet<QString> referencedFunctions() const;
+
 
     virtual QgsExpressionNode *clone() const /Factory/;
 
@@ -323,7 +326,8 @@ The value of the literal.
 
     virtual QSet<QString> referencedVariables() const;
 
-    virtual bool needsGeometry() const;
+    virtual QSet<QString> referencedFunctions() const;
+
 
     virtual QgsExpressionNode *clone() const /Factory/;
 
@@ -367,6 +371,8 @@ The name of the column.
 
     virtual QSet<QString> referencedVariables() const;
 
+    virtual QSet<QString> referencedFunctions() const;
+
     virtual bool needsGeometry() const;
 
 
@@ -466,6 +472,9 @@ The ELSE expression used for the condition.
 
     virtual QSet<QString> referencedVariables() const;
 
+    virtual QSet<QString> referencedFunctions() const;
+
+
     virtual bool needsGeometry() const;
 
     virtual QgsExpressionNode *clone() const /Factory/;

diff --git a/python/core/auto_generated/fieldformatter/qgsvaluerelationfieldformatter.sip.in b/python/core/auto_generated/fieldformatter/qgsvaluerelationfieldformatter.sip.in
@@ -8,6 +8,7 @@
 
 
 
+
 class QgsValueRelationFieldFormatter : QgsFieldFormatter
 {
 %Docstring
@@ -56,25 +57,70 @@ Constructor for QgsValueRelationFieldFormatter.
     virtual QVariant createCache( QgsVectorLayer *layer, int fieldIndex, const QVariantMap &config ) const;
 
 
-    static QgsValueRelationFieldFormatter::ValueRelationCache createCache( const QVariantMap &config );
+    static QStringList valueToStringList( const QVariant &value );
+%Docstring
+Utility to convert an array or a string representation of an array ``value`` to a string list
+
+.. versionadded:: 3.2
+%End
+
+    static QgsValueRelationFieldFormatter::ValueRelationCache createCache( const QVariantMap &config, const QgsFeature &formFeature = QgsFeature() );
 %Docstring
 Create a cache for a value relation field.
 This can be used to keep the value map in the local memory
 if doing multiple lookups in a loop.
 
+:param config: The widget configuration
+:param formFeature: The feature currently being edited with current attribute values
+
+:return: A kvp list of values for the widget
+
 .. versionadded:: 3.0
 %End
 
-    static QStringList valueToStringList( const QVariant &value );
+    static bool expressionRequiresFormScope( const QString &expression );
 %Docstring
-Utility to convert an array or a string representation of and array ``value`` to a string list
+Check if the ``expression`` requires a form scope (i.e. if it uses fields
+or geometry of the currently edited feature).
 
-:param value: The value to be converted
+:param expression: The widget's filter expression
 
-:return: A string list
+:return: true if the expression requires a form scope
 
 .. versionadded:: 3.2
 %End
+
+    static QSet<QString> expressionFormAttributes( const QString &expression );
+%Docstring
+Return a list of attributes required by the form context ``expression``
+
+:param expression: Form filter expression
+
+:return: list of attributes required by the expression
+
+.. versionadded:: 3.2
+%End
+
+    static QSet<QString> expressionFormVariables( const QString &expression );
+%Docstring
+Return a list of variables required by the form context ``expression``
+
+:param expression: Form filter expression
+
+:return: list of variables required by the expression
+
+.. versionadded:: 3.2
+%End
+
+    static bool expressionIsUsable( const QString &expression, const QgsFeature &feature );
+%Docstring
+Check whether the ``feature`` has all values required by the ``expression``
+
+:return: True if the expression can be used
+
+.. versionadded:: 3.2
+%End
+
 };
 
 

diff --git a/python/core/auto_generated/qgsexpressioncontext.sip.in b/python/core/auto_generated/qgsexpressioncontext.sip.in
@@ -763,6 +763,14 @@ Creates a new scope which contains variables and functions relating to the globa
 For instance, QGIS version numbers and variables specified through QGIS options.
 
 .. seealso:: :py:func:`setGlobalVariable`
+%End
+
+    static QgsExpressionContextScope *formScope( const QgsFeature &formFeature = QgsFeature( ) ) /Factory/;
+%Docstring
+Creates a new scope which contains functions and variables from the current attribute form/table feature.
+The variables and values in this scope will reflect the current state of the form/row being edited.
+
+.. versionadded:: 3.2
 %End
 
     static void setGlobalVariable( const QString &name, const QVariant &value );

diff --git a/python/gui/auto_generated/editorwidgets/core/qgseditorwidgetwrapper.sip.in b/python/gui/auto_generated/editorwidgets/core/qgseditorwidgetwrapper.sip.in
@@ -213,6 +213,7 @@ This will be disabled when the form is not editable.
 .. versionadded:: 3.0
 %End
 
+
   signals:
 
     void valueChanged( const QVariant &value );
@@ -279,6 +280,34 @@ change the visual cue.
 .. versionadded:: 2.16
 %End
 
+
+    QgsFeature formFeature() const;
+%Docstring
+The feature currently being edited, in its current state
+
+:return: the feature currently being edited, in its current state
+
+.. versionadded:: 3.2
+%End
+
+    void setFormFeature( const QgsFeature &feature );
+%Docstring
+Set the feature currently being edited to ``feature``
+
+.. versionadded:: 3.2
+%End
+
+    bool setFormFeatureAttribute( const QString &attributeName, const QVariant &attributeValue );
+%Docstring
+Update the feature currently being edited by changing its
+attribute ``attributeName`` to ``attributeValue``
+
+:return: bool true on success
+
+.. versionadded:: 3.2
+%End
+
+
 };
 
 

diff --git a/python/gui/auto_generated/qgsattributeeditorcontext.sip.in b/python/gui/auto_generated/qgsattributeeditorcontext.sip.in
@@ -180,6 +180,25 @@ QGIS forms
 
     const QgsAttributeEditorContext *parentContext() const;
 
+    QgsFeature formFeature() const;
+%Docstring
+Return current feature from the currently edited form or table row
+
+.. seealso:: :py:func:`setFormFeature`
+
+.. versionadded:: 3.2
+%End
+
+    void setFormFeature( const QgsFeature &feature );
+%Docstring
+Set current ``feature`` for the currently edited form or table row
+
+.. seealso:: :py:func:`formFeature`
+
+.. versionadded:: 3.2
+%End
+
+
 };
 
 /************************************************************************

diff --git a/python/gui/auto_generated/qgsattributeform.sip.in b/python/gui/auto_generated/qgsattributeform.sip.in
@@ -141,7 +141,8 @@ on all attribute widgets.
 
  void attributeChanged( const QString &attribute, const QVariant &value ) /Deprecated/;
 %Docstring
-Notifies about changes of attributes
+Notifies about changes of attributes, this signal is not emitted when the value is set
+back to the original one.
 
 :param attribute: The name of the attribute that changed.
 :param value:     The new value of the attribute.

diff --git a/resources/function_help/json/current_value b/resources/function_help/json/current_value
@@ -0,0 +1,7 @@
+{
+  "name": "current_value",
+  "type": "function",
+  "description": "Returns the current, unsaved value of a field in the form or table row currently being edited. This will differ from the feature's actual attribute values for features which are currently being edited or have not yet been added to a layer.",
+  "arguments": [ {"arg":"field_name","description":"a field name in the current form or table row"}],
+  "examples": [ { "expression":"current_value( 'FIELD_NAME' )","returns":"The current value of field 'FIELD_NAME'."} ]
+}
diff --git a/src/core/expression/qgsexpression.cpp b/src/core/expression/qgsexpression.cpp
@@ -276,6 +276,14 @@ QSet<QString> QgsExpression::referencedVariables() const
   return d->mRootNode->referencedVariables();
 }
 
+QSet<QString> QgsExpression::referencedFunctions() const
+{
+  if ( !d->mRootNode )
+    return QSet<QString>();
+
+  return d->mRootNode->referencedFunctions();
+}
+
 QSet<int> QgsExpression::referencedAttributeIndexes( const QgsFields &fields ) const
 {
   if ( !d->mRootNode )
@@ -771,6 +779,10 @@ void QgsExpression::initVariableHelp()
 
   //provider notification
   sVariableHelpTexts.insert( QStringLiteral( "notification_message" ), QCoreApplication::translate( "notification_message", "Content of the notification message sent by the provider (available only for actions triggered by provider notifications)." ) );
+
+  //form context variable
+  sVariableHelpTexts.insert( QStringLiteral( "current_geometry" ), QCoreApplication::translate( "current_geometry", "Represents the geometry of the feature currently being edited in the form or the table row. Can be used for in a form/row context to filter the related features." ) );
+  sVariableHelpTexts.insert( QStringLiteral( "current_feature" ), QCoreApplication::translate( "current_feature", "Represents the feature currently being edited in the form or the table row. Can be used for in a form/row context to filter the related features." ) );
 }
 
 QString QgsExpression::variableHelpText( const QString &variableName )
@@ -945,3 +957,14 @@ bool QgsExpression::isField() const
 {
   return d->mRootNode && d->mRootNode->nodeType() == QgsExpressionNode::ntColumnRef;
 }
+
+QList<const QgsExpressionNode *> QgsExpression::nodes() const
+{
+  if ( !d->mRootNode )
+    return QList<const QgsExpressionNode *>();
+
+  return d->mRootNode->nodes();
+}
+
+
+
diff --git a/src/core/expression/qgsexpression.h b/src/core/expression/qgsexpression.h
@@ -29,6 +29,7 @@
 #include "qgis.h"
 #include "qgsunittypes.h"
 #include "qgsinterval.h"
+#include "qgsexpressionnode.h"
 
 class QgsFeature;
 class QgsGeometry;
@@ -41,7 +42,6 @@ class QgsDistanceArea;
 class QDomElement;
 class QgsExpressionContext;
 class QgsExpressionPrivate;
-class QgsExpressionNode;
 class QgsExpressionFunction;
 
 /**
@@ -258,6 +258,44 @@ class CORE_EXPORT QgsExpression
      */
     QSet<QString> referencedVariables() const;
 
+    /**
+     * Return a list of the names of all functions which are used in this expression.
+     *
+     * \since QGIS 3.2
+     */
+    QSet<QString> referencedFunctions() const;
+
+#ifndef SIP_RUN
+
+    /**
+     * Return a list of all nodes which are used in this expression
+     *
+     * \note not available in Python bindings
+     * \since QGIS 3.2
+     */
+    QList<const QgsExpressionNode *> nodes( ) const;
+
+    /**
+     * Return a list of all nodes of the given class which are used in this expression
+     *
+     * \note not available in Python bindings
+     * \since QGIS 3.2
+     */
+    template <class T>
+    QList<const T *> findNodes( ) const
+    {
+      QList<const T *> lst;
+      const QList<const QgsExpressionNode *> allNodes( nodes() );
+      for ( const auto &node : allNodes )
+      {
+        const T *n = dynamic_cast<const T *>( node );
+        if ( n )
+          lst << n;
+      }
+      return lst;
+    }
+#endif
+
     /**
      * Return a list of field name indexes obtained from the provided fields.
      *

diff --git a/src/core/expression/qgsexpressionnode.cpp b/src/core/expression/qgsexpressionnode.cpp
@@ -57,3 +57,4 @@ void QgsExpressionNode::cloneTo( QgsExpressionNode *target ) const
   target->parserFirstColumn = parserFirstColumn;
   target->parserFirstLine = parserFirstLine;
 }
+