Qt Reference Documentation

[Previous: Importing Reusable Components] [Next: Animation and Transitions]

# QML States

## States Elements

- State
- PropertyChanges
- StateGroup
- StateChangeScript
- ParentChange
- AnchorChanges

Many user interface designs are 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 `stop` state, a red light will turn on while the yellow and the green lights will turn off. In the `caution` state, the yellow light is on while the other lights are turned off.

In QML, states are a set of property configurations defined in a State element. Different configurations could, for example:

- Show some UI elements and hide others
- Present different available actions to the user
- Start, stop, or pause animations
- Execute some script required in the new state
- Change a property value for a particular item
- Show a different view or screen

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

Non-Item objects may use states through the StateGroup element.

## Creating States

To create a state, add a State object to the item's states property, which holds a list of states for that item.

A warning `signal` component may have two states, the `NORMAL` and the `CRITICAL` state. Suppose that in the `NORMAL` state, the `color` of the signal should be `green` and the warning `flag` is down. Meanwhile, in the `CRITICAL` state, the `color` should be `red` and the flag is `up`. We may model the states using the `State` element and the color and flag configurations with the `PropertyChanges` element.

     Rectangle {
         id: signal
         width: 200; height: 200
         state: "NORMAL"

         states: [
             State {
                 name: "NORMAL"
                 PropertyChanges { target: signal; color: "green"}
                 PropertyChanges { target: flag; state: "FLAG_DOWN"}
             },
             State {
                 name: "CRITICAL"
                 PropertyChanges { target: signal; color: "red"}
                 PropertyChanges { target: flag; state: "FLAG_UP"}
             }
         ]
     }

The PropertyChanges element will change the values of object properties. Objects are referenced through their id. Objects outside the component are also referenced using the `id` property, exemplified by the property change to the external `flag` object.

Further, the state may change by assigning the `state` property with the appropriate signal state. A state switch could be in a MouseArea element, assigning a different state whenever the signal receives a mouse click.

     Rectangle {
         id: signalswitch
         width: 75; height: 75
         color: "blue"

         MouseArea {
             anchors.fill: parent
             onClicked: {
                 if (signal.state == "NORMAL")
                     signal.state = "CRITICAL"
                 else
                     signal.state = "NORMAL"
             }
         }
     }

The State element is not limited to performing modifications on property values. It can also:

- Run some script using StateChangeScript
- Override an existing signal handler for an object using PropertyChanges
- Re-parent an Item using ParentChange
- Modify anchor values using AnchorChanges

## The Default State

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

## The `when` Property

For convenience, the State element has a `when` property that can bind to expressions to change the state whenever the bound expression evaluates to `true`. The `when` property will revert the state back to the default state when the expression evaluates to false.

     Rectangle {
         id: bell
         width: 75; height: 75
         color: "yellow"

         states: State {
                     name: "RINGING"
                     when: (signal.state == "CRITICAL")
                     PropertyChanges {target: speaker; play: "RING!"}
                 }
     }

The `bell` component will change to the `RINGING` state whenever the `signal.state` is `CRITICAL`.

## Animating State Changes

State changes induce abrupt value changes. The Transition element allow smoother changes during state changes. In transitions, animations and interpolation behaviors are definable. The Animation and Transitions article has more information about creating state animations.

The States and Transitions example demonstrates how to declare a basic set of states and apply animated transitions between them.