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

/****************************************************************************
**
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: http://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 http://www.qt.io/terms-conditions. For further
** information use the contact form at http://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: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \example webenginewidgets/simplebrowser
    \title WebEngine Widgets Simple Browser Example
    \ingroup webengine-widgetexamples
    \brief A simple browser based on Qt WebEngine 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 emit loadProgress
    \skipto closeTab
    \skipto });
    \printline }
    \dots
    \printline }

    \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 menu items to the context menu, so that users can right-click a link
    to have it opened in the same tab, a new window, or a new tab. 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::OpenLinkInThisWindow action is
    \uicontrol Follow. For clarity, we rename it
    \uicontrol {Open Link in This Tab}. Also, we add the actions for opening
    links in a separate window or in a new tab:

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

    \section1 Implementing WebPage Functionality

    As mentioned earlier, each \c WebView contains a \c WebPage instance that
    was created by using QWebEngineProfile::defaultProfile().

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

    \quotefromfile webenginewidgets/simplebrowser/webpage.h
    \skipto WebPage :
    \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/webpage.cpp
    \skipto WebPage::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::certificateError(
    \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 connect(m_urlLineEdit
    \printline connect

    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 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 QWebEngineDownloadItem, 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 QWebEngineDownloadItem object will periodically emit the \l
    {QWebEngineDownloadItem::}{downloadProgress} signal to notify potential
    observers of the download progress and the \l
    {QWebEngineDownloadItem::}{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 Licensing

    All icons used in the example, with the exception of \c{AppLogoColor.png},
    originate from the public domain
    \l{http://tango.freedesktop.org/Tango_Icon_Library}{Tango Icon Library}.
*/