Merge pull request #56 from NathanW2/function_help

Handle function help the same way as context help; Allows easier management of function help texts

Author: wonder-sk

resources/CMakeLists.txt

@@ -2,3 +2,4 @@ INSTALL(FILES srs.db qgis.db qgis_help.db symbology-ng-style.xml spatialite.db c
         DESTINATION ${QGIS_DATA_DIR}/resources)
 
 ADD_SUBDIRECTORY(context_help)
+ADD_SUBDIRECTORY(function_help)

resources/function_help/CMakeLists.txt

@@ -0,0 +1,4 @@
+FILE(GLOB HELP_FILES *-*) 
+
+INSTALL(FILES ${HELP_FILES} DESTINATION ${QGIS_DATA_DIR}/resources/function_help)
+

resources/function_help/length-en_US

@@ -0,0 +1,13 @@
+<h3>length() function</h3>
+Returns the length of a string.
+
+<p><h4>Syntax</h4>
+     length(<i>string</i>)</p>
+
+<p><h4>Arguments</h4>
+<!-- List args for functions here-->
+<i>  string</i> -> is string.  The String to count the length of.</p>
+
+<p><h4>Example</h4>
+<!-- Show example of function.-->
+     length('HELLO') -> 5</p>

resources/function_help/lower-en_US

@@ -0,0 +1,11 @@
+<h3>lower() function</h3>
+Converts a string to lower case letters.
+
+<p><h4>  Syntax</h4>
+     lower(<i>string</i>)</p>
+
+<p><h4>  Arguments</h4>
+<i>  string</i> -> is string.  The String to convert to lower case.</p>
+
+<p><h4>  Example</h4>
+     lower('HELLO World') -> 'hello world'</p>

resources/function_help/replace-en_US

@@ -0,0 +1,15 @@
+<h3>replace() function</h3>
+Returns a string with the the supplied string replaced.
+
+<p><h4>Syntax</h4>
+     replace(<i>string,before,after</i>)</p>
+
+<p><h4>Arguments</h4>
+<!-- List args for functions here-->
+<i>  string</i> -> is string.  The start string.<br>
+<i>  before</i> -> is string.  The string to replace.<br>
+<i>  after</i> -> is string.  The string that will repalce <i>before</i><br></p>
+
+<p><h4>Example</h4>
+<!-- Show example of function.-->
+     replace('QGIS SHOULD ROCK','SHOULD','DOES') -> 'QGIS DOES ROCK'</p>

resources/function_help/substr-en_US

@@ -0,0 +1,15 @@
+<h3>substr() function</h3>
+Return a part of a string
+
+<p><h4>Syntax</h4>
+     substr(<i>string,startpos,length</i>)</p>
+
+<p><h4>Arguments</h4>
+<!-- List args for functions here-->
+<i>  string</i> -> is string.  The full string.<br>
+<i>  startpos</i> -> is number.  The start position to extract from.<br>
+<i>  length</i> -> is number.  The length of the string to extract.<br></p>
+
+<p><h4>Example</h4>
+<!-- Show example of function.-->
+     substr('HELLO WORLD',3,5) -> 'LLO W'</p>

resources/function_help/template

@@ -0,0 +1,13 @@
+<h3>{function} function</h3>
+Converts a string to lower case letters.
+
+<p><h4>Syntax</h4>
+     lower(<i>args</i>)</p>
+
+<p><h4>Arguments</h4>
+<!-- List args for functions here-->
+<i>  string</i> -> is string.  The String to convert to lower case.</p>
+
+<p><h4>Example</h4>
+<!-- Show example of function.-->
+     lower('HELLO World') -> 'hello world'</p>

resources/function_help/upper-en_US

@@ -0,0 +1,13 @@
+<h3>upper() function</h3>
+Converts a string to upper case letters.
+
+<p><h4>Syntax</h4>
+     upper(<i>string</i>)</p>
+
+<p><h4>Arguments</h4>
+<!-- List args for functions here-->
+<i>  string</i> -> is string.  The String to convert to upper case.</p>
+
+<p><h4>Example</h4>
+<!-- Show example of function.-->
+     upper('hello WOrld') -> 'HELLO WORLD'</p>

src/core/qgsexpression.cpp

@@ -392,16 +392,10 @@ FnDef QgsExpression::BuiltinFunctions[] =
   FnDef( "toreal", 1, fcnToReal, "Conversions" ),
   FnDef( "tostring", 1, fcnToString, "Conversions" ),
   // string manipulation
-  FnDef( "lower", 1, fcnLower, "String", "<b>Convert to lower case</b> "
-  "<br> Converts a string to lower case letters. "
-  "<br> <i>Usage:</i><br>lower('HELLO WORLD') will return 'hello world'" ),
-  FnDef( "upper", 1, fcnUpper, "String" , "<b>Convert to upper case</b> "
-  "<br> Converts a string to upper case letters. "
-  "<br> <i>Usage:</i><br>upper('hello world') will return 'HELLO WORLD'" ),
-  FnDef( "length", 1, fcnLength, "String", "<b>Length of string</b> "
-  "<br> Returns the legnth of a string. "
-  "<br> <i>Usage:</i><br>length('hello') will return 5" ),
-  FnDef( "replace", 3, fcnReplace, "String", "<b>Replace a section of a string.</b> " ),
+  FnDef( "lower", 1, fcnLower, "String"),
+  FnDef( "upper", 1, fcnUpper, "String"),
+  FnDef( "length", 1, fcnLength, "String"),
+  FnDef( "replace", 3, fcnReplace, "String"),
   FnDef( "regexp_replace", 3, fcnRegexpReplace, "String" ),
   FnDef( "substr", 3, fcnSubstr, "String" ),
   // geometry accessors

