path: root/src/webengine/doc/src/qtwebengine-features.qdoc

/****************************************************************************
**
** Copyright (C) 2017 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$
**
****************************************************************************/

/*!
    \page qtwebengine-features.html
    \title Qt WebEngine Features

    \brief Summarizes Qt WebEngine features.

    Qt WebEngine supports the following features:

    \list
        \li \l{Audio and Video Codecs}
        \li \l{Chromium DevTools}
        \li \l{Client Certificates}
        \li \l{Drag and Drop}
        \li \l{Fullscreen}
        \li \l{HTML5 DRM}
        \li \l{HTML5 Geolocation}
        \li \l{HTTP/2 Protocol}
        \li \l{Native Dialogs}
        \li \l{Pepper Plugin API}
        \li \l{Print to PDF}
        \li \l{Process Models}
        \li \l{Spellchecker}
        \li \l{Touch}
        \li \l{View Source}
        \li \l{WebRTC}
        \li \l{Notifications}
    \endlist

    \section1 Audio and Video Codecs

    Qt WebEngine supports the MPEG-4 Part 14 (MP4) file format only if the
    required proprietary audio and video codecs, such as H.264 and MPEG layer-3
    (MP3), have been enabled. Proprietary codecs can be enabled by passing the
    following option to the \c configure tool when configuring Qt:

    \code
    -webengine-proprietary-codecs
    \endcode

    For example, the following option could be passed when configuring Qt for
    building it at the top level:

    \code
    configure -webengine-proprietary-codecs
    \endcode

    For more information, see \l{Qt Configure Options}.

    When using qmake to build just the Qt WebEngine module, the following
    command can be used (in this example, the Qt WebEngine source code is
    located in \c {C:\qt\qtwebengine}):

    \code
    qmake C:\qt\qtwebengine -- -webengine-proprietary-codecs
    \endcode

    \warning When distributing proprietary codec libraries, you must acquire
    licenses for them.

    \l FFmpeg is a cross-platform solution to record, convert, and stream audio
    and video. It can be configured for use with several codecs, which rises
    licensing issues during distribution with the codec libraries. For some
    codecs, open source implementations, such as \l{OpenH264 Project Homepage}
    {OpenH264}, are available.

    \section1 Chromium DevTools

    The Chromium DevTools provide the ability to inspect and debug layout and
    performance issues of any web content.

    This feature can be tested by launching a Qt WebEngine application with the
    command line option \c {--remote-debugging-port=[your-port]} or by setting
    the environment variable \c QTWEBENGINE_REMOTE_DEBUGGING, and then using a
    Chromium based browser (such as \l{WebEngine Widgets Simple Browser Example}
    {Simple Browser} or \l{WebEngine Quick Nano Browser}{Nano Browser}) to connect
    to \c {http://localhost:[your-port]}.

    The Chromium DevTools page can also be shown within the application. To set
    this up, you can call either QWebEnginePage::setInspectedPage() to the page
    to be inspected, which implicitly loads the DevTools into the \c this page,
    or QWebEnginePage::setDevToolsPage() to let the \c this page be inspected.

    The respective QML properties are \l{WebEngineView::devToolsView}
    {WebEngineView.devToolsView} and \l{WebEngineView::inspectedView}
    {WebEngineView.inspectedView}.

    For more information, see \l {Qt WebEngine Debugging and Profiling}.

    \section1 Client Certificates

    Some web servers, in particular many intranet sites, require the client to
    authenticate itself with a certificate, called a \e {client certificate}. Qt WebEngine
    will read the client certificates installed in the system settings in macOS and
    Windows, and on Linux those installed into the NSS database. Certificates can
    be installed into the NSS database using the \c pk12util tool.

    By default, QtWebEngine will not offer any client certificates to servers, as doing
    so uniquely identifies the user and might violate privacy expectations.

    To activate support for client certificates, an application needs to listen to
    the QWebEnginePage::selectClientCertificate signal and select one of the offered
    certificates. For applications that can navigate to untrusted web sites, it is
    recommended to always give the user a choice before uniquely identifying them
    to a remote server.

    \section1 Custom Schemes

    Qt WebEngine makes it possible for the application to define its own custom
    URL schemes with specialized security policies and transport mechanisms.

    Custom schemes can be used to implement alternative network protocols with
    all the usual web security policies, privileged internal schemes for
    displaying user interface compoments or debugging information, sandboxed
    schemes with extra restrictions, and so on.

    For more information, see \l QWebEngineUrlScheme and \l
    QWebEngineUrlSchemeHandler.

    \section1 Drag and Drop

    Qt WebEngine supports HTML5 drag and drop.

    This feature can be tested by opening an HTML5 drag and drop demo, such as
    \l{HTML5 Demos - Drag and Drop}, \l{HTML5 Demos - Simple Drag and Drop}, or
    \l{HTML5 Demos - Drag and Drop, Automatic Upload}, in \l{WebEngine Widgets
    Simple Browser Example}{Simple Browser} or \l{WebEngine Quick Nano Browser}
    {Nano Browser}.

    Dragging files into the browser is not actually part of HTML5, but it is
    supported. It can be tested by opening \l{HTML5 Demos - File API}.

    Support for this feature was added in Qt 5.7.0.

    \section1 Fullscreen

    Qt WebEngine supports viewing web content in fullscreen mode. For more
    information, see \l{WebEngineSettings::fullscreenSupportEnabled}
    {WebEngineSettings.fullscreenSupportEnabled},
    \l{WebEngineView::fullScreenRequested}{WebEngineView.fullScreenRequested},
    QWebEngineSettings::FullScreenSupportEnabled, and
    QWebEnginePage::fullScreenRequested.

    This feature can be tested by playing a video from YouTube in \l{WebEngine
    Widgets Video Player Example}{Video Player} or \l{WebEngine Quick Nano Browser}
    {Nano Browser}, and clicking the full screen icon to go into fullscreen
    mode.

    Support for this feature was added in Qt 5.6.0.

    \section1 HTML5 DRM

    Qt WebEngine supports viewing DRM protected videos if the \l{Widevine DRM}
    plugin has been installed.

    The video format most commonly used by DRM services, H.264, requires
    proprietary audio and video codecs. For more information about enabling the
    codecs, see \l{Audio and Video Codecs}.

    This feature can be tested by playing a video in \l{WebEngine Widgets Simple Browser
    Example}{Simple Browser} or \l{WebEngine Quick Nano Browser}{Nano Browser}
    from \l{castLabs}, \l{Swank Motion Pictures, Inc.}, or \l{Shaka Player}.

    Support for this feature was added in Qt 5.7.0.

    \section1 HTML5 Geolocation

    Qt WebEngine supports JavaScript Geolocation API with \l {Qt Location} as a
    backend. The application has to explicitly allow the feature by using
    QWebEnginePage::Geolocation or \l{WebEngineView::Feature}
    {WebEngineView.Feature}.

    If Qt Location has been built before Qt WebEngine then this feature can be
    tested by using \l{WebEngine Widgets Maps Example}{Maps} and allowing it to
    find the current position of the user. Note that on Windows an external GPS
    receiver must be connected to the application. For more information, see
    \l{Qt Positioning}.

    Support for this feature was added in Qt 5.5.0.

    \section1 HTTP/2 Protocol

    Qt WebEngine supports the Chromium implementation of the \l{HTTP/2}
    protocol.

    This feature can be tested by opening an HTTP/2 demo, such as the
    \l{Akamai HTTP/2 Demo}, in \l{WebEngine Widgets Simple Browser Example}
    {Simple Browser} or \l{WebEngine Quick Nano Browser}{Nano Browser}.

    \section1 Native Dialogs

    A web page might request dialogs for the following functions:

    \list
        \li Entering user credentials for HTTP and proxy authentication
        \li Displaying JavaScript alerts, confirmation dialogs, and prompts
        \li Picking colors
        \li Selecting files
        \li Displaying form validation messages
    \endlist

    Qt WebEngine provides standard dialogs for these functions. In widget-based
    applications, the standard dialogs are based on QDialog, whereas in Qt Quick
    applications, they can be based either on Qt Quick Controls 1 or Qt Quick
    Controls 2 (since Qt 5.8). The latter are used only on \c eglfs platforms.

    To explicitly force either dialogs based on Qt Quick Controls 1 or Qt Quick
    Controls 2, set the \c QTWEBENGINE_DIALOG_SET environment variable to either
    \c{QtQuickControls1} or \c{QtQuickControls2}.

    Qt WebEngine Widgets dialogs can be customized by reimplementing the
    QWebEnginePage::chooseFiles(), QWebEnginePage::javaScriptAlert(),
    QWebEnginePage::javaScriptConfirm(), and QWebEnginePage::javaScriptPrompt()
    functions.

    Since Qt 5.8, Qt Quick dialogs can be customized by connecting to the
    WebEngineView::authenticationDialogRequested(),
    WebEngineView::javaScriptDialogRequested(),
    WebEngineView::colorDialogRequested(),
    WebEngineView::fileDialogRequested(), and
    WebEngineView::formValidationMessageRequested() signals. For an example,
    see \l{WebEngine Qt Quick Custom Dialogs Example}.

    \section1 Pepper Plugin API

    Qt WebEngine supports loading Pepper Plugin API (PPAPI) plugins if
    WebEngineSettings::pluginsEnabled or QWebEngineSettings::PluginsEnabled
    is set.

    Except for the Adobe Flash Player plugin, the plugins must be loaded
    manually using the Chromium command line syntax with the
    \c --register-pepper-plugins argument. The argument value is a list of
    entries, separated by commas, that contain the file path and one or several
    MIME types, separated by semicolons:

    \code
    <file-path-plugin1>;<mime-type-plugin1>,<file-path-plugin2>;<mime-type1-plugin2>;<mime-type2-plugin2>
    \endcode

    For example:

    \code
    --register-pepper-plugins="libppapi_example.so;application/x-ppapi-example"
    \endcode

    The MIME type is important because it determines which embeds the plugin is
    used for.

    Support for this feature was added in Qt 5.6.0.

    \section2 Pepper Flash Player Plugin Support

    The Pepper Flash player plugin can be loaded automatically if it is
    installed in one of the following locations, depending on the platform:

    \list
        \li Windows
            \code
            C:\Windows\SysWOW64\Macromed\Flash\pepflashplayer*.dll
            C:\Windows\System32\Macromed\Flash\pepflashplayer*.dll
            \endcode
        \li OS X
            \code
            /Library/Internet Plug-Ins/PepperFlashPlayer/PepperFlashPlayer.plugin
            \endcode
        \li Linux
            \code
            /usr/lib/pepperflashplugin-nonfree/libpepflashplayer.so
            /usr/lib/adobe-flashplugin/libpepflashplayer.so
            /usr/lib/PepperFlash/libpepflashplayer.so
            /usr/lib64/chromium/PepperFlash/libpepflashplayer.so
            \endcode
    \endlist

    You can also load the Pepper Flash player from a specific location by using
    command line arguments:

    \code
    --ppapi-flash-path=./libpepflashplayer.so
    \endcode

    By default, the Flash version is set to \c{11.2.999.999}. You can use the
    \c{ppapi-flash-version=} argument to set another Flash version in the
    format \c{major.minor.build.revision}:

    \code
    --ppapi-flash-version=16.0.0.235
    \endcode

    This feature can be tested in \l{WebEngine Widgets Simple Browser Example}{Simple Browser}
    or \l{WebEngine Quick Nano Browser}{Nano Browser} if the Adobe Flash PPAPI
    plugin is installed and plugins are enabled in the browser. To test the
    feature, the \c https://helpx.adobe.com/flash-player.html page can be opened
    in the browser.

    \section1 Print to PDF

    Qt WebEngine supports printing a web page to a PDF file. For more
    information, see QWebEnginePage::printToPdf() and
    \l{WebEngineView::printToPdf}{WebEngineView.printToPdf}.

    This feature can be tested using \l{WebEngine Widgets Html2Pdf Example}
    {Html2Pdf}.

    Support for this feature was added in Qt 5.7.0.

    \section1 Process Models

    Qt WebEngine uses multiple OS processes to isolate web sites from each other
    and from the client application, improving security and robustness. The
    following process models, or ways to divide web sites between OS processes,
    are supported:

    \list
      \li \l{Process per Site Instance}
      \li \l{Process per Site}
      \li \l{Single Process}
    \endlist

    \section2 Process per Site Instance

    This is the default model. Pages from separate sites are put into separate
    processes and separate visits to the same site are also isolated.

    Two web pages are considered as belonging to the same site if they originate
    from the same registered domain name (for example, \c wikipedia.org) and
    scheme (for example, \c https). This is similar to the same-origin policy
    but subdomains are ignored. For example, both \c{https://en.wikipedia.org/}
    and \c{https://de.wikipedia.org/} would belong to the same site.

    A site instance is a collection of web pages belonging to the same site.
    When the application explicitly loads a URL into Qt WebEngine (via \l
    QWebEnginePage::setUrl, for example), a new site instance is created for the
    page. However, when the user clicks same-site links on the page, the
    existing site instance is merely extended with more pages.

    For instance, in the \l{WebEngine Widgets Simple Browser Example}{Simple
    Browser} example, when a user opens two tabs and explicitly enters
    \c{https://en.wikipedia.org/} into the URL bars, both tabs will have their
    own separate OS processes (because explicitly entering a URL creates a new
    site instance). However, when the user then middle-clicks some same-site
    links to open more tabs, these new tabs will share the same OS process
    (because user interaction extends the existing site instance).

    \section2 Process per Site

    Pages from separate sites are put into separate processes. Unlike Process
    per Site Instance, all visits to the same site will share an OS process.

    The benefit of this model is reduced memory consumption, because more web
    pages will share processes. The drawbacks include reduced security,
    robustness, and responsiveness.

    To enable this model, use the command-line argument \c{--process-per-site}.
    See \l{Using Command-Line Arguments}.

    \section2 Single Process

    For debugging purposes only, a single process mode can be enabled using the
    command-line argument \c{--single-process}. See \l{Using Command-Line
    Arguments} and \l{Qt WebEngine Debugging and Profiling}.

    \section1 Spellchecker

    Qt WebEngine supports integrating spellchecking support into HTML forms to
    enable users to submit spellchecked messages. When the user clicks on
    an underlined misspelled word, the default context menu displays up to four
    suggestions. Selecting one will replace the misspelled word.

    To be able to check the spelling, the spellchecker needs dictionaries. It
    supports dictionaries from the \l{Hunspell project}, but they have to be
    compiled into a special binary format. A Hunspell dictionary consists of two
    files:

    \list

        \li A \c .dic file that is a dictionary containing words for the
            language
        \li An \c .aff file that defines the meaning of special flags in the
            dictionary
    \endlist

    These two files can be converted into the \c bdic format by using the
    \c qwebengine_convert_dict tool that is shipped together with Qt.
    When the Qt WebEngine spellchecker initializes, it will try to load the
    \c bdict dictionaries and to check them for consistency.

    If \c QTWEBENGINE_DICTIONARIES_PATH is set, the spellchecker uses the
    dictionaries in the specified directory without looking anywere else.
    Otherwise, it uses the \e qtwebengine_dictionaries directory relative to the
    executable if it exists. If it does not exist, it will look in \c
    QT_INSTALL_PREFIX/qtwebengine_dictionaries.

    On macOS, depending on how Qt WebEngine is configured at build time, there
    are two possibilities how spellchecking data is found:

    \list
        \li Hunspell dictionaries (default) - .bdic dictionaries are used, just
            like on other platforms
        \li Native dictionaries - the macOS spellchecking APIs are used (which
            means the results will depend on the installed OS dictionaries)
    \endlist

    Thus, in the macOS Hunspell case, Qt WebEngine will look in the \e
    qtwebengine_dictionaries subdirectory located inside the application bundle
    \c Resources directory, and also in the \c Resources directory located
    inside the Qt framework bundle.

    To summarize, in case of Hunspell usage, the following paths are considered:

    \list
        \li \c QTWEBENGINE_DICTIONARIES_PATH, if set
        \li QCoreApplication::applicationDirPath()/qtwebengine_dictionaries
            or QCoreApplication::applicationDirPath()/../Contents/Resources/qtwebengine_dictionaries
            (on macOS)
        \li [QLibraryInfo::DataPath]/qtwebengine_dictionaries
            or path/to/QtWebEngineCore.framework/Resources/qtwebengine_dictionaries (Qt framework
            bundle on macOS)
    \endlist

    Spellchecking is disabled by default and can be enabled per profile by
    using the QWebEngineProfile::setSpellCheckEnabled() method in widget-based
    applications and the \l {QQuickWebEngineProfile::spellCheckEnabled}
    {WebEngineProfile.spellCheckEnabled} property in Qt Quick applications.

    The current language used for spellchecking is defined per profile, and can
    be set using the QWebEngineProfile::setSpellCheckLanguages() method or the
    \l {QQuickWebEngineProfile::spellCheckLanguages}
    {WebEngineProfile.spellCheckLanguages} property.

    This feature can be tested by building and running the
    \l{WebEngine Widgets Spellchecker Example}{Spellchecker Example}.

    Support for this feature was added in Qt 5.8.0.

    \section1 Touch

    Qt WebEngine supports touch devices for navigating and interacting with web pages.

    Applications can prohibit the use of touch events in the following ways:

    \list
        \li Passing the flag \c --touch-events=disabled on the command line will disable touch event
        support in JavaScript API (meaning \c ontouchstart and related handlers will not be present
        in the \c document.window object). Touch events will still be delivered to web pages.

       \li Installing an event filter object using \l {QObject::installEventFilter} on the WebEngine
       view focus proxy object, and filtering out all touch events.

    \endlist

    \section1 View Source

    Qt WebEngine supports viewing the HTML source of a web page.

    This feature can be used from custom menus or assigned to custom events.
    For more information, see WebEngineView::WebAction, and QWebEnginePage::WebAction.

    This feature can be tested by opening a web page in \l{WebEngine Widgets
    Simple Browser Example}{Simple Browser} or \l{WebEngine Quick Nano Browser}
    {Nano Browser}, and then selecting \c{Page Source} in the context menu. The
    \c{Page Source} context menu entry opens the source view in a new tab.

    For opening the source view in the current tab, URLs with \l{view-source URI scheme}
    are also supported. For example, you can type the following URL to the URL bar
    to view the HTML source of the qt.io web page:
    \code
    view-source:https://www.qt.io/
    \endcode

    Auto-completion of incomplete URLs with \l{view-source URI scheme} makes the usage of
    this feature more comfortable. For example, the following incomplete URL also loads
    the source view of the qt.io web page:
    \code
    view-source:qt.io
    \endcode

    Support for this feature was added in Qt 5.8.0.

    \section1 WebRTC

    WebRTC provides browsers with Real-Time Communications (RTC) capabilities
    via simple APIs. For more information, see \l{WebEngineView::Feature}
    {WebEngineView.Feature} and QWebEnginePage::Feature.

    This feature can be tested by setting up a webcam or microphone and then
    opening \c https://test.webrtc.org/ in \l{WebEngine Widgets Simple Browser
    Example}{Simple Browser} or \l{WebEngine Quick Nano Browser}{Nano Browser}.

    \section1 Notifications

    Qt WebEngine supports JavaScript Web Notification API.
    The application has to explicitly allow the feature by using
    QWebEnginePage::Notifications or \l{WebEngineView::Feature}
    {WebEngineView.Notifications}.

    Support for this feature was added in Qt 5.13.0.
*/