Help: Open example documentation in extra window

Also remove the hack that HelpManager::handleHelpRequest looks
for ?view=split in the URL and use an enum instead.

Change-Id: I4ad74775381cf0b321181358266d8e89c6e277b5
Reviewed-by: Karsten Heimrich <karsten.heimrich@digia.com>

share/qtcreator/welcomescreen/widgets/Delegate.qml

@@ -228,7 +228,7 @@ Rectangle {
                                            model.dependencies,
                                            model.platforms)
             else
-                gettingStarted.openSplitHelp(model.docUrl);
+                gettingStarted.openHelpInExtraWindow(model.docUrl);
         }
 
     }

src/plugins/coreplugin/helpmanager.cpp

@@ -282,9 +282,14 @@ QByteArray HelpManager::fileData(const QUrl &url)
     return d->m_helpEngine->fileData(url);
 }
 
-void HelpManager::handleHelpRequest(const QString &url)
+void HelpManager::handleHelpRequest(const QUrl &url, HelpManager::HelpViewerLocation location)
 {
-    emit m_instance->helpRequested(QUrl(url));
+    emit m_instance->helpRequested(url, location);
+}
+
+void HelpManager::handleHelpRequest(const QString &url, HelpViewerLocation location)
+{
+    handleHelpRequest(QUrl(url), location);
 }
 
 QStringList HelpManager::registeredNamespaces()

src/plugins/coreplugin/helpmanager.h

@@ -53,6 +53,13 @@ class CORE_EXPORT HelpManager : public QObject
     Q_OBJECT
 
 public:
+    enum HelpViewerLocation {
+        SideBySideIfPossible = 0,
+        SideBySideAlways = 1,
+        HelpModeAlways = 2,
+        ExternalHelpAlways = 3
+    };
+
     typedef QHash<QString, QStringList> Filters;
 
     static QObject *instance();
@@ -85,13 +92,16 @@ public:
     static void addUserDefinedFilter(const QString &filter, const QStringList &attr);
 
 public slots:
-    static void handleHelpRequest(const QString &url);
+    static void handleHelpRequest(const QUrl &url,
+                                  Core::HelpManager::HelpViewerLocation location = HelpModeAlways);
+    static void handleHelpRequest(const QString &url,
+                                  Core::HelpManager::HelpViewerLocation location = HelpModeAlways);
 
 signals:
     void setupFinished();
     void documentationChanged();
     void collectionFileChanged();
-    void helpRequested(const QUrl &url);
+    void helpRequested(const QUrl &url, Core::HelpManager::HelpViewerLocation location);
 
 private:
     explicit HelpManager(QObject *parent = 0);

src/plugins/help/generalsettingspage.cpp

@@ -103,7 +103,7 @@ QWidget *GeneralSettingsPage::widget()
         m_ui->helpStartComboBox->setCurrentIndex(m_startOption);
 
         m_contextOption = HelpManager::customValue(QLatin1String("ContextHelpOption"),
-                                                   Help::Constants::SideBySideIfPossible).toInt();
+                                                   Core::HelpManager::SideBySideIfPossible).toInt();
         m_ui->contextHelpComboBox->setCurrentIndex(m_contextOption);
 
         connect(m_ui->currentPageButton, SIGNAL(clicked()), this, SLOT(setCurrentPage()));

src/plugins/help/helpconstants.h

@@ -42,13 +42,6 @@ enum {
     ShowLastPages = 2
 };
 
-enum {
-    SideBySideIfPossible = 0,
-    SideBySideAlways = 1,
-    HelpModeAlways = 2,
-    ExternalHelpAlways = 3
-};
-
 static const QLatin1String ListSeparator("|");
 static const QLatin1String DefaultZoomFactor("0.0");
 static const QLatin1String AboutBlank("about:blank");

src/plugins/help/helpplugin.cpp

