/**************************************************************************** ** ** Copyright (C) 2016 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$ ** ****************************************************************************/ /*! \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 Functionality 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 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_otrProfile \printline m_otrProfile \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_otrProfile.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_otrProfile.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 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 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 */