Qt Reference Documentation

QML States

Overview

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 state to another.

This applies generally to interface elements 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. On the other end of the scale, when a simple button is pressed, it may change to a "pressed" state in which its color and position is modified to give a pressed appearance.

In QML, any object can change between different states to apply sets of changes that modify the properties of relevant items. Each state could present a different configuration that 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"

Changes between states can be animated using transitions, as discussed further below.

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

Non-Item objects can 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.

Following is an example. Here, the Rectangle is initially placed in the default (0, 0) position. It has defined an additional state named "moved", in which a PropertyChanges object repositions the rectangle to (50, 50). Clicking within the MouseArea changes the state to the "moved" state, thus moving the Rectangle.

 import Qt 4.7

 Rectangle {
     id: myRect
     width: 200; height: 200
     color: "red"

     MouseArea {
         anchors.fill: parent
         onClicked: myRect.state = 'moved'
     }

     states: [
         State {
             name: "moved"
             PropertyChanges { target: myRect; x: 50; y: 50 }
         }
     ]
 }

A State item defines all the changes to be made in the new state. You could specify additional properties to be changed, or create additional PropertyChanges for other objects. (Note that a State can modify the properties of other objects, not just the object that owns the state.)

For example:

 State {
     name: "moved"
     PropertyChanges { target: myRect; x: 50; y: 50; color: "blue" }
     PropertyChanges { target: someOtherItem; width: 1000 }
 }

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

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

The default state

Of course, the Rectangle in the example above could have simply been moved by setting its position to (50, 50) in the mouse area's onClicked handler. However, aside from enabling batched property changes, the use of states allows an item to revert to its default state, which contains all of the items' initial property values before they were modified in a state change.

The default state is specified by an empty string. If the MouseArea in the above example was changed to this:

 MouseArea {
     anchors.fill: parent
     onClicked: myRect.state == 'moved' ? myRect.state = "" : myRect.state = 'moved';
 }

This would toggle the Rectangle's state between the moved and default states when clicked. The properties can be reverted to their initial values without requiring the definition of another State that defines these value changes.

The "when" property

The when property is useful for specifying when a state should be applied. This can be set to an expression that evaluates to true when an item should change to a particular state.

If the above example was changed to this:

 Rectangle {
     ...

     MouseArea {
         id: mouseArea
         anchors.fill: parent
     }

     states: State {
         name: "moved"; when: mouseArea.pressed
         ...
     }

The Rectangle would automatically change to the moved state when the mouse is pressed, and revert to the default state when it is released. This is simpler (and a better, more declarative method) than creating onPressed and onReleased handlers in the MouseArea to set the current state.

Animating state changes

State changes can be easily animated through transitions. A Transition defines the animations that should be applied when an item changes from one state to another.

If the above example was modified to include the following Transition, the movement of the Rectangle would be animated:

 Rectangle {
     ...

     MouseArea { ... }

     states: [
        ...
     ]

     transitions: [
         Transition {
             NumberAnimation { properties: "x,y"; duration: 500 }
         }
     ]
  }

This Transition defines that if any x or y properties have changed during a state change within this item, their values should be animated over 500 millliseconds.

See the Transitions documentation for more information.

X

Thank you for giving your feedback.

Make sure it is related to this specific page. For more general bugs and requests, please use the Qt Bug Tracker.