// 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.

    \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.

    \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.

*/
