/****************************************************************************
**
** Copyright (C) 2019 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.
**
****************************************************************************/

/*!
    \contentspage {Qt Creator Manual}
    \page quick-states.html
    \if defined(qtdesignstudio)
    \previouspage quick-property-bindings.html
    \nextpage studio-fonts.html
    \else
    \previouspage quick-connections-backend.html
    \nextpage qmldesigner-pathview-editor.html
    \endif

    \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

    The \uicontrol States pane displays the different \l{State}{states}
    of the component in the Design mode. The \uicontrol States pane is
    collapsed by default to save space. Select \uicontrol Expand in
    the context menu to view the whole pane.

    \image qmldesigner-transitions.png "States pane"

    To add states, click the \inlineimage plus.png
    button. Then modify the new state in the editor. 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 on the canvas and then add animation to the change between the
    states.

    To determine when the state should be applied, select
    \uicontrol {Set when Condition} in the menu and specify a
    \l [QtQuick]{State::when}{when} property for the state.

    You can preview the states in the \uicontrol States pane and click them to
    switch between states on the canvas.

    \section1 Using States

    QML states typically describe user interface configurations, such as the UI
    controls, their properties and behavior and the available actions. For
    example, you can use states to create two views.

    To add states, click the empty slot in the \uicontrol States pane.
    Then modify the new state in the \uicontrol {Form Editor} or the
    \uicontrol Properties pane.

    \image qmldesigner-states.png "States pane"

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

    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:

    \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 the \uicontrol States pane, click the empty slot to create a
            new state and give it a name. For example, \c Normal.
        \li In the \uicontrol Properties pane (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.
            \image qmldesigner-screen-design.png "Designing views"
        \li Create additional states for each view and set the visibility
            or opacity of the items in the view.
        \li To determine which view opens when the application starts, use the
            \uicontrol {Text Editor} to set the state of the root item of the
           .qml file, as specified by the following code snippet:
            \qml
            Item {
                state: "Normal"
            }
            \endqml
        \endlist

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

    \section1 Animating Transitions Between States

    To make movement between states smooth, you can specify transitions. You can
    use different types of animated transitions. For example, you can animate
    changes to property values and colors. You can use rotation animation to
    control the direction of rotation. For more information, see
    \l{Animation and Transitions in Qt Quick}.

    You can use the \c ParallelAnimation type to start several animations at
    the same time. Or use the \c SequentialAnimation type to run them one
    after another.

    You can use the \uicontrol {Text Editor} to specify transitions. For more
    information, see \l{Transition}.

    Alternatively, you can use the \uicontrol Timeline view to animate the
    properties of UI components and to bind the animations to states. For more
    information, see \l {Binding Animations to States}.
*/