src/gui/qgsexpressionbuilderwidget.cpp

@@ -17,8 +17,12 @@
 #include "qgslogger.h"
 #include "qgsexpression.h"
 #include "qgsmessageviewer.h"
+#include "qgsapplication.h"
 
+#include <QSettings>
 #include <QMenu>
+#include <QFile>
+#include <QTextStream>
 
 QgsExpressionBuilderWidget::QgsExpressionBuilderWidget( QWidget *parent )
     : QWidget( parent )
@@ -79,7 +83,7 @@ QgsExpressionBuilderWidget::QgsExpressionBuilderWidget( QWidget *parent )
     QString name = func.mName;
     if ( func.mParams >= 1 )
       name += "(";
-    registerItem( func.mGroup, func.mName, " " + name + " ", func.mHelpText );
+    registerItem( func.mGroup, func.mName, " " + name + " ");
   };
 }
 
@@ -106,18 +110,19 @@ void QgsExpressionBuilderWidget::on_expressionTree_clicked( const QModelIndex &i
   // right click so we just show the help.
   if ( item->getItemType() == QgsExpressionItem::Field )
   {
-    txtHelpText->setText( tr( "Double click to add field name to expression string. <br> "
+    txtHelpText->setHtml( tr( "Double click to add field name to expression string. <br> "
                               "Or right click to select loading value options then "
                               "double click an item in the value list to add it to the expression string." ) );
-    txtHelpText->setToolTip( txtHelpText->text() );
+    txtHelpText->setToolTip( txtHelpText->toPlainText() );
   }
   else
   {
     // Show the help for the current item.
     mValueGroupBox->hide();
     mValueListWidget->clear();
-    txtHelpText->setText( item->getHelpText() );
-    txtHelpText->setToolTip( txtHelpText->text() );
+    QString help = loadFunctionHelp( item );
+    txtHelpText->setText( help );
+    txtHelpText->setToolTip( txtHelpText->toPlainText() );
   }
 }
 
@@ -347,3 +352,74 @@ void QgsExpressionBuilderWidget::loadAllValues()
   fillFieldValues( fieldIndex, -1 );
 }
 
+QString QgsExpressionBuilderWidget::loadFunctionHelp( QgsExpressionItem* functionName )
+{
+  if ( functionName != NULL )
+  {
+    // set up the path to the help file
+    QString helpFilesPath = QgsApplication::pkgDataPath() + "/resources/function_help/";
+    /*
+     * determine the locale and create the file name from
+     * the context id
+     */
+    QString lang = QLocale::system().name();
+
+    QSettings settings;
+    if ( settings.value( "locale/overrideFlag", false ).toBool() )
+    {
+      QLocale l( settings.value( "locale/userLocale", "en_US" ).toString() );
+      lang = l.name();
+    }
+    /*
+     * If the language isn't set on the system, assume en_US,
+     * otherwise we get the banner at the top of the help file
+     * saying it isn't available in "your" language. Some systems
+     * may be installed without the LANG environment being set.
+     */
+    if ( lang.length() == 0 || lang == "C" )
+    {
+      lang = "en_US";
+    }
+    QString fullHelpPath = helpFilesPath + functionName->text() + "-" + lang;
+    // get the help content and title from the localized file
+    QString helpContents;
+    QFile file( fullHelpPath );
+    // check to see if the localized version exists
+    if ( !file.exists() )
+    {
+      // change the file name to the en_US version (default)
+      fullHelpPath = helpFilesPath + functionName->text() + "-en_US";
+      file.setFileName( fullHelpPath );
+
+      // Check for some sort of english locale and if not found, include
+      // translate this for us message
+      if ( !lang.contains( "en_" ) )
+      {
+          helpContents = "<i>" + tr( "This help file is not available in your language %1. If you would like to translate it, please contact the QGIS  development team." ).arg( lang ) + "</i><hr />";
+      }
+
+    }
+    if ( !file.open( QIODevice::ReadOnly | QIODevice::Text ) )
+    {
+        helpContents = tr( "This help file does not exist for your language:<p><b>%1</b><p>If you would like to create it, contact the QGIS development team" )
+                     .arg( fullHelpPath );
+    }
+    else
+    {
+      QTextStream in( &file );
+      in.setCodec( "UTF-8" ); // Help files must be in Utf-8
+      while ( !in.atEnd() )
+      {
+        QString line = in.readLine();
+        helpContents += line;
+      }
+    }
+    file.close();
+
+    // Set the browser text to the help contents
+    QString myStyle = QgsApplication::reportStyleSheet();
+    helpContents = "<head><style>" + myStyle + "</style></head><body>" + helpContents + "</body>";
+    return helpContents;
+  }
+  return "";
+}