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 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 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:

  • Show some UI items 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.

Creating States

The States view displays the different states of a UI, beginning with a base state.

"States view"

To add states, select Create New State. Click the new state to switch to it in Form Editor, and then modify the properties of components in Properties.

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 in Form Editor and then add animation to the change between the states.

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

"States and Properties views"

Setting the Default State

To determine the startup state of the application, select to open the Actions menu, and then select Set as Default.

To reset the state later, select Actions > Reset Default.

Applying States

To determine when a state should be applied, select Actions > Set when Condition. In Binding Editor, specify a when property for the state. Set the value of the property to a boolean expression that evaluates to true when you want the state to be applied.

This enables you to evaluate the truthfulness of several components' properties and move the UI to the state in which these conditions apply. You can evaluate whether something is true or false, greater than or equal to something else, and so on. You can also use operators, such as AND or OR, to evaluate the truthfulness of several components.

The when conditions are evaluated from left to right and in order of appearance in the code. Therefore, if you have two conditions for two different states that both evaluate to true, the first state is applied.

In Binding Editor, select the component and property to create the expression. For example, to change the state when a button is pressed, you could select a button component and its pressed property.

"Binding Editor in States view"

When you compose the expressions in Binding Editor, the code completion feature lists the components and their properties you can use in the expressions.

Summary of Logical Operators

You can use the following logical operators in the expressions to combine several conditions in one expression:

OperatorMeaningEvaluates to true if
!NOTThe condition is not met.
&&ANDBoth conditions are met.
||OREither of the conditions is met.
<Less thanThe left operand is less than the right operand.
>Greater thanThe left operand is greater than the right operand.
>=Greater than or equalThe left operand is greater than or equal to the right operand.
<=Less than or equalThe left operand is less than or equal to the right operand.
==EqualThe operands are equal.
===Strict equalThe operands are equal and of the same type.
!=Not equalThe operands are not equal.
!==Strict not equalThe operands are of the same type but not equal, or are of different type.

In addition, you can use arithmetic operators to compare numbers before checks.

Examples of when Conditions

To apply a state to a button when the button is pressed, you could simply write:

when: control.pressed

To apply a state when the button is not pressed, selected, nor hovered on, you could combine conditions, as follows:

when: !control.pressed && !control.checked && !control.hovered

To apply a state when the button is pressed or selected, but not hovered on, you could write:

when: control.pressed || control.checked && !control.hovered

Using States

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:

  • Align items on different views with each other.
  • 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.
  • Minimize the differences between the base state and the other states to keep the QML code short and readable and to improve performance.
  • Avoid problems when using transitions and animation when changing states.

To create views for an application by using states:

"Designing views"

  1. In the base state, add all items you will need in the application (1). While you work on one view, you can click the icon to hide items on the canvas that are not part of a view.
  2. In States, click the empty slot to create a new state and give it a name. For example, Normal.
  3. In Properties (2), deselect the Visibility check box or set 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.
  4. Create additional states for each view and set the visibility or opacity of the items in the view.
  5. To determine which state is applied when the application starts, select Actions > Set as Default.

Using SCXML State Machines

To use QML together with an SCXML state machine, add states and bind them to the state machine in the Backends tab of the Connections view, as described in Managing C++ Backend Objects.

In the States view, you can select Actions > Set when Condition to edit the when condition of states to map QML states to the states of the SCXML state machine. For an example, see Qt SCXML Traffic Light QML Example (Dynamic).

If you add animation to the states, you can preview or run the application to test the animation.

Animating Transitions Between States

To make movement between states smooth, you can use Transition Editor to animate the changes between states. First, you need to add states in the States view and edit some properties that can be animated, such as colors or numbers, in the Properties view. For example, you can animate the changes in the position of an object.

In Transition Editor, you can set the start frame, end frame, and duration for the transition of each property. You can also set an easing curve for each transition.

Use the slider on the menu bar to the zooming level in the view.

To add transitions:

  1. Select View > Views > Transition Editor to display the view.
  2. Select the (Add Transition) button to add a transition. This works only if you have added at least one state and modified at least one property in it.

    "Transition Editor view"

  3. Move the blue bar next to the component or property name to set the start and end frame of the animation of the property. Pull its left and right edges to set the duration of the animation.
  4. To attach an easing curve to a transition, select (Easing Curve Editor (C)) on the toolbar. For more information, see Editing Easing Curves.
  5. To modify transition settings, select the (Transition Settings (S)) button on the toolbar.

    "Transition settings"

For an example of animating transitions between states, see Creating a Qt Quick Application.

© 2020 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.