Add manual help viewer based on Qt Help Framework

CMakeLists.txt

@@ -894,6 +894,8 @@ add_library(mixxx-lib STATIC EXCLUDE_FROM_ALL
   src/waveform/widgets/softwarewaveformwidget.cpp
   src/waveform/widgets/waveformwidgetabstract.cpp
   src/widget/controlwidgetconnection.cpp
+  src/widget/helpbrowser.cpp
+  src/widget/helpviewer.cpp
   src/widget/hexspinbox.cpp
   src/widget/paintable.cpp
   src/widget/wanalysislibrarytableview.cpp
@@ -1957,6 +1959,7 @@ find_package(Qt5
     Concurrent
     Core
     Gui
+    Help
     Network
     OpenGL
     Qml
@@ -1971,6 +1974,7 @@ target_link_libraries(mixxx-lib PUBLIC
   Qt5::Concurrent
   Qt5::Core
   Qt5::Gui
+  Qt5::Help
   Qt5::Network
   Qt5::OpenGL
   Qt5::Qml

src/controllers/dlgprefcontroller.cpp

@@ -105,6 +105,22 @@ DlgPrefController::DlgPrefController(
                 QDesktopServices::openUrl(QUrl::fromLocalFile(path));
             });
 
+    // Open mapping support links
+    connect(m_ui.labelLoadedMappingSupportLinks,
+            &QLabel::linkActivated,
+            [this](const QString& link) {
+                const QUrl url(link);
+                qWarning() << url.scheme() << url.path();
+                VERIFY_OR_DEBUG_ASSERT(url.isValid()) {
+                    return;
+                }
+                if (url.scheme() == "manual") {
+                    emit showHelp(url.path());
+                    return;
+                }
+                QDesktopServices::openUrl(url);
+            });
+
     // Input mappings
     connect(m_ui.btnAddInputMapping,
             &QAbstractButton::clicked,
@@ -319,12 +335,12 @@ QString DlgPrefController::mappingSupportLinks(
                 wikiLink);
     }
 
-    QString manualLink = pMapping->manualLink();
-    if (!manualLink.isEmpty()) {
+    QString helpDocument = pMapping->manualDocument();
+    if (!helpDocument.isEmpty()) {
         linkList << coloredLinkString(
                 m_pLinkColor,
                 "Mixxx Manual",
-                manualLink);
+                QStringLiteral("manual://") + helpDocument);
     }
 
     // There is always at least one support link.
@@ -530,8 +546,8 @@ void DlgPrefController::slotApply() {
     setDirty(false);
 }
 
-QUrl DlgPrefController::helpUrl() const {
-    return QUrl(MIXXX_MANUAL_CONTROLLERS_URL);
+QString DlgPrefController::helpDocument() const {
+    return QString(MIXXX_MANUAL_CONTROLLERS_PATH);
 }
 
 QString DlgPrefController::mappingPathFromIndex(int index) const {

src/controllers/dlgprefcontroller.h

@@ -28,7 +28,7 @@ class DlgPrefController : public DlgPreferencePage {
             UserSettingsPointer pConfig);
     virtual ~DlgPrefController();
 
-    QUrl helpUrl() const override;
+    QString helpDocument() const override;
 
   public slots:
     /// Called when the preference dialog (not this page) is shown to the user.

src/controllers/dlgprefcontrollerdlg.ui

@@ -361,7 +361,7 @@
              <string notr="true">(forum link for mapping goes here)</string>
             </property>
             <property name="openExternalLinks">
-             <bool>true</bool>
+             <bool>false</bool>
             </property>
             <property name="textInteractionFlags">
              <set>Qt::LinksAccessibleByKeyboard|Qt::LinksAccessibleByMouse</set>

src/controllers/dlgprefcontrollers.cpp

@@ -103,8 +103,8 @@ void DlgPrefControllers::slotResetToDefaults() {
     }
 }
 
-QUrl DlgPrefControllers::helpUrl() const {
-    return QUrl(MIXXX_MANUAL_CONTROLLERS_URL);
+QString DlgPrefControllers::helpDocument() const {
+    return QString(MIXXX_MANUAL_CONTROLLERS_PATH);
 }
 
 bool DlgPrefControllers::handleTreeItemClick(QTreeWidgetItem* clickedItem) {

src/controllers/dlgprefcontrollers.h

@@ -25,7 +25,7 @@ class DlgPrefControllers : public DlgPreferencePage, public Ui::DlgPrefControlle
     virtual ~DlgPrefControllers();
 
     bool handleTreeItemClick(QTreeWidgetItem* clickedItem);
-    QUrl helpUrl() const override;
+    QString helpDocument() const override;
 
   public slots:
     /// Called when the preference dialog (not this page) is shown to the user.

src/controllers/legacycontrollermapping.h

@@ -129,7 +129,7 @@ class LegacyControllerMapping {
         return m_manualPage;
     }
 
-    QString manualLink() const {
+    QString manualDocument() const {
         QString page = manualPage();
         if (page.isEmpty()) {
             return {};

src/defs_urls.h

@@ -32,34 +32,33 @@
 #define MIXXX_MANUAL_URL                        \
     "https://manual.mixxx.org/" TO_VERSION_STR( \
             MIXXX_VERSION_MAJOR, MIXXX_VERSION_MINOR)
-#define MIXXX_MANUAL_SHORTCUTS_URL \
-    MIXXX_MANUAL_URL "/chapters/controlling_mixxx.html#using-a-keyboard"
+#define MIXXX_MANUAL_INDEX_PATH "/index.html"
 #define MIXXX_MANUAL_COMMANDLINEOPTIONS_URL \
     MIXXX_MANUAL_URL "/chapters/appendix.html#command-line-options"
-#define MIXXX_MANUAL_CONTROLLERS_URL \
-    MIXXX_MANUAL_URL "/chapters/controlling_mixxx.html#using-midi-hid-controllers"
+#define MIXXX_MANUAL_SHORTCUTS_PATH \
+    "/chapters/controlling_mixxx.html#using-a-keyboard"
+#define MIXXX_MANUAL_CONTROLLERS_PATH \
+    "/chapters/controlling_mixxx.html#using-midi-hid-controllers"
 #define MIXXX_MANUAL_CONTROLLERMANUAL_PREFIX \
-    MIXXX_MANUAL_URL "/hardware/controllers/"
+    "/hardware/controllers/"
 #define MIXXX_MANUAL_CONTROLLERMANUAL_SUFFIX ".html"
 #define MIXXX_MANUAL_CONTROLS_URL \
     MIXXX_MANUAL_URL "/chapters/advanced_topics.html#mixxx-controls"
-#define MIXXX_MANUAL_SOUND_URL \
-    MIXXX_MANUAL_URL "/chapters/preferences.html#sound-hardware"
-#define MIXXX_MANUAL_LIBRARY_URL \
-    MIXXX_MANUAL_URL "/chapters/preferences.html#library"
+#define MIXXX_MANUAL_SOUND_PATH \
+    "/chapters/preferences.html#sound-hardware"
+#define MIXXX_MANUAL_LIBRARY_PATH \
+    "/chapters/preferences.html#library"
 #define MIXXX_MANUAL_CUE_MODES_URL \
     MIXXX_MANUAL_URL "/chapters/user_interface.html#using-cue-modes"
-#define MIXXX_MANUAL_BEATS_URL \
-    MIXXX_MANUAL_URL "/chapters/preferences.html#beat-detection"
-#define MIXXX_MANUAL_KEY_URL \
-    MIXXX_MANUAL_URL "/chapters/preferences.html#key-detection"
-#define MIXXX_MANUAL_EQ_URL \
-    MIXXX_MANUAL_URL "/chapters/preferences.html#equalizers"
-#define MIXXX_MANUAL_BROADCAST_URL \
-    MIXXX_MANUAL_URL "/chapters/livebroadcasting.html#configuring-mixxx"
-#define MIXXX_MANUAL_VINYL_URL \
-    MIXXX_MANUAL_URL "/chapters/vinyl_control.html#configuring-vinyl-control"
+#define MIXXX_MANUAL_BEATS_PATH \
+    "/chapters/preferences.html#beat-detection"
+#define MIXXX_MANUAL_KEY_PATH \
+    "/chapters/preferences.html#key-detection"
+#define MIXXX_MANUAL_EQ_PATH \
+    "/chapters/preferences.html#equalizers"
+#define MIXXX_MANUAL_BROADCAST_PATH \
+    "/chapters/livebroadcasting.html#configuring-mixxx"
+#define MIXXX_MANUAL_VINYL_PATH \
+    "/chapters/vinyl_control.html#configuring-vinyl-control"
 #define MIXXX_MANUAL_VINYL_TROUBLESHOOTING_URL \
     MIXXX_MANUAL_URL "/chapters/vinyl_control.html#troubleshooting"
-#define MIXXX_MANUAL_FILENAME   "Mixxx-Manual.pdf"
-#define MIXXX_KBD_SHORTCUTS_FILENAME "Mixxx-Keyboard-Shortcuts.pdf"

src/mixxx.cpp

@@ -68,6 +68,7 @@
 #include "waveform/sharedglcontext.h"
 #include "waveform/visualsmanager.h"
 #include "waveform/waveformwidgetfactory.h"
+#include "widget/helpviewer.h"
 #include "widget/wmainmenubar.h"
 
 #ifdef __VINYLCONTROL__
@@ -107,6 +108,8 @@ MixxxMainWindow::MixxxMainWindow(
     DEBUG_ASSERT(pCoreServices);
     m_pCoreServices->initializeSettings();
     m_pCoreServices->initializeKeyboard();
+
+    m_pHelpViewer = new mixxx::HelpViewer(pCoreServices->getSettings());
     // These depend on the settings
     createMenuBar();
     m_pMenuBar->hide();
@@ -225,6 +228,10 @@ MixxxMainWindow::MixxxMainWindow(
             m_pCoreServices->getLibrary());
     m_pPrefDlg->setWindowIcon(QIcon(":/images/mixxx_icon.svg"));
     m_pPrefDlg->setHidden(true);
+    connect(m_pPrefDlg,
+            &DlgPreferences::showHelp,
+            this,
+            &MixxxMainWindow::slotHelpShowManual);
 
     // Connect signals to the menubar. Should be done before emit newSkinLoaded.
     connectMenuBar();
@@ -623,8 +630,10 @@ void MixxxMainWindow::slotUpdateWindowTitle(TrackPointer pTrack) {
 void MixxxMainWindow::createMenuBar() {
     ScopedTimer t("MixxxMainWindow::createMenuBar");
     DEBUG_ASSERT(m_pCoreServices->getKeyboardConfig());
-    m_pMenuBar = make_parented<WMainMenuBar>(
-            this, m_pCoreServices->getSettings(), m_pCoreServices->getKeyboardConfig().get());
+    m_pMenuBar = make_parented<WMainMenuBar>(this,
+            m_pCoreServices->getSettings(),
+            m_pCoreServices->getKeyboardConfig().get(),
+            m_pHelpViewer->hasLocalHelp());
     if (m_pCentralWidget) {
         m_pMenuBar->setStyleSheet(m_pCentralWidget->styleSheet());
     }
@@ -686,6 +695,12 @@ void MixxxMainWindow::connectMenuBar() {
             Qt::UniqueConnection);
 
     // Help
+    connect(m_pMenuBar,
+            &WMainMenuBar::showManual,
+            this,
+            &MixxxMainWindow::slotHelpShowManual,
+            Qt::UniqueConnection);
+
     connect(m_pMenuBar,
             &WMainMenuBar::showAbout,
             this,
@@ -973,6 +988,10 @@ void MixxxMainWindow::slotChangedPlayingDeck(int deck) {
     }
 }
 
+void MixxxMainWindow::slotHelpShowManual(const QString& documentPath) {
+    m_pHelpViewer->open(documentPath);
+}
+
 void MixxxMainWindow::slotHelpAbout() {
     DlgAbout* about = new DlgAbout(this);
     about->show();

src/mixxx.h

@@ -39,11 +39,12 @@ class VinylControlManager;
 class VisualsManager;
 class WMainMenuBar;
 
-#ifdef __ENGINEPRIME__
 namespace mixxx {
+#ifdef __ENGINEPRIME__
 class LibraryExporter;
-} // namespace mixxx
 #endif
+class HelpViewer;
+} // namespace mixxx
 
 /// This Class is the base class for Mixxx.
 /// It sets up the main window providing a menubar.
@@ -72,6 +73,8 @@ class MixxxMainWindow : public QMainWindow {
     void slotFileLoadSongPlayer(int deck);
     /// show the preferences dialog
     void slotOptionsPreferences();
+    /// show the manual
+    void slotHelpShowManual(const QString& documentPath);
     /// show the about dialog
     void slotHelpAbout();
     // show keywheel
@@ -132,6 +135,7 @@ class MixxxMainWindow : public QMainWindow {
 
     parented_ptr<WMainMenuBar> m_pMenuBar;
 
+    mixxx::HelpViewer* m_pHelpViewer;
     DlgDeveloperTools* m_pDeveloperToolsDlg;
 
     DlgPreferences* m_pPrefDlg;

src/preferences/dialog/dlgprefbeats.cpp

@@ -52,8 +52,8 @@ DlgPrefBeats::DlgPrefBeats(QWidget* parent, UserSettingsPointer pConfig)
 DlgPrefBeats::~DlgPrefBeats() {
 }
 
-QUrl DlgPrefBeats::helpUrl() const {
-    return QUrl(MIXXX_MANUAL_BEATS_URL);
+QString DlgPrefBeats::helpDocument() const {
+    return QString(MIXXX_MANUAL_BEATS_PATH);
 }
 
 void DlgPrefBeats::loadSettings() {

src/preferences/dialog/dlgprefbeats.h

@@ -16,7 +16,7 @@ class DlgPrefBeats : public DlgPreferencePage, public Ui::DlgBeatsDlg {
     DlgPrefBeats(QWidget *parent, UserSettingsPointer _config);
     virtual ~DlgPrefBeats();
 
-    QUrl helpUrl() const override;
+    QString helpDocument() const override;
 
   public slots:
     // Apply changes to widget

src/preferences/dialog/dlgprefbroadcast.cpp

@@ -187,8 +187,8 @@ void DlgPrefBroadcast::slotUpdate() {
     btnDisconnectAll->setEnabled(enabled);
 }
 
-QUrl DlgPrefBroadcast::helpUrl() const {
-    return QUrl(MIXXX_MANUAL_BROADCAST_URL);
+QString DlgPrefBroadcast::helpDocument() const {
+    return QString(MIXXX_MANUAL_BROADCAST_PATH);
 }
 
 void DlgPrefBroadcast::applyModel() {

src/preferences/dialog/dlgprefbroadcast.h

@@ -20,7 +20,7 @@ class DlgPrefBroadcast : public DlgPreferencePage, public Ui::DlgPrefBroadcastDl
                      BroadcastSettingsPointer pBroadcastSettings);
     virtual ~DlgPrefBroadcast();
 
-    QUrl helpUrl() const override;
+    QString helpDocument() const override;
 
   public slots:
     /** Apply changes to widget */

src/preferences/dialog/dlgprefeq.cpp

@@ -304,8 +304,8 @@ void DlgPrefEQ::slotSingleEqChecked(int checked) {
     applySelections();
 }
 
-QUrl DlgPrefEQ::helpUrl() const {
-    return QUrl(MIXXX_MANUAL_EQ_URL);
+QString DlgPrefEQ::helpDocument() const {
+    return QString(MIXXX_MANUAL_EQ_PATH);
 }
 
 void DlgPrefEQ::loadSettings() {

src/preferences/dialog/dlgprefeq.h

@@ -19,7 +19,7 @@ class DlgPrefEQ : public DlgPreferencePage, public Ui::DlgPrefEQDlg  {
             UserSettingsPointer _config);
     virtual ~DlgPrefEQ();
 
-    QUrl helpUrl() const override;
+    QString helpDocument() const override;
 
     QString getEQEffectGroupForDeck(int deck) const;
     QString getQuickEffectGroupForDeck(int deck) const;

src/preferences/dialog/dlgpreferencepage.cpp

@@ -10,6 +10,6 @@ DlgPreferencePage::DlgPreferencePage(QWidget* pParent)
 DlgPreferencePage::~DlgPreferencePage() {
 }
 
-QUrl DlgPreferencePage::helpUrl() const {
-    return QUrl();
+QString DlgPreferencePage::helpDocument() const {
+    return QString();
 }

src/preferences/dialog/dlgpreferencepage.h

@@ -14,13 +14,16 @@ class DlgPreferencePage : public QWidget {
     DlgPreferencePage(QWidget* pParent);
     virtual ~DlgPreferencePage();
 
-    /// Returns the help URL for the current page.
+    /// Returns the help document for the current page.
     /// Subclasses can provide a path to the appropriate manual page by
-    /// overriding this. The default implementation returns an invalid QUrl.
-    virtual QUrl helpUrl() const;
+    /// overriding this. The default implementation returns an empty QString.
+    virtual QString helpDocument() const;
 
     QColor m_pLinkColor;
 
+  signals:
+    void showHelp(const QString& documentPath);
+
   public slots:
     /// Called when the preference dialog is shown to the user (not necessarily
     /// when this PreferencePage is shown to the user). At this point, the

src/preferences/dialog/dlgpreferences.cpp

@@ -401,9 +401,7 @@ void DlgPreferences::slotButtonPressed(QAbstractButton* pButton) {
             break;
         case QDialogButtonBox::HelpRole:
             if (pCurrentPage) {
-                QUrl helpUrl = pCurrentPage->helpUrl();
-                DEBUG_ASSERT(helpUrl.isValid());
-                QDesktopServices::openUrl(helpUrl);
+                emit showHelp(pCurrentPage->helpDocument());
             }
             break;
         default:
@@ -431,6 +429,8 @@ void DlgPreferences::addPageWidget(PreferencesPage page,
             page.pDlg,
             &DlgPreferencePage::slotResetToDefaults);
 
+    connect(page.pDlg, &DlgPreferencePage::showHelp, this, &DlgPreferences::showHelp);
+
     // Add a new scroll area to the stacked pages widget containing the page
     QScrollArea* sa = new QScrollArea(pagesWidget);
     sa->setWidgetResizable(true);
@@ -475,7 +475,7 @@ void DlgPreferences::switchToPage(DlgPreferencePage* pWidget) {
         return;
     }
 
-    if (pWidget->helpUrl().isValid()) {
+    if (!pWidget->helpDocument().isEmpty()) {
         pButton->show();
     } else {
         pButton->hide();

src/preferences/dialog/dlgpreferences.h

@@ -91,6 +91,7 @@ class DlgPreferences : public QDialog, public Ui::DlgPreferencesDlg {
   signals:
     void closeDlg();
     void showDlg();
+    void showHelp(const QString& documentPath);
 
     // Emitted just after the user clicks Apply or OK.
     void applyPreferences();