diff options
Diffstat (limited to 'src/declarative/util/qdeclarativepropertychanges.cpp')
| -rw-r--r-- | src/declarative/util/qdeclarativepropertychanges.cpp | 120 |
1 files changed, 49 insertions, 71 deletions
diff --git a/src/declarative/util/qdeclarativepropertychanges.cpp b/src/declarative/util/qdeclarativepropertychanges.cpp index 12c6353..c28ada3 100644 --- a/src/declarative/util/qdeclarativepropertychanges.cpp +++ b/src/declarative/util/qdeclarativepropertychanges.cpp @@ -61,51 +61,34 @@ QT_BEGIN_NAMESPACE /*! \qmlclass PropertyChanges QDeclarativePropertyChanges + \ingroup qml-state-elements \since 4.7 \brief The PropertyChanges element describes new property bindings or values for a state. - PropertyChanges provides a state change that modifies the properties of an item. + PropertyChanges is used to define the property values or bindings in a + \l State. This enables an item's property values to be changed when it + \l {QML States}{changes between states}. - Here is a property change that modifies the text and color of a \l Text element - when it is clicked: + To create a PropertyChanges object, specify the \l target item whose + properties are to be modified, and define the new property values or + bindings. For example: - \qml - 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' } - } - \endqml - - By default, PropertyChanges will establish new bindings where appropriate. - For example, the following creates a new binding for myItem's \c height property. - - \qml - PropertyChanges { - target: myItem - height: parent.height - } - \endqml - - 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 \l{PropertyChanges::explicit}{explicit} + \snippet doc/src/snippets/declarative/propertychanges.qml import + \codeline + \snippet doc/src/snippets/declarative/propertychanges.qml 0 + + When the mouse is pressed, the \l Rectangle changes to the \e resized + state. In this state, the PropertyChanges object sets the rectangle's + color to blue and the \c height value to that of \c container.height. + + Note this automatically binds \c rect.height to \c container.height + in the \e resized state. If a property binding should not be + established, and the height should just be set to the value of + \c container.height at the time of the state change, set the \l explicit property to \c true. - - State-specific script for signal handlers can also be specified: + + A PropertyChanges object can also override the default signal handler + for an object to implement a signal handler specific to the new state: \qml PropertyChanges { @@ -114,36 +97,31 @@ QT_BEGIN_NAMESPACE } \endqml - You can reset a property in a state change by assigning \c undefined. In the following - example we reset \c theText's width when we enter state1. This will give the text its - natural width (which is the whole string on one line). + \note PropertyChanges can be used to change anchor margins, but not other anchor + values; use AnchorChanges for this instead. Similarly, to change an \l Item's + \l {Item::}{parent} value, use ParentChanges instead. - \qml - 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 - } - } - } - \endqml + \section2 Resetting property values - 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). + The \c undefined value can be used to reset the property value for a state. + In the following example, when \c theText changes to the \e widerText + state, its \c width property is reset, giving the text its natural width + and displaying the whole string on a single line. + + \snippet doc/src/snippets/declarative/propertychanges.qml reset + + + \section2 Immediate property changes in transitions + + When \l 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 \e immediately during a + \l Transition, without animation; in these cases, the PropertyAction + element can be used to force an immediate property change. + + See the PropertyAction documentation for more details. \sa {declarative/animation/states}{states example}, {qmlstate}{States}, QtDeclarative */ @@ -396,12 +374,12 @@ void QDeclarativePropertyChanges::setObject(QObject *o) /*! \qmlproperty bool PropertyChanges::restoreEntryValues - - 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. + This property holds whether the previous values should be restored when + leaving the state. + + The default value is \c true. Setting this value to \c false creates a + temporary state that has permanent effects on property values. */ bool QDeclarativePropertyChanges::restoreEntryValues() const { |