/****************************************************************************
**
** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** 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 Digia.  For licensing terms and
** conditions see http://qt.digia.com/licensing.  For further information
** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
\ingroup qtquick-states
\page qtquick-statesanimations-states.html
\title Qt Quick States
\brief Creating and setting states

\section1 Related Types
\generatelist{related}

Many user interface designs are \e{state driven}; interfaces have configurations
that differ depending on the current state. For example, a traffic signal will
configure its flags or lights depending on its state. While in the signal's
\c stop state, a red light will turn on while the yellow and the green lights
will turn off. In the \c caution state, the yellow light is on while the other
lights are turned off.

In QML, \e states are a set of property configurations defined in a \l State
type. Different configurations could, for example:

\list
\li Show some UI components 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 or screen
\endlist

All \l {Item}-based objects have a \c state property, and can specify additional
states by adding new \c State objects to the item's \l {Item::}{states}
property. Each state within a component has a unique \c name, an empty string
being the default. To change the current state
of an item, set the \l {Item::}{state} property to the name of the state.

Non-Item objects may use states through the \l StateGroup type.

\section1 Creating States

To create a state, add a \l State object to the item's \l {Item::}{states} property,
which holds a list of states for that item.

A warning \c signal component may have two states, the \c NORMAL and the
\c CRITICAL state. Suppose that in the \c NORMAL state, the \c color of the
signal should be \c green and the warning \c flag is down. Meanwhile, in the
\c CRITICAL state, the \c color should be \c red and the flag is \c up. We may
model the states using the \c State type and the color and flag
configurations with the \c PropertyChanges type.
\snippet qml/states.qml signal states
The \l PropertyChanges type will change the values of object properties.
Objects are referenced through their
\l{qtqml-syntax-objectattributes.html#the-id-assignment}{id}. Objects outside
the component are also referenced using the \c id property, exemplified by the
property change to the external \c flag object.

Further, the state may change by assigning the \c state property with the
appropriate signal state. A state switch could be in a \l MouseArea type,
assigning a different state whenever the signal receives a mouse click.
\snippet qml/states.qml switch states

The State type is not limited to performing modifications on property values.
It can also:
\list
\li Run some script using \l StateChangeScript
\li Override an existing signal handler for an object using \l PropertyChanges
\li Re-parent an \l Item using \l ParentChange
\li Modify anchor values using \l AnchorChanges
\endlist

\section1 The Default State

Every \l Item based component has a \c state property and a \e{default state}.
The default state is the empty string (\c{""}) and contains all of an item's
initial property values. The default state is useful for managing property
values before state changes. Setting the \c state property to an empty string
will load the default state.

\section1 The \c when Property

For convenience, the \l State type has a \c when property that can bind to
expressions to change the state whenever the bound expression evaluates to
\c true. The \c when property will revert the state back to the
\l {The Default State}{default state} when the expression evaluates to false.

\snippet qml/states.qml when property
The \c bell component will change to the \c RINGING state whenever the
\c signal.state is \c CRITICAL.

\section1 Animating State Changes

State changes induce abrupt value changes. The \l Transition type allow
smoother changes during state changes. In transitions, animations and
interpolation behaviors are definable. The
\l{qtquick-statesanimations-animations.html}
{Animation and Transitions} article has more information about creating state
animations.

The \l {declarative/animation/states}{States and Transitions example}
demonstrates how to declare a basic set of states and apply animated
transitions between them.

\l{qtquick-statesanimations-behaviors.html}{Using Qt Quick Behaviors with States}
explains a common problem when using Behaviors to animate state changes.

\section1 State Fast Forwarding

In order for Transition to correctly animate state changes, it is sometimes necessary
for the engine to fast forward and rewind a state (that is, internally set and unset the state)
before it is finally applied. The process is as follows:

\list 1
\li The state is fast forwarded to determine the complete set of end values.
\li The state is rewound.
\li The state is fully applied, with transitions.
\endlist

In some cases this may cause unintended behavior. For example, a state that changes
a view's \e model or a Loader's \e sourceComponent will set these properties
multiple times (to apply, rewind, and then reapply), which can be relatively expensive.

State fast forwarding should be considered an implementation detail,
and may change in later versions.

*/