From 4dde65da1cec9699f5d371d1ffdcd157b11cf87a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=BCri=20Valdmann?= Date: Fri, 20 Jul 2018 15:57:17 +0200 Subject: Add webui example Example of using QWebEngineUrlScheme and QWebEngineUrlSchemeHandler. Change-Id: I1316831600e7c9b8f7ca7b205ecb3c29bfcdcd84 Reviewed-by: Allan Sandfeld Jensen Reviewed-by: Leena Miettinen Reviewed-by: Michal Klocek --- examples/webenginewidgets/webenginewidgets.pro | 3 +- examples/webenginewidgets/webui/about.html | 129 ++++++++++++++++ .../webui/doc/images/webui-example.png | Bin 0 -> 28862 bytes examples/webenginewidgets/webui/doc/src/webui.qdoc | 165 +++++++++++++++++++++ examples/webenginewidgets/webui/main.cpp | 80 ++++++++++ examples/webenginewidgets/webui/webui.pro | 16 ++ examples/webenginewidgets/webui/webui.qrc | 5 + examples/webenginewidgets/webui/webuihandler.cpp | 94 ++++++++++++ examples/webenginewidgets/webui/webuihandler.h | 67 +++++++++ 9 files changed, 558 insertions(+), 1 deletion(-) create mode 100644 examples/webenginewidgets/webui/about.html create mode 100644 examples/webenginewidgets/webui/doc/images/webui-example.png create mode 100644 examples/webenginewidgets/webui/doc/src/webui.qdoc create mode 100644 examples/webenginewidgets/webui/main.cpp create mode 100644 examples/webenginewidgets/webui/webui.pro create mode 100644 examples/webenginewidgets/webui/webui.qrc create mode 100644 examples/webenginewidgets/webui/webuihandler.cpp create mode 100644 examples/webenginewidgets/webui/webuihandler.h (limited to 'examples/webenginewidgets') diff --git a/examples/webenginewidgets/webenginewidgets.pro b/examples/webenginewidgets/webenginewidgets.pro index eb4e1f287..20c7ead50 100644 --- a/examples/webenginewidgets/webenginewidgets.pro +++ b/examples/webenginewidgets/webenginewidgets.pro @@ -10,7 +10,8 @@ SUBDIRS += \ html2pdf \ simplebrowser \ stylesheetbrowser \ - videoplayer + videoplayer \ + webui qtConfig(webengine-geolocation): SUBDIRS += maps qtConfig(webengine-webchannel): SUBDIRS += markdowneditor diff --git a/examples/webenginewidgets/webui/about.html b/examples/webenginewidgets/webui/about.html new file mode 100644 index 000000000..7b5a58969 --- /dev/null +++ b/examples/webenginewidgets/webui/about.html @@ -0,0 +1,129 @@ + + + + Qt WebEngine WebUI Example + + + +

WebEngine Widgets
WebUI Example

+ Aside from the built-in schemes, such as http and + qrc, Qt WebEngine may be extended with custom + schemes by creating custom scheme handlers. +

+ +

+ This is a simple HTML page loaded from a custom scheme and + displayed by a QWebEngineView. Even the Quit button + below is a standard HTML <button> element. +

+ +

+ Read the documentation to find out +

+
+ How to create a custom scheme handler which serves HTML + and handles HTML form submissions. +
+
+
+ How to prevent ordinary web content from accessing the + custom scheme. +
+
+
+ How to prevent any other scheme from submitting HTML + form data. +
+

+ + + diff --git a/examples/webenginewidgets/webui/doc/images/webui-example.png b/examples/webenginewidgets/webui/doc/images/webui-example.png new file mode 100644 index 000000000..84e2c7fc3 Binary files /dev/null and b/examples/webenginewidgets/webui/doc/images/webui-example.png differ diff --git a/examples/webenginewidgets/webui/doc/src/webui.qdoc b/examples/webenginewidgets/webui/doc/src/webui.qdoc new file mode 100644 index 000000000..d5eb13d02 --- /dev/null +++ b/examples/webenginewidgets/webui/doc/src/webui.qdoc @@ -0,0 +1,165 @@ +/**************************************************************************** +** +** Copyright (C) 2018 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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 https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example webenginewidgets/webui + \title WebEngine Widgets WebUI Example + \ingroup webengine-widgetexamples + \brief Displays HTML over a custom scheme. + + \image webui-example.png + + \e {WebUI} demonstrates how to implement a custom scheme in a secure way. + + Aside from the built-in URL schemes, such as \c {http} and \c {qrc}, Qt + WebEngine may be extended with \e {custom schemes} by creating \e {custom + scheme handlers}. This example shows: + + \list + \li How to create a custom scheme handler which serves HTML and handles + HTML form submissions. + \li How to prevent ordinary web content from accessing the custom scheme. + \li How to prevent any other scheme from submitting HTML form data. + \endlist + + \include examples-run.qdocinc + + \section1 Overview + + The example program consists of a single \l {QWebEngineView} showing a + simple HTML page loaded from the URL \c {webui:about}, over our custom + scheme. Pressing the button at the bottom of the page will trigger an HTML + form submission via POST to the same URL, at which point our custom scheme + handler will cause the application to exit. + + The program is divided into two parts, the \c {main} function for setting + everything up, and the \c {WebUiHandler} class for implementing our custom + scheme handler. The \c {main} function is quite short: + + \quotefromfile webenginewidgets/webui/main.cpp + \skipto int main + \printuntil /^\}/ + + Aside from the relatively standard setup of widgets, two points are + noteworthy. First, we call the static method \c + {WebUiHandler::registerUrlScheme()} to register our custom scheme with the + web engine. Second, we create and install our custom scheme handler \c + {WebUiHandler} using \l + {QWebEngineProfile::installUrlSchemeHandler()}{installUrlSchemeHandler()}. + The following sections describe these aspects in more detail. + + \section1 Registering the Scheme + + As custom schemes are integrated directly into the web engine, they do not + necessarily need to follow the standard security rules which apply to + ordinary web content. Depending on the chosen configuration, content served + over a custom scheme may be given access to local resources, be set to + ignore Content-Security-Policy rules, or conversely, be denied access to any + other content entirely. + + In order to take advantage of these possibilities, the custom scheme must + first be registered. This means creating and configuring a \l + {QWebEngineUrlScheme} object and then handing it over to \l + {QWebEngineUrlScheme::addScheme()}. The example program does exactly this in + the static method \c {WebUiHandler::registerUrlScheme()}: + + \quotefromfile webenginewidgets/webui/webuihandler.cpp + \skipto void WebUiHandler::registerUrlScheme + \printuntil /^\}/ + + A custom scheme needs a name, which can be set by passing it to + the constructor of \c {QWebEngineUrlScheme} or by calling \l + {QWebEngineUrlScheme::setName}. In the above, the name \c {webui} is set + through the constructor. Additionally, we activate the flags \l + {QWebEngineUrlScheme::Secure}{Secure}, \l + {QWebEngineUrlScheme::Local}{Local} and \l + {QWebEngineUrlScheme::LocalAccessAllowed}{LocalAccessAllowed}. Since our + custom scheme handler will not deliver resources received from insecure + network connections, we can safely mark it as \c {Secure}. The \c {Local} + flag prevents content from non-local schemes (such as \c {http}) from + interacting with our custom scheme. Without this flag it would be possible, + for example, to embed the \c {webui:about} page in an \c