1 | // Copyright (C) 2016 The Qt Company Ltd. |
2 | // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only |
3 | |
4 | /*! |
5 | \class QPropertyAnimation |
6 | \inmodule QtCore |
7 | \brief The QPropertyAnimation class animates Qt properties. |
8 | \since 4.6 |
9 | |
10 | \ingroup animation |
11 | |
12 | QPropertyAnimation interpolates over \l{Qt's Property System}{Qt |
13 | properties}. As property values are stored in \l{QVariant}s, the |
14 | class inherits QVariantAnimation, and supports animation of the |
15 | same \l{QMetaType::Type}{meta types} as its super class. |
16 | |
17 | A class declaring properties must be a QObject. To make it |
18 | possible to animate a property, it must provide a setter (so that |
19 | QPropertyAnimation can set the property's value). Note that this |
20 | makes it possible to animate many of Qt's widgets. Let's look at |
21 | an example: |
22 | |
23 | \snippet code/src_corelib_animation_qpropertyanimation.cpp 0 |
24 | |
25 | \note You can also control an animation's lifespan by choosing a |
26 | \l{QAbstractAnimation::DeletionPolicy}{delete policy} while starting the |
27 | animation. |
28 | |
29 | The property name and the QObject instance of which property |
30 | should be animated are passed to the constructor. You can then |
31 | specify the start and end value of the property. The procedure is |
32 | equal for properties in classes you have implemented |
33 | yourself--just check with QVariantAnimation that your QVariant |
34 | type is supported. |
35 | |
36 | The QVariantAnimation class description explains how to set up the |
37 | animation in detail. Note, however, that if a start value is not |
38 | set, the property will start at the value it had when the |
39 | QPropertyAnimation instance was created. |
40 | |
41 | QPropertyAnimation works like a charm on its own. For complex |
42 | animations that, for instance, contain several objects, |
43 | QAnimationGroup is provided. An animation group is an animation |
44 | that can contain other animations, and that can manage when its |
45 | animations are played. Look at QParallelAnimationGroup for an |
46 | example. |
47 | |
48 | \sa QVariantAnimation, QAnimationGroup, {The Animation Framework} |
49 | */ |
50 | |
51 | #include "qpropertyanimation.h" |
52 | #include "qanimationgroup.h" |
53 | #include "qpropertyanimation_p.h" |
54 | |
55 | #include <QtCore/QMutex> |
56 | #include <QtCore/QHash> |
57 | #include <QtCore/private/qlocking_p.h> |
58 | |
59 | QT_BEGIN_NAMESPACE |
60 | |
61 | QPropertyAnimationPrivate::~QPropertyAnimationPrivate() |
62 | = default; |
63 | |
64 | void QPropertyAnimationPrivate::updateMetaProperty() |
65 | { |
66 | const QObject *target = targetObject.valueBypassingBindings(); |
67 | if (!target || propertyName.value().isEmpty()) { |
68 | propertyType = QMetaType::UnknownType; |
69 | propertyIndex = -1; |
70 | return; |
71 | } |
72 | |
73 | //propertyType will be set to a valid type only if there is a Q_PROPERTY |
74 | //otherwise it will be set to QVariant::Invalid at the end of this function |
75 | propertyType = target->property(name: propertyName.value()).userType(); |
76 | propertyIndex = target->metaObject()->indexOfProperty(name: propertyName.value()); |
77 | |
78 | if (propertyType != QMetaType::UnknownType) |
79 | convertValues(t: propertyType); |
80 | if (propertyIndex == -1) { |
81 | //there is no Q_PROPERTY on the object |
82 | propertyType = QMetaType::UnknownType; |
83 | if (!target->dynamicPropertyNames().contains(t: propertyName)) |
84 | qWarning(msg: "QPropertyAnimation: you're trying to animate a non-existing property %s of " |
85 | "your QObject" , |
86 | propertyName.value().constData()); |
87 | } else if (!target->metaObject()->property(index: propertyIndex).isWritable()) { |
88 | qWarning(msg: "QPropertyAnimation: you're trying to animate the non-writable property %s of " |
89 | "your QObject" , |
90 | propertyName.value().constData()); |
91 | } |
92 | } |
93 | |
94 | void QPropertyAnimationPrivate::updateProperty(const QVariant &newValue) |
95 | { |
96 | if (state == QAbstractAnimation::Stopped) |
97 | return; |
98 | |
99 | if (!targetObject) |
100 | return; |
101 | |
102 | if (newValue.userType() == propertyType) { |
103 | //no conversion is needed, we directly call the QMetaObject::metacall |
104 | //check QMetaProperty::write for an explanation of these |
105 | int status = -1; |
106 | int flags = 0; |
107 | void *argv[] = { const_cast<void *>(newValue.constData()), const_cast<QVariant *>(&newValue), &status, &flags }; |
108 | QMetaObject::metacall(targetObject, QMetaObject::WriteProperty, propertyIndex, argv); |
109 | } else { |
110 | targetObject->setProperty(name: propertyName.value().constData(), value: newValue); |
111 | } |
112 | } |
113 | |
114 | /*! |
115 | Construct a QPropertyAnimation object. \a parent is passed to QObject's |
116 | constructor. |
117 | */ |
118 | QPropertyAnimation::QPropertyAnimation(QObject *parent) |
119 | : QVariantAnimation(*new QPropertyAnimationPrivate, parent) |
120 | { |
121 | } |
122 | |
123 | /*! |
124 | Construct a QPropertyAnimation object. \a parent is passed to QObject's |
125 | constructor. The animation changes the property \a propertyName on \a |
126 | target. The default duration is 250ms. |
127 | |
128 | \sa targetObject, propertyName |
129 | */ |
130 | QPropertyAnimation::QPropertyAnimation(QObject *target, const QByteArray &propertyName, QObject *parent) |
131 | : QVariantAnimation(*new QPropertyAnimationPrivate, parent) |
132 | { |
133 | setTargetObject(target); |
134 | setPropertyName(propertyName); |
135 | } |
136 | |
137 | /*! |
138 | Destroys the QPropertyAnimation instance. |
139 | */ |
140 | QPropertyAnimation::~QPropertyAnimation() |
141 | { |
142 | stop(); |
143 | } |
144 | |
145 | /*! |
146 | \property QPropertyAnimation::targetObject |
147 | \brief the target QObject for this animation. |
148 | |
149 | This property defines the target QObject for this animation. |
150 | */ |
151 | QObject *QPropertyAnimation::targetObject() const |
152 | { |
153 | return d_func()->targetObject; |
154 | } |
155 | |
156 | QBindable<QObject *> QPropertyAnimation::bindableTargetObject() |
157 | { |
158 | return &d_func()->targetObject; |
159 | } |
160 | |
161 | void QPropertyAnimation::setTargetObject(QObject *target) |
162 | { |
163 | Q_D(QPropertyAnimation); |
164 | if (d->state != QAbstractAnimation::Stopped) { |
165 | qWarning(msg: "QPropertyAnimation::setTargetObject: you can't change the target of a running animation" ); |
166 | return; |
167 | } |
168 | |
169 | d->targetObject.removeBindingUnlessInWrapper(); |
170 | const QObject *oldTarget = d->targetObject.valueBypassingBindings(); |
171 | if (oldTarget == target) |
172 | return; |
173 | |
174 | if (oldTarget != nullptr) |
175 | QObject::disconnect(sender: oldTarget, signal: &QObject::destroyed, receiver: this, zero: nullptr); |
176 | d->targetObject.setValueBypassingBindings(target); |
177 | |
178 | if (target != nullptr) { |
179 | QObject::connect(sender: target, signal: &QObject::destroyed, context: this, |
180 | slot: [d] { d->targetObjectDestroyed(); }); |
181 | } |
182 | d->updateMetaProperty(); |
183 | d->targetObject.notify(); |
184 | } |
185 | |
186 | /*! |
187 | \property QPropertyAnimation::propertyName |
188 | \brief the target property name for this animation |
189 | |
190 | This property defines the target property name for this animation. The |
191 | property name is required for the animation to operate. |
192 | */ |
193 | QByteArray QPropertyAnimation::propertyName() const |
194 | { |
195 | Q_D(const QPropertyAnimation); |
196 | return d->propertyName; |
197 | } |
198 | |
199 | void QPropertyAnimation::setPropertyName(const QByteArray &propertyName) |
200 | { |
201 | Q_D(QPropertyAnimation); |
202 | if (d->state != QAbstractAnimation::Stopped) { |
203 | qWarning(msg: "QPropertyAnimation::setPropertyName: you can't change the property name of a running animation" ); |
204 | return; |
205 | } |
206 | |
207 | d->propertyName.removeBindingUnlessInWrapper(); |
208 | |
209 | if (d->propertyName.valueBypassingBindings() == propertyName) |
210 | return; |
211 | |
212 | d->propertyName.setValueBypassingBindings(propertyName); |
213 | d->updateMetaProperty(); |
214 | d->propertyName.notify(); |
215 | } |
216 | |
217 | QBindable<QByteArray> QPropertyAnimation::bindablePropertyName() |
218 | { |
219 | return &d_func()->propertyName; |
220 | } |
221 | |
222 | /*! |
223 | \reimp |
224 | */ |
225 | bool QPropertyAnimation::event(QEvent *event) |
226 | { |
227 | return QVariantAnimation::event(event); |
228 | } |
229 | |
230 | /*! |
231 | This virtual function is called by QVariantAnimation whenever the current value |
232 | changes. \a value is the new, updated value. It updates the current value |
233 | of the property on the target object. |
234 | |
235 | \sa currentValue, currentTime |
236 | */ |
237 | void QPropertyAnimation::updateCurrentValue(const QVariant &value) |
238 | { |
239 | Q_D(QPropertyAnimation); |
240 | d->updateProperty(newValue: value); |
241 | } |
242 | |
243 | /*! |
244 | \reimp |
245 | |
246 | If the startValue is not defined when the state of the animation changes from Stopped to Running, |
247 | the current property value is used as the initial value for the animation. |
248 | */ |
249 | void QPropertyAnimation::updateState(QAbstractAnimation::State newState, |
250 | QAbstractAnimation::State oldState) |
251 | { |
252 | Q_D(QPropertyAnimation); |
253 | |
254 | if (!d->targetObject && oldState == Stopped) { |
255 | qWarning(msg: "QPropertyAnimation::updateState (%s): Changing state of an animation without " |
256 | "target" , |
257 | d->propertyName.value().constData()); |
258 | return; |
259 | } |
260 | |
261 | QVariantAnimation::updateState(newState, oldState); |
262 | |
263 | QPropertyAnimation *animToStop = nullptr; |
264 | { |
265 | Q_CONSTINIT static QBasicMutex mutex; |
266 | auto locker = qt_unique_lock(mutex); |
267 | using QPropertyAnimationPair = std::pair<QObject *, QByteArray>; |
268 | typedef QHash<QPropertyAnimationPair, QPropertyAnimation*> QPropertyAnimationHash; |
269 | Q_CONSTINIT static QPropertyAnimationHash hash; |
270 | |
271 | // in case the targetObject gets deleted, the following happens: |
272 | // 1. targetObject's destroyed signal calls our targetObjectDestroyed. |
273 | // 2. targetObjectDestroyed calls stop() |
274 | // 3. QAbstractAnimation::stop() calls setState(Stopped) |
275 | // 4. setState(Stopped) calls updateState(newState, oldState) |
276 | // 5. we arrive here. d->targetObject is not yet set to nullptr, we can safely use it. |
277 | Q_ASSERT(d->targetObject); |
278 | |
279 | QPropertyAnimationPair key(d->targetObject, d->propertyName); |
280 | if (newState == Running) { |
281 | d->updateMetaProperty(); |
282 | animToStop = hash.value(key, defaultValue: nullptr); |
283 | hash.insert(key, value: this); |
284 | locker.unlock(); |
285 | // update the default start value |
286 | if (oldState == Stopped) { |
287 | d->setDefaultStartEndValue( |
288 | d->targetObject->property(name: d->propertyName.value().constData())); |
289 | //let's check if we have a start value and an end value |
290 | const char *what = nullptr; |
291 | if (!startValue().isValid() && (d->direction == Backward || !d->defaultStartEndValue.isValid())) { |
292 | what = "start" ; |
293 | } |
294 | if (!endValue().isValid() && (d->direction == Forward || !d->defaultStartEndValue.isValid())) { |
295 | if (what) |
296 | what = "start and end" ; |
297 | else |
298 | what = "end" ; |
299 | } |
300 | if (Q_UNLIKELY(what)) { |
301 | qWarning(msg: "QPropertyAnimation::updateState (%s, %s, %ls): starting an animation " |
302 | "without %s value" , |
303 | d->propertyName.value().constData(), |
304 | d->targetObject->metaObject()->className(), |
305 | qUtf16Printable(d->targetObject->objectName()), what); |
306 | } |
307 | } |
308 | } else if (hash.value(key) == this) { |
309 | hash.remove(key); |
310 | } |
311 | } |
312 | |
313 | //we need to do that after the mutex was unlocked |
314 | if (animToStop) { |
315 | // try to stop the top level group |
316 | QAbstractAnimation *current = animToStop; |
317 | while (current->group() && current->state() != Stopped) |
318 | current = current->group(); |
319 | current->stop(); |
320 | } |
321 | } |
322 | |
323 | QT_END_NAMESPACE |
324 | |
325 | #include "moc_qpropertyanimation.cpp" |
326 | |