Skip to content

Commit 48bcca6

Browse files
authored
Merge pull request #3911 from alexbruy/generic-help
Generic help for QGIS
2 parents 3145a01 + bcb69c5 commit 48bcca6

14 files changed

+533
-31
lines changed

doc/CMakeLists.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ ELSE(TXT2TAGS_EXECUTABLE)
2222
)
2323
ENDIF(TXT2TAGS_EXECUTABLE)
2424

25-
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)
25+
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)
2626

2727
INSTALL(FILES ${QGIS_DOC_FILES} DESTINATION ${QGIS_DATA_DIR}/doc)
2828
INSTALL(FILES ../images/icons/qgis-icon-60x60.png DESTINATION ${QGIS_DATA_DIR}/doc/images)

doc/nohelp.html

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
<!DOCTYPE html>
2+
<html>
3+
<head>
4+
<title>No help found</title>
5+
<meta charset="UTF-8">
6+
</head>
7+
<body>
8+
<center><a href="http://qgis.org"><img src="qgis-icon-60x60.png" border=0></a></center>
9+
<h1><center>Oops!</center></h1>
10+
<p>QGIS help is currently not available. This is likely because:</p>
11+
<ul>
12+
<li>No internet connection is available</li>
13+
<li>The offline help files are not available or the location of these
14+
files is not properly configured</li>
15+
<li>No help content is available for the requested topic</li>
16+
</ul>
17+
<p>Please check that the correct location of the offline help files is
18+
specified in the QGIS options dialog (Settings&nbsp;&rarr; Options&nbsp;&rarr;System).</p>
19+
</body>
20+
</html>

python/core/qgsapplication.sip

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -254,6 +254,11 @@ static void qtgui_UpdatePyArgv(PyObject *argvlist, int argc, char **argv)
254254
*/
255255
static QString platform();
256256

257+
/** Returns the QGIS locale.
258+
* @note added in QGIS 3.0
259+
*/
260+
static QString locale();
261+
257262
//! Returns the path to user's themes folder
258263
static QString userThemesFolder();
259264

python/gui/gui.sip

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,7 @@
8888
%Include qgsgradientcolorrampdialog.sip
8989
%Include qgsgradientstopeditor.sip
9090
%Include qgsgroupwmsdatadialog.sip
91+
%Include qgshelp.sip
9192
%Include qgshighlight.sip
9293
%Include qgshistogramwidget.sip
9394
%Include qgshtmlannotationitem.sip

python/gui/qgshelp.sip

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
/** \ingroup gui
2+
* \class QgsHelp
3+
* @brief Helper class for showing help topic URI for the given key.
4+
*
5+
* Help can be stored online, on the local directory or on the intranet
6+
* server. Location of the QGIS help can be configured in QGIS options.
7+
* Multiple locations are supported, they will be used in order of
8+
* preference, from top to bottom.
9+
*
10+
* URI construction takes in account following information:
11+
* - QGIS version
12+
* - language of the QGIS UI
13+
*
14+
* If no help found, default error page with information how to setup
15+
* help system will be shown.
16+
*
17+
* @note added in QGIS 3.0
18+
*/
19+
class QgsHelp
20+
{
21+
%TypeHeaderCode
22+
#include <qgshelp.h>
23+
%End
24+
25+
public:
26+
27+
/** Opens help topic for the given help key using default system
28+
* web browser. If help topic not found, builtin error page shown.
29+
* @param key key which identified help topic
30+
* @note added in QGIS 3.0
31+
*/
32+
static void openHelp( const QString& key );
33+
34+
/** Returns URI of the help topic for the given key. If help topic
35+
* not found, URI of the builtin error page returned.
36+
* @param key key which identified help topic
37+
* @note added in QGIS 3.0
38+
*/
39+
static QUrl helpUrl( const QString& key );
40+
};

