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:
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.
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 }
}
]
}
The State item defines all the changes to be made in the new state. It could specify additional properties to be changed, or create additional PropertyChanges for other objects. It can also modify the properties of other objects, not just the object that owns the state. For example:
Rectangle {
...
states: [
State {
name: "moved"
PropertyChanges { target: myRect; x: 50; y: 50; color: "blue" }
PropertyChanges { target: someOtherItem; width: 1000 }
}
]
}
As a convenience, if an item only has one state, its states property can be defined as a single State, without the square-brace list syntax:
Item {
...
states: State {
...
}
}
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.
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, one of the features of QML states is the ability of an item to revert to its default state. The default state contains all of an item's initial property values before they were modified in a state change.
For example, suppose the Rectangle should move to (50,50) when the mouse is pressed, and then move back to its original position when the mouse is released. This can be achieved by using the when property, like this:
Rectangle {
...
MouseArea {
id: mouseArea
anchors.fill: parent
}
states: State {
name: "moved"; when: mouseArea.pressed
...
}
}
The when property is set to an expression that evaluates to true when the item should be set to that state. When the mouse is pressed, the state is changed to moved. When it is released, the item reverts to its default state, which defines all of the item's original property values.
Alternatively, an item can be explicitly set to its default state by setting its state property to an empty string (""). For example, instead of using the when property, the above code could be changed to:
Rectangle {
...
MouseArea {
anchors.fill: parent
onPressed: myRect.state = 'moved';
onReleased: myRect.state = '';
}
states: State {
name: "moved"
...
}
}
Obviously it makes sense to use the when property when possible as it provides a simpler (and a better, more declarative) solution than assigning the state from signal handlers.
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.