Qt Reference Documentation

QML PropertyChanges Element

The PropertyChanges element describes new property bindings or values for a state. More...

  • List of all members, including inherited members
  • Properties

    Detailed Description

    PropertyChanges provides a state change that modifies the properties of an item.

    Here is a property change that modifies the text and color of a Text element when it is clicked:

     Text {
         id: myText
         width: 100; height: 100
         text: "Hello"
         color: "blue"
         states: State {
             name: "myState"
             PropertyChanges {
                 target: myText
                 text: "Goodbye"
                 color: "red"
         MouseArea { anchors.fill: parent; onClicked: myText.state = 'myState' }

    By default, PropertyChanges will establish new bindings where appropriate. For example, the following creates a new binding for myItem's height property.

     PropertyChanges {
         target: myItem
         height: parent.height

    If you don't want a binding to be established (and instead just want to assign the value of the binding at the time the state is entered), you should set the PropertyChange's explicit property to true.

    State-specific script for signal handlers can also be specified:

     PropertyChanges {
         target: myMouseArea
         onClicked: doSomethingDifferent()

    You can reset a property in a state change by assigning undefined. In the following example we reset theText's width when we enter state1. This will give the text its natural width (which is the whole string on one line).

     import Qt 4.7
     Rectangle {
         width: 640
         height: 480
         Text {
             id: theText
             width: 50
             wrapMode: Text.WordWrap
             text: "a text string that is longer than 50 pixels"
         states: State {
             name: "state1"
             PropertyChanges {
                 target: theText
                 width: undefined

    Anchor margins should be changed with PropertyChanges, but other anchor changes or changes to an Item's parent should be done using the associated change elements (ParentChange and AnchorChanges, respectively).

    See also states example, States, and QtDeclarative.

    Property Documentation

    explicit : bool

    If explicit is set to true, any potential bindings will be interpreted as once-off assignments that occur when the state is entered.

    In the following example, the addition of explicit prevents myItem.width from being bound to parent.width. Instead, it is assigned the value of parent.width at the time of the state change.

     PropertyChanges {
         target: myItem
         explicit: true
         width: parent.width

    By default, explicit is false.

    restoreEntryValues : bool

    Whether or not the previous values should be restored when leaving the state. By default, restoreEntryValues is true.

    By setting restoreEntryValues to false, you can create a temporary state that has permanent effects on property values.

    target : Object

    This property holds the object which contains the properties to be changed.


    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.

    [0]; s.parentNode.insertBefore(ga, s); })();