Add initialize function

The initialization function will set-up any platform specific
requirements needed to display the WebView correctly.
Initially we tried to avoid this, as it's not a very nice approach, and
it was only needed when QtWebEngine back-end was the used (see:
QtWebEngine::initialize()). Since we now require special set-up for OS X
as well, it has become unreasonable to expect that the user should
implement this logic in their application and that it's more convenient
if we provide a uniform solution to make the WebView work on all
platforms.
The implication of this change, is that we now actually expose a C++ API
and will therefore need to export the module again
(making it a non-internal module).

Change-Id: I87678db7cd50b25465bcf623c008f04a4cffd7df
Reviewed-by: Eskil Abrahamsen Blomfeldt <eskil.abrahamsen-blomfeldt@theqtcompany.com>

8 files changed, 141 insertions, 23 deletions

diff --git a/examples/webview/minibrowser/main.cpp b/examples/webview/minibrowser/main.cpp
index 04d6097..5daecc0 100644
--- a/examples/webview/minibrowser/main.cpp
+++ b/examples/webview/minibrowser/main.cpp
@@ -46,10 +46,7 @@
 #include <QScreen>
 #include <QQmlApplicationEngine>
 #include <QtQml/QQmlContext>
-
-#ifdef QT_WEBVIEW_WEBENGINE_BACKEND
-#include <QtWebEngine>
-#endif // QT_WEBVIEW_WEBENGINE_BACKEND
+#include <QtWebView/QtWebView>
 
 // Workaround: As of Qt 5.4 QtQuick does not expose QUrl::fromUserInput.
 class Utils : public QObject {
@@ -74,17 +71,7 @@ int main(int argc, char *argv[])
     QGuiApplication app(argc, argv);
     QGuiApplication::setApplicationDisplayName(QCoreApplication::translate("main",
                                                                            "QtWebView Example"));
-#ifdef Q_OS_OSX
-    // On OS X, correct WebView / QtQuick compositing and stacking requires running
-    // Qt in layer-backed mode, which again resuires rendering on the Gui thread.
-    qWarning("Setting QT_MAC_WANTS_LAYER=1 and QSG_RENDER_LOOP=basic");
-    qputenv("QT_MAC_WANTS_LAYER", "1");
-    qputenv("QSG_RENDER_LOOP", "basic");
-#endif
-
-#ifdef QT_WEBVIEW_WEBENGINE_BACKEND
-    QtWebEngine::initialize();
-#endif // QT_WEBVIEW_WEBENGINE_BACKEND
+    QtWebView::initialize();
     QCommandLineParser parser;
     QCoreApplication::setApplicationVersion(QT_VERSION_STR);
     parser.setApplicationDescription(QGuiApplication::applicationDisplayName());
diff --git a/examples/webview/minibrowser/minibrowser.pro b/examples/webview/minibrowser/minibrowser.pro
index a95b6d4..c7ffb31 100644
--- a/examples/webview/minibrowser/minibrowser.pro
+++ b/examples/webview/minibrowser/minibrowser.pro
@@ -1,11 +1,6 @@
 TEMPLATE = app
 
-QT += qml quick
-
-!osx:qtHaveModule(webengine) {
-        QT += webengine
-        DEFINES += QT_WEBVIEW_WEBENGINE_BACKEND
-}
+QT += qml quick webview
 
 SOURCES += main.cpp
 
diff --git a/src/webview/doc/qtwebview.qdocconf b/src/webview/doc/qtwebview.qdocconf
index 93855f1..caf3037 100644
--- a/src/webview/doc/qtwebview.qdocconf
+++ b/src/webview/doc/qtwebview.qdocconf
@@ -16,6 +16,7 @@ qhp.QtWebView.customFilters.Qt.name             = QtWebView 1.0
 qhp.QtWebView.customFilters.Qt.filterAttributes = qtwebview 1.0
 
 qhp.QtWebView.subprojects                       = qmltypes examples
+qhp.QtWebView.subprojects.classes.selectors     = class function namespace fake:headerfile
 qhp.QtWebView.subprojects.qmltypes.title        = QML Types
 qhp.QtWebView.subprojects.qmltypes.indexTitle   = Qt WebView QML Types
 qhp.QtWebView.subprojects.qmltypes.selectors    = qmlclass
diff --git a/src/webview/doc/src/qtwebview-overview.qdoc b/src/webview/doc/src/qtwebview-overview.qdoc
index b485893..8a0643b 100644
--- a/src/webview/doc/src/qtwebview-overview.qdoc
+++ b/src/webview/doc/src/qtwebview-overview.qdoc
@@ -38,6 +38,13 @@
   This is especially important on platforms such as iOS, where policy dictates
   that all web content is displayed using the operating system's web view.
 
+  \section1 Prerequisites
+
+  To make the Qt WebView module function correctly across all platforms, it's necessary
+  that \b QtWebView::initialize() is called right after the \b QGuiApplication instance is created.
+
+  \sa QtWebView::initialize()
+
   \section1 QML Types
 
   The module provides a single QML component for displaying web content in
diff --git a/src/webview/qtwebviewfunctions.cpp b/src/webview/qtwebviewfunctions.cpp
new file mode 100644
index 0000000..2f917b2
--- /dev/null
+++ b/src/webview/qtwebviewfunctions.cpp
@@ -0,0 +1,74 @@
+/****************************************************************************
+**
+** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the QtWebEngine module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 3 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPLv3 included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 3 requirements
+** will be met: https://www.gnu.org/licenses/lgpl.html.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 2.0 or later as published by the Free
+** Software Foundation and appearing in the file LICENSE.GPL included in
+** the packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 2.0 requirements will be
+** met: http://www.gnu.org/licenses/gpl-2.0.html.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include "qtwebviewfunctions.h"
+
+#ifdef QT_WEBVIEW_WEBENGINE_BACKEND
+#include <QtWebEngine/qtwebengineglobal.h>
+#endif // QT_WEBVIEW_WEBENGINE_BACKEND
+
+QT_BEGIN_NAMESPACE
+
+/*!
+    \namespace QtWebView
+    \inmodule QtWebView
+    \brief The QtWebView namespace provides functions that makes it easier to set-up and use the WebView.
+    \inheaderfile QtWebView
+*/
+
+/*!
+    \fn void QtWebView::initialize()
+
+    This function initializes resources or sets options that are required by the different back-ends.
+
+    \note The \c initialize() function needs to be called immediately after the QGuiApplication
+    instance is created.
+ */
+
+void QtWebView::initialize()
+{
+#if defined(QT_WEBVIEW_WEBENGINE_BACKEND)
+    QtWebEngine::initialize();
+#elif defined(Q_OS_OSX)
+    // On OS X, correct WebView / QtQuick compositing and stacking requires running
+    // Qt in layer-backed mode, which again resuires rendering on the Gui thread.
+    qWarning("Setting QT_MAC_WANTS_LAYER=1 and QSG_RENDER_LOOP=basic");
+    qputenv("QT_MAC_WANTS_LAYER", "1");
+    qputenv("QSG_RENDER_LOOP", "basic");
+#endif
+}
+
+QT_END_NAMESPACE
diff --git a/src/webview/qtwebviewfunctions.h b/src/webview/qtwebviewfunctions.h
new file mode 100644
index 0000000..3d5c252
--- /dev/null
+++ b/src/webview/qtwebviewfunctions.h
@@ -0,0 +1,51 @@
+/****************************************************************************
+**
+** Copyright (C) 2015 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** This file is part of the QtWebView module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL3$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see http://www.qt.io/terms-conditions. For further
+** information use the contact form at http://www.qt.io/contact-us.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 3 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPLv3 included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 3 requirements
+** will be met: https://www.gnu.org/licenses/lgpl.html.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 2.0 or later as published by the Free
+** Software Foundation and appearing in the file LICENSE.GPL included in
+** the packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 2.0 requirements will be
+** met: http://www.gnu.org/licenses/gpl-2.0.html.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#ifndef QTWEBVIEWFUNCTIONS_H
+#define QTWEBVIEWFUNCTIONS_H
+
+#include <QtWebView/qwebview_global.h>
+
+QT_BEGIN_NAMESPACE
+
+namespace QtWebView
+{
+    Q_WEBVIEW_EXPORT void initialize();
+}
+
+QT_END_NAMESPACE
+
+#endif // QTWEBVIEWFUNCTIONS_H
diff --git a/src/webview/webview-lib.pri b/src/webview/webview-lib.pri
index 320e947..3577915 100644
--- a/src/webview/webview-lib.pri
+++ b/src/webview/webview-lib.pri
@@ -6,7 +6,11 @@ ANDROID_JAR_DEPENDENCIES = \
 INCLUDEPATH += $$PWD
 
 PUBLIC_HEADERS += \
-    qwebview_global.h
+    qwebview_global.h \
+    qtwebviewfunctions.h
+
+SOURCES += \
+    qtwebviewfunctions.cpp
 
 COMMON_HEADERS += \
     qwebview_p.h \
diff --git a/src/webview/webview.pro b/src/webview/webview.pro
index 48db44b..6b0eb41 100644
--- a/src/webview/webview.pro
+++ b/src/webview/webview.pro
@@ -3,7 +3,6 @@ include($$PWD/webview-lib.pri)
 load(qt_build_config)
 
 TARGET = QtWebView
-CONFIG += internal_module
 
 QT += core-private gui-private qml-private quick-private quick qml