diff -r ef0373b55136 -r 758a864f9613 src/declarative/util/qdeclarativeanimation.cpp --- a/src/declarative/util/qdeclarativeanimation.cpp Fri Sep 17 08:34:18 2010 +0300 +++ b/src/declarative/util/qdeclarativeanimation.cpp Mon Oct 04 01:19:32 2010 +0300 @@ -74,6 +74,7 @@ /*! \qmlclass Animation QDeclarativeAbstractAnimation + \ingroup qml-animation-transition \since 4.7 \brief The Animation element is the base of all QML animations. @@ -83,11 +84,6 @@ element directly will result in an error. */ -/*! - \class QDeclarativeAbstractAnimation - \internal -*/ - QDeclarativeAbstractAnimation::QDeclarativeAbstractAnimation(QObject *parent) : QObject(*(new QDeclarativeAbstractAnimationPrivate), parent) { @@ -336,7 +332,7 @@ stopped - either by setting the \c running property to false, or by calling the \c stop() method. - In the following example, the rectangle will spin indefinately. + In the following example, the rectangle will spin indefinitely. \code Rectangle { @@ -554,6 +550,7 @@ /*! \qmlclass PauseAnimation QDeclarativePauseAnimation + \ingroup qml-animation-transition \since 4.7 \inherits Animation \brief The PauseAnimation element provides a pause for an animation. @@ -572,12 +569,6 @@ \sa {QML Animation}, {declarative/animation/basics}{Animation basics example} */ -/*! - \internal - \class QDeclarativePauseAnimation -*/ - - QDeclarativePauseAnimation::QDeclarativePauseAnimation(QObject *parent) : QDeclarativeAbstractAnimation(*(new QDeclarativePauseAnimationPrivate), parent) { @@ -630,6 +621,7 @@ /*! \qmlclass ColorAnimation QDeclarativeColorAnimation + \ingroup qml-animation-transition \since 4.7 \inherits PropertyAnimation \brief The ColorAnimation element animates changes in color values. @@ -645,21 +637,17 @@ Like any other animation element, a ColorAnimation can be applied in a number of ways, including transitions, behaviors and property value - sources. The \l PropertyAnimation documentation shows a variety of methods + sources. The \l {QML Animation} documentation shows a variety of methods for creating animations. - When used in a transition, ColorAnimation will by default animate - all properties of type color that have changed. If a \l{PropertyAnimation::}{property} - or \l{PropertyAnimation::}{properties} are explicitly set for the animation, + For convenience, when a ColorAnimation is used in a \l Transition, it will + animate any \c color properties that have been modified during the state + change. If a \l{PropertyAnimation::}{property} or + \l{PropertyAnimation::}{properties} are explicitly set for the animation, then those are used instead. \sa {QML Animation}, {declarative/animation/basics}{Animation basics example} */ -/*! - \internal - \class QDeclarativeColorAnimation -*/ - QDeclarativeColorAnimation::QDeclarativeColorAnimation(QObject *parent) : QDeclarativePropertyAnimation(parent) { @@ -690,9 +678,12 @@ } \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 { @@ -710,9 +701,12 @@ 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 { @@ -729,6 +723,7 @@ /*! \qmlclass ScriptAction QDeclarativeScriptAction + \ingroup qml-animation-transition \since 4.7 \inherits Animation \brief The ScriptAction element allows scripts to be run during an animation. @@ -765,10 +760,6 @@ \sa StateChangeScript */ -/*! - \internal - \class QDeclarativeScriptAction -*/ QDeclarativeScriptAction::QDeclarativeScriptAction(QObject *parent) :QDeclarativeAbstractAnimation(*(new QDeclarativeScriptActionPrivate), parent) { @@ -877,37 +868,50 @@ /*! \qmlclass PropertyAction QDeclarativePropertyAction + \ingroup qml-animation-transition \since 4.7 \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. - - For example, to explicitly set \c {theImage.smooth = true} during a \l Transition: - \code + PropertyAction is used to specify an immediate property change during an + animation. The property change is not animated. + + It is useful for setting non-animated property values during an animation. + + 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: theImage; property: "smooth"; value: true } - ... + SequentialAnimation { + PropertyAction { target: rect; property: "transformOrigin" } + RotationAnimation { ... } + } } - \endcode - - Or, to set \c theWebView.url to the value set for the destination state: - \code - transitions: Transition { - ... - PropertyAction { target: theWebView; property: "url" } - ... - } - \endcode - - - \sa QtDeclarative -*/ -/*! - \internal - \class QDeclarativePropertyAction + \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 {QML Animation}, QtDeclarative */ QDeclarativePropertyAction::QDeclarativePropertyAction(QObject *parent) : QDeclarativeAbstractAnimation(*(new QDeclarativePropertyActionPrivate), parent) @@ -939,7 +943,7 @@ if (d->target == o) return; d->target = o; - emit targetChanged(d->target, d->propertyName); + emit targetChanged(); } QString QDeclarativePropertyAction::property() const @@ -954,7 +958,7 @@ if (d->propertyName == n) return; d->propertyName = n; - emit targetChanged(d->target, d->propertyName); + emit propertyChanged(); } /*! @@ -1008,7 +1012,11 @@ /*! \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 { @@ -1128,6 +1136,7 @@ /*! \qmlclass NumberAnimation QDeclarativeNumberAnimation + \ingroup qml-animation-transition \since 4.7 \inherits PropertyAnimation \brief The NumberAnimation element animates changes in qreal-type values. @@ -1143,7 +1152,7 @@ Like any other animation element, a NumberAnimation can be applied in a number of ways, including transitions, behaviors and property value - sources. The \l PropertyAnimation documentation shows a variety of methods + sources. The \l {QML Animation} documentation shows a variety of methods for creating animations. Note that NumberAnimation may not animate smoothly if there are irregular @@ -1152,12 +1161,6 @@ \sa {QML Animation}, {declarative/animation/basics}{Animation basics example} */ - -/*! - \internal - \class QDeclarativeNumberAnimation -*/ - QDeclarativeNumberAnimation::QDeclarativeNumberAnimation(QObject *parent) : QDeclarativePropertyAnimation(parent) { @@ -1183,7 +1186,7 @@ /*! \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: @@ -1198,9 +1201,12 @@ } \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 @@ -1216,11 +1222,14 @@ /*! \qmlproperty real NumberAnimation::to - This property holds the ending number value. - - 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. + This property holds the end value for the animation. + + 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 { @@ -1237,6 +1246,7 @@ /*! \qmlclass Vector3dAnimation QDeclarativeVector3dAnimation + \ingroup qml-animation-transition \since 4.7 \inherits PropertyAnimation \brief The Vector3dAnimation element animates changes in QVector3d values. @@ -1244,14 +1254,13 @@ Vector3dAnimation is a specialized PropertyAnimation that defines an animation to be applied when a Vector3d value changes. + Like any other animation element, a Vector3dAnimation 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 + for creating animations. + \sa {QML Animation}, {declarative/animation/basics}{Animation basics example} */ - -/*! - \internal - \class QDeclarativeVector3dAnimation -*/ - QDeclarativeVector3dAnimation::QDeclarativeVector3dAnimation(QObject *parent) : QDeclarativePropertyAnimation(parent) { @@ -1267,10 +1276,14 @@ /*! \qmlproperty real Vector3dAnimation::from - This property holds the starting value. - - If this value is not set, it defaults to the value defined in the start - state of the \l Transition. + 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. + + \sa {QML Animation} */ QVector3D QDeclarativeVector3dAnimation::from() const { @@ -1285,10 +1298,14 @@ /*! \qmlproperty real Vector3dAnimation::to - This property holds the ending value. - - If this value is not set, it defaults to the value defined in the end - state of the \l Transition or \l Behavior. + This property holds the end 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 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 { @@ -1305,6 +1322,7 @@ /*! \qmlclass RotationAnimation QDeclarativeRotationAnimation + \ingroup qml-animation-transition \since 4.7 \inherits PropertyAnimation \brief The RotationAnimation element animates changes in rotation values. @@ -1323,25 +1341,25 @@ \snippet doc/src/snippets/declarative/rotationanimation.qml 0 - Notice the RotationAnimation did not need to set a \l {RotationAnimation::}{target} + Notice the RotationAnimation did not need to set a \l target value. As a convenience, when used in a transition, RotationAnimation will rotate all properties named "rotation" or "angle". You can override this by providing 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 PropertyAnimation documentation shows a variety of methods + sources. The \l {QML Animation} documentation shows a variety of methods for creating animations. \sa {QML Animation}, {declarative/animation/basics}{Animation basics example} */ - -/*! - \internal - \class QDeclarativeRotationAnimation -*/ - QVariant _q_interpolateShortestRotation(qreal &f, qreal &t, qreal progress) { qreal newt = t; @@ -1394,7 +1412,7 @@ /*! \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: @@ -1409,8 +1427,12 @@ } \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 { @@ -1425,10 +1447,14 @@ /*! \qmlproperty real RotationAnimation::to - This property holds the ending value. - - If this value is not set, it defaults to the value defined in the end - state of the \l Transition or \l Behavior. + 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. + + \sa {QML Animation} */ qreal QDeclarativeRotationAnimation::to() const { @@ -1534,6 +1560,7 @@ /*! \qmlclass SequentialAnimation QDeclarativeSequentialAnimation + \ingroup qml-animation-transition \since 4.7 \inherits Animation \brief The SequentialAnimation element allows animations to be run sequentially. @@ -1554,9 +1581,13 @@ Like any other animation element, a SequentialAnimation can be applied in a number of ways, including transitions, behaviors and property value - sources. The \l PropertyAnimation documentation shows a variety of methods + sources. The \l {QML Animation} documentation shows a variety of methods for creating animations. + \note Once an animation has been grouped into a SequentialAnimation or + ParallelAnimation, it cannot be individually started and stopped; the + SequentialAnimation or ParallelAnimation must be started and stopped as a group. + \sa ParallelAnimation, {QML Animation}, {declarative/animation/basics}{Animation basics example} */ @@ -1603,6 +1634,7 @@ /*! \qmlclass ParallelAnimation QDeclarativeParallelAnimation + \ingroup qml-animation-transition \since 4.7 \inherits Animation \brief The ParallelAnimation element allows animations to be run in parallel. @@ -1619,16 +1651,15 @@ Like any other animation element, a ParallelAnimation can be applied in a number of ways, including transitions, behaviors and property value - sources. The \l PropertyAnimation documentation shows a variety of methods + sources. The \l {QML Animation} documentation shows a variety of methods for creating animations. + \note Once an animation has been grouped into a SequentialAnimation or + ParallelAnimation, it cannot be individually started and stopped; the + SequentialAnimation or ParallelAnimation must be started and stopped as a group. + \sa SequentialAnimation, {QML Animation}, {declarative/animation/basics}{Animation basics example} */ -/*! - \internal - \class QDeclarativeParallelAnimation -*/ - QDeclarativeParallelAnimation::QDeclarativeParallelAnimation(QObject *parent) : QDeclarativeAnimationGroup(parent) { @@ -1717,6 +1748,7 @@ /*! \qmlclass PropertyAnimation QDeclarativePropertyAnimation + \ingroup qml-animation-transition \since 4.7 \inherits Animation \brief The PropertyAnimation element animates changes in property values. @@ -1829,8 +1861,14 @@ /*! \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 { @@ -1850,8 +1888,14 @@ /*! \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 { @@ -1929,15 +1973,15 @@ \o \inlineimage qeasingcurve-inquart.png \row \o \c Easing.OutQuart - \o Easing curve for a cubic (t^4) function: decelerating from zero velocity. + \o Easing curve for a quartic (t^4) function: decelerating from zero velocity. \o \inlineimage qeasingcurve-outquart.png \row \o \c Easing.InOutQuart - \o Easing curve for a cubic (t^4) function: acceleration until halfway, then deceleration. + \o Easing curve for a quartic (t^4) function: acceleration until halfway, then deceleration. \o \inlineimage qeasingcurve-inoutquart.png \row \o \c Easing.OutInQuart - \o Easing curve for a cubic (t^4) function: deceleration until halfway, then acceleration. + \o Easing curve for a quartic (t^4) function: deceleration until halfway, then acceleration. \o \inlineimage qeasingcurve-outinquart.png \row \o \c Easing.InQuint @@ -1945,15 +1989,15 @@ \o \inlineimage qeasingcurve-inquint.png \row \o \c Easing.OutQuint - \o Easing curve for a cubic (t^5) function: decelerating from zero velocity. + \o Easing curve for a quintic (t^5) function: decelerating from zero velocity. \o \inlineimage qeasingcurve-outquint.png \row \o \c Easing.InOutQuint - \o Easing curve for a cubic (t^5) function: acceleration until halfway, then deceleration. + \o Easing curve for a quintic (t^5) function: acceleration until halfway, then deceleration. \o \inlineimage qeasingcurve-inoutquint.png \row \o \c Easing.OutInQuint - \o Easing curve for a cubic (t^5) function: deceleration until halfway, then acceleration. + \o Easing curve for a quintic (t^5) function: deceleration until halfway, then acceleration. \o \inlineimage qeasingcurve-outinquint.png \row \o \c Easing.InSine @@ -2096,7 +2140,7 @@ if (d->target == o) return; d->target = o; - emit targetChanged(d->target, d->propertyName); + emit targetChanged(); } QString QDeclarativePropertyAnimation::property() const @@ -2111,7 +2155,7 @@ if (d->propertyName == n) return; d->propertyName = n; - emit targetChanged(d->target, d->propertyName); + emit propertyChanged(); } QString QDeclarativePropertyAnimation::properties() const @@ -2378,18 +2422,20 @@ d->actions = &data->actions; } else { delete data; + d->va->setFromSourcedValue(0); //clear previous data + d->va->setAnimValue(0, QAbstractAnimation::DeleteWhenStopped); //clear previous data d->actions = 0; } } /*! \qmlclass ParentAnimation QDeclarativeParentAnimation + \ingroup qml-animation-transition \since 4.7 \inherits Animation \brief The ParentAnimation element animates changes in parent values. - ParentAnimation defines an animation to applied when a ParentChange - occurs. This allows parent changes to be smoothly animated. + ParentAnimation is used to animate a parent change for an \l Item. For example, the following ParentChange changes \c blueRect to become a child of \c redRect when it is clicked. The inclusion of the @@ -2407,17 +2453,18 @@ to animate the parent change via another item that does not have clipping enabled. Such an item can be set using the \l via property. - By default, when used in a transition, ParentAnimation animates all parent - changes. This can be overriden by setting a specific target item using the + For convenience, when a ParentAnimation is used in a \l Transition, it will + animate any ParentChange that has occurred during the state change. + This can be overridden by setting a specific target item using the \l target property. + Like any other animation element, a ParentAnimation 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 + for creating animations. + \sa {QML Animation}, {declarative/animation/basics}{Animation basics example} */ - -/*! - \internal - \class QDeclarativeParentAnimation -*/ QDeclarativeParentAnimation::QDeclarativeParentAnimation(QObject *parent) : QDeclarativeAnimationGroup(*(new QDeclarativeParentAnimationPrivate), parent) { @@ -2469,7 +2516,10 @@ \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 { @@ -2738,18 +2788,28 @@ /*! \qmlclass AnchorAnimation QDeclarativeAnchorAnimation + \ingroup qml-animation-transition \since 4.7 \inherits Animation \brief The AnchorAnimation element animates changes in anchor values. - AnchorAnimation is used to animate an AnchorChange. It will anchor all - anchor changes specified in a \l State. + AnchorAnimation is used to animate an anchor change. In the following snippet we animate the addition of a right anchor to a \l Rectangle: \snippet doc/src/snippets/declarative/anchoranimation.qml 0 - \sa AnchorChanges + For convenience, when an AnchorAnimation is used in a \l Transition, it will + animate any AnchorChanges that have occurred during the state change. + This can be overridden by setting a specific target item using the + \l target property. + + Like any other animation element, an AnchorAnimation 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 + for creating animations. + + \sa {QML Animation}, AnchorChanges */ QDeclarativeAnchorAnimation::QDeclarativeAnchorAnimation(QObject *parent)