PropertyChanges QML Type
Describes new property bindings or values for a state. More...
Import Statement: | import QtQuick |
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() }
Note: PropertyChanges can be used to change anchor margins, but not other anchor values; use AnchorChanges for this instead. Similarly, to change an Item's parent value, use ParentChange instead.
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.
Note: The visible and enabled properties of Item do not behave exactly the same as other properties in PropertyChanges. Since these properties can be changed implicitly through their parent's state, they should be set explicitly in all PropertyChanges. An item will still not be enabled/visible if one of its parents is not enabled or visible.
Note: For backwards compatibility with Qt 5, you can also specify PropertyChanges using the target property and plain property names without IDs. For example: PropertyChanges { target: myItem; x: 15 }
. The form with ID instead of target is recommended. You may also need to use the form with target if the file is to be edited with Qt Design Studio. Mind that Qt Design Studio also imposes a number of further restrictions on the files it can work with.
See also States example, Qt Quick States, and Qt Qml.
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 |
This property holds whether the previous values should be restored when leaving the state.
The default value is true
. Setting this value to false
creates a temporary state that has permanent effects on property values.
target : QtObject |
This property holds the object which contains the properties to be changed.
Note: You generally don't have to use this property. It only exists for compatibility with Qt 5 and for compatibility with Qt Design Studio.
© 2024 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.