1/*
2 * Copyright 2007 Aaron Seigo <aseigo@kde.org>
3 * 2007 Alexis Ménard <darktears31@gmail.com>
4 *
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU Library General Public License as
7 * published by the Free Software Foundation; either version 2, or
8 * (at your option) any later version.
9 *
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details
14 *
15 * You should have received a copy of the GNU Library General Public
16 * License along with this program; if not, write to the
17 * Free Software Foundation, Inc.,
18 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
19 */
20
21#ifndef PLASMA_ANIMATOR_H
22#define PLASMA_ANIMATOR_H
23
24#include <QtGui/QImage>
25#include <QtCore/QObject>
26#include <QtCore/QAbstractAnimation>
27#include <QtCore/QEasingCurve>
28
29#include <plasma/plasma_export.h>
30
31class QGraphicsItem;
32class QGraphicsWidget;
33class QTimeLine;
34
35namespace Plasma
36{
37
38class AnimatorPrivate;
39class Animation;
40
41/**
42 * @class Animator plasma/animator.h <Plasma/Animator>
43 *
44 * @short A system for applying effects to Plasma elements
45 */
46class PLASMA_EXPORT Animator : public QObject
47{
48 Q_OBJECT
49 Q_ENUMS(Animation)
50 Q_ENUMS(CurveShape)
51 Q_ENUMS(Movement)
52
53public:
54
55 enum Animation {
56 AppearAnimation = 0, /*<< Animate the appearance of an element */
57 DisappearAnimation, /*<< Animate the disappearance of an element */
58 ActivateAnimation, /*<< When something is activated or launched,
59 such as an app icon being clicked */
60 FadeAnimation, /*<< Can be used for both fade in and out */
61 GrowAnimation, /*<< Grow animated object geometry */
62 PulseAnimation, /*<< Pulse animated object (opacity/geometry/scale) */
63 RotationAnimation, /*<< Rotate an animated object */
64 RotationStackedAnimation, /*<< for flipping one object with another */
65 SlideAnimation, /*<< Move the position of animated object */
66 GeometryAnimation, /*<< Geometry animation*/
67 ZoomAnimation, /*<<Zoom animation */
68 PixmapTransitionAnimation, /*<< Transition between two pixmaps*/
69 WaterAnimation /*<< Water animation using ripple effect */,
70 LastAnimation = 1024
71 };
72
73 enum CurveShape {
74 EaseInCurve = 0,
75 EaseOutCurve,
76 EaseInOutCurve,
77 LinearCurve,
78 PendularCurve
79 };
80
81 enum Movement {
82 SlideInMovement = 0,
83 SlideOutMovement,
84 FastSlideInMovement,
85 FastSlideOutMovement
86 };
87
88 /**
89 * Singleton accessor
90 **/
91#ifndef KDE_NO_DEPRECATED
92 static KDE_DEPRECATED Animator *self();
93#endif
94
95 /**
96 * Factory to build new animation objects. To control their behavior,
97 * check \ref AbstractAnimation properties.
98 * @since 4.4
99 **/
100 static Plasma::Animation *create(Animator::Animation type, QObject *parent = 0);
101
102 /**
103 * Factory to build new animation objects from Javascript files. To control their behavior,
104 * check \ref AbstractAnimation properties.
105 * @since 4.5
106 **/
107 static Plasma::Animation *create(const QString &animationName, QObject *parent = 0);
108
109 /**
110 * Factory to build new custom easing curves.
111 * @since 4.5
112 */
113 static QEasingCurve create(Animator::CurveShape type);
114
115 /**
116 * Starts a standard animation on a QGraphicsItem.
117 *
118 * @param item the item to animate in some fashion
119 * @param anim the type of animation to perform
120 * @return the id of the animation
121 * @deprecated use new Animator API with Qt Kinetic
122 **/
123#ifndef KDE_NO_DEPRECATED
124 KDE_DEPRECATED Q_INVOKABLE int animateItem(QGraphicsItem *item,Animation anim);
125#endif
126
127 /**
128 * Stops an item animation before the animation is complete.
129 * Note that it is not necessary to call
130 * this on normal completion of the animation.
131 *
132 * @param id the id of the animation as returned by animateItem
133 * @deprecated use new Animator API with Qt Kinetic
134 */
135#ifndef KDE_NO_DEPRECATED
136 KDE_DEPRECATED Q_INVOKABLE void stopItemAnimation(int id);
137#endif
138
139 /**
140 * Starts a standard animation on a QGraphicsItem.
141 *
142 * @param item the item to animate in some fashion
143 * @param anim the type of animation to perform
144 * @return the id of the animation
145 * @deprecated use new Animator API with Qt Kinetic
146 **/
147#ifndef KDE_NO_DEPRECATED
148 KDE_DEPRECATED Q_INVOKABLE int moveItem(QGraphicsItem *item, Movement movement, const QPoint &destination);
149#endif
150
151 /**
152 * Stops an item movement before the animation is complete.
153 * Note that it is not necessary to call
154 * this on normal completion of the animation.
155 *
156 * @param id the id of the animation as returned by moveItem
157 * @deprecated use new Animator API with Qt Kinetic
158 */
159#ifndef KDE_NO_DEPRECATED
160 KDE_DEPRECATED Q_INVOKABLE void stopItemMovement(int id);
161#endif
162
163 /**
164 * Starts a custom animation, preventing the need to create a timeline
165 * with its own timer tick.
166 *
167 * @param frames the number of frames this animation should persist for
168 * @param duration the length, in milliseconds, the animation will take
169 * @param curve the curve applied to the frame rate
170 * @param receive the object that will handle the actual animation
171 * @param method the method name of slot to be invoked on each update.
172 * It must take a qreal. So if the slot is animate(qreal),
173 * pass in "animate" as the method parameter.
174 * It has an optional integer paramenter that takes an
175 * integer that reapresents the animation id, useful if
176 * you want to manage multiple animations with a sigle slot
177 *
178 * @return an id that can be used to identify this animation.
179 * @deprecated use new Animator API with Qt Kinetic
180 */
181#ifndef KDE_NO_DEPRECATED
182 KDE_DEPRECATED Q_INVOKABLE int customAnimation(int frames, int duration,
183 Animator::CurveShape curve, QObject *receiver, const char *method);
184#endif
185
186 /**
187 * Stops a custom animation. Note that it is not necessary to call
188 * this on object destruction, as custom animations associated with
189 * a given QObject are cleaned up automatically on QObject destruction.
190 *
191 * @param id the id of the animation as returned by customAnimation
192 * @deprecated use new Animator API with Qt Kinetic
193 */
194#ifndef KDE_NO_DEPRECATED
195 KDE_DEPRECATED Q_INVOKABLE void stopCustomAnimation(int id);
196#endif
197
198#ifndef KDE_NO_DEPRECATED
199 KDE_DEPRECATED Q_INVOKABLE int animateElement(QGraphicsItem *obj, Animation);
200#endif
201#ifndef KDE_NO_DEPRECATED
202 KDE_DEPRECATED Q_INVOKABLE void stopElementAnimation(int id);
203#endif
204#ifndef KDE_NO_DEPRECATED
205 KDE_DEPRECATED Q_INVOKABLE void setInitialPixmap(int id, const QPixmap &pixmap);
206#endif
207#ifndef KDE_NO_DEPRECATED
208 KDE_DEPRECATED Q_INVOKABLE QPixmap currentPixmap(int id);
209#endif
210
211 /**
212 * Can be used to query if there are other animations happening. This way
213 * heavy operations can be delayed until all animations are finished.
214 * @return true if there are animations going on.
215 * @since 4.1
216 * @deprecated use new Animator API with Qt Kinetic
217 */
218#ifndef KDE_NO_DEPRECATED
219 KDE_DEPRECATED Q_INVOKABLE bool isAnimating() const;
220#endif
221
222 /**
223 * Register a widget as a scrolling widget.
224 * This function is deprecated:
225 * use a ScrollWidget, with setWidget() as your widget instead.
226 *
227 * @param widget the widget that offers a scrolling behaviour
228 * @since 4.4
229 */
230#ifndef KDE_NO_DEPRECATED
231 KDE_DEPRECATED void registerScrollingManager(QGraphicsWidget *widget);
232#endif
233
234 /**
235 * unregister the scrolling manager of a certain widget
236 * This function is deprecated: use ScrollWidget instead.
237 *
238 * @param widget the widget we don't want no longer animated
239 * @since 4.4
240 */
241#ifndef KDE_NO_DEPRECATED
242 KDE_DEPRECATED void unregisterScrollingManager(QGraphicsWidget *widget);
243#endif
244
245Q_SIGNALS:
246 void animationFinished(QGraphicsItem *item, Plasma::Animator::Animation anim);
247 void movementFinished(QGraphicsItem *item);
248 void elementAnimationFinished(int id);
249 void customAnimationFinished(int id);
250#ifndef KDE_NO_DEPRECATED
251 KDE_DEPRECATED void scrollStateChanged(QGraphicsWidget *widget, QAbstractAnimation::State newState,
252 QAbstractAnimation::State oldState);
253#endif
254
255#ifndef KDE_NO_DEPRECATED
256protected:
257 void timerEvent(QTimerEvent *event);
258#endif
259
260private:
261#ifndef KDE_NO_DEPRECATED
262 friend class AnimatorSingleton;
263 explicit Animator(QObject * parent = 0);
264 ~Animator();
265
266 Q_PRIVATE_SLOT(d, void animatedItemDestroyed(QObject*))
267 Q_PRIVATE_SLOT(d, void movingItemDestroyed(QObject*))
268 Q_PRIVATE_SLOT(d, void animatedElementDestroyed(QObject*))
269 Q_PRIVATE_SLOT(d, void customAnimReceiverDestroyed(QObject*))
270 Q_PRIVATE_SLOT(d, void scrollStateChanged(QAbstractAnimation::State,
271 QAbstractAnimation::State))
272#else
273 Animator();
274#endif
275
276 friend class AnimatorPrivate;
277 AnimatorPrivate * const d;
278};
279
280} // namespace Plasma
281
282#endif
283
284