diff options
Diffstat (limited to 'examples/webenginewidgets/simplebrowser/doc/src/simplebrowser.qdoc')
| -rw-r--r-- | examples/webenginewidgets/simplebrowser/doc/src/simplebrowser.qdoc | 263 |
1 files changed, 263 insertions, 0 deletions
diff --git a/examples/webenginewidgets/simplebrowser/doc/src/simplebrowser.qdoc b/examples/webenginewidgets/simplebrowser/doc/src/simplebrowser.qdoc new file mode 100644 index 000000000..b8df9b02a --- /dev/null +++ b/examples/webenginewidgets/simplebrowser/doc/src/simplebrowser.qdoc @@ -0,0 +1,263 @@ +/**************************************************************************** +** +** 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. +*/ |