Merge pull request #3911 from alexbruy/generic-help

Generic help for QGIS
qgis · Jan 10, 2017 · 48bcca60339da59324d40d1235234555781b08f2 · 48bcca6
2 parents 3145a01 + bcb69c5
commit 48bcca60339da59324d40d1235234555781b08f2
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
@@ -22,7 +22,7 @@ ELSE(TXT2TAGS_EXECUTABLE)
   )
 ENDIF(TXT2TAGS_EXECUTABLE)
 
-SET(QGIS_DOC_FILES ${QGIS_DOC_FILES} index.html news.html developersmap.html contributors.json favicon.ico style.css release-sponsors.html AUTHORS CONTRIBUTORS SPONSORS DONORS TRANSLATORS LICENSE)
+SET(QGIS_DOC_FILES ${QGIS_DOC_FILES} index.html news.html developersmap.html nohelp.html contributors.json favicon.ico style.css release-sponsors.html AUTHORS CONTRIBUTORS SPONSORS DONORS TRANSLATORS LICENSE)
 
 INSTALL(FILES ${QGIS_DOC_FILES} DESTINATION ${QGIS_DATA_DIR}/doc)
 INSTALL(FILES ../images/icons/qgis-icon-60x60.png DESTINATION ${QGIS_DATA_DIR}/doc/images)

diff --git a/doc/nohelp.html b/doc/nohelp.html
@@ -0,0 +1,20 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>No help found</title>
+  <meta charset="UTF-8">
+</head>
+<body>
+<center><a href="http://qgis.org"><img src="qgis-icon-60x60.png" border=0></a></center>
+<h1><center>Oops!</center></h1>
+<p>QGIS help is currently not available. This is likely because:</p>
+<ul>
+  <li>No internet connection is available</li>
+  <li>The offline help files are not available or the location of these
+  files is not properly configured</li>
+  <li>No help content is available for the requested topic</li>
+</ul>
+<p>Please check that the correct location of the offline help files is
+specified in the QGIS options dialog (Settings&nbsp;&rarr; Options&nbsp;&rarr;System).</p>
+</body>
+</html>
diff --git a/python/core/qgsapplication.sip b/python/core/qgsapplication.sip
@@ -254,6 +254,11 @@ static void qtgui_UpdatePyArgv(PyObject *argvlist, int argc, char **argv)
      */
     static QString platform();
 
+    /** Returns the QGIS locale.
+     * @note added in QGIS 3.0
+     */
+    static QString locale();
+
     //! Returns the path to user's themes folder
     static QString userThemesFolder();
 

diff --git a/python/gui/gui.sip b/python/gui/gui.sip
@@ -88,6 +88,7 @@
 %Include qgsgradientcolorrampdialog.sip
 %Include qgsgradientstopeditor.sip
 %Include qgsgroupwmsdatadialog.sip
+%Include qgshelp.sip
 %Include qgshighlight.sip
 %Include qgshistogramwidget.sip
 %Include qgshtmlannotationitem.sip

diff --git a/python/gui/qgshelp.sip b/python/gui/qgshelp.sip
@@ -0,0 +1,40 @@
+/** \ingroup gui
+ * \class QgsHelp
+ * @brief Helper class for showing help topic URI for the given key.
+ *
+ * Help can be stored online, on the local directory or on the intranet
+ * server. Location of the QGIS help can be configured in QGIS options.
+ * Multiple locations are supported, they will be used in order of
+ * preference, from top to bottom.
+ *
+ * URI construction takes in account following information:
+ *  - QGIS version
+ *  - language of the QGIS UI
+ *
+ * If no help found, default error page with information how to setup
+ * help system will be shown.
+ *
+ * @note added in QGIS 3.0
+ */
+class QgsHelp
+{
+%TypeHeaderCode
+#include <qgshelp.h>
+%End
+
+  public:
+
+    /** Opens help topic for the given help key using default system
+     * web browser. If help topic not found, builtin error page shown.
+     * @param key key which identified help topic
+     * @note added in QGIS 3.0
+     */
+    static void openHelp( const QString& key );
+
+    /** Returns URI of the help topic for the given key. If help topic
+     * not found, URI of the builtin error page returned.
+     * @param key key which identified help topic
+     * @note added in QGIS 3.0
+     */
+    static QUrl helpUrl( const QString& key );
+};
diff --git a/src/app/qgsoptions.cpp b/src/app/qgsoptions.cpp
@@ -265,6 +265,16 @@ QgsOptions::QgsOptions( QWidget *parent, Qt::WindowFlags fl )
     mListHiddenBrowserPaths->addItem( newItem );
   }
 
