QgsActionManager: improve docs + add tests

nyalldawson · nyalldawson · commit bc779a06ed55 · 2016-05-29T00:45:17.000+10:00
diff --git a/python/core/qgsactionmanager.sip b/python/core/qgsactionmanager.sip
@@ -54,6 +54,11 @@ class QgsActionManager
      */
     void addAction( QgsAction::ActionType type, const QString& name, const QString& action, const QString& icon, bool capture = false );
 
+    /**
+     * Add a new action to this list.
+     */
+    void addAction( const QgsAction& action );
+
     //! Remove an action at given index
     void removeAction( int index );
 
@@ -65,6 +70,20 @@ class QgsActionManager
                    const QgsFeature &feat,
                    int defaultValueIndex = 0 ) /PyName=doActionFeature/;
 
+    /** Does the action using the expression engine to replace any embedded expressions
+     * in the action definition.
+     * @param index action index
+     * @param feature feature to run action for
+     * @param context expression context to evalute expressions under
+     * @param substitutionMap deprecated - kept for compatibilty with projects, will be removed for 3.0
+     */
+    // TODO QGIS 3.0 remove substition map - force use of expression variables
+    void doAction( int index,
+                   const QgsFeature& feature,
+                   const QgsExpressionContext& context,
+                   const QMap<QString, QVariant> *substitutionMap = nullptr );
+
+
     /** Does the action using the expression builder to expand it
      *  and getting values from the passed feature attribute map.
      *  substitutionMap is used to pass custom substitutions, to replace
@@ -86,8 +105,9 @@ class QgsActionManager
 
     /** Expands the given action, replacing all %'s with the value as
      *  given.
+     * @deprecated use QgsExpression::replaceExpressionText() instead
      */
-    QString expandAction( QString action, const QMap<int, QVariant> &attributes, uint defaultValueIndex );
+    QString expandAction( QString action, const QMap<int, QVariant> &attributes, uint defaultValueIndex ) /Deprecated/;
 
     /** Expands the given action using the expression builder
      *  This function currently replaces each expression between [% and %]
@@ -96,10 +116,11 @@ class QgsActionManager
      *
      *  Additional substitutions can be passed through the substitutionMap
      *  parameter
+     *  @deprecated use QgsExpression::replaceExpressionText() instead
      */
     QString expandAction( const QString& action,
                           QgsFeature &feat,
-                          const QMap<QString, QVariant> *substitutionMap = 0 );
+                          const QMap<QString, QVariant> *substitutionMap = 0 ) /Deprecated/;
 
 
     //! Writes the actions out in XML format
@@ -112,23 +133,50 @@ class QgsActionManager
     /**
      * Get the action at the specified index.
      */
-    QgsAction at( int idx ) const;
+    QgsAction at( int idx ) const /Factory/;
+%MethodCode
+  if ( a0 < 0 || a0 >= sipCpp->size() )
+  {
+    PyErr_SetString(PyExc_KeyError, QByteArray::number(a0));
+    sipIsErr = 1;
+  }
+  else
+  {
+    sipRes = new QgsAction( sipCpp->at( a0 ) );
+  }
+%End
+
     /**
      * Get the action at the specified index.
      */
     QgsAction operator[]( int idx ) const;
+%MethodCode
+  if ( a0 < 0 || a0 >= sipCpp->size() )
+  {
+    PyErr_SetString(PyExc_KeyError, QByteArray::number(a0));
+    sipIsErr = 1;
+  }
+  else
+  {
+    sipRes = new QgsAction( sipCpp->at( a0 ) );
+  }
+%End
 
     /** @deprecated Initialize QgsPythonRunner instead
      * @note not available in Python bindings
      */
     // Q_DECL_DEPRECATED static void setPythonExecute( void ( * )( const QString & ) );
 
     /**
-     * Get the index of the default action
+     * Returns the index of the default action, or -1 if no default action is available.
+     * @see setDefaultAction()
      */
     int defaultAction() const;
+
     /**
-     * Set the index of the default action
+     * Set the index of the default action.
+     * @param actionNumber index of action which should be made the default for the layer
+     * @see defaultAction()
      */
     void setDefaultAction( int actionNumber );
 };
diff --git a/src/core/qgsactionmanager.h b/src/core/qgsactionmanager.h
@@ -122,8 +122,9 @@ class CORE_EXPORT QgsActionManager
 
     /** Expands the given action, replacing all %'s with the value as
      *  given.
+     * @deprecated use QgsExpression::replaceExpressionText() instead
      */
-    QString expandAction( QString action, const QgsAttributeMap &attributes, uint defaultValueIndex );
+    Q_DECL_DEPRECATED QString expandAction( QString action, const QgsAttributeMap &attributes, uint defaultValueIndex );
 
     /** Expands the given action using the expression builder
      *  This function currently replaces each expression between [% and %]
@@ -132,10 +133,11 @@ class CORE_EXPORT QgsActionManager
      *
      *  Additional substitutions can be passed through the substitutionMap
      *  parameter
+     *  @deprecated use QgsExpression::replaceExpressionText() instead
      */
-    QString expandAction( const QString& action,
-                          QgsFeature &feat,
-                          const QMap<QString, QVariant> *substitutionMap = nullptr );
+    Q_DECL_DEPRECATED QString expandAction( const QString& action,
+                                            QgsFeature &feat,
+                                            const QMap<QString, QVariant> *substitutionMap = nullptr );
 
 
     //! Writes the actions out in XML format
@@ -165,11 +167,15 @@ class CORE_EXPORT QgsActionManager
     Q_DECL_DEPRECATED static void setPythonExecute( void ( * )( const QString & ) );
 
     /**
-     * Get the index of the default action
+     * Returns the index of the default action, or -1 if no default action is available.
+     * @see setDefaultAction()
      */
     int defaultAction() const { return mDefaultAction < 0 || mDefaultAction >= size() ? -1 : mDefaultAction; }
+
     /**
-     * Set the index of the default action
+     * Set the index of the default action.
+     * @param actionNumber index of action which should be made the default for the layer
+     * @see defaultAction()
      */
     void setDefaultAction( int actionNumber ) { mDefaultAction = actionNumber ; }
 
diff --git a/src/core/qgsattributeaction.h b/src/core/qgsattributeaction.h
@@ -1,13 +1,13 @@
 /***************************************************************************
-                          qgsactionmanager.h
+                        qgsactionmanager.h
 
- This is a legacy header to keep backwards compatibility until QGIS 3.
+This is a legacy header to keep backwards compatibility until QGIS 3.
 
-                             -------------------
-    begin                : Oct 24 2004
-    copyright            : (C) 2004 by Gavin Macaulay
-    email                : gavin at macaulay dot co dot nz
- ***************************************************************************/
+                           -------------------
+  begin                : Oct 24 2004
+  copyright            : (C) 2004 by Gavin Macaulay
+  email                : gavin at macaulay dot co dot nz
+***************************************************************************/
 
 /***************************************************************************
  *                                                                         *
diff --git a/tests/src/python/CMakeLists.txt b/tests/src/python/CMakeLists.txt
@@ -7,6 +7,7 @@ IF (WITH_SERVER)
   ADD_PYTHON_TEST(PyQgsLocalServer test_qgis_local_server.py)
 ENDIF (WITH_SERVER)
 
+ADD_PYTHON_TEST(PyQgsActionManager test_qgsactionmanager.py)
 ADD_PYTHON_TEST(PyQgsAggregateCalculator test_qgsaggregatecalculator.py)
 ADD_PYTHON_TEST(PyQgsAnalysis test_qgsanalysis.py)
 ADD_PYTHON_TEST(PyQgsApplication test_qgsapplication.py)
diff --git a/tests/src/python/test_qgsactionmanager.py b/tests/src/python/test_qgsactionmanager.py
