Debian Codegraph @

clutter/deprecated/clutter-behaviour.c

raw
1 /*
2 * Clutter.
3 *
4 * An OpenGL based 'interactive canvas' library.
5 *
6 * Authored By Matthew Allum <[email protected]>
7 *
8 * Copyright (C) 2006 OpenedHand
9 *
10 * This library is free software; you can redistribute it and/or
11 * modify it under the terms of the GNU Lesser General Public
12 * License as published by the Free Software Foundation; either
13 * version 2 of the License, or (at your option) any later version.
14 *
15 * This library is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 * Lesser General Public License for more details.
19 *
20 * You should have received a copy of the GNU Lesser General Public
21 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
22 */
23
24 /**
25 * SECTION:clutter-behaviour
26 * @Title: ClutterBehaviour
27 * @short_description: Class for providing behaviours to actors
28 * @Deprecated: 1.6: Use clutter_actor_animate(), #ClutterAnimator or
29 * #ClutterState instead
30 *
31 * #ClutterBehaviour is the base class for implementing behaviours. A
32 * behaviour is a controller object for #ClutterActor<!-- -->s; you can
33 * use a behaviour to control one or more properties of an actor (such
34 * as its opacity, or its position). A #ClutterBehaviour is driven by
35 * an "alpha function" stored inside a #ClutterAlpha object; an alpha
36 * function is a function depending solely on time. The alpha function
37 * computes a value which is then applied to the properties of the
38 * actors driven by a behaviour.
39 *
40 * Clutter provides some pre-defined behaviours, like #ClutterBehaviourPath,
41 * which controls the position of a set of actors making them "walk" along
42 * a set of nodes; #ClutterBehaviourOpacity, which controls the opacity
43 * of a set of actors; #ClutterBehaviourScale, which controls the width
44 * and height of a set of actors.
45 *
46 * To visualize the effects of different alpha functions on a
47 * #ClutterBehaviour implementation it is possible to take the
48 * #ClutterBehaviourPath as an example:
49 *
50 * ![](path-alpha-func.png)
51 *
52 * The actors position between the path's end points directly correlates
53 * to the #ClutterAlpha's current alpha value driving the behaviour. With
54 * the #ClutterAlpha's function set to a linear ramp the actor
55 * will follow the path at a constant velocity, but when changing to
56 * a sine wave the actor initially accelerates before quickly
57 * decelerating.
58 *
59 * In order to implement a new behaviour you should subclass #ClutterBehaviour
60 * and override the "alpha_notify" virtual function; inside the overridden
61 * function you should obtain the alpha value from the #ClutterAlpha
62 * instance bound to the behaviour and apply it to the desiderd property
63 * (or properties) of every actor controlled by the behaviour.
64 *
65 * #ClutterBehaviour is available since Clutter 0.2.
66 *
67 * #ClutterBehaviour and its sub-classes have been discouraged sing Clutter
68 * 1.0, and formally deprecated since Clutter 1.6. You should use the
69 * [implicit animation][clutter-actor-animation] support inside #ClutterActor
70 * if you still have code using #ClutterBehaviour.
71 */
72
73 #ifdef HAVE_CONFIG_H
74 #include "config.h"
75 #endif
76
77 #define CLUTTER_DISABLE_DEPRECATION_WARNINGS
78 #include "clutter-behaviour.h"
79 #include "clutter-alpha.h"
80
81 #include "clutter-debug.h"
82 #include "clutter-main.h"
83 #include "clutter-marshal.h"
84 #include "clutter-private.h"
85 #include "clutter-scriptable.h"
86 #include "clutter-script-private.h"
87
88 struct _ClutterBehaviourPrivate
89 {
90 ClutterAlpha *alpha;
91
92 guint notify_id;
93 GSList *actors;
94 };
95
96 enum
97 {
98 PROP_0,
99 PROP_ALPHA,
100
101 PROP_LAST
102 };
103
104 static GParamSpec *obj_props[PROP_LAST];
105
106 enum {
107 APPLIED,
108 REMOVED,
109 LAST_SIGNAL
110 };
111
112 static guint behave_signals[LAST_SIGNAL] = { 0 };
113
114 static void clutter_scriptable_iface_init (ClutterScriptableIface *iface);
115
116 G_DEFINE_ABSTRACT_TYPE_WITH_CODE (ClutterBehaviour,
117 clutter_behaviour,
118 G_TYPE_OBJECT,
119 G_ADD_PRIVATE (ClutterBehaviour)
120 G_IMPLEMENT_INTERFACE (CLUTTER_TYPE_SCRIPTABLE,
121 clutter_scriptable_iface_init))
122
123 static gboolean
124 clutter_behaviour_parse_custom_node (ClutterScriptable *scriptable,
125 ClutterScript *script,
126 GValue *value,
127 const gchar *name,
128 JsonNode *node)
129 {
130 if (strncmp (name, "alpha", 5) == 0)
131 {
132 GObject *alpha;
133
134 alpha = _clutter_script_parse_alpha (script, node);
135 if (alpha != NULL)
136 {
137 g_value_init (value, CLUTTER_TYPE_ALPHA);
138 g_value_set_object (value, alpha);
139
140 return TRUE;
141 }
142 }
143
144 return FALSE;
145 }
146
147 static void
148 clutter_scriptable_iface_init (ClutterScriptableIface *iface)
149 {
150 iface->parse_custom_node = clutter_behaviour_parse_custom_node;
151 }
152
153 static void
154 clutter_behaviour_dispose (GObject *gobject)
155 {
156 ClutterBehaviour *self = CLUTTER_BEHAVIOUR (gobject);
157
158 clutter_behaviour_set_alpha (self, NULL);
159 clutter_behaviour_remove_all (self);
160
161 G_OBJECT_CLASS (clutter_behaviour_parent_class)->dispose (gobject);
162 }
163
164 static void
165 clutter_behaviour_set_property (GObject *object,
166 guint prop_id,
167 const GValue *value,
168 GParamSpec *pspec)
169 {
170 ClutterBehaviour *behaviour = CLUTTER_BEHAVIOUR (object);
171
172 switch (prop_id)
173 {
174 case PROP_ALPHA:
175 clutter_behaviour_set_alpha (behaviour, g_value_get_object (value));
176 break;
177 default:
178 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
179 break;
180 }
181 }
182
183 static void
184 clutter_behaviour_get_property (GObject *object,
185 guint prop_id,
186 GValue *value,
187 GParamSpec *pspec)
188 {
189 ClutterBehaviour *behaviour = CLUTTER_BEHAVIOUR (object);
190 ClutterBehaviourPrivate *priv = behaviour->priv;
191
192 switch (prop_id)
193 {
194 case PROP_ALPHA:
195 g_value_set_object (value, priv->alpha);
196 break;
197 default:
198 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
199 break;
200 }
201 }
202
203 static void
204 clutter_behaviour_alpha_notify_unimplemented (ClutterBehaviour *behaviour,
205 gdouble alpha_value)
206 {
207 g_warning ("ClutterBehaviourClass::alpha_notify not implemented for '%s'",
208 g_type_name (G_TYPE_FROM_INSTANCE (behaviour)));
209 }
210
211 static void
212 clutter_behaviour_class_init (ClutterBehaviourClass *klass)
213 {
214 GObjectClass *object_class = G_OBJECT_CLASS (klass);
215
216 object_class->dispose = clutter_behaviour_dispose;
217 object_class->set_property = clutter_behaviour_set_property;
218 object_class->get_property = clutter_behaviour_get_property;
219
220 /**
221 * ClutterBehaviour:alpha:
222 *
223 * The #ClutterAlpha object used to drive this behaviour. A #ClutterAlpha
224 * object binds a #ClutterTimeline and a function which computes a value
225 * (the "alpha") depending on the time. Each time the alpha value changes
226 * the alpha-notify virtual function is called.
227 *
228 * Since: 0.2
229 *
230 * Deprecated: 1.6
231 */
232 obj_props[PROP_ALPHA] =
233 g_param_spec_object ("alpha",
234 P_("Alpha"),
235 P_("Alpha Object to drive the behaviour"),
236 CLUTTER_TYPE_ALPHA,
237 CLUTTER_PARAM_READWRITE);
238
239 g_object_class_install_properties (object_class,
240 PROP_LAST,
241 obj_props);
242
243 klass->alpha_notify = clutter_behaviour_alpha_notify_unimplemented;
244
245 /**
246 * ClutterBehaviour::applied:
247 * @behaviour: the #ClutterBehaviour that received the signal
248 * @actor: the actor the behaviour was applied to.
249 *
250 * The ::apply signal is emitted each time the behaviour is applied
251 * to an actor.
252 *
253 * Since: 0.4
254 *
255 * Deprecated: 1.6
256 */
257 behave_signals[APPLIED] =
258 g_signal_new ("applied",
259 G_OBJECT_CLASS_TYPE (object_class),
260 G_SIGNAL_RUN_FIRST,
261 G_STRUCT_OFFSET (ClutterBehaviourClass, applied),
262 NULL, NULL,
263 _clutter_marshal_VOID__OBJECT,
264 G_TYPE_NONE, 1,
265 CLUTTER_TYPE_ACTOR);
266 /**
267 * ClutterBehaviour::removed:
268 * @behaviour: the #ClutterBehaviour that received the signal
269 * @actor: the removed actor
270 *
271 * The ::removed signal is emitted each time a behaviour is not applied
272 * to an actor anymore.
273 *
274 * Since: 0.4
275 *
276 * Deprecated: 1.6
277 */
278 behave_signals[REMOVED] =
279 g_signal_new ("removed",
280 G_OBJECT_CLASS_TYPE (object_class),
281 G_SIGNAL_RUN_FIRST,
282 G_STRUCT_OFFSET (ClutterBehaviourClass, removed),
283 NULL, NULL,
284 _clutter_marshal_VOID__OBJECT,
285 G_TYPE_NONE, 1,
286 CLUTTER_TYPE_ACTOR);
287 }
288
289 static void
290 clutter_behaviour_init (ClutterBehaviour *self)
291 {
292 self->priv = clutter_behaviour_get_instance_private (self);
293 }
294
295 static void
296 remove_actor_on_destroy (ClutterActor *actor,
297 ClutterBehaviour *behaviour)
298 {
299 clutter_behaviour_remove (behaviour, actor);
300 }
301
302 /**
303 * clutter_behaviour_apply:
304 * @behave: a #ClutterBehaviour
305 * @actor: a #ClutterActor
306 *
307 * Applies @behave to @actor. This function adds a reference on
308 * the actor.
309 *
310 * Since: 0.2
311 *
312 * Deprecated: 1.6
313 */
314 void
315 clutter_behaviour_apply (ClutterBehaviour *behave,
316 ClutterActor *actor)
317 {
318 ClutterBehaviourPrivate *priv;
319
320 g_return_if_fail (CLUTTER_IS_BEHAVIOUR (behave));
321 g_return_if_fail (CLUTTER_IS_ACTOR (actor));
322
323 priv = behave->priv;
324
325 if (g_slist_find (priv->actors, actor))
326 {
327 g_warning ("The behaviour of type %s already applies "
328 "to the actor of type %s",
329 g_type_name (G_OBJECT_TYPE (behave)),
330 g_type_name (G_OBJECT_TYPE (actor)));
331 return;
332 }
333
334 priv->actors = g_slist_append (priv->actors, g_object_ref (actor));
335 g_signal_connect (actor, "destroy",
336 G_CALLBACK (remove_actor_on_destroy),
337 behave);
338
339 g_signal_emit (behave, behave_signals[APPLIED], 0, actor);
340 }
341
342 /**
343 * clutter_behaviour_is_applied:
344 * @behave: a #ClutterBehaviour
345 * @actor: a #ClutterActor
346 *
347 * Check if @behave applied to @actor.
348 *
349 * Return value: TRUE if actor has behaviour. FALSE otherwise.
350 *
351 * Since: 0.4
352 *
353 * Deprecated: 1.6
354 */
355 gboolean
356 clutter_behaviour_is_applied (ClutterBehaviour *behave,
357 ClutterActor *actor)
358 {
359 g_return_val_if_fail (CLUTTER_IS_BEHAVIOUR (behave), FALSE);
360 g_return_val_if_fail (CLUTTER_IS_ACTOR (actor), FALSE);
361
362 return (g_slist_find (behave->priv->actors, actor) != NULL);
363 }
364
365 /**
366 * clutter_behaviour_remove:
367 * @behave: a #ClutterBehaviour
368 * @actor: a #ClutterActor
369 *
370 * Removes @actor from the list of #ClutterActor<!-- -->s to which
371 * @behave applies. This function removes a reference on the actor.
372 *
373 * Since: 0.2
374 *
375 * Deprecated: 1.6
376 */
377 void
378 clutter_behaviour_remove (ClutterBehaviour *behave,
379 ClutterActor *actor)
380 {
381 ClutterBehaviourPrivate *priv;
382
383 g_return_if_fail (CLUTTER_IS_BEHAVIOUR (behave));
384 g_return_if_fail (CLUTTER_IS_ACTOR (actor));
385
386 priv = behave->priv;
387
388 if (!g_slist_find (priv->actors, actor))
389 {
390 g_warning ("The behaviour of type %s is not applied "
391 "to the actor of type %s",
392 g_type_name (G_OBJECT_TYPE (behave)),
393 g_type_name (G_OBJECT_TYPE (actor)));
394 return;
395 }
396
397 g_signal_handlers_disconnect_by_func (actor,
398 G_CALLBACK (remove_actor_on_destroy),
399 behave);
400
401 priv->actors = g_slist_remove (priv->actors, actor);
402
403 g_signal_emit (behave, behave_signals[REMOVED], 0, actor);
404
405 g_object_unref (actor);
406 }
407
408 /**
409 * clutter_behaviour_get_n_actors:
410 * @behave: a #ClutterBehaviour
411 *
412 * Gets the number of actors this behaviour is applied too.
413 *
414 * Return value: The number of applied actors
415 *
416 * Since: 0.2
417 *
418 * Deprecated: 1.6
419 */
420 gint
421 clutter_behaviour_get_n_actors (ClutterBehaviour *behave)
422 {
423 g_return_val_if_fail (CLUTTER_IS_BEHAVIOUR (behave), 0);
424
425 return g_slist_length (behave->priv->actors);
426 }
427
428 /**
429 * clutter_behaviour_get_nth_actor:
430 * @behave: a #ClutterBehaviour
431 * @index_: the index of an actor this behaviour is applied too.
432 *
433 * Gets an actor the behaviour was applied to referenced by index num.
434 *
435 * Return value: (transfer none): A Clutter actor or NULL if @index_ is invalid.
436 *
437 * Since: 0.2
438 *
439 * Deprecated: 1.6
440 */
441 ClutterActor *
442 clutter_behaviour_get_nth_actor (ClutterBehaviour *behave,
443 gint index_)
444 {
445 g_return_val_if_fail (CLUTTER_IS_BEHAVIOUR (behave), NULL);
446
447 return g_slist_nth_data (behave->priv->actors, index_);
448 }
449
450
451 /**
452 * clutter_behaviour_actors_foreach:
453 * @behave: a #ClutterBehaviour
454 * @func: (scope call): a function called for each actor
455 * @data: optional data to be passed to the function, or %NULL
456 *
457 * Calls @func for every actor driven by @behave.
458 *
459 * Since: 0.2
460 *
461 * Deprecated: 1.6
462 */
463 void
464 clutter_behaviour_actors_foreach (ClutterBehaviour *behave,
465 ClutterBehaviourForeachFunc func,
466 gpointer data)
467 {
468 GSList *l;
469
470 g_return_if_fail (CLUTTER_IS_BEHAVIOUR (behave));
471 g_return_if_fail (func != NULL);
472
473 for (l = behave->priv->actors; l != NULL; l = l->next)
474 {
475 ClutterActor *actor = l->data;
476
477 g_assert (CLUTTER_IS_ACTOR (actor));
478
479 func (behave, actor, data);
480 }
481 }
482
483 /**
484 * clutter_behaviour_get_alpha:
485 * @behave: a #ClutterBehaviour
486 *
487 * Retrieves the #ClutterAlpha object bound to @behave.
488 *
489 * Return value: (transfer none): a #ClutterAlpha object, or %NULL if no alpha
490 * object has been bound to this behaviour.
491 *
492 * Since: 0.2
493 *
494 * Deprecated: 1.6
495 */
496 ClutterAlpha *
497 clutter_behaviour_get_alpha (ClutterBehaviour *behave)
498 {
499 g_return_val_if_fail (CLUTTER_IS_BEHAVIOUR (behave), NULL);
500
501 return behave->priv->alpha;
502 }
503
504 static void
505 notify_cb (GObject *object,
506 GParamSpec *param_spec,
507 ClutterBehaviour *behave)
508 {
509 ClutterBehaviourClass *klass;
510
511 klass = CLUTTER_BEHAVIOUR_GET_CLASS (behave);
512
513 CLUTTER_NOTE (ANIMATION, "notify::alpha");
514
515 /* no actors, we can stop right here */
516 if (behave->priv->actors == NULL)
517 return;
518
519 if (klass->alpha_notify != NULL)
520 {
521 gdouble alpha_value = clutter_alpha_get_alpha (behave->priv->alpha);
522
523 CLUTTER_NOTE (ANIMATION, "calling %s::alpha_notify (%p, %.4f)",
524 g_type_name (G_TYPE_FROM_CLASS (klass)),
525 behave, alpha_value);
526
527 klass->alpha_notify (behave, alpha_value);
528 }
529 }
530
531 /**
532 * clutter_behaviour_set_alpha:
533 * @behave: a #ClutterBehaviour
534 * @alpha: a #ClutterAlpha or %NULL to unset a previously set alpha
535 *
536 * Binds @alpha to a #ClutterBehaviour. The #ClutterAlpha object
537 * is what makes a behaviour work: for each tick of the timeline
538 * used by #ClutterAlpha a new value of the alpha parameter is
539 * computed by the alpha function; the value should be used by
540 * the #ClutterBehaviour to update one or more properties of the
541 * actors to which the behaviour applies.
542 *
543 * If @alpha is not %NULL, the #ClutterBehaviour will take ownership
544 * of the #ClutterAlpha instance.
545 *
546 * Since: 0.2
547 *
548 * Deprecated: 1.6
549 */
550 void
551 clutter_behaviour_set_alpha (ClutterBehaviour *behave,
552 ClutterAlpha *alpha)
553 {
554 ClutterBehaviourPrivate *priv;
555
556 g_return_if_fail (CLUTTER_IS_BEHAVIOUR (behave));
557 g_return_if_fail (alpha == NULL || CLUTTER_IS_ALPHA (alpha));
558
559 priv = behave->priv;
560
561 if (priv->alpha == alpha)
562 return;
563
564 if (priv->notify_id)
565 {
566 CLUTTER_NOTE (ANIMATION, "removing previous notify-id (%d)",
567 priv->notify_id);
568
569 g_signal_handler_disconnect (priv->alpha, priv->notify_id);
570 priv->notify_id = 0;
571 }
572
573 if (priv->alpha != NULL)
574 {
575 CLUTTER_NOTE (ANIMATION, "removing previous alpha object");
576
577 g_object_unref (priv->alpha);
578 priv->alpha = NULL;
579 }
580
581 if (alpha != NULL)
582 {
583 priv->alpha = g_object_ref_sink (alpha);
584
585 priv->notify_id = g_signal_connect (priv->alpha, "notify::alpha",
586 G_CALLBACK(notify_cb),
587 behave);
588
589 CLUTTER_NOTE (ANIMATION, "setting new alpha object (%p, notify:%d)",
590 priv->alpha, priv->notify_id);
591 }
592
593 g_object_notify_by_pspec (G_OBJECT (behave), obj_props[PROP_ALPHA]);
594 }
595
596 /**
597 * clutter_behaviour_get_actors:
598 * @behave: a #ClutterBehaviour
599 *
600 * Retrieves all the actors to which @behave applies. It is not recommended
601 * for derived classes to use this in there alpha notify method but use
602 * #clutter_behaviour_actors_foreach as it avoids alot of needless allocations.
603 *
604 * Return value: (transfer container) (element-type Clutter.Actor): a list of
605 * actors. You should free the returned list with g_slist_free() when
606 * finished using it.
607 *
608 * Since: 0.2
609 *
610 * Deprecated: 1.6
611 */
612 GSList *
613 clutter_behaviour_get_actors (ClutterBehaviour *behave)
614 {
615 ClutterBehaviourPrivate *priv;
616 GSList *retval, *l;
617
618 g_return_val_if_fail (CLUTTER_BEHAVIOUR (behave), NULL);
619
620 priv = behave->priv;
621 retval = NULL;
622 for (l = priv->actors; l != NULL; l = l->next)
623 retval = g_slist_prepend (retval, l->data);
624
625 return g_slist_reverse (retval);
626 }
627
628 /**
629 * clutter_behaviour_remove_all:
630 * @behave: a #ClutterBehaviour
631 *
632 * Removes every actor from the list that @behave holds.
633 *
634 * Since: 0.4
635 *
636 * Deprecated: 1.6
637 */
638 void
639 clutter_behaviour_remove_all (ClutterBehaviour *behave)
640 {
641 ClutterBehaviourPrivate *priv;
642 GSList *l;
643
644 g_return_if_fail (CLUTTER_IS_BEHAVIOUR (behave));
645
646 priv = behave->priv;
647 for (l = priv->actors; l != NULL; l = l->next)
648 {
649 ClutterActor *actor = l->data;
650
651 g_signal_emit (behave, behave_signals[REMOVED], 0, actor);
652 g_signal_handlers_disconnect_by_func (actor,
653 G_CALLBACK (remove_actor_on_destroy),
654 behave);
655 g_object_unref (actor);
656 }
657
658 g_slist_free (priv->actors);
659 priv->actors = NULL;
660 }