src/app/qgsoptions.cpp

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -265,6 +265,16 @@ QgsOptions::QgsOptions( QWidget *parent, Qt::WindowFlags fl )
265265
mListHiddenBrowserPaths->addItem( newItem );
266266
}
267267

268+
//locations of the QGIS help
269+
QStringList helpPathList = mSettings->value( QStringLiteral( "help/helpSearchPath" ) ).toStringList();
270+
Q_FOREACH ( const QString& path, helpPathList )
271+
{
272+
QTreeWidgetItem* item = new QTreeWidgetItem();
273+
item->setText( 0, path );
274+
item->setFlags( Qt::ItemIsEnabled | Qt::ItemIsSelectable | Qt::ItemIsEditable );
275+
mHelpPathTreeWidget->addTopLevelItem( item );
276+
}
277+
268278
//Network timeout
269279
mNetworkTimeoutSpinBox->setValue( mSettings->value( QStringLiteral( "/qgis/networkAndProxy/networkTimeout" ), "60000" ).toInt() );
270280
leUserAgent->setText( mSettings->value( QStringLiteral( "/qgis/networkAndProxy/userAgent" ), "Mozilla/5.0" ).toString() );
@@ -1096,6 +1106,17 @@ void QgsOptions::saveOptions()
10961106
}
10971107
mSettings->setValue( QStringLiteral( "/browser/hiddenPaths" ), pathsList );
10981108

1109+
//QGIS help locations
1110+
QStringList helpPaths;
1111+
for ( int i = 0; i < mHelpPathTreeWidget->topLevelItemCount(); ++i )
1112+
{
1113+
if ( QTreeWidgetItem* item = mHelpPathTreeWidget->topLevelItem( i ) )
1114+
{
1115+
helpPaths << item->text( 0 );
1116+
}
1117+
}
1118+
mSettings->setValue( QStringLiteral( "help/helpSearchPath" ), helpPaths );
1119+
10991120
//Network timeout
11001121
mSettings->setValue( QStringLiteral( "/qgis/networkAndProxy/networkTimeout" ), mNetworkTimeoutSpinBox->value() );
11011122
mSettings->setValue( QStringLiteral( "/qgis/networkAndProxy/userAgent" ), leUserAgent->text() );
@@ -1713,6 +1734,59 @@ void QgsOptions::on_mBtnRemovePluginPath_clicked()
17131734
delete itemToRemove;
17141735
}
17151736

