[processing] Allow algorithms to return a translated short description

This is used in the algorithm's tooltip in the toolbox, and is intended for single sentence description of the algorithm, e.g. "Converts 2D features to 3D by sampling a DEM raster." Convert grass algorithms to use short description for the descriptive parts of their names, to cleanup the toolbox and make it more uniform.
qgis · May 16, 2018 · 5edcc64 · 5edcc64
1 parent 698fad6
commit 5edcc64
Show file tree

Hide file tree

Showing 6 changed files with 45 additions and 10 deletions.
diff --git a/python/core/auto_generated/processing/qgsprocessingalgorithm.sip.in b/python/core/auto_generated/processing/qgsprocessingalgorithm.sip.in
@@ -106,7 +106,20 @@ provider's ID and the algorithms unique name (e.g. "qgis:mergelayers" ).
 Returns the translated algorithm name, which should be used for any user-visible display
 of the algorithm name.
 
+Algorithm display names should be short, e.g. ideally no more than 3 or 4 words.
+The name should use sentence case (e.g. "Raster layer statistics", not "Raster Layer Statistics").
+
 .. seealso:: :py:func:`name`
+
+.. seealso:: :py:func:`shortDescription`
+%End
+
+    virtual QString shortDescription() const;
+%Docstring
+Returns an optional translated short description of the algorithm. This should be
+at most a single sentence, e.g. "Converts 2D features to 3D by sampling a DEM raster."
+
+.. versionadded:: 3.2
 %End
 
     virtual QStringList tags() const;

diff --git a/python/plugins/processing/algs/grass7/Grass7Algorithm.py b/python/plugins/processing/algs/grass7/Grass7Algorithm.py
@@ -102,6 +102,7 @@ def __init__(self, descriptionfile):
         super().__init__()
         self._name = ''
         self._display_name = ''
+        self._short_description = ''
         self._group = ''
         self._groupId = ''
         self.groupIdRegex = re.compile('^[^\s\(]+')
@@ -142,6 +143,9 @@ def name(self):
     def displayName(self):
         return self._display_name
 
+    def shortDescription(self):
+        return self._short_description
+
     def group(self):
         return self._group
 
@@ -191,13 +195,12 @@ def defineCharacteristicsFromFile(self):
             self.grass7Name = line
             # Second line if the algorithm name in Processing
             line = lines.readline().strip('\n').strip()
-            self._name = line
-            self._display_name = QCoreApplication.translate("GrassAlgorithm", line)
-            if " - " not in self._name:
-                self._name = self.grass7Name + " - " + self._name
-                self._display_name = self.grass7Name + " - " + self._display_name
-
-            self._name = self._name[:self._name.find(' ')].lower()
+            self._short_description = line
+            if " - " not in line:
+                self._name = self.grass7Name
+            else:
+                self._name = line[:line.find(' ')].lower()
+            self._display_name = self._name
             # Read the grass group
             line = lines.readline().strip('\n').strip()
             self._group = QCoreApplication.translate("GrassAlgorithm", line)

diff --git a/python/plugins/processing/gui/ProcessingToolbox.py b/python/plugins/processing/gui/ProcessingToolbox.py
@@ -508,8 +508,9 @@ def __init__(self, alg):
         self.setData(0, ProcessingToolbox.TYPE_ROLE, ProcessingToolbox.ALG_ITEM)
 
     def formatAlgorithmTooltip(self, alg):
-        return '<p><b>{}</b></p><p>{}</p>'.format(
+        return '<p><b>{}</b></p>{}<p>{}</p>'.format(
             alg.displayName(),
+            '<p>{}</p>'.format(alg.shortDescription()) if alg.shortDescription() else '',
             QCoreApplication.translate('Toolbox', 'Algorithm ID: ‘{}’').format('<i>{}</i>'.format(alg.id()))
         )
 

diff --git a/python/plugins/processing/modeler/ModelerDialog.py b/python/plugins/processing/modeler/ModelerDialog.py
@@ -779,9 +779,10 @@ def __init__(self, alg):
         self.setData(0, ModelerDialog.TYPE_ROLE, ModelerDialog.ALG_ITEM)
 
     def formatAlgorithmTooltip(self, alg):
-        return '<p><b>{}</b></p><p>{}</p>'.format(
+        return '<p><b>{}</b></p>{}<p>{}</p>'.format(
             alg.displayName(),
-            QCoreApplication.translate('TreeAlgorithmItem', 'Algorithm ID: ‘{}’').format('<i>{}</i>'.format(alg.id()))
+            '<p>{}</p>'.format(alg.shortDescription()) if alg.shortDescription() else '',
+            QCoreApplication.translate('Toolbox', 'Algorithm ID: ‘{}’').format('<i>{}</i>'.format(alg.id()))
         )
 
 

diff --git a/src/core/processing/qgsprocessingalgorithm.cpp b/src/core/processing/qgsprocessingalgorithm.cpp
@@ -49,6 +49,11 @@ QString QgsProcessingAlgorithm::id() const
     return name();
 }
 
+QString QgsProcessingAlgorithm::shortDescription() const
+{
+  return QString();
+}
+
 QString QgsProcessingAlgorithm::shortHelpString() const
 {
   return QString();

diff --git a/src/core/processing/qgsprocessingalgorithm.h b/src/core/processing/qgsprocessingalgorithm.h
@@ -146,10 +146,22 @@ class CORE_EXPORT QgsProcessingAlgorithm
     /**
      * Returns the translated algorithm name, which should be used for any user-visible display
      * of the algorithm name.
+     *
+     * Algorithm display names should be short, e.g. ideally no more than 3 or 4 words.
+     * The name should use sentence case (e.g. "Raster layer statistics", not "Raster Layer Statistics").
+     *
      * \see name()
+     * \see shortDescription()
      */
     virtual QString displayName() const = 0;
 
+    /**
+     * Returns an optional translated short description of the algorithm. This should be
+     * at most a single sentence, e.g. "Converts 2D features to 3D by sampling a DEM raster."
+     * \since QGIS 3.2
+     */
+    virtual QString shortDescription() const;
+
     /**
      * Returns a list of tags which relate to the algorithm, and are used to assist users in searching
      * for suitable algorithms. These tags should be localised.