path: root/examples/webenginewidgets/simplebrowser/doc/src/simplebrowser.qdoc

// Copyright (C) 2016 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \example webenginewidgets/simplebrowser
    \title WebEngine Widgets Simple Browser Example
    \ingroup webengine-widgetexamples
    \brief A simple browser based on \QWE Widgets.

    \image simplebrowser.png

    \e {Simple Browser} demonstrates how to use the
    \l{Qt WebEngine Widgets C++ Classes}{Qt WebEngine C++ classes} to develop a
    small Web browser application that contains the following elements:

    \list
        \li Menu bar for opening stored pages and managing windows and tabs.
        \li Navigation bar for entering a URL and for moving backward and
            forward in the web page browsing history.
        \li Multi-tab area for displaying web content within tabs.
        \li Status bar for displaying hovered links.
        \li A simple download manager.
    \endlist

    The web content can be opened in new tabs or separate windows. HTTP and
    proxy authentication can be used for accessing web pages.

    \include examples-run.qdocinc

    \section1 Class Hierarchy

    We start with sketching a diagram of the main classes that we are going to
    implement:

    \image simplebrowser-model.png

    \list
        \li \c{Browser} is a class managing the application windows.
        \li \c{BrowserWindow} is a \l QMainWindow showing the menu, a navigation
            bar, \c {TabWidget}, and a status bar.
        \li \c{TabWidget} is a \l QTabWidget and contains one or multiple
            browser tabs.
        \li \c{WebView} is a \l QWebEngineView, provides a view for \c{WebPage},
            and is added as a tab in \c{TabWidget}.
        \li \c{WebPage} is a \l QWebEnginePage that represents website content.
    \endlist

    Additionally, we will implement some auxiliary classes:

    \list
        \li \c{WebPopupWindow} is a \l QWidget for showing popup windows.
        \li \c{DownloadManagerWidget} is a \l QWidget implementing the downloads
        list.
    \endlist

    \section1 Creating the Browser Main Window

    This example supports multiple main windows that are owned by a \c Browser
    object. This class also owns the \c DownloadManagerWidget and could be used
    for further functionality, such as bookmarks and history managers.

    In \c main.cpp, we create the first \c BrowserWindow instance and add it
    to the \c Browser object. If no arguments are passed on the command line,
    we open the \l{Qt Homepage}:

    \quotefromfile webenginewidgets/simplebrowser/main.cpp
    \skipto main
    \printuntil }

    \section1 Creating Tabs

    The \c BrowserWindow constructor initializes all the necessary user interface
    related objects. The \c centralWidget of \c BrowserWindow contains an instance of
    \c TabWidget. The \c TabWidget contains one or several \c WebView instances as tabs,
    and delegates it's signals and slots to the currently selected one:

    \quotefromfile webenginewidgets/simplebrowser/tabwidget.h
    \skipto TabWidget :
    \printuntil {
    \dots
    \skipto signals
    \printuntil triggerWebPageAction
    \skipto }
    \dots
    \printline };

    Each tab contains an instance of \c WebView:

    \quotefromfile webenginewidgets/simplebrowser/tabwidget.cpp
    \skipto TabWidget::createTab(
    \printuntil }
    \skipto TabWidget::createBackgroundTab(
    \printuntil }

    In \c TabWidget::setupView(), we make sure that the \c TabWidget always forwards
    the signals of the currently selected \c WebView:

    \quotefromfile webenginewidgets/simplebrowser/tabwidget.cpp
    \skipto TabWidget::setupView
    \printuntil /^\}/

    \section1 Implementing WebView Functionality

    The \c WebView is derived from QWebEngineView to support the following
    functionality:

    \list
        \li Displaying error messages in case \c renderProcess dies
        \li Handling \c createWindow requests
        \li Adding custom menu items to context menus
    \endlist

    First, we create the WebView with the necessary methods and signals:

    \quotefromfile webenginewidgets/simplebrowser/webview.h
    \skipto WebView :
    \printuntil WebView(
    \dots
    \skipto protected:
    \printuntil webActionEnabledChanged
    \skipto }
    \dots
    \printline };

    \section2 Displaying Error Messages

    If the render process is terminated, we display a QMessageBox with an error
    code, and then we reload the page:

    \quotefromfile webenginewidgets/simplebrowser/webview.cpp
    \skipto WebView::WebView(QWidget *parent)
    \printuntil {
    \skipto renderProcessTerminated
    \dots
    \printuntil QTimer
    \printline });
    \printline }

    \section2 Managing WebWindows

    The loaded page might want to create windows of the type
    QWebEnginePage::WebWindowType, for example, when a JavaScript program
    requests to open a document in a new window or dialog.
    This is handled by overriding \c QWebView::createWindow():

    \skipto WebView::createWindow(
    \printuntil return nullptr;
    \printuntil }

    In case of \c QWebEnginePage::WebDialog, we create an instance of a custom \c WebPopupWindow class:

    \quotefromfile webenginewidgets/simplebrowser/webpopupwindow.h
    \skipto class WebPopupWindow
    \printuntil };

    \section2 Adding Context Menu Items

    We add a menu item to the context menu, so that users can right-click to have an inspector
    opened in a new window. We override QWebEngineView::contextMenuEvent and use
    QWebEnginePage::createStandardContextMenu to create a default QMenu with a
    default list of QWebEnginePage::WebAction actions.

    The default name for QWebEnginePage::InspectElement action is
    \uicontrol Inspect. For clarity, we rename it to \uicontrol {Open Inspector In New Window} when
    there is no Inspector present yet,
    and \uicontrol {Inspect Element} when it's already created.

    We also check if the QWebEnginePage::ViewSource action is in the menu, because if it's not
    we have to add a separator as well.

    \quotefromfile webenginewidgets/simplebrowser/webview.cpp
    \skipto WebView::contextMenuEvent(
    \printuntil menu->popup
    \printline }

    \section1 Implementing WebPage and WebView Functionality

    We implement \c WebPage as a subclass of QWebEnginePage and \c WebView as
    as subclass of QWebEngineView to enable HTTP, proxy authentication, as well
    as ignoring SSL certificate errors when accessing web pages:

    \quotefromfile webenginewidgets/simplebrowser/webpage.h
    \skipto WebPage :
    \printuntil }

    \quotefromfile webenginewidgets/simplebrowser/webview.h
    \skipto WebView :
    \printuntil }

    In all the cases above, we display the appropriate dialog to the user. In
    case of authentication, we need to set the correct credential values on the
    QAuthenticator object:

    \quotefromfile webenginewidgets/simplebrowser/webview.cpp
    \skipto WebView::handleAuthenticationRequired(
    \printuntil }
    \printuntil }
    \printline }

    The \c handleProxyAuthenticationRequired signal handler implements the very same
    steps for the authentication of HTTP proxies.

    In case of SSL errors, we just need to return a boolean value indicating
    whether the certificate should be ignored.

    \quotefromfile webenginewidgets/simplebrowser/webpage.cpp
    \skipto WebPage::handleCertificateError(
    \printuntil }
    \printuntil }

    \section1 Opening a Web Page

    This section describes the workflow for opening a new page. When the user
    enters a URL in the navigation bar and presses \uicontrol Enter, the \c
    QLineEdit::returnPressed signal is emitted and the new URL is then handed
    over to \c TabWidget::setUrl:

    \quotefromfile webenginewidgets/simplebrowser/browserwindow.cpp
    \skipto BrowserWindow::BrowserWindow
    \printline BrowserWindow::BrowserWindow
    \skipto /^\{/
    \printline /^\{/
    \dots
    \skipto connect(m_urlLineEdit
    \printuntil });
    \dots
    \skipto /^\}/
    \printline /^\}/

    The call is forwarded to the currently selected tab:

    \quotefromfile webenginewidgets/simplebrowser/tabwidget.cpp
    \skipto TabWidget::setUrl(
    \printuntil }
    \printuntil }

    The \c setUrl() method of \c WebView just forwards the \c url to the associated \c WebPage,
    which in turn starts the downloading of the page's content in the background.

    \section1 Implementing Private Browsing

    \e{Private browsing}, \e{incognito mode}, or \e{off-the-record mode} is a
    feature of many browsers where normally persistent data, such as cookies,
    the HTTP cache, or browsing history, is kept only in memory, leaving no
    trace on disk. In this example we will implement private browsing on the
    window level with tabs in one window all in either normal or private mode.
    Alternatively we could implement private browsing on the tab-level, with
    some tabs in a window in normal mode, others in private mode.

    Implementing private browsing is quite easy using \QWE. All one has
    to do is to create a new \l{QWebEngineProfile} and use it in the
    \l{QWebEnginePage} instead of the default profile. In the example this new
    profile is owned by the \c Browser object:

    \quotefromfile webenginewidgets/simplebrowser/browser.h
    \skipto /^class Browser$/
    \printuntil public:
    \dots
    \skipto createWindow
    \printline createWindow
    \skipto private:
    \printline private:
    \dots
    \skipto m_profile
    \printline m_profile
    \printline /^\};$/

    Required profile for \e{private browsing} is created together with its
    first window. The default constructor for \l{QWebEngineProfile} already
    puts it in \e{off-the-record} mode.

    \quotefromfile webenginewidgets/simplebrowser/browser.cpp

    \skipto Browser::createWindow
    \printuntil m_profile.reset
    \dots

    All that is left to do is to pass the appropriate profile down to the
    appropriate \l QWebEnginePage objects. The \c Browser object will hand to
    each new \c BrowserWindow either the global default profile
    (see \l{QWebEngineProfile::defaultProfile}) or one shared
    \e{off-the-record} profile instance:

    \dots
    \skipto m_profile.get
    \printuntil mainWindow = new BrowserWindow
    \skipto return mainWindow
    \printuntil /^\}/

    The \c BrowserWindow and \c TabWidget objects will then ensure that all \l
    QWebEnginePage objects contained in a window will use this profile.

    \section1 Managing Downloads

    Downloads are associated with a \l QWebEngineProfile. Whenever a download is
    triggered on a web page the \l QWebEngineProfile::downloadRequested signal is
    emitted with a \l QWebEngineDownloadRequest, which in this example is forwarded
    to \c DownloadManagerWidget::downloadRequested:

    \quotefromfile webenginewidgets/simplebrowser/browser.cpp
    \skipto Browser::Browser
    \printuntil /^\}/

    This method prompts the user for a file name (with a pre-filled suggestion)
    and starts the download (unless the user cancels the \uicontrol {Save As}
    dialog):

    \quotefromfile webenginewidgets/simplebrowser/downloadmanagerwidget.cpp
    \skipto DownloadManagerWidget::downloadRequested
    \printuntil /^\}/

    The \l QWebEngineDownloadRequest object will periodically emit the \l
    {QWebEngineDownloadRequest::}{receivedBytesChanged} signal to notify potential
    observers of the download progress and the \l
    {QWebEngineDownloadRequest::}{stateChanged} signal when the download is
    finished or when an error occurs. See \c downloadmanagerwidget.cpp for an
    example of how these signals can be handled.

    \section1 Files and Attributions

    The example uses icons from the Tango Icon Library:

    \table
    \row
        \li \l{simplebrowser-tango}{Tango Icon Library}
        \li Public Domain
    \endtable
*/