Move newViewRequested to the public API

This moves the API to public, with proper versioning, adds
documentation and adjust the warning to also report an null parameter
to openIn that would cause the load to fail.

The experimental example code is copied from quicktestbrowser to
quicknanobrowser.

Change-Id: I23b06c7a5add0323d0540a783873584438d85ea8
Reviewed-by: Szabolcs David <davidsz@inf.u-szeged.hu>
Reviewed-by: Andras Becsi <andras.becsi@theqtcompany.com>

4 files changed, 47 insertions, 6 deletions

diff --git a/src/webengine/api/qquickwebenginenewviewrequest.cpp b/src/webengine/api/qquickwebenginenewviewrequest.cpp
index f2a361f55..053fcd2f6 100644
--- a/src/webengine/api/qquickwebenginenewviewrequest.cpp
+++ b/src/webengine/api/qquickwebenginenewviewrequest.cpp
@@ -39,6 +39,18 @@
 #include "qquickwebengineview_p_p.h"
 #include "web_contents_adapter.h"
 
+/*!
+    \qmltype WebEngineNewViewRequest
+    \instantiates QQuickWebEngineNewViewRequest
+    \inqmlmodule QtWebEngine 1.1
+    \since QtWebEngine 1.1
+
+    \brief A utility class for the WebEngineView::newViewRequested signal.
+
+    This class contains information about the request of a page to open a new window.
+
+    \sa WebEngineView::newViewRequested
+*/
 QQuickWebEngineNewViewRequest::QQuickWebEngineNewViewRequest()
 {
 }
@@ -47,20 +59,48 @@ QQuickWebEngineNewViewRequest::~QQuickWebEngineNewViewRequest()
 {
 }
 
+/*!
+    \qmlproperty WebEngineView::NewViewDestination WebEngineNewViewRequest::destination
+    \brief The type of view that is requested by the page.
+ */
 QQuickWebEngineView::NewViewDestination QQuickWebEngineNewViewRequest::destination() const
 {
     return m_destination;
 }
 
+/*!
+    \qmlproperty bool WebEngineNewViewRequest::isUserInitiated
+    \brief Whether this window request was directly triggered as the result of a keyboard or mouse event.
+
+    Use this property to block possibly unwanted "popups".
+ */
 bool QQuickWebEngineNewViewRequest::isUserInitiated() const
 {
     return m_isUserInitiated;
 }
 
+/*!
+    \qmlmethod WebEngineNewViewRequest::openIn(WebEngineView view)
+
+    Call this method to fulfill the request and determine which WebEngineView
+    should be used to contain the new page. Any state, history or loaded page
+    within \a view will be lost as result of this.
+
+    \sa WebEngineView::newViewRequested
+  */
 void QQuickWebEngineNewViewRequest::openIn(QQuickWebEngineView *view)
 {
-    if (view) {
-        view->d_func()->adoptWebContents(m_adapter.data());
-        m_adapter.reset();
+    if (!m_adapter) {
+        qWarning("Trying to open an empty request, it was either already used or was invalidated."
+            "\nYou must complete the request synchronously within the newViewRequested signal handler."
+            " If a view hasn't been adopted before returning, the request will be invalidated.");
+        return;
+    }
+
+    if (!view) {
+        qWarning("Trying to open a WebEngineNewViewRequest in an invalid WebEngineView.");
+        return;
     }
+    view->d_func()->adoptWebContents(m_adapter.data());
+    m_adapter.reset();
 }
diff --git a/src/webengine/api/qquickwebengineview.cpp b/src/webengine/api/qquickwebengineview.cpp
index a93cd7079..dbafd9655 100644
--- a/src/webengine/api/qquickwebengineview.cpp
+++ b/src/webengine/api/qquickwebengineview.cpp
@@ -349,6 +349,7 @@ void QQuickWebEngineViewPrivate::focusContainer()
 
 void QQuickWebEngineViewPrivate::adoptNewWindow(WebContentsAdapter *newWebContents, WindowOpenDisposition disposition, bool userGesture, const QRect &)
 {
+    Q_Q(QQuickWebEngineView);
     QQuickWebEngineNewViewRequest request;
     // This increases the ref-count of newWebContents and will tell Chromium
     // to start loading it and possibly return it to its parent page window.open().
@@ -372,7 +373,7 @@ void QQuickWebEngineViewPrivate::adoptNewWindow(WebContentsAdapter *newWebConten
         Q_UNREACHABLE();
     }
 
-    Q_EMIT e->newViewRequested(&request);
+    Q_EMIT q->newViewRequested(&request);
 }
 
 void QQuickWebEngineViewPrivate::close()
diff --git a/src/webengine/api/qquickwebengineview_p.h b/src/webengine/api/qquickwebengineview_p.h
index d625dbdd9..72620b0f7 100644
--- a/src/webengine/api/qquickwebengineview_p.h
+++ b/src/webengine/api/qquickwebengineview_p.h
@@ -44,6 +44,7 @@ QT_BEGIN_NAMESPACE
 
 class QQuickWebEngineLoadRequest;
 class QQuickWebEngineNavigationRequest;
+class QQuickWebEngineNewViewRequest;
 class QQuickWebEngineProfile;
 class QQuickWebEngineViewExperimental;
 class QQuickWebEngineViewPrivate;
@@ -156,6 +157,7 @@ Q_SIGNALS:
     void navigationRequested(QQuickWebEngineNavigationRequest *request);
     void javaScriptConsoleMessage(JavaScriptConsoleMessageLevel level, const QString &message, int lineNumber, const QString &sourceID);
     void zoomFactorChanged(qreal arg);
+    Q_REVISION(1) void newViewRequested(QQuickWebEngineNewViewRequest *request);
 
 protected:
     void geometryChanged(const QRectF &newGeometry, const QRectF &oldGeometry);
diff --git a/src/webengine/api/qquickwebengineview_p_p.h b/src/webengine/api/qquickwebengineview_p_p.h
index 964a4f0d9..cdd6b1955 100644
--- a/src/webengine/api/qquickwebengineview_p_p.h
+++ b/src/webengine/api/qquickwebengineview_p_p.h
@@ -51,7 +51,6 @@ class UIDelegatesManager;
 
 QT_BEGIN_NAMESPACE
 class QQuickWebEngineHistory;
-class QQuickWebEngineNewViewRequest;
 class QQuickWebEngineView;
 class QQmlComponent;
 class QQmlContext;
@@ -114,7 +113,6 @@ public Q_SLOTS:
     void grantFeaturePermission(const QUrl &securityOrigin, Feature, bool granted);
 
 Q_SIGNALS:
-    void newViewRequested(QQuickWebEngineNewViewRequest *request);
     void fullScreenRequested(bool fullScreen);
     void isFullScreenChanged();
     void extraContextMenuEntriesComponentChanged();