diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/corelib/animation/qabstractanimation.cpp | 87 | ||||
| -rw-r--r-- | src/corelib/animation/qvariantanimation.cpp | 166 |
2 files changed, 153 insertions, 100 deletions
diff --git a/src/corelib/animation/qabstractanimation.cpp b/src/corelib/animation/qabstractanimation.cpp index 71ef45c..440a37d 100644 --- a/src/corelib/animation/qabstractanimation.cpp +++ b/src/corelib/animation/qabstractanimation.cpp @@ -42,51 +42,58 @@ /*! \class QAbstractAnimation \ingroup animation - \brief The QAbstractAnimation class provides an abstract base class for animations. + \brief The QAbstractAnimation class is the base of all animations. \since 4.5 \preliminary - This class is part of \l{The Animation Framework}. It serves as a base class - for standard animations and groups, with functions for shared - functionality, and it also makes it easy for you to define custom + The class defines the functions for the functionality shared by + all animations. By inheriting this class, you can create custom animations that plug into the rest of the animation framework. - If you want to create an animation, you should look at the two subclasses, - QVariantAnimation and QAnimationGroup, instead. - - QAbstractAnimation provides an interface for the current time and - duration, the loop count, and the state of an animation. These properties - define the base functionality common to all animations in Qt. The virtual - duration() function returns the local duration of the animation; i.e., for - how long the animation should update the current time before - looping. Subclasses can implement this function differently; for example, - QVariantAnimation returns the duration of a simple animated property, whereas - QAnimationGroup returns the duration of a set or sequence of - animations. You can also set a loop count by calling setLoopCount(); a - loop count of 2 will let the animation run twice (the default value is - 1). - - Like QTimeLine, QAbstractAnimation also provides an interface for starting - and stopping an animation, and for tracking its progress. You can call the - start() slot to start the animation. When the animation starts, the - stateChanged() signal is emitted, and state() returns Running. If you call the - stop() slot, the stateChanged() signal is emitted, and state() returns - Stopped. If you call the pause() slot, the stateChanged() signal is emitted - and state() returns Paused. If the animation reaches the end, the finished() - signal is emitted. You can check the current state by calling state(). - - QAbstractAnimation provides two functions that are pure virtual, and must - be reimplemented in a subclass: duration(), and updateCurrentTime(). The - duration() function lets you report a duration for the animation (a return - value of -1 signals that the animation runs forever until explicitly - stopped). The current time is delivered by the framework through calls to - updateCurrentTime(). By reimplementing this function, you can track the - animation progress and update your target objects accordingly. By - reimplementing updateState(), you can track the animation's state - changes, which is particularily useful for animations that are not driven - by time. - - \sa QVariantAnimation, QAnimationGroup, {The Animation Framework} + The progress of an animation is given by its current time + (currentTime()), which is measured in milliseconds from the start + of the animation (0) to its end (duration()). The value is updated + automatically while the animation is running. It can also be set + directly with setCurrentTime(). + + At any point an animation is in one of three states: + \l{QAbstractAnimation::}{Running}, + \l{QAbstractAnimation::}{Stopped}, or + \l{QAbstractAnimation::}{Paused}--as defined by the + \l{QAbstractAnimation::}{State} enum. The current state can be + changed by calling start(), stop(), pause(), or resume(). An + animation will always reset its \l{currentTime()}{current time} + when it is started. If paused, it will continue with the same + current time when resumed. When an animation is stopped, it cannot + be resumed, but will keep its current time (until started again). + QAbstractAnimation will emit stateChanged() whenever its state + changes. + + An animation can loop any number of times by setting the loopCount + property. When an animation's current time reaches its duration(), + it will reset the current time and keep running. A loop count of 1 + (the default value) means that the animation will run one time. + Note that a duration of -1 means that the animation will run until + stopped; the current time will increase indefinitely. When the + current time equals duration() and the animation is in its + final loop, the \l{QAbstractAnimation::}{Stopped} state is + entered, and the finished() signal is emitted. + + QAbstractAnimation provides pure virtual functions used by + subclasses to track the progress of the animation: duration() and + updateCurrentTime(). The duration() function lets you report a + duration for the animation (as discussed above). The current time + is delivered by the animation framework through calls to + updateCurrentTime(). By reimplementing this function, you can + track the animation progress. Note that neither the interval + between calls nor the number of calls to this function are + defined; though, it will normally be 60 updates per second. + + By reimplementing updateState(), you can track the animation's + state changes, which is particularly useful for animations that + are not driven by time. + + \sa QVariantAnimation, QPropertyAnimation, QAnimationGroup, {The Animation Framework} */ /*! diff --git a/src/corelib/animation/qvariantanimation.cpp b/src/corelib/animation/qvariantanimation.cpp index 9f8cbf0..73ed0df 100644 --- a/src/corelib/animation/qvariantanimation.cpp +++ b/src/corelib/animation/qvariantanimation.cpp @@ -59,26 +59,68 @@ QT_BEGIN_NAMESPACE \since 4.5 \preliminary - This class is part of {The Animation Framework}. It serves as a base class - for property and item animations, with functions for shared functionality. - - If you want to create an animation, you should look at QPropertyAnimation instead. - + This class is part of \l{The Animation Framework}. It serves as a + base class for property and item animations, with functions for + shared functionality. + + QVariantAnimation cannot be used directly as it is an abstract + class; it does not implement + \l{QAbstractAnimation::}{updateCurrentValue()} from + QAbstractAnimation. The class performs interpolation over + \l{QVariant}s, but leaves using the interpolated values to its + subclasses. Currently, Qt provides QPropertyAnimation, which + animates Qt \l{Qt's Property System}{properties}. See the + QPropertyAnimation class description if you wish to animate such + properties. + You can then set start and end values for the property by calling setStartValue() and setEndValue(), and finally call start() to - start the animation. When control goes back to the event loop, QVariantAnimation - will interpolate the property of the target object and emit the valueChanged - signal. To react to a change in the current value you have to reimplement the - updateCurrentValue virtual method. - - There are two ways to affect how QVariantAnimation interpolates the values. - You can set an easing curve by calling setEasingCurve(), and configure the - duration by calling setDuration(). You can change how the QVariants are - interpolated by creating a subclass of QVariantAnimation, and reimplementing the - virtual interpolated() function. - - - \sa QPropertyAnimation, {The Animation Framework} + start the animation. QVariantAnimation will interpolate the + property of the target object and emit valueChanged(). To react to + a change in the current value you have to reimplement the + updateCurrentValue() virtual function. + + It is also possible to set values at specified steps situated + between the start and end value. The interpolation will then + touch these points at the specified steps. Note that the start and + end values are defined as the key values at 0.0 and 1.0. + + There are two ways to affect how QVariantAnimation interpolates + the values. You can set an easing curve by calling + setEasingCurve(), and configure the duration by calling + setDuration(). You can change how the QVariants are interpolated + by creating a subclass of QVariantAnimation, and reimplementing + the virtual interpolated() function. + + Subclassing QVariantAnimation can be an alternative if you have + \l{QVariant}s that you do not wish to declare as Qt properties. + Note, however, that you in most cases will be better off declaring + your QVariant as a property. + + Not all QVariant types are supported. Below is a list of currently + supported QVariant types: + + \list + \o \l{QMetaType::}{Int} + \o \l{QMetaType::}{Double} + \o \l{QMetaType::}{Float} + \o \l{QMetaType::}{QLine} + \o \l{QMetaType::}{QLineF} + \o \l{QMetaType::}{QPoint} + \o \l{QMetaType::}{QSize} + \o \l{QMetaType::}{QSizeF} + \o \l{QMetaType::}{QRect} + \o \l{QMetaType::}{QRectF} + \endlist + + If you need to interpolate other variant types, including custom + types, you have to implement interpolation for these yourself. + You do this by reimplementing interpolated(), which returns + interpolation values for the value being interpolated. + + \omit We need some snippets around here. \endomit + + \sa QPropertyAnimation, QAbstractAnimation, {The Animation Framework} */ /*! @@ -175,26 +217,16 @@ void QVariantAnimationPrivate::updateCurrentValue() endProgress = currentInterval.end.first; const qreal localProgress = (progress - startProgress) / (endProgress - startProgress); - bool changed = false; - { - //we do that here in a limited scope so that ret is dereferenced and frees memory - //and the call to updateCurrentValue can recreate QVariant of the same type (for ex. in - //QGraphicsItem::setPos - QVariant ret = q->interpolated(currentInterval.start.second, - currentInterval.end.second, - localProgress); - if (currentValue != ret) { - changed = true; - qSwap(currentValue, ret); - } - } - - if (changed) { - //the value has changed - q->updateCurrentValue(currentValue); + QVariant ret = q->interpolated(currentInterval.start.second, + currentInterval.end.second, + localProgress); + qSwap(currentValue, ret); + q->updateCurrentValue(currentValue); #ifndef QT_EXPERIMENTAL_SOLUTION if (connectedSignals & changedSignalMask) #endif + if (currentValue != ret) { + //the value has changed emit q->valueChanged(currentValue); } } @@ -271,16 +303,16 @@ QVariantAnimation::~QVariantAnimation() \property QVariantAnimation::easingCurve \brief the easing curve of the animation - This property defines the easing curve of the animation. By default, a - linear easing curve is used, resulting in linear interpolation of the - end property. For many animations, it's useful to try different easing - curves, including QEasingCurve::InCirc, which provides a circular entry curve, - and QEasingCurve::InOutElastic, which provides an elastic effect on the values - of the interpolated property. + This property defines the easing curve of the animation. By + default, a linear easing curve is used, resulting in linear + interpolation. Other curves are provided, for instance, + QEasingCurve::InCirc, which provides a circular entry curve. + Another example is QEasingCurve::InOutElastic, which provides an + elastic effect on the values of the interpolated variant. - The easing curve is used with the interpolator, the interpolated() virtual - function, the animation's duration, and loopCount, to control how the - current value changes as the animation progresses. + The easing curve is used with the interpolator, the interpolated() + virtual function, the animation's duration, and iterationCount, to + control how the current value changes as the animation progresses. */ QEasingCurve QVariantAnimation::easingCurve() const { @@ -382,8 +414,8 @@ QVariantAnimation::Interpolator QVariantAnimationPrivate::getInterpolator(int in \property QVariantAnimation::duration \brief the duration of the animation - This property describes the duration of the animation. The default - duration is 250 milliseconds. + This property describes the duration in milliseconds of the + animation. The default duration is 250 milliseconds. \sa QAbstractAnimation::duration() */ @@ -519,17 +551,22 @@ void QVariantAnimation::setKeyValues(const KeyValues &keyValues) /*! \property QVariantAnimation::currentValue - \brief the current value of the animation + \brief the current value of the animation. - This property describes the current value; an interpolation between the - start value and the end value, using the current time for progress. + This property describes the current value; an interpolated value + between the \l{startValue}{start value} and the \l{endValue}{end + value}, using the current time for progress. The value itself is + obtained from interpolated(), which is called repeatedly as the + animation is running. - QVariantAnimation calls the virtual updateCurrentValue() function when the - current value changes. This is particularily useful for subclasses that - need to track updates. + QVariantAnimation calls the virtual updateCurrentValue() function + when the current value changes. This is particularly useful for + subclasses that need to track updates. For example, + QPropertyAnimation uses this function to animate Qt \l{Qt's + Property System}{properties}. \sa startValue, endValue - */ +*/ QVariant QVariantAnimation::currentValue() const { Q_D(const QVariantAnimation); @@ -559,13 +596,22 @@ void QVariantAnimation::updateState(QAbstractAnimation::State oldState, } /*! - This virtual function returns the linear interpolation between variants \a - from and \a to, at \a progress, usually a value between 0 and 1. You can reimplement - this function in a subclass of QVariantAnimation to provide your own interpolation - algorithm. Note that in order for the interpolation to work with a QEasingCurve - that return a value smaller than 0 or larger than 1 (such as QEasingCurve::InBack) - you should make sure that it can extrapolate. If the semantic of the datatype - does not allow extrapolation this function should handle that gracefully. + + This virtual function returns the linear interpolation between + variants \a from and \a to, at \a progress, usually a value + between 0 and 1. You can reimplement this function in a subclass + of QVariantAnimation to provide your own interpolation algorithm. + + Note that in order for the interpolation to work with a + QEasingCurve that return a value smaller than 0 or larger than 1 + (such as QEasingCurve::InBack) you should make sure that it can + extrapolate. If the semantic of the datatype does not allow + extrapolation this function should handle that gracefully. + + You should call the QVariantAnimation implementation of this + function if you want your class to handle the types already + supported by Qt (see class QVariantAnimation description for a + list of supported types). \sa QEasingCurve */ |