diff options
Diffstat (limited to 'examples/webengine/lifecycle/doc/src/lifecycle.qdoc')
| -rw-r--r-- | examples/webengine/lifecycle/doc/src/lifecycle.qdoc | 167 |
1 files changed, 167 insertions, 0 deletions
diff --git a/examples/webengine/lifecycle/doc/src/lifecycle.qdoc b/examples/webengine/lifecycle/doc/src/lifecycle.qdoc new file mode 100644 index 000000000..4151d0597 --- /dev/null +++ b/examples/webengine/lifecycle/doc/src/lifecycle.qdoc @@ -0,0 +1,167 @@ +/**************************************************************************** +** +** Copyright (C) 2019 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 webengine/lifecycle + \title WebEngine Lifecycle Example + \ingroup webengine-examples + \brief Freezes and discards background tabs to reduce CPU and memory usage. + + \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. + + \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. + + \section1 Overview of Lifecycle States + + Each \l {WebEngineView} item can be in one of three \e {lifecycle states}: + active, frozen, or discarded. These states, like the sleep states of a CPU, + control the resource usage of web views. + + The \e {active} state is the normal, unrestricted state of a web view. All + visible web views are always in the active state, as are all web views that + have not yet finished loading. Only invisible, idle web views can be + transitioned to other lifecycle states. + + The \e {frozen} state is a low CPU usage state. In this state, most HTML + task sources are suspended (frozen) and, as a result, most DOM event + processing and JavaScript execution will also be suspended. The web view + must be invisible in order to be frozen as rendering is not possible in this + state. + + The \e {discarded} state is an extreme resource-saving state. In this state, + the browsing context of the web view will be discarded and the corresponding + renderer subprocess shut down. CPU and memory usage in this state is reduced + virtually to zero. On exiting this state the web page will be automatically + reloaded. The process of entering and exiting the discarded state is similar + to serializing the browsing history of the web view and destroying the view, + then creating a new view and restoring its history. + + See also \l {WebEngineView::LifecycleState}. The equivalent in the Widgets + API is \l {QWebEnginePage::LifecycleState}. + + \section2 The \c {lifecycleState} and \c {recommendedState} Properties + + The \l {WebEngineView::}{lifecycleState} property of the \l {WebEngineView} + type is a read-write property that controls the current lifecycle state of + the web view. This property is designed to place as few restrictions as + possible on what states can be transitioned to. For example, it is allowed + to freeze a web view that is currently playing music in the background, + stopping the music. In order to implement a less aggressive resource-saving + strategy that avoids interrupting user-visible background activity, the \l + {WebEngineView::} {recommendedState} property must be used. + + The \l {WebEngineView::}{recommendedState} property of the \l + {WebEngineView} type is a read-only property that calculates a safe limit on + the \l {WebEngineView::}{lifecycleState} property, taking into account the + current activity of the web view. So, in the example of a web view playing + music in the background, the recommended state will be \c {Active} since a + more aggressive state would stop the music. If the application wants to + avoid interrupting background activity, then it should avoid putting the web + view into a more aggressively resource-saving lifecycle state than what's + given by \l {WebEngineView::}{recommendedState}. + + See also \l {WebEngineView::lifecycleState} and \l + {WebEngineView::recommendedState}. The equivalents in the Widgets API are \l + {QWebEnginePage::lifecycleState} and \l {QWebEnginePage::recommendedState}. + + \section2 The Page Lifecycle API + + The \l {WebEngineView::}{lifecycleState} property is connected to the \l + {https://wicg.github.io/page-lifecycle/spec.html}{Page Lifecycle API}, a + work-in-progress extension to the HTML standard that specifies two new DOM + events, \c {freeze} and \c {resume}, and adds a new \c + {Document.wasDiscarded} boolean property. The \c {freeze} and \c {resume} + events are fired when transitioning from the \c {Active} to the \c {Frozen + state}, and vice-versa. The \c {Document.wasDiscarded} property is set to \c + {true} when transition from the \c {Discarded} state to the \c {Active} + state. + + \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. + +*/ |