@@ -65,7 +65,6 @@
 #include <coreplugin/editormanager/ieditor.h>
 #include <coreplugin/findplaceholder.h>
 #include <coreplugin/icore.h>
-#include <coreplugin/helpmanager.h>
 #include <coreplugin/minisplitter.h>
 #include <coreplugin/modemanager.h>
 #include <coreplugin/rightpane.h>
@@ -176,8 +175,8 @@ bool HelpPlugin::initialize(const QStringList &arguments, QString *error)
         SLOT(fontChanged()));
     connect(m_generalSettingsPage, SIGNAL(returnOnCloseChanged()), this,
         SLOT(updateCloseButton()));
-    connect(HelpManager::instance(), SIGNAL(helpRequested(QUrl)), this,
+    connect(HelpManager::instance(), SIGNAL(helpRequested(QUrl,Core::HelpManager::HelpViewerLocation)),
-        SLOT(handleHelpRequest(QUrl)));
+            this, SLOT(handleHelpRequest(QUrl,Core::HelpManager::HelpViewerLocation)));
     connect(m_searchTaskHandler, SIGNAL(search(QUrl)), this,
             SLOT(switchToHelpMode(QUrl)));
 
@@ -678,45 +677,48 @@ void HelpPlugin::setupHelpEngineIfNeeded()
 {
     m_helpManager->setEngineNeedsUpdate();
     if (ModeManager::currentMode() == m_mode
-        || contextHelpOption() == Help::Constants::ExternalHelpAlways)
+        || contextHelpOption() == Core::HelpManager::ExternalHelpAlways)
         m_helpManager->setupGuiHelpEngine();
 }
 
