diff options
Diffstat (limited to 'examples/webenginequick/quicknanobrowser/doc/src/quicknanobrowser.qdoc')
| -rw-r--r-- | examples/webenginequick/quicknanobrowser/doc/src/quicknanobrowser.qdoc | 187 |
1 files changed, 187 insertions, 0 deletions
diff --git a/examples/webenginequick/quicknanobrowser/doc/src/quicknanobrowser.qdoc b/examples/webenginequick/quicknanobrowser/doc/src/quicknanobrowser.qdoc new file mode 100644 index 000000000..1dc209c2e --- /dev/null +++ b/examples/webenginequick/quicknanobrowser/doc/src/quicknanobrowser.qdoc @@ -0,0 +1,187 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \example webenginequick/quicknanobrowser + \title WebEngine Quick Nano Browser + \ingroup webengine-examples + \brief A web browser implemented using the WebEngineView QML type. + + \image quicknanobrowser-demo.jpg + \examplecategory {Application Examples} + \examplecategory {Web Technologies} + + \e {Quick Nano Browser} demonstrates how to use the \l{Qt WebEngine QML Types} + {Qt WebEngine QML types} to develop a small web browser application that consists of a browser + window with a title bar, toolbar, tab view, and status bar. The web content is loaded in a web + engine view within the tab view. If certificate errors occur, users are prompted for action in a + message dialog. The status bar pops up to display the URL of a hovered link. + + A web page can issue a request for being displayed in fullscreen mode. Users can allow full + screen mode by using a toolbar button. They can leave fullscreen mode by using a keyboard + shortcut. Additional toolbar buttons enable moving backwards and forwards in the browser + history, reloading tab content, and opening a settings menu for enabling the following features: + JavaScript, plugins, fullscreen mode, off the record, HTTP disk cache, autoloading images, and + ignoring certificate errors. + + \include examples-run.qdocinc + + \section1 Creating the Main Browser Window + + When the browser main window is loaded, it creates an empty tab using the default profile. Each + tab is a web engine view that fills the main window. + + We create the main window in the \e BrowserWindow.qml file using the ApplicationWindow type: + + \quotefromfile webenginequick/quicknanobrowser/BrowserWindow.qml + \skipto ApplicationWindow + \printuntil currentWebView + \dots + \skipto width + \printuntil title + + We use the TabBar Qt Quick control to create a tab bar anchored to the top of the window, and + create a new, empty tab: + + \skipto TabBar { + \printuntil return webview + \printuntil } + + The tab contains a web engine view that loads web content: + + \skipto Component { + \printuntil currentWebView.reload + \printuntil /^\ {8}\}/ + + We use the \l Action type to create new tabs: + + \quotefromfile webenginequick/quicknanobrowser/BrowserWindow.qml + \skipto reload + \skipto Action + \printuntil } + + We use the \l TextField Qt Quick Control within a \l ToolBar to create an address bar that + shows the current URL and where users can enter another URL: + + \quotefromfile webenginequick/quicknanobrowser/BrowserWindow.qml + \skipto menuBar: ToolBar + \printuntil anchors.fill + \dots + \skipto TextField + \printuntil addressBar + \dots + \skipto focus + \printuntil /^\ {12}\}/ + + \section1 Handling Certificate Errors + + If the certificate of the site being loaded triggers a certificate error, we call the + \l{WebEngineCertificateError::}{defer()} QML method to pause the URL request and wait for user + input: + + \quotefromfile webenginequick/quicknanobrowser/BrowserWindow.qml + \skipto onCertificateError + \printuntil } + + We use the Dialog type to prompt users to continue or cancel the loading of the web page. + If users select \uicontrol Yes, we call the + \l{WebEngineCertificateError::}{acceptCertificate()} method to continue loading content from + the URL. If users select \uicontrol No, we call the + \l{WebEngineCertificateError::}{rejectCertificate()} method to reject the request and stop + loading content from the URL: + + \skipto Dialog { + \printuntil /^\ {4}\}/ + + \section1 Handling Feature Permission Requests + + We use the \c onFeaturePermissionRequested() signal handler to handle requests for + accessing a certain feature or device. The \c securityOrigin parameter identifies the + requester web site, and the \c feature parameter is the requested feature. We use these + to construct the message of the dialog: + + \quotefromfile webenginequick/quicknanobrowser/BrowserWindow.qml + \skipto onFeaturePermissionRequested + \printuntil } + + We show a dialog where the user is asked to grant or deny access. The custom + \c questionForFeature() JavaScript function generates a human-readable question about + the request. + If users select \uicontrol Yes, we call the \l{WebEngineView::}{grantFeaturePermission()} + method with a third \c true parameter to grant the \c securityOrigin web site the permission + to access the \c feature. + If users select \uicontrol No, we call the same method but with the \c false parameter to + deny access: + + \skipto id: sslDialog + \skipto Dialog { + \printuntil /^\ {4}\}/ + + + \section1 Entering and Leaving Fullscreen Mode + + We create a menu item for allowing fullscreen mode in a settings menu that we place on the tool + bar. Also, we create an action for leaving fullscreen mode by using a keyboard shortcut. + We call the \l{FullScreenRequest::}{accept()} method to accept the fullscreen request. + The methdod sets the \l{WebEngineView::}{isFullScreen} property to be equal to the + \l{FullScreenRequest::}{toggleOn} property. + + \quotefromfile webenginequick/quicknanobrowser/BrowserWindow.qml + \skipto onFullScreenRequested + \printuntil /^\ {16}\}/ + + When entering fullscreen mode, we display a notification using the FullScreenNotification custom + type that we create in \e FullScreenNotification.qml. + + We use the \l Action type in the settings menu to create a shortcut for leaving fullscreen mode + by pressing the escape key: + + \quotefromfile webenginequick/quicknanobrowser/BrowserWindow.qml + \skipto Settings + \printuntil appSettings + \skipto fullScreenSupportEnabled + \printuntil Action + \skipto Escape + \printuntil /^\ {4}\}/ + + \section1 Handling WebAuth/FIDO UX Requests + + We use the \c onWebAuthUxRequested() signal handler to handle requests for + WebAuth/FIDO UX. The \c request parameter is an instance of WebEngineWebAuthUxRequest + which contains UX request details and APIs required to process the request. + We use it to construct WebAuthUX dialog and initiates the UX request flow. + + \quotefromfile webenginequick/quicknanobrowser/BrowserWindow.qml + \skipto onWebAuthUxRequested + \printuntil } + + The \l WebEngineWebAuthUxRequest object periodically emits the \l + {WebEngineWebAuthUxRequest::}{stateChanged} signal to notify potential + observers of the current WebAuth UX states. The observers update the WebAuth + dialog accordingly. We use onStateChanged() signal handler to handle + state change requests. See \c WebAuthDialog.qml for an example + of how these signals can be handled. + + \quotefromfile webenginequick/quicknanobrowser/WebAuthDialog.qml + \skipto Connections + \printuntil } + \skipto function init(request) + \printuntil } + + \section1 Signing Requirement for macOS + + To allow web sites access to the location, camera, and microphone when running + \e {Quick Nano Browser} on macOS, the application needs to be signed. This is + done automatically when building, but you need to set up a valid signing identity + for the build environment. + + \section1 Files and Attributions + + The example uses icons from the Tango Icon Library: + + \table + \row + \li \l{quicknanobrowser-tango}{Tango Icon Library} + \li Public Domain + \endtable +*/ |