1737+
void QgsOptions::on_mBtnAddHelpPath_clicked()
1738+
{
1739+
QTreeWidgetItem* item = new QTreeWidgetItem();
1740+
item->setText( 0, QString() );
1741+
item->setFlags( Qt::ItemIsEnabled | Qt::ItemIsSelectable | Qt::ItemIsEditable );
1742+
mHelpPathTreeWidget->addTopLevelItem( item );
1743+
}
1744+
1745+
void QgsOptions::on_mBtnRemoveHelpPath_clicked()
1746+
{
1747+
QList<QTreeWidgetItem*> items = mHelpPathTreeWidget->selectedItems();
1748+
for ( int i = 0; i < items.size(); ++i )
1749+
{
1750+
int idx = mHelpPathTreeWidget->indexOfTopLevelItem( items.at( i ) );
1751+
if ( idx >= 0 )
1752+
{
1753+
delete mHelpPathTreeWidget->takeTopLevelItem( idx );
1754+
}
1755+
}
1756+
}
1757+
1758+
void QgsOptions::on_mBtnMoveHelpUp_clicked()
1759+
{
1760+
QList<QTreeWidgetItem*> selectedItems = mHelpPathTreeWidget->selectedItems();
1761+
QList<QTreeWidgetItem*>::iterator itemIt = selectedItems.begin();
1762+
for ( ; itemIt != selectedItems.end(); ++itemIt )
1763+
{
1764+
int currentIndex = mHelpPathTreeWidget->indexOfTopLevelItem( *itemIt );
1765+
if ( currentIndex > 0 )
1766+
{
1767+
mHelpPathTreeWidget->takeTopLevelItem( currentIndex );
1768+
mHelpPathTreeWidget->insertTopLevelItem( currentIndex - 1, *itemIt );
1769+
mHelpPathTreeWidget->setCurrentItem( *itemIt );
1770+
}
1771+
}
1772+
}
1773+
1774+
void QgsOptions::on_mBtnMoveHelpDown_clicked()
1775+
{
1776+
QList<QTreeWidgetItem*> selectedItems = mHelpPathTreeWidget->selectedItems();
1777+
QList<QTreeWidgetItem*>::iterator itemIt = selectedItems.begin();
1778+
for ( ; itemIt != selectedItems.end(); ++itemIt )
1779+
{
1780+
int currentIndex = mHelpPathTreeWidget->indexOfTopLevelItem( *itemIt );
1781+
if ( currentIndex < mHelpPathTreeWidget->topLevelItemCount() - 1 )
1782+
{
1783+
mHelpPathTreeWidget->takeTopLevelItem( currentIndex );
1784+
mHelpPathTreeWidget->insertTopLevelItem( currentIndex + 1, *itemIt );
1785+
mHelpPathTreeWidget->setCurrentItem( *itemIt );
1786+
}
1787+
}
1788+
}
1789+
17161790
void QgsOptions::on_mBtnAddTemplatePath_clicked()
17171791
{
17181792
QString myDir = QFileDialog::getExistingDirectory(

src/app/qgsoptions.h

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -139,6 +139,22 @@ class APP_EXPORT QgsOptions : public QgsOptionsDialogBase, private Ui::QgsOption
139139
* used for finding Plugin libs. */
140140
void on_mBtnRemovePluginPath_clicked();
141141

142+
/* Let the user add a path to the list of search paths
143+
* used for finding QGIS help. */
144+
void on_mBtnAddHelpPath_clicked();
145+
146+
/* Let the user remove a path from the list of search paths
147+
* used for finding QGIS help. */
148+
void on_mBtnRemoveHelpPath_clicked();
149+
150+
/* Let the user move selected path(s) up in the list raising
151+
* their priority. */
152+
void on_mBtnMoveHelpUp_clicked();
153+
154+
/* Let the user move selected path(s) down in the list lowering
155+
* their priority. */
156+
void on_mBtnMoveHelpDown_clicked();
157+
142158
/* Let the user add a path to the list of search paths
143159
* used for finding composer template files. */
144160
void on_mBtnAddTemplatePath_clicked();

src/core/qgsapplication.cpp

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@
4848
#include <QIcon>
4949
#include <QPixmap>
5050
#include <QThreadPool>
51+
#include <QLocale>
5152

5253
#ifndef Q_OS_WIN
5354
#include <netinet/in.h>
@@ -902,6 +903,20 @@ QString QgsApplication::platform()
902903
return sPlatformName;
903904
}
904905

906+
QString QgsApplication::locale()
907+
{
908+
QSettings settings;
909+
bool overrideLocale = settings.value( QStringLiteral( "locale/overrideFlag" ), false ).toBool();
910+
if ( overrideLocale )
911+
{
912+
return settings.value( QStringLiteral( "locale/userLocale" ), QString() ).toString();
913+
}
914+
else
915+
{
916+
return QLocale::system().name().left( 2 );
917+
}
918+
}
919+
905920
QString QgsApplication::userThemesFolder()
906921
{
907922
return qgisSettingsDirPath() + QStringLiteral( "/themes" );

src/core/qgsapplication.h

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -241,6 +241,11 @@ class CORE_EXPORT QgsApplication : public QApplication
241241
*/
242242
static QString platform();
243243

244+
/** Returns the QGIS locale.
245+
* @note added in QGIS 3.0
246+
*/
247+
static QString locale();
248+
244249
//! Returns the path to user's themes folder
245250
static QString userThemesFolder();
246251

src/core/qgsexpressioncontext.cpp

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -521,9 +521,11 @@ QgsExpressionContextScope* QgsExpressionContextUtils::globalScope()
521521
//add some extra global variables
522522
scope->addVariable( QgsExpressionContextScope::StaticVariable( QStringLiteral( "qgis_version" ), Qgis::QGIS_VERSION, true ) );
523523
scope->addVariable( QgsExpressionContextScope::StaticVariable( QStringLiteral( "qgis_version_no" ), Qgis::QGIS_VERSION_INT, true ) );
524+
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 ) );
524525
scope->addVariable( QgsExpressionContextScope::StaticVariable( QStringLiteral( "qgis_release_name" ), Qgis::QGIS_RELEASE_NAME, true ) );
525526
scope->addVariable( QgsExpressionContextScope::StaticVariable( QStringLiteral( "qgis_platform" ), QgsApplication::platform(), true ) );
526527
scope->addVariable( QgsExpressionContextScope::StaticVariable( QStringLiteral( "qgis_os_name" ), QgsApplication::osName(), true ) );
528+
scope->addVariable( QgsExpressionContextScope::StaticVariable( QStringLiteral( "qgis_locale" ), QgsApplication::locale(), true ) );
527529
scope->addVariable( QgsExpressionContextScope::StaticVariable( QStringLiteral( "user_account_name" ), QgsApplication::userLoginName(), true ) );
528530
scope->addVariable( QgsExpressionContextScope::StaticVariable( QStringLiteral( "user_full_name" ), QgsApplication::userFullName(), true ) );
529531