-HelpViewer *HelpPlugin::viewerForContextMode()
+bool HelpPlugin::canShowHelpSideBySide() const
 {
-    bool showSideBySide = false;
     RightPanePlaceHolder *placeHolder = RightPanePlaceHolder::current();
-    switch (contextHelpOption()) {
+    if (!placeHolder)
-        case Help::Constants::SideBySideIfPossible: {
+        return false;
-            // side by side if possible
+    if (placeHolder->isVisible())
-            if (IEditor *editor = EditorManager::currentEditor()) {
+        return true;
-                if (!placeHolder || !placeHolder->isVisible()) {
-                    if (!editor->widget())
-                        break;
-                    if (!editor->widget()->isVisible())
-                        break;
-                    if (editor->widget()->width() < 800)
-                        break;
-                }
-            }
-        }   // fall through
-        case Help::Constants::SideBySideAlways: {
-            // side by side
-            showSideBySide = true;
-        }   break;
-        case Help::Constants::ExternalHelpAlways:
-            return externalHelpViewer();
-        default: // help mode
-            break;
-    }
 
-    if (placeHolder && showSideBySide) {
+    IEditor *editor = EditorManager::currentEditor();
+    if (!editor)
+        return true;
+    QTC_ASSERT(editor->widget(), return true);
+    if (!editor->widget()->isVisible())
+        return true;
+    if (editor->widget()->width() < 800)
+        return false;
+    return true;
+}
+
+HelpViewer *HelpPlugin::viewerForHelpViewerLocation(Core::HelpManager::HelpViewerLocation location)
+{
+    Core::HelpManager::HelpViewerLocation actualLocation = location;
+    if (location == Core::HelpManager::SideBySideIfPossible)
+        actualLocation = canShowHelpSideBySide() ? Core::HelpManager::SideBySideAlways
+                                                 : Core::HelpManager::HelpModeAlways;
+
+    if (actualLocation == Core::HelpManager::ExternalHelpAlways)
+        return externalHelpViewer();
+
+    if (actualLocation == Core::HelpManager::SideBySideAlways) {
         createRightPaneContextViewer();
         RightPaneWidget::instance()->setWidget(m_rightPaneSideBarWidget);
         RightPaneWidget::instance()->setShown(true);
         return m_rightPaneSideBarWidget->currentViewer();
     }
 
+    QTC_CHECK(actualLocation == Core::HelpManager::HelpModeAlways);
+
     activateHelpMode(); // should trigger an createPage...
     HelpViewer *viewer = m_centralWidget->currentHelpViewer();
     if (!viewer)
@@ -724,6 +726,11 @@ HelpViewer *HelpPlugin::viewerForContextMode()
     return viewer;
 }
 
+HelpViewer *HelpPlugin::viewerForContextHelp()
+{
+    return viewerForHelpViewerLocation(contextHelpOption());
+}
+
 static QUrl findBestLink(const QMap<QString, QUrl> &links, QString *highlightId)
 {
     if (highlightId)
@@ -768,7 +775,7 @@ void HelpPlugin::activateContext()
             links.insert(idFromContext, idFromContext);
     }
 
-    if (HelpViewer* viewer = viewerForContextMode()) {
+    if (HelpViewer *viewer = viewerForContextHelp()) {
         QUrl source = findBestLink(links, &m_contextHelpHighlightId);
         if (!source.isValid()) {
             // No link found or no context object
@@ -937,13 +944,13 @@ void HelpPlugin::highlightSearchTermsInContextHelp()
 {
     if (m_contextHelpHighlightId.isEmpty())
         return;
-    HelpViewer* viewer = viewerForContextMode();
+    HelpViewer *viewer = viewerForContextHelp();
     QTC_ASSERT(viewer, return);
     viewer->highlightId(m_contextHelpHighlightId);
     m_contextHelpHighlightId.clear();
 }
 
-void HelpPlugin::handleHelpRequest(const QUrl &url)
+void HelpPlugin::handleHelpRequest(const QUrl &url, Core::HelpManager::HelpViewerLocation location)
 {
     if (HelpViewer::launchWithExternalApp(url))
         return;
@@ -964,12 +971,10 @@ void HelpPlugin::handleHelpRequest(const QUrl &url)
     }
 
     const QUrl newUrl(address);
-    if (newUrl.queryItemValue(QLatin1String("view")) == QLatin1String("split")) {
+    HelpViewer *viewer = viewerForHelpViewerLocation(location);
-        if (HelpViewer* viewer = viewerForContextMode())
+    QTC_ASSERT(viewer, return);
-            viewer->setSource(newUrl);
+    viewer->setSource(newUrl);
-    } else {
+    Core::ICore::raiseWindow(viewer);
-        switchToHelpMode(newUrl);
-    }
 }
 
 void HelpPlugin::slotAboutToShowBackMenu()
@@ -1014,16 +1019,17 @@ void HelpPlugin::doSetupIfNeeded()
     }
 }
 
-int HelpPlugin::contextHelpOption() const
+Core::HelpManager::HelpViewerLocation HelpPlugin::contextHelpOption() const
 {
     QSettings *settings = Core::ICore::settings();
     const QString key = QLatin1String(Help::Constants::ID_MODE_HELP) + QLatin1String("/ContextHelpOption");
     if (settings->contains(key))
-        return settings->value(key, Help::Constants::SideBySideIfPossible).toInt();
+        return Core::HelpManager::HelpViewerLocation(
+                    settings->value(key, Core::HelpManager::SideBySideIfPossible).toInt());
 
     const QHelpEngineCore &engine = LocalHelpManager::helpEngine();
-    return engine.customValue(QLatin1String("ContextHelpOption"),
+    return Core::HelpManager::HelpViewerLocation(engine.customValue(QLatin1String("ContextHelpOption"),
-        Help::Constants::SideBySideIfPossible).toInt();
+        Core::HelpManager::SideBySideIfPossible).toInt());
 }
 
 void HelpPlugin::setupNavigationMenus(QAction *back, QAction *next, QWidget *parent)

src/plugins/help/helpplugin.h

@@ -32,6 +32,7 @@
 
 #include "helpwidget.h"
 
+#include <coreplugin/helpmanager.h>
 #include <coreplugin/icontext.h>
 #include <extensionsystem/iplugin.h>
 
@@ -113,7 +114,7 @@ private slots:
     void setupHelpEngineIfNeeded();
 
     void highlightSearchTermsInContextHelp();
-    void handleHelpRequest(const QUrl &url);
+    void handleHelpRequest(const QUrl &url, Core::HelpManager::HelpViewerLocation location);
 
     void slotAboutToShowBackMenu();
     void slotAboutToShowNextMenu();
@@ -128,13 +129,15 @@ private:
     void activateHelpMode();
     Utils::StyledBar *createWidgetToolBar();
     Utils::StyledBar *createIconToolBar(bool external);
-    HelpViewer* viewerForContextMode();
+    bool canShowHelpSideBySide() const;
+    HelpViewer *viewerForHelpViewerLocation(Core::HelpManager::HelpViewerLocation location);
+    HelpViewer *viewerForContextHelp();
     HelpWidget *createHelpWidget(const Core::Context &context, HelpWidget::WidgetStyle style);
     void createRightPaneContextViewer();
     HelpViewer *externalHelpViewer();
 
     void doSetupIfNeeded();
-    int contextHelpOption() const;
+    Core::HelpManager::HelpViewerLocation contextHelpOption() const;
     void setupNavigationMenus(QAction *back, QAction *next, QWidget *parent);
 
 private:

src/plugins/qtsupport/gettingstartedwelcomepage.cpp

@@ -279,14 +279,14 @@ ExamplesWelcomePage::Id ExamplesWelcomePage::id() const
     return m_showExamples ? Examples : Tutorials;
 }
 
