/****************************************************************************
**
** 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.
    \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 classes that we are going to
    implement:

    \image simplebrowser-model.png

    \list
        \li \c{Browser} is a singleton 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

    \section1 Creating the Browser Main Window

    This example supports multiple main windows that are owned by a
    \c Browser singleton object. This class could also be used for further
    functionality, such as downloading files, 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 }

    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 Downloading favicons
        \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 handleIconLoaded
    \skipto }
    \dots
    \printline };

    \section2 Downloading Favicons

    To download a favicon, we use QNetworkAccessManager and create a
    QNetworkRequest every time the URL specified by
    QWebEngineView::iconUrlChanged is emitted:

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

    \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,
    \c QLineEdit::returnPressed is emitted, which lets \c BrowserWindow
    load the requested page:

    \quotefromfile webenginewidgets/simplebrowser/browserwindow.cpp
    \skipto connect(m_urlLineEdit
    \printuntil });

    The \c loadPage() method calls the \c setUrl() method of \c TabWidget:

    \skipto void BrowserWindow::loadPage(const QUrl
    \printuntil }
    \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.
*/