src/gui/CMakeLists.txt

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -237,6 +237,7 @@ SET(QGIS_GUI_SRCS
237237
qgsgroupwmsdatadialog.cpp
238238
qgshighlight.cpp
239239
qgshistogramwidget.cpp
240+
qgshelp.cpp
240241
qgshtmlannotationitem.cpp
241242
qgsidentifymenu.cpp
242243
qgskeyvaluewidget.cpp
@@ -303,7 +304,7 @@ SET(QGIS_GUI_SRCS
303304
qgsshortcutsmanager.cpp
304305
qgsslider.cpp
305306
qgssublayersdialog.cpp
306-
qgssubstitutionlistwidget.cpp
307+
qgssubstitutionlistwidget.cpp
307308
qgssqlcomposerdialog.cpp
308309
qgssvgannotationitem.cpp
309310
qgstablewidgetbase.cpp
@@ -503,7 +504,7 @@ SET(QGIS_GUI_MOC_HDRS
503504
symbology-ng/qgslayerpropertieswidget.h
504505
symbology-ng/qgsnullsymbolrendererwidget.h
505506
symbology-ng/qgspenstylecombobox.h
506-
symbology-ng/qgspointclusterrendererwidget.h
507+
symbology-ng/qgspointclusterrendererwidget.h
507508
symbology-ng/qgspointdisplacementrendererwidget.h
508509
symbology-ng/qgsrendererpropertiesdialog.h
509510
symbology-ng/qgsrendererwidget.h
@@ -651,6 +652,7 @@ SET(QGIS_GUI_HDRS
651652
qgsdetaileditemdata.h
652653
qgsexpressionbuilderdialog.h
653654
qgsfiledropedit.h
655+
qgshelp.h
654656
qgshighlight.h
655657
qgsmapcanvasitem.h
656658
qgsmapcanvasmap.h
@@ -718,7 +720,7 @@ SET(QGIS_GUI_HDRS
718720
layertree/qgslayertreeembeddedwidgetregistry.h
719721

720722
raster/qgsrasterrendererwidget.h
721-
723+
722724
symbology-ng/qgssymbolwidgetcontext.h
723725
)
724726

0 commit comments

Comments
 (0)