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>

1 files changed, 43 insertions, 3 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();
 }