1 files changed, 84 insertions, 0 deletions
diff --git a/examples/webenginequick/lifecycle/doc/src/lifecycle.qdoc b/examples/webenginequick/lifecycle/doc/src/lifecycle.qdoc
new file mode 100644
index 000000000..1580da26d
--- /dev/null
+++ b/examples/webenginequick/lifecycle/doc/src/lifecycle.qdoc
@@ -0,0 +1,84 @@
+// Copyright (C) 2019 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+    \example webenginequick/lifecycle
+    \title WebEngine Lifecycle Example
+    \ingroup webengine-examples
+    \brief Freezes and discards background tabs to reduce CPU and memory usage.
+    \examplecategory {Web Technologies}
+
+    \image lifecycle.png
+
+    \e {WebEngine Lifecycle Example} demonstrates how the \l
+    {WebEngineView::}{lifecycleState} and \l {WebEngineView::}{recommendedState}
+    properties of the \l {WebEngineView} can be used to reduce the CPU and
+    memory usage of background tabs in a tabbed browser.
+
+    For an overview of the lifecycle feature, see \l {Page Lifecycle API}.
+
+    \include examples-run.qdocinc
+
+    \section1 UI Elements of the Example
+
+    The example uses \l {Qt Quick Controls 2} to implement a traditional tabbed
+    browser in the \l {Material Style} (dark variant). The main application
+    window (\c {WebBrowser.qml}) is divided into a header bar at the top and a
+    main viewing area filling the rest of the window. The header contains the
+    tab bar (\c {WebTabBar.qml}) with one button per tab (\c
+    {WebTabButton.qml}). The main area consists of a stack of tabs (\c
+    {WebTabStack.qml} and \c {WebTab.qml}). Each tab in turn has a tool bar at
+    the top and a \l {WebEngineView} for displaying web pages. Finally, the main
+    window also has a \l {Drawer} for changing settings. The drawer can be
+    opened by clicking the "⋮" button on the tool bar.
+
+    \note Note that \c {WebTab.qml} uses \l {QUrl::}
+    {fromUserInput} to handle incomplete URLs.
+
+    \section1 Lifecycle States in the Example
+
+    The example implements two ways of changing the lifecycle state: manual and
+    automatic. The manual way uses the \l {WebEngineView::}{lifecycleState}
+    property directly to change the web view lifecycle state, while the
+    automatic way is timer-based and also takes into account the \l
+    {WebEngineView::}{recommendedState}.
+
+    The tab titles in the tab bar are color coded with frozen tabs shown in blue
+    and discarded in red.
+
+    \section2 Manual Lifecycle Control
+
+    \image lifecycle-manual.png
+
+    Manual control is provided by context menus on the tab bar buttons (\c
+    {WebTabButton.qml}). The menu has three radio buttons, one for each
+    lifecycle state, with the current state checked. Some buttons may be
+    disabled, either because they represent illegal state transitions (for
+    example, a \c {Discarded} view cannot directly transition to the \c {Frozen}
+    state), or because other preconditions are not fulfilled (for example, a
+    visible view can only be in the \c {Active} state).
+
+    \section2 Automatic Lifecycle Control
+
+    \image lifecycle-automatic.png
+
+    Automatic control is implemented with a \l {Timer} in the \c {WebTab}
+    component (\c {WebTab.qml}). The timer is started whenever the \l
+    {WebEngineView::}{lifecycleState} of the web view does not match it's \l
+    {WebEngineView::}{recommendedState}. Once the timer fires, the view's
+    lifecycle state is set to the recommended state.
+
+    The time delay is used to avoid changing the lifecycle state too quickly
+    when the user is switching between tabs. The freezing and discarding delays
+    can be changed in the settings drawer accessed through the "⋮" button on the
+    tool bar.
+
+    This is a rather simple algorithm for automatic lifecycle control, however
+    more sophisticated algorithms could also be conceived and implemented on the
+    basis of the \l {WebEngineView::}{lifecycleState} property. For example, the
+    Chromium browser experimentally uses a pretrained deep neural network to
+    predict the next tab activation time by the user, essentially ranking tabs
+    based on how interesting they are to the user. Implementing such an
+    algorithm is left as an exercise to the reader for now.
+
+*/