+  //locations of the QGIS help
+  QStringList helpPathList = mSettings->value( QStringLiteral( "help/helpSearchPath" ) ).toStringList();
+  Q_FOREACH ( const QString& path, helpPathList )
+  {
+    QTreeWidgetItem* item = new QTreeWidgetItem();
+    item->setText( 0, path );
+    item->setFlags( Qt::ItemIsEnabled | Qt::ItemIsSelectable | Qt::ItemIsEditable );
+    mHelpPathTreeWidget->addTopLevelItem( item );
+  }
+
   //Network timeout
   mNetworkTimeoutSpinBox->setValue( mSettings->value( QStringLiteral( "/qgis/networkAndProxy/networkTimeout" ), "60000" ).toInt() );
   leUserAgent->setText( mSettings->value( QStringLiteral( "/qgis/networkAndProxy/userAgent" ), "Mozilla/5.0" ).toString() );
@@ -1096,6 +1106,17 @@ void QgsOptions::saveOptions()
   }
   mSettings->setValue( QStringLiteral( "/browser/hiddenPaths" ), pathsList );
 
+  //QGIS help locations
+  QStringList helpPaths;
+  for ( int i = 0; i < mHelpPathTreeWidget->topLevelItemCount(); ++i )
+  {
+    if ( QTreeWidgetItem* item = mHelpPathTreeWidget->topLevelItem( i ) )
+    {
+      helpPaths << item->text( 0 );
+    }
+  }
+  mSettings->setValue( QStringLiteral( "help/helpSearchPath" ), helpPaths );
+
   //Network timeout
   mSettings->setValue( QStringLiteral( "/qgis/networkAndProxy/networkTimeout" ), mNetworkTimeoutSpinBox->value() );
   mSettings->setValue( QStringLiteral( "/qgis/networkAndProxy/userAgent" ), leUserAgent->text() );
@@ -1713,6 +1734,59 @@ void QgsOptions::on_mBtnRemovePluginPath_clicked()
   delete itemToRemove;
 }
 
+void QgsOptions::on_mBtnAddHelpPath_clicked()
+{
+  QTreeWidgetItem* item = new QTreeWidgetItem();
+  item->setText( 0, QString() );
+  item->setFlags( Qt::ItemIsEnabled | Qt::ItemIsSelectable | Qt::ItemIsEditable );
+  mHelpPathTreeWidget->addTopLevelItem( item );
+}
+
+void QgsOptions::on_mBtnRemoveHelpPath_clicked()
+{
+  QList<QTreeWidgetItem*> items = mHelpPathTreeWidget->selectedItems();
+  for ( int i = 0; i < items.size(); ++i )
+  {
+    int idx = mHelpPathTreeWidget->indexOfTopLevelItem( items.at( i ) );
+    if ( idx >= 0 )
+    {
+      delete mHelpPathTreeWidget->takeTopLevelItem( idx );
+    }
+  }
+}
+
+void QgsOptions::on_mBtnMoveHelpUp_clicked()
+{
+  QList<QTreeWidgetItem*> selectedItems = mHelpPathTreeWidget->selectedItems();
+  QList<QTreeWidgetItem*>::iterator itemIt = selectedItems.begin();
+  for ( ; itemIt != selectedItems.end(); ++itemIt )
+  {
+    int currentIndex = mHelpPathTreeWidget->indexOfTopLevelItem( *itemIt );
+    if ( currentIndex > 0 )
+    {
+      mHelpPathTreeWidget->takeTopLevelItem( currentIndex );
+      mHelpPathTreeWidget->insertTopLevelItem( currentIndex - 1, *itemIt );
+      mHelpPathTreeWidget->setCurrentItem( *itemIt );
+    }
+  }
+}
+
+void QgsOptions::on_mBtnMoveHelpDown_clicked()
+{
+  QList<QTreeWidgetItem*> selectedItems = mHelpPathTreeWidget->selectedItems();
+  QList<QTreeWidgetItem*>::iterator itemIt = selectedItems.begin();
+  for ( ; itemIt != selectedItems.end(); ++itemIt )
+  {
+    int currentIndex = mHelpPathTreeWidget->indexOfTopLevelItem( *itemIt );
+    if ( currentIndex <  mHelpPathTreeWidget->topLevelItemCount() - 1 )
+    {
+      mHelpPathTreeWidget->takeTopLevelItem( currentIndex );
+      mHelpPathTreeWidget->insertTopLevelItem( currentIndex + 1, *itemIt );
+      mHelpPathTreeWidget->setCurrentItem( *itemIt );
+    }
+  }
+}
+
 void QgsOptions::on_mBtnAddTemplatePath_clicked()
 {
   QString myDir = QFileDialog::getExistingDirectory(

diff --git a/src/app/qgsoptions.h b/src/app/qgsoptions.h
@@ -139,6 +139,22 @@ class APP_EXPORT QgsOptions : public QgsOptionsDialogBase, private Ui::QgsOption
      * used for finding Plugin libs. */
     void on_mBtnRemovePluginPath_clicked();
 
+    /* Let the user add a path to the list of search paths
+     * used for finding QGIS help. */
+    void on_mBtnAddHelpPath_clicked();
+
+    /* Let the user remove a path from the list of search paths
+     * used for finding QGIS help. */
+    void on_mBtnRemoveHelpPath_clicked();
+
+    /* Let the user move selected path(s) up in the list raising
+     * their priority. */
+    void on_mBtnMoveHelpUp_clicked();
+
+    /* Let the user move selected path(s) down in the list lowering
+     * their priority. */
+    void on_mBtnMoveHelpDown_clicked();
+
     /* Let the user add a path to the list of search paths
      * used for finding composer template files. */
     void on_mBtnAddTemplatePath_clicked();

diff --git a/src/core/qgsapplication.cpp b/src/core/qgsapplication.cpp
@@ -48,6 +48,7 @@
 #include <QIcon>
 #include <QPixmap>
 #include <QThreadPool>
+#include <QLocale>
 
 #ifndef Q_OS_WIN
 #include <netinet/in.h>
@@ -902,6 +903,20 @@ QString QgsApplication::platform()
   return sPlatformName;
 }
 
+QString QgsApplication::locale()
+{
+  QSettings settings;
+  bool overrideLocale = settings.value( QStringLiteral( "locale/overrideFlag" ), false ).toBool();
+  if ( overrideLocale )
+  {
+    return settings.value( QStringLiteral( "locale/userLocale" ), QString() ).toString();
+  }
+  else
+  {
+    return QLocale::system().name().left( 2 );
+  }
+}
+
 QString QgsApplication::userThemesFolder()
 {
   return qgisSettingsDirPath() + QStringLiteral( "/themes" );

diff --git a/src/core/qgsapplication.h b/src/core/qgsapplication.h
@@ -241,6 +241,11 @@ class CORE_EXPORT QgsApplication : public QApplication
      */
     static QString platform();
 
+    /** Returns the QGIS locale.
+     * @note added in QGIS 3.0
+     */
+    static QString locale();
+
     //! Returns the path to user's themes folder
     static QString userThemesFolder();
 

diff --git a/src/core/qgsexpressioncontext.cpp b/src/core/qgsexpressioncontext.cpp
@@ -521,9 +521,11 @@ QgsExpressionContextScope* QgsExpressionContextUtils::globalScope()
   //add some extra global variables
   scope->addVariable( QgsExpressionContextScope::StaticVariable( QStringLiteral( "qgis_version" ), Qgis::QGIS_VERSION, true ) );
   scope->addVariable( QgsExpressionContextScope::StaticVariable( QStringLiteral( "qgis_version_no" ), Qgis::QGIS_VERSION_INT, true ) );
+  scope->addVariable( QgsExpressionContextScope::StaticVariable( QStringLiteral( "qgis_short_version" ), QStringLiteral( "%1.%2" ).arg( Qgis::QGIS_VERSION_INT / 10000 ).arg( Qgis::QGIS_VERSION_INT / 100 % 100 ), true ) );
   scope->addVariable( QgsExpressionContextScope::StaticVariable( QStringLiteral( "qgis_release_name" ), Qgis::QGIS_RELEASE_NAME, true ) );
   scope->addVariable( QgsExpressionContextScope::StaticVariable( QStringLiteral( "qgis_platform" ), QgsApplication::platform(), true ) );
   scope->addVariable( QgsExpressionContextScope::StaticVariable( QStringLiteral( "qgis_os_name" ), QgsApplication::osName(), true ) );
+  scope->addVariable( QgsExpressionContextScope::StaticVariable( QStringLiteral( "qgis_locale" ), QgsApplication::locale(), true ) );
   scope->addVariable( QgsExpressionContextScope::StaticVariable( QStringLiteral( "user_account_name" ), QgsApplication::userLoginName(), true ) );
   scope->addVariable( QgsExpressionContextScope::StaticVariable( QStringLiteral( "user_full_name" ), QgsApplication::userFullName(), true ) );
 

diff --git a/src/gui/CMakeLists.txt b/src/gui/CMakeLists.txt
@@ -237,6 +237,7 @@ SET(QGIS_GUI_SRCS
   qgsgroupwmsdatadialog.cpp
   qgshighlight.cpp
   qgshistogramwidget.cpp
+  qgshelp.cpp
   qgshtmlannotationitem.cpp
   qgsidentifymenu.cpp
   qgskeyvaluewidget.cpp
@@ -303,7 +304,7 @@ SET(QGIS_GUI_SRCS
   qgsshortcutsmanager.cpp
   qgsslider.cpp
   qgssublayersdialog.cpp
-  qgssubstitutionlistwidget.cpp  
+  qgssubstitutionlistwidget.cpp
   qgssqlcomposerdialog.cpp
   qgssvgannotationitem.cpp
   qgstablewidgetbase.cpp
@@ -503,7 +504,7 @@ SET(QGIS_GUI_MOC_HDRS
   symbology-ng/qgslayerpropertieswidget.h
   symbology-ng/qgsnullsymbolrendererwidget.h
   symbology-ng/qgspenstylecombobox.h
-  symbology-ng/qgspointclusterrendererwidget.h  
+  symbology-ng/qgspointclusterrendererwidget.h
   symbology-ng/qgspointdisplacementrendererwidget.h
   symbology-ng/qgsrendererpropertiesdialog.h
   symbology-ng/qgsrendererwidget.h
@@ -651,6 +652,7 @@ SET(QGIS_GUI_HDRS
   qgsdetaileditemdata.h
   qgsexpressionbuilderdialog.h
   qgsfiledropedit.h
+  qgshelp.h
   qgshighlight.h
   qgsmapcanvasitem.h
   qgsmapcanvasmap.h
@@ -718,7 +720,7 @@ SET(QGIS_GUI_HDRS
   layertree/qgslayertreeembeddedwidgetregistry.h
 
   raster/qgsrasterrendererwidget.h
-  
+
   symbology-ng/qgssymbolwidgetcontext.h
 )