-void ExamplesWelcomePage::openSplitHelp(const QUrl &help)
+void ExamplesWelcomePage::openHelpInExtraWindow(const QUrl &help)
 {
-    Core::HelpManager::handleHelpRequest(help.toString()+QLatin1String("?view=split"));
+    Core::HelpManager::handleHelpRequest(help, Core::HelpManager::ExternalHelpAlways);
 }
 
 void ExamplesWelcomePage::openHelp(const QUrl &help)
 {
-    Core::HelpManager::handleHelpRequest(help.toString());
+    Core::HelpManager::handleHelpRequest(help, Core::HelpManager::HelpModeAlways);
 }
 
 void ExamplesWelcomePage::openUrl(const QUrl &url)
@@ -414,7 +414,7 @@ void ExamplesWelcomePage::openProject(const QString &projectFile,
         Core::ICore::openFiles(filesToOpen);
         Core::ModeManager::activateMode(Core::Constants::MODE_EDIT);
         if (help.isValid())
-            Core::HelpManager::handleHelpRequest(help.toString() + QLatin1String("?view=split"));
+            openHelpInExtraWindow(help.toString());
         Core::ModeManager::activateMode(ProjectExplorer::Constants::MODE_SESSION);
     }
     if (!errorMessage.isEmpty())

src/plugins/qtsupport/gettingstartedwelcomepage.h

@@ -61,7 +61,7 @@ public:
     Q_INVOKABLE void openUrl(const QUrl &url);
 
 public slots:
-    void openSplitHelp(const QUrl &help);
+    void openHelpInExtraWindow(const QUrl &help);
     void openHelp(const QUrl &help);
     void openProject(const QString& projectFile, const QStringList& additionalFilesToOpen,
                      const QString &mainFile, const QUrl& help, const QStringList &dependencies,

src/plugins/welcome/welcomeplugin.cpp

@@ -156,6 +156,7 @@ WelcomeMode::WelcomeMode() :
     layout->addWidget(m_welcomePage);
 #else
     QWidget *container = QWidget::createWindowContainer(m_welcomePage, m_modeWidget);
+    container->setProperty("nativeAncestors", true);
     m_modeWidget->setLayout(layout);
     layout->addWidget(container);
 #endif // USE_QUICK_WIDGET