/****************************************************************************
**
** Copyright (C) 2020 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Creator documentation.
**
** 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.
**
****************************************************************************/

/*!
    \page quick-states.html
    \if defined(qtdesignstudio)
    \previouspage quick-property-bindings.html
    \else
    \previouspage quick-connections-backend.html
    \endif
    \nextpage studio-3d.html

    \title Adding States

    User interfaces are designed to present different interface configurations
    in different scenarios, or to modify their appearances in response to user
    interaction. Often, there are a set of changes that are made concurrently,
    such that the interface could be seen to be internally changing from one
    \e state to another.

    This applies generally to interfaces regardless of their complexity. A photo
    viewer may initially present images in a grid, and when an image is clicked,
    change to a detailed state where the individual image is expanded and the
    interface is changed to present new options for image editing. At the other
    end of the scale, when a button is pressed, it may change to a
    \e pressed state in which its color and position are modified so that it
    appears to be pressed down.

    In QML, any item can change between different states to apply sets of
    changes that modify the properties of relevant items. Each state can
    present a different configuration that can, for example:

    \list
        \li Show some UI items and hide others.
        \li Present different available actions to the user.
        \li Start, stop, or pause animations.
        \li Execute some script required in the new state.
        \li Change a property value for a particular item.
        \li Show a different view.
    \endlist

    \section1 Creating States

    To open the \uicontrol States view, select \uicontrol View >
    \uicontrol Views > \uicontrol States. To collapse or expand
    the open view, select \uicontrol {Toggle States} or press
    \key {Ctr+Alt+S}. You can also right-click the view and select
    \uicontrol Collapse or \uicontrol Expand.

    The \uicontrol States view displays the different \l{State}{states}
    of a UI, beginning with a \e {base state}.

    \image qmldesigner-transitions.png "States view"

    To add states, select \uicontrol {Create New State}. Click the new state to
    switch to it in \uicontrol {Form Editor}, and then modify the properties of
    components in \uicontrol Properties.

    For example, to change the appearance of a button, you can hide the button
    image and show another image in its place. Or, to add movement to the view,
    you can change the position of an object in \uicontrol {Form Editor}
    and then add animation to the change between the states.

    The properties that you change in a state are highlighted with blue color.
    In \uicontrol {Text Editor}, you can see the changes recorded as changes
    to the base state.

    \image qmldesigner-states.png "States and Properties views"

    \note If you have \l{Locking Items}{locked an item} in \uicontrol Navigator,
    and you attempt to remove states where you change the values of its
    properties, you are prompted to confirm the removal.

    For more information, watch the following video:

    \youtube FzmLuRHQXaw

    \section1 Setting the Default State

    To determine the startup state of the application,
    select \inlineimage icons/action-icon.png
    to open the \uicontrol Actions menu, and then select
    \uicontrol {Set as Default}.

    To reset the state later, select \uicontrol Actions >
    \uicontrol {Reset Default}.

    \section1 Applying States

    To determine when a state should be applied, select \uicontrol Actions >
    \uicontrol {Set when Condition}. In \uicontrol {Binding Editor}, specify
    a \l [QtQuick]{State::when}{when} property for the state. Set the value of
    the property to a boolean expression that evaluates to \c true when you want
    the state to be applied.

    This enables you to evaluate the truthfulness of several components'
    properties and move the UI to the state in which these conditions apply.
    You can evaluate whether something is true or false, greater than or equal
    to something else, and so on. You can also use operators, such as AND or
    OR, to evaluate the truthfulness of several components.

    The when conditions are evaluated from left to right and in order of
    appearance in the code. Therefore, if you have two conditions for two
    different states that both evaluate to \c true, the first state is applied.

    In \uicontrol {Binding Editor}, select the component and property to
    create the expression. For example, to change the state when a button is
    pressed, you could select a button component and its pressed property.

    \image qtquick-states-binding-editor.png "Binding Editor in States view"

    When you compose the expressions in \uicontrol {Binding Editor}, the
    \l{Completing Code}{code completion} feature lists the components and
    their properties you can use in the expressions.

    \include creator-logical-operators.qdocinc logical operators

    \section2 Examples of when Conditions

    To apply a state to a button when the button is pressed, you could simply
    write:

    \badcode
    when: control.pressed
    \endcode

    To apply a state when the button is not pressed, select the \uicontrol NOT
    check box.

    \image qtquick-states-binding-editor-not.png "NOT check box in Binding Editor"

    To apply a state when the button is not pressed, selected, nor hovered on,
    you could combine conditions, as follows:

    \badcode
    when: !control.pressed && !control.checked && !control.hovered
    \endcode

    To apply a state when the button is pressed or selected, but not hovered on,
    you could write:

    \badcode
    when: control.pressed || control.checked && !control.hovered
    \endcode

    \section1 Using States

    To keep the QML code clean, you should create a base state that contains all
    the types you will need in the application. You can then create states,
    in which you hide and show a set of items and modify their properties.
    This allows you to:

    \list
        \li Align items on different views with each other.
        \li Avoid excessive property changes. If an item is invisible in the
            base state, you must define all changes to its child types as
            property changes, which leads to complicated QML code.
        \li Minimize the differences between the base state and the other states
            to keep the QML code short and readable and to improve performance.
        \li Avoid problems when using transitions and animation when changing
            states.
    \endlist

    To create views for an application by using states:

    \image qmldesigner-screen-design.png "Designing views"

    \list 1
        \li In the base state, add all items you will need in the application
            (1). While you work on one view, you can click the
            \inlineimage eye_open.png
            icon to hide items on the canvas that are not part of a view.
        \li In \uicontrol States, click the empty slot to create a
            new state and give it a name. For example, \c Normal.
        \li In \uicontrol Properties (2), deselect the \uicontrol Visibility
            check box or set \uicontrol Opacity to 0 for each item that is not
            needed in this view. If you specify the setting for the parent item,
            all child items inherit it and are also hidden.
        \li Create additional states for each view and set the visibility
            or opacity of the items in the view.
        \li To determine which state is applied when the application starts,
            select \uicontrol Actions > \uicontrol {Set as Default}.
    \endlist

    \if defined(qtcreator)
    \include qtquick-states-scxml.qdocinc scxml state machines
    \endif

    \include qtquick-transition-editor.qdocinc transition editor
*/
