diff options
Diffstat (limited to 'examples/webenginewidgets/videoplayer/doc/src/videoplayer.qdoc')
-rw-r--r-- | examples/webenginewidgets/videoplayer/doc/src/videoplayer.qdoc | 186 |
1 files changed, 186 insertions, 0 deletions
diff --git a/examples/webenginewidgets/videoplayer/doc/src/videoplayer.qdoc b/examples/webenginewidgets/videoplayer/doc/src/videoplayer.qdoc new file mode 100644 index 000000000..599e13e6c --- /dev/null +++ b/examples/webenginewidgets/videoplayer/doc/src/videoplayer.qdoc @@ -0,0 +1,186 @@ +/**************************************************************************** +** +** Copyright (C) 2017 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 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/videoplayer + \title WebEngine Widgets Video Player Example + \ingroup webengine-widgetexamples + \brief Displays full screen video using \l QWebEngineView + + \image videoplayer-example.png + + \e {Video Player} demonstrates how to support full screen playback of HTML5 + video using \l QWebEngineView. + + \l {https://fullscreen.spec.whatwg.org/}{The Fullscreen API} is a + cross-browser Javascript API that enables a web page to request that one of + its HTML elements be made to occupy the user's entire screen. It is + commonly used for full screen video playback via the \c <video> element, but + can in principle be used to display any HTML content in full screen mode. Qt + WebEngine supports this API, however it is disabled by default. This example + shows the steps needed to switch it on, including: + + \list + \li Enabling it in \l QWebEngineSettings. + \li Handling the \l QWebEnginePage::fullScreenRequested signal by creating + a new full screen window. + \li Displaying a notification popup to ensure that the user is aware + that something is being displayed full screen. + \endlist + + \include examples-run.qdocinc + + \section1 Overview + + Once started, the example program will create a normal (non-fullscreen) + window with a \l QWebEngineView showing an embedded YouTube video player. + You can then click on the full screen toggle button (bottom-right corner) to + enter full screen mode. This should also display a centered notification + overlay informing you that you can exit full screen mode by pressing the + escape key. + + Implementation-wise entering full screen mode entails creating a new full + screen window with a separate \l QWebEngineView instance and migrating the + \l QWebEnginePage from the normal window's \l QWebEngineView to this new \l + QWebEngineView. Exiting full screen mode reverses this migration. + + The example code is divided between three classes, \c MainWindow, \c + FullScreenWindow, and \c FullScreenNotification. The classes \c MainWindow + and \c FullScreenWindow are each responsible for managing one top-level + window, while \c FullScreenNotification is responsible for styling and + animating the notification box. A \c MainWindow is created on startup and + lives for the entire program runtime, while a new \c FullScreenWindow is + created every time full screen mode is entered. + + \section1 MainWindow Class Declaration + + A \c MainWindow is a \l QMainWindow with a \l QWebEngineView as the central + widget: + + \quotefromfile webenginewidgets/videoplayer/mainwindow.h + \skipto #include + \printuntil /^\}/ + + \section1 MainWindow Class Definition + + In the constructor we start by setting up the \l QWebEngineView as the + central widget: + + \quotefromfile webenginewidgets/videoplayer/mainwindow.cpp + \skipto MainWindow::MainWindow + \printuntil setCentralWidget + + We then configure Qt WebEngine to advertise support for the Fullscreen API: + + \printline QWebEngineSettings + + Without this line the full screen toggle button would be disabled (grayed + out) as the Javascript running on the page can detect that our browser + does not support full screen mode. + + Next we connect the \c fullScreenRequested signal to our slot: + + \printuntil &MainWindow::fullScreenRequested + + This signal is emitted whenever the Javascript on the page wants to enter or + exit full screen mode. Without handling this signal (but still keeping the + \c FullScreenSupportEnabled attribute as \c true) the toggle button will be + enabled but clicking on it will have no effect as Javascript's full screen + request will be denied. + + Finally, we load some HTML (see + \l{webenginewidgets/videoplayer/data/index.html}{index.html} included with + the example) into our \l QWebEngineView: + + \printline load + + The second part of \c MainWindow is handling the full screen requests: + + \skipto MainWindow::fullScreenRequested + \printuntil /^\}/ + + We create a new \c FullScreenWindow when entering full screen mode, and + delete it when exiting. + + \section1 FullScreenWindow Class Declaration + + A \c FullScreenWindow is a \l QWidget containing a \l QWebEngineView and a + \c FullScreenNotification. + + \quotefromfile webenginewidgets/videoplayer/fullscreenwindow.h + \skipto #include + \printuntil /^\}/ + + \section1 FullScreenWindow Class Definition + + The constructor is responsible for hiding the normal window (while saving + its geometry) and showing the new \c FullScreenWindow instead: + + \quotefromfile webenginewidgets/videoplayer/fullscreenwindow.cpp + \skipto FullScreenWindow::FullScreenWindow + \printuntil /^\}/ + + The call to \l QWebEngineView::setPage will move the web page from the \c + MainWindow's view to \c FullScreenWindow's view. + + In the destructor we use the same method to move the page back, after which + we restore the main window's geometry and visibility: + + \skipto FullScreenWindow::~FullScreenWindow + \printuntil /^\}/ + + We override \l QWidget::resizeEvent to do manual layout, keeping the \l + QWebEngineView maximized, and the \c FullScreenNotification centered within + the window: + + \skipto FullScreenWindow::resizeEvent + \printuntil /^\}/ + + \section1 FullScreenNotification Class Declaration + + A \c FullScreenNotification is just a \l QLabel with some styling and + animation: + + \quotefromfile webenginewidgets/videoplayer/fullscreennotification.h + \skipto #include + \printuntil /^\}/ + + \section1 FullScreenWindow Class Definition + + In the constructor we configure the QLabel and set up a delayed fade-out + animation using \l {The Animation Framework}: + + \quotefromfile webenginewidgets/videoplayer/fullscreennotification.cpp + \skipto FullScreenNotification::FullScreenNotification + \printuntil /^\}/ + + The custom signal \c shown, which we use to trigger the animation, is + emitted from the \c showEvent method: + + \skipto FullScreenNotification::showEvent + \printuntil /^\}/ +*/ |