PropertyChanges QML Type

Describes new property bindings or values for a state. More...

• List of all members, including inherited members

Properties

• explicit : bool
• restoreEntryValues : bool
• target : QtObject

Detailed Description

PropertyChanges is used to define the property values or bindings in a State. This enables an item's property values to be changed when it changes between states.

To create a PropertyChanges object, bind to properties of the target item like you would bind to local properties. This way you can define the new property values or bindings. For example:

import QtQuick

Item {
    id: container
    width: 300; height: 300

    Rectangle {
        id: rect
        width: 100; height: 100
        color: "red"

        MouseArea {
           id: mouseArea
           anchors.fill: parent
        }

        states: State {
           name: "resized"; when: mouseArea.pressed
           PropertyChanges {
               rect {
                   color: "blue"
                   height: container.height
               }
           }
        }
    }
}

When the mouse is pressed, the Rectangle changes to the resized state. In this state, the PropertyChanges object sets the rectangle's color to blue and the height value to that of container.height.

Note this automatically binds rect.height to container.height in the resized state. If a property binding should not be established, and the height should just be set to the value of container.height at the time of the state change, set the explicit property to true.

A PropertyChanges object can also override the default signal handler for an object to implement a signal handler specific to the new state:

PropertyChanges {
    myMouseArea.onClicked: doSomethingDifferent()
}

Resetting Property Values

The undefined value can be used to reset the property value for a state. In the following example, when myText changes to the widerText state, its width property is reset, giving the text its natural width and displaying the whole string on a single line.

Rectangle {
    width: 300; height: 200

    Text {
        id: myText
        width: 50
        wrapMode: Text.WordWrap
        text: "a text string that is longer than 50 pixels"

        states: State {
            name: "widerText"
            PropertyChanges { myText.width: undefined }
        }
    }

    MouseArea {
        anchors.fill: parent
        onClicked: myText.state = "widerText"
    }
}

Immediate Property Changes in Transitions

When Transitions are used to animate state changes, they animate properties from their values in the current state to those defined in the new state (as defined by PropertyChanges objects). However, it is sometimes desirable to set a property value immediately during a Transition, without animation; in these cases, the PropertyAction type can be used to force an immediate property change.

See the PropertyAction documentation for more details.

See also States example, Qt Quick States, and Qt Qml.

Property Documentation

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