From 29a58643f7e74393898813bf9ce7363ee32ac884 Mon Sep 17 00:00:00 2001 From: Michael Bruning Date: Fri, 29 Jan 2016 15:37:52 +0100 Subject: Document Chromium version also in the documentation. The changes files may not be available or obvious for all users. Change-Id: I470e8bf70ebacc34457788f595ca0fa22349e580 Task-number: QTBUG-48098 Reviewed-by: Joerg Bornemann --- src/webengine/doc/src/qtwebengine-overview.qdoc | 3 +++ 1 file changed, 3 insertions(+) (limited to 'src/webengine/doc/src/qtwebengine-overview.qdoc') diff --git a/src/webengine/doc/src/qtwebengine-overview.qdoc b/src/webengine/doc/src/qtwebengine-overview.qdoc index 53ff4b462..40e2a9a96 100644 --- a/src/webengine/doc/src/qtwebengine-overview.qdoc +++ b/src/webengine/doc/src/qtwebengine-overview.qdoc @@ -73,6 +73,9 @@ \l{https://chromium.googlesource.com/chromium/src/+/master/docs/chromium_browser_vs_google_chrome.md}{overview} that is part of the documentation in the \l {Chromium Project} upstream source tree. + This version of Qt WebEngine is based on Chromium snapshot version 45.0.2554.101, with + additional security fixes from the 46, 47 and 48 branches of the \l {Chromium Project}. + Chromium is tightly integrated to the \l{Qt Quick Scene Graph}{Qt Quick scene graph}, which is based on OpenGL ES 2.0 or OpenGL 2.0 for its rendering. This provides you with one-pass compositing of web content and all the Qt Quick UI. The integration to Chromium is transparent -- cgit v1.2.3 From 918ca3ccd62f6d9270fb0019e89b69e4bd259d60 Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Tue, 16 Feb 2016 15:20:28 +0100 Subject: Doc: Link to Platform Notes from the Overview Task-number: QTBUG-51138 Change-Id: I292b23d450f393fca2dd0a9b12d903309a6000bc Reviewed-by: Kai Koehne --- src/webengine/doc/src/qtwebengine-overview.qdoc | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'src/webengine/doc/src/qtwebengine-overview.qdoc') diff --git a/src/webengine/doc/src/qtwebengine-overview.qdoc b/src/webengine/doc/src/qtwebengine-overview.qdoc index 40e2a9a96..f67adbaf6 100644 --- a/src/webengine/doc/src/qtwebengine-overview.qdoc +++ b/src/webengine/doc/src/qtwebengine-overview.qdoc @@ -46,6 +46,10 @@ application to use Qt WebEngine widgets, see \l{Porting from Qt WebKit to Qt WebEngine}. For new applications, we recommend using Qt Quick and the WebEngineView QML type. + For more information about the requirements for building Qt WebEngine from source on the + supported platforms and for other platform-specific information, see + \l{Qt WebEngine Platform Notes}. + \section1 Qt WebEngine Architecture \image qtwebengine-architecture.png -- cgit v1.2.3 From 77912347e6cd1a024d600cf66a1bb75638acf20e Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Wed, 24 Feb 2016 11:06:55 +0100 Subject: Doc: Improve the overview - Add module diagrams and descriptions of main classes - Add initializing Qt WebEngine Change-Id: I29f3e9aadbcc86b09c722d1c63b4a5c2c585d215 Reviewed-by: Allan Sandfeld Jensen --- src/webengine/doc/src/qtwebengine-overview.qdoc | 99 +++++++++++++++++++++---- 1 file changed, 84 insertions(+), 15 deletions(-) (limited to 'src/webengine/doc/src/qtwebengine-overview.qdoc') diff --git a/src/webengine/doc/src/qtwebengine-overview.qdoc b/src/webengine/doc/src/qtwebengine-overview.qdoc index f67adbaf6..36866a6b5 100644 --- a/src/webengine/doc/src/qtwebengine-overview.qdoc +++ b/src/webengine/doc/src/qtwebengine-overview.qdoc @@ -50,6 +50,9 @@ supported platforms and for other platform-specific information, see \l{Qt WebEngine Platform Notes}. + The \l {Qt WebChannel} module can be used to create a bi-directional communication channel + between QObject objects on the C++ side and JavaScript on the QML side. + \section1 Qt WebEngine Architecture \image qtwebengine-architecture.png @@ -57,14 +60,38 @@ The functionality in Qt WebEngine is divided into the following modules: \list - \li \l{Qt WebEngine Widgets}, which provides a web browser engine and C++ classes to render - web content and to interact with it - \li \l{Qt WebEngine}, which provides QML types for rendering web content within a QML - application - \li \l{Qt WebEngine Core}, which provides common API used by Qt WebEngine and - Qt WebEngine Widgets + \li \l{Qt WebEngine Widgets} for creating widget-based web applications + \li \l{Qt WebEngine} for creating Qt Quick based web applications + \li \l{Qt WebEngine Core} for interacting with Chromium \endlist + Page rendering and JavaScript execution are separated from the GUI process into the Qt WebEngine + Process. It is a library that must be shipped with the application if the Qt libraries are + bundled into the application. + + \section2 Qt WebEngine Widgets + + \image qtwebenginewidgets-model.png + + A \e {web engine view} is the main widget component of the Qt WebEngine module. It can be used + in various applications to load web content. Within a view, a \e {web engine page} holds a main + frame that is responsible for web content, the \e history of navigated links, and \e actions. + The view and page are quite similar, as they provide a set of common functions. + + All pages belong to a \e {web engine profile} that contains shared \e settings, \e scripts, and + \e cookies. Profiles can be used to isolate pages from each other. A typical use case is a + dedicated profile for a \e {private browsing} mode, where no information is permanently saved. + + \section2 Qt WebEngine + + \image qtwebengine-model.png + + The Qt WebEngine QML implementation contains the same elements as the C++ implementation, + except that there is no separately accessible web engine page. The supported page functionality + is integrated into the web engine view. + + \section2 Qt WebEngine Core + The Qt WebEngine core is based on the \l {Chromium Project}. Chromium provides its own network and painting engines and is developed tightly together with its dependent modules, and therefore Qt WebEngine provides better and more reliable support for the latest HTML5 @@ -80,12 +107,29 @@ This version of Qt WebEngine is based on Chromium snapshot version 45.0.2554.101, with additional security fixes from the 46, 47 and 48 branches of the \l {Chromium Project}. + \section2 Qt WebEngine Process + + The Qt WebEngine Process renders web pages and executes JavaScript. + Chromium is tightly integrated to the \l{Qt Quick Scene Graph}{Qt Quick scene graph}, which is based on OpenGL ES 2.0 or OpenGL 2.0 for its rendering. This provides you with one-pass compositing of web content and all the Qt Quick UI. The integration to Chromium is transparent to developers, who just work with Qt and JavaScript. - To expose QObjects to JavaScript, developers can use the \l {Qt WebChannel} module. + The document object model (DOM) of a page is constructed when the document is ready, typically + when the page is completely loaded. Therefore, executing scripts as soon as a document is + created is not suitable for DOM operations, where one has to wait until the DOM is ready. + + In addition, an injected script shares the same \e world as the other scripts executed on the + page, which might lead to conflicts. To avoid this, the Chromium API for + \e{Content Script Extensions} is implemented by \e {web engine script}. It specifies the + script to run, the injection point, and the world where the script is run. This enables + accessing the DOM to manipulate it within a world. + + Because the render process is separated from the GUI process, they should ideally share an + OpenGL context to enable one process to access the resources uploaded by the other, such as + images or textures. However, some inter-process communication is needed for safety and + reliability, because it enables restarting a crashed process. \section1 Embedding Web Content into Widget Based Applications @@ -99,23 +143,48 @@ view->show(); \endcode - An instance of QWebEngineView has one QWebEnginePage. QWebEnginePage provides access to the - page's navigation history and the ability to run JavaScript code in the context of the page's - main frame and enables customization of handlers for specific events like showing custom - authentication dialogs. + An instance of QWebEngineView has one QWebEnginePage. QWebEnginePage can have a + QWebEngineHistory that provides access to the page's navigation history and several QAction + objects that apply actions on the web page. In addition, a QWebEnginePage has the ability to + run JavaScript code in the context of the page's main frame and to enable customization of + handlers for specific events like showing custom authentication dialogs. + + Each QWebEnginePage belongs to a QWebEngineProfile that can have a QWebEngineScriptCollection + for specifying page settings, a QWebEngineScriptCollection for running scripts on the page, and + a QWebEngineCookieStore for accessing the HTTP cookies of Chromium. A QWebEnginePage can also + directly point to a script collection or cookie store. \section1 Embedding Web Content into Qt Quick Applications - The WebEngineView QML type allows QML applications to render regions of dynamic web content. A - \e{WebEngineView} type may share the screen with other QML types or encompass the full screen - as specified within the QML application. + The WebEngineView QML type allows Qt Quick applications to render regions of dynamic web + content. A \e{WebEngineView} type may share the screen with other QML types or encompass the + full screen as specified within the Qt Quick application. + + To make sure that OpenGL context can be shared between the GUI and render processes, the web + engine must be initialized by using \l QtWebEngine::initialize in the application main source + file, as illustrated by the following code snippet: + + \code + int main(int argc, char **argv) + { + Application app(argc, argv); + + QtWebEngine::initialize(); + + QQmlApplicationEngine appEngine; + appEngine.load(QUrl("qrc:/main.qml")); + + return app.exec(); + } + \endcode An application can load pages into the WebEngineView, using either an URL or HTML string, and navigate within session history. By default, links to different pages load within the same WebEngineView object, but web sites may request them to be opened as a new tab, window, or dialog. - The following sample QML application loads a web page and responds to session history context: + The following sample QML application loads a web page using the \l{WebEngineView::}{url} + property: \qml import QtQuick 2.1 -- cgit v1.2.3 From ea5b3418f2da62797ab7995bb87cbe7ce2c6150a Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Thu, 25 Feb 2016 10:10:35 +0100 Subject: Doc: fix copy/paste error in the overview Change-Id: Id9d633f5a68d563d2266743c5ecd2572f9da89c2 Reviewed-by: Kai Koehne --- src/webengine/doc/src/qtwebengine-overview.qdoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/webengine/doc/src/qtwebengine-overview.qdoc') diff --git a/src/webengine/doc/src/qtwebengine-overview.qdoc b/src/webengine/doc/src/qtwebengine-overview.qdoc index 36866a6b5..9dc78a736 100644 --- a/src/webengine/doc/src/qtwebengine-overview.qdoc +++ b/src/webengine/doc/src/qtwebengine-overview.qdoc @@ -149,7 +149,7 @@ run JavaScript code in the context of the page's main frame and to enable customization of handlers for specific events like showing custom authentication dialogs. - Each QWebEnginePage belongs to a QWebEngineProfile that can have a QWebEngineScriptCollection + Each QWebEnginePage belongs to a QWebEngineProfile that can have a QWebEngineSettings for specifying page settings, a QWebEngineScriptCollection for running scripts on the page, and a QWebEngineCookieStore for accessing the HTTP cookies of Chromium. A QWebEnginePage can also directly point to a script collection or cookie store. -- cgit v1.2.3