From fb612f3d2b181742730e18ca15c0944af0b743c5 Mon Sep 17 00:00:00 2001
From: Szabolcs David <davidsz@inf.u-szeged.hu>
Date: Mon, 1 Dec 2014 04:34:04 -0800
Subject: 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>
---
 .../api/qquickwebenginenewviewrequest.cpp          | 46 ++++++++++++++++++++--
 1 file changed, 43 insertions(+), 3 deletions(-)

(limited to 'src/webengine/api/qquickwebenginenewviewrequest.cpp')

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();
 }
-- 
cgit v1.2.3