From 056574f7d6c331ec7d972b298585e1a3a6c975ac Mon Sep 17 00:00:00 2001 From: Bea Lam Date: Tue, 17 Aug 2010 14:05:53 +1000 Subject: Docs - clarify use of PropertyChanges for immediate property changes in a State (e.g. for setting a transformOrigin for a RotationAnimation). Also improve some other animation docs in general. --- doc/src/declarative/animation.qdoc | 19 ++- doc/src/snippets/declarative/propertychanges.qml | 92 +++++++++++ doc/src/snippets/declarative/rotationanimation.qml | 3 +- src/declarative/util/qdeclarativeanimation.cpp | 169 +++++++++++++++------ .../util/qdeclarativepropertychanges.cpp | 119 ++++++--------- 5 files changed, 273 insertions(+), 129 deletions(-) create mode 100644 doc/src/snippets/declarative/propertychanges.qml diff --git a/doc/src/declarative/animation.qdoc b/doc/src/declarative/animation.qdoc index 7416341..53a0c55 100644 --- a/doc/src/declarative/animation.qdoc +++ b/doc/src/declarative/animation.qdoc @@ -156,11 +156,13 @@ The \l {PropertyAnimation::}{to} property is also required to specify the new \section2 Standalone Animations Animations can also be created as ordinary QML objects that are not bound to -any particular objects and properties. An example: +any particular objects and properties. Here is an example, using a +PropertyAnimation object. The animation is explicitly started when the +\l Rectangle is clicked: \snippet doc/src/snippets/declarative/animation-standalone.qml 0 -A standalone animation is not running by default and must be started explicitly +A standalone animation object is not running by default and must be started explicitly using the \l {Animation::}{running} property or \l {Animation::}{start()} and \l {Animation::}{stop()} methods. Since the animation is not bound to a particular object or property, it must define the \l @@ -183,10 +185,13 @@ object and add it to an item's \l {Item::}{transitions} property. An example: \snippet doc/src/snippets/declarative/animation-transitions.qml 0 -When the \l Rectangle changes to the \e moved state, its \c x and \c y property -values are changed by the PropertyChanges object, and the PropertyAnimation -defined within the \l Transition is triggered on these properties. The -animation will not be applied at any time other than during the state change. +The PropertyChanges object in the \e moved state defines that when the +\l Rectangle is in this state, its position should be changed +to (50, 50). When the \l Rectangle changes to the \e moved state, the +\l Transition will be triggered, and the transition's \l PropertyAnimation will +animate the changes in the \c x and \c y properties to their new values. +The animation will not be applied at any time other than during the state +change. Notice the example does not set any \l {PropertyAnimation::}{from} and \l {PropertyAnimation::}{to} values for the PropertyAnimation. As a convenience, @@ -234,7 +239,7 @@ and rotation changes. A ColorAnimation allows color values for the \l {ColorAnimation::}{from} and \l {ColorAnimation::}{to} properties. The -following animates the rectangle's \l {Rectangle::color} property: +following animates the rectangle's \l {Rectangle::}{color} property: \snippet doc/src/snippets/declarative/animation-elements.qml color diff --git a/doc/src/snippets/declarative/propertychanges.qml b/doc/src/snippets/declarative/propertychanges.qml new file mode 100644 index 0000000..9f119bf --- /dev/null +++ b/doc/src/snippets/declarative/propertychanges.qml @@ -0,0 +1,92 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the QtDeclarative module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ +//![import] +import Qt 4.7 +//![import] + +Column { + +//![0] +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 { target: rect; color: "blue"; height: container.height } + } + } +} +//![0] + +//![reset] +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 { target: myText; width: undefined } + } + } + + MouseArea { + anchors.fill: parent + onClicked: myText.state = "widerText" + } +} +//![reset] +} diff --git a/doc/src/snippets/declarative/rotationanimation.qml b/doc/src/snippets/declarative/rotationanimation.qml index c81395a..b56cb3f 100644 --- a/doc/src/snippets/declarative/rotationanimation.qml +++ b/doc/src/snippets/declarative/rotationanimation.qml @@ -52,7 +52,8 @@ Item { smooth: true states: State { - name: "rotated"; PropertyChanges { target: rect; rotation: 180 } + name: "rotated" + PropertyChanges { target: rect; rotation: 180 } } transitions: Transition { diff --git a/src/declarative/util/qdeclarativeanimation.cpp b/src/declarative/util/qdeclarativeanimation.cpp index 3b8cb37..4e9e8d5 100644 --- a/src/declarative/util/qdeclarativeanimation.cpp +++ b/src/declarative/util/qdeclarativeanimation.cpp @@ -694,9 +694,12 @@ QDeclarativeColorAnimation::~QDeclarativeColorAnimation() } \endqml - If this value is not set and the ColorAnimation is defined within - a \l Transition, it defaults to the value defined in the starting - state of the \l Transition. + If the ColorAnimation is defined within a \l Transition or \l Behavior, + this value defaults to the value defined in the starting state of the + \l Transition, or the current value of the property at the moment the + \l Behavior is triggered. + + \sa {QML Animation} */ QColor QDeclarativeColorAnimation::from() const { @@ -714,9 +717,12 @@ void QDeclarativeColorAnimation::setFrom(const QColor &f) This property holds the color value at which the animation should end. - If this value is not set and the ColorAnimation is defined within - a \l Transition or \l Behavior, it defaults to the value defined in the end - state of the \l Transition or \l Behavior. + If the ColorAnimation is defined within a \l Transition or \l Behavior, + this value defaults to the value defined in the end state of the + \l Transition, or the value of the property change that triggered the + \l Behavior. + + \sa {QML Animation} */ QColor QDeclarativeColorAnimation::to() const { @@ -887,29 +893,45 @@ QAbstractAnimation *QDeclarativeScriptAction::qtAnimation() \inherits Animation \brief The PropertyAction element allows immediate property changes during animation. - PropertyAction is used to specify an immediate property change - during an animation. The property change is not animated. + PropertyAction is used to specify an immediate property change during an + animation. The property change is not animated. - For example, to explicitly set \c {theImage.smooth = true} during a \l Transition: - \code - transitions: Transition { - ... - PropertyAction { target: theImage; property: "smooth"; value: true } - ... - } - \endcode + It is useful for setting non-animated property values during an animation. - Or, to set \c theWebView.url to the value set for the destination state: - \code + For example, here is a SequentialAnimation that sets the image's + \l {Image::}{smooth} property to \c true, animates the width of the image, + then sets \l {Image::}{smooth} back to \c false: + + \snippet doc/src/snippets/declarative/propertyaction.qml standalone + + PropertyAction is also useful for setting the exact point at which a property + change should occur during a \l Transition. For example, if PropertyChanges + was used in a \l State to rotate an item around a particular + \l {Item::}{transformOrigin}, it might be implemented like this: + + \snippet doc/src/snippets/declarative/propertyaction.qml transition + + However, with this code, the \c transformOrigin is not set until \e after + the animation, as a \l State is taken to define the values at the \e end of + a transition. The animation would rotate at the default \c transformOrigin, + then jump to \c Item.BottomRight. To fix this, insert a PropertyChanges + before the RotationAnimation begins: + + \qml transitions: Transition { - ... - PropertyAction { target: theWebView; property: "url" } - ... + SequentialAnimation { + PropertyAction { target: rect; property: "transformOrigin" } + RotationAnimation { ... } + } } - \endcode - + \endqml + + This immediately sets the \c transformOrigin property to the value defined + in the end state of the \l Transition (i.e. the value defined in the + PropertyChanges object) so that the rotation animation begins with the + correct transform origin. - \sa QtDeclarative + \sa {QML Animation}, QtDeclarative */ /*! \internal @@ -1014,7 +1036,11 @@ QDeclarativeListProperty QDeclarativePropertyAction::exclude() /*! \qmlproperty any PropertyAction::value This property holds the value to be set on the property. - If not set, then the value defined for the end state of the transition. + + If the PropertyAction is defined within a \l Transition or \l Behavior, + this value defaults to the value defined in the end state of the + \l Transition, or the value of the property change that triggered the + \l Behavior. */ QVariant QDeclarativePropertyAction::value() const { @@ -1190,7 +1216,7 @@ void QDeclarativeNumberAnimation::init() /*! \qmlproperty real NumberAnimation::from - This property holds the starting number value. + This property holds the starting value for the animation. For example, the following animation is not applied until the \c x value has reached 100: @@ -1205,9 +1231,12 @@ void QDeclarativeNumberAnimation::init() } \endqml - If this value is not set and the NumberAnimation is defined within - a \l Transition, it defaults to the value defined in the start - state of the \l Transition. + If the NumberAnimation is defined within a \l Transition or \l Behavior, + this value defaults to the value defined in the starting state of the + \l Transition, or the current value of the property at the moment the + \l Behavior is triggered. + + \sa {QML Animation} */ qreal QDeclarativeNumberAnimation::from() const @@ -1223,11 +1252,14 @@ void QDeclarativeNumberAnimation::setFrom(qreal f) /*! \qmlproperty real NumberAnimation::to - This property holds the ending number value. + This property holds the end value for the animation. - If this value is not set and the NumberAnimation is defined within - a \l Transition or \l Behavior, it defaults to the value defined in the end - state of the \l Transition or \l Behavior. + If the NumberAnimation is defined within a \l Transition or \l Behavior, + this value defaults to the value defined in the end state of the + \l Transition, or the value of the property change that triggered the + \l Behavior. + + \sa {QML Animation} */ qreal QDeclarativeNumberAnimation::to() const { @@ -1280,10 +1312,14 @@ QDeclarativeVector3dAnimation::~QDeclarativeVector3dAnimation() /*! \qmlproperty real Vector3dAnimation::from - This property holds the starting value. + This property holds the starting value for the animation. + + If the Vector3dAnimation is defined within a \l Transition or \l Behavior, + this value defaults to the value defined in the starting state of the + \l Transition, or the current value of the property at the moment the + \l Behavior is triggered. - If this value is not set, it defaults to the value defined in the start - state of the \l Transition. + \sa {QML Animation} */ QVector3D QDeclarativeVector3dAnimation::from() const { @@ -1298,10 +1334,14 @@ void QDeclarativeVector3dAnimation::setFrom(QVector3D f) /*! \qmlproperty real Vector3dAnimation::to - This property holds the ending value. + This property holds the end value for the animation. - If this value is not set, it defaults to the value defined in the end - state of the \l Transition or \l Behavior. + If the Vector3dAnimation is defined within a \l Transition or \l Behavior, + this value defaults to the value defined in the end state of the + \l Transition, or the value of the property change that triggered the + \l Behavior. + + \sa {QML Animation} */ QVector3D QDeclarativeVector3dAnimation::to() const { @@ -1343,6 +1383,12 @@ void QDeclarativeVector3dAnimation::setTo(QVector3D t) your own properties via \l {PropertyAnimation::properties}{properties} or \l {PropertyAnimation::property}{property}. + Also, note the \l Rectangle will be rotated around its default + \l {Item::}{transformOrigin} (which is \c Item.Center). To use a different + transform origin, set the origin in the PropertyChanges object and apply + the change at the start of the animation using PropertyAction. See the + PropertyAction documentation for more details. + Like any other animation element, a RotationAnimation can be applied in a number of ways, including transitions, behaviors and property value sources. The \l {QML Animation} documentation shows a variety of methods @@ -1408,7 +1454,7 @@ QDeclarativeRotationAnimation::~QDeclarativeRotationAnimation() /*! \qmlproperty real RotationAnimation::from - This property holds the starting number value. + This property holds the starting value for the animation. For example, the following animation is not applied until the \c angle value has reached 100: @@ -1423,8 +1469,12 @@ QDeclarativeRotationAnimation::~QDeclarativeRotationAnimation() } \endqml - If this value is not set, it defaults to the value defined in the start - state of the \l Transition. + If the RotationAnimation is defined within a \l Transition or \l Behavior, + this value defaults to the value defined in the starting state of the + \l Transition, or the current value of the property at the moment the + \l Behavior is triggered. + + \sa {QML Animation} */ qreal QDeclarativeRotationAnimation::from() const { @@ -1439,10 +1489,14 @@ void QDeclarativeRotationAnimation::setFrom(qreal f) /*! \qmlproperty real RotationAnimation::to - This property holds the ending value. + This property holds the end value for the animation.. + + If the RotationAnimation is defined within a \l Transition or \l Behavior, + this value defaults to the value defined in the end state of the + \l Transition, or the value of the property change that triggered the + \l Behavior. - If this value is not set, it defaults to the value defined in the end - state of the \l Transition or \l Behavior. + \sa {QML Animation} */ qreal QDeclarativeRotationAnimation::to() const { @@ -1854,8 +1908,14 @@ void QDeclarativePropertyAnimation::setDuration(int duration) /*! \qmlproperty real PropertyAnimation::from - This property holds the starting value. - If not set, then the value defined in the start state of the transition. + This property holds the starting value for the animation. + + If the PropertyAnimation is defined within a \l Transition or \l Behavior, + this value defaults to the value defined in the starting state of the + \l Transition, or the current value of the property at the moment the + \l Behavior is triggered. + + \sa {QML Animation} */ QVariant QDeclarativePropertyAnimation::from() const { @@ -1875,8 +1935,14 @@ void QDeclarativePropertyAnimation::setFrom(const QVariant &f) /*! \qmlproperty real PropertyAnimation::to - This property holds the ending value. - If not set, then the value defined in the end state of the transition or \l Behavior. + This property holds the end value for the animation. + + If the PropertyAnimation is defined within a \l Transition or \l Behavior, + this value defaults to the value defined in the end state of the + \l Transition, or the value of the property change that triggered the + \l Behavior. + + \sa {QML Animation} */ QVariant QDeclarativePropertyAnimation::to() const { @@ -2502,7 +2568,10 @@ void QDeclarativeParentAnimation::setTarget(QDeclarativeItem *target) \qmlproperty Item ParentAnimation::newParent The new parent to animate to. - If not set, then the parent defined in the end state of the transition. + If the ParentAnimation is defined within a \l Transition or \l Behavior, + this value defaults to the value defined in the end state of the + \l Transition, or the value of the property change that triggered the + \l Behavior. */ QDeclarativeItem *QDeclarativeParentAnimation::newParent() const { diff --git a/src/declarative/util/qdeclarativepropertychanges.cpp b/src/declarative/util/qdeclarativepropertychanges.cpp index 25edd35..c28ada3 100644 --- a/src/declarative/util/qdeclarativepropertychanges.cpp +++ b/src/declarative/util/qdeclarativepropertychanges.cpp @@ -65,48 +65,30 @@ QT_BEGIN_NAMESPACE \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 { @@ -115,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 */ @@ -397,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 { -- cgit v0.12