Add API in expression to set help string on a variable

qgis · Oct 15, 2021 · 4284beb · 4284beb
1 parent 134d3bf
commit 4284beb
Show file tree

Hide file tree

Showing 4 changed files with 53 additions and 1 deletion.
diff --git a/python/core/auto_generated/expression/qgsexpression.sip.in b/python/core/auto_generated/expression/qgsexpression.sip.in
@@ -605,6 +605,23 @@ Returns a string list of search tags for a specified function.
 :param name: function name
 
 .. versionadded:: 3.12
+%End
+
+    static bool addVariableHelpText( const QString name, const QString &description );
+%Docstring
+Adds a help string for a custom variable.
+
+The specified variable ``name`` should not have an existing help string set. If a help string is already present then
+``False`` will be returned and no changes will occur.
+
+:param name: variable name
+:param description: the help string to add. This is user visible, and should be a translated string.
+
+:return: ``True`` if the help string was successfully added
+
+.. seealso:: :py:func:`variableHelpText`
+
+.. versionadded:: 3.22
 %End
 
     static QString variableHelpText( const QString &variableName );
@@ -615,6 +632,8 @@ Returns the help text for a specified variable.
 
 .. seealso:: :py:func:`helpText`
 
+.. seealso:: :py:func:`addVariableHelpText`
+
 .. versionadded:: 2.12
 %End
 

diff --git a/src/core/expression/qgsexpression.cpp b/src/core/expression/qgsexpression.cpp
@@ -900,6 +900,17 @@ void QgsExpression::initVariableHelp()
   sVariableHelpTexts()->insert( QStringLiteral( "form_mode" ), QCoreApplication::translate( "form_mode", "What the form is used for, like AddFeatureMode, SingleEditMode, MultiEditMode, SearchMode, AggregateSearchMode or IdentifyMode as string." ) );
 }
 
+
+bool QgsExpression::addVariableHelpText( const QString name, const QString &description )
+{
+  if ( sVariableHelpTexts()->contains( name ) )
+  {
+    return false;
+  }
+  sVariableHelpTexts()->insert( name, description );
+  return true;
+}
+
 QString QgsExpression::variableHelpText( const QString &variableName )
 {
   QgsExpression::initVariableHelp();

diff --git a/src/core/expression/qgsexpression.h b/src/core/expression/qgsexpression.h
@@ -603,10 +603,25 @@ class CORE_EXPORT QgsExpression
      */
     static QStringList tags( const QString &name );
 
+    /**
+     * Adds a help string for a custom variable.
+     *
+     * The specified variable \a name should not have an existing help string set. If a help string is already present then
+     * FALSE will be returned and no changes will occur.
+     *
+     * \param name variable name
+     * \param description the help string to add. This is user visible, and should be a translated string.
+     * \returns TRUE if the help string was successfully added
+     * \see variableHelpText()
+     * \since QGIS 3.22
+     */
+    static bool addVariableHelpText( const QString name, const QString &description );
+
     /**
      * Returns the help text for a specified variable.
      * \param variableName name of variable
      * \see helpText()
+     * \see addVariableHelpText()
      * \since QGIS 2.12
      */
     static QString variableHelpText( const QString &variableName );

diff --git a/tests/src/python/test_qgsexpression.py b/tests/src/python/test_qgsexpression.py
@@ -83,7 +83,8 @@ def testAutoCountsCorrectArgs(self):
         args = function.params()
         self.assertEqual(args, 3)
 
-    def testHelp(self):
+    def testHelpPythonFunction(self):
+        """Test help about python function."""
         QgsExpression.registerFunction(self.help_with_variable)
         html = ('<h3>help_with_variable function</h3><br>'
                 'The help comes from a variable.')
@@ -94,6 +95,12 @@ def testHelp(self):
                 'The help comes from the python docstring.')
         self.assertEqual(self.help_with_docstring.helpText(), html)
 
+    def testHelpString(self):
+        """Test add custom help string."""
+        self.assertTrue(QgsExpression.addVariableHelpText("custom_variable_help", "custom help 1"))
+        self.assertFalse(QgsExpression.addVariableHelpText("custom_variable_help", "other help 2"))
+        self.assertEqual(QgsExpression.variableHelpText("custom_variable_help"), "custom help 1")
+
     def testAutoArgsAreExpanded(self):
         function = self.expandargs
         args = function.params()