Debian Codegraph @

clutter/deprecated/clutter-box.c

raw
1 /*
2 * Clutter.
3 *
4 * An OpenGL based 'interactive canvas' library.
5 *
6 * Copyright (C) 2009,2010 Intel Corporation.
7 *
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Lesser General Public
10 * License as published by the Free Software Foundation; either
11 * version 2 of the License, or (at your option) any later version.
12 *
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Lesser General Public License for more details.
17 *
18 * You should have received a copy of the GNU Lesser General Public
19 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
20 *
21 * Author:
22 * Emmanuele Bassi <[email protected]>
23 */
24
25 /**
26 * SECTION:clutter-box
27 * @short_description: A Generic layout container
28 *
29 * #ClutterBox is a #ClutterActor sub-class implementing the #ClutterContainer
30 * interface. A Box delegates the whole size requisition and size allocation to
31 * a #ClutterLayoutManager instance.
32 *
33 * #ClutterBox is available since Clutter 1.2
34 *
35 * #ClutterBox is deprecated since Clutter 1.10; all its relevant API is provided
36 * by #ClutterActor, via the #ClutterActor:layout-manager property.
37 *
38 * ## Using ClutterBox
39 *
40 * The following code shows how to create a #ClutterBox with
41 * a #ClutterLayoutManager sub-class, and how to add children to
42 * it via clutter_box_pack().
43 *
44 * |[<!-- language="C" -->
45 * ClutterActor *box;
46 * ClutterLayoutManager *layout;
47 *
48 * // Create the layout manager first
49 * layout = clutter_box_layout_new ();
50 * clutter_box_layout_set_homogeneous (CLUTTER_BOX_LAYOUT (layout), TRUE);
51 * clutter_box_layout_set_spacing (CLUTTER_BOX_LAYOUT (layout), 12);
52 *
53 * // Then create the ClutterBox actor. The Box will take
54 * // ownership of the ClutterLayoutManager instance by sinking
55 * // its floating reference
56 * box = clutter_box_new (layout);
57 *
58 * // Now add children to the Box using the variadic arguments
59 * // function clutter_box_pack() to set layout properties
60 * clutter_box_pack (CLUTTER_BOX (box), actor,
61 * "x-align", CLUTTER_BOX_ALIGNMENT_CENTER,
62 * "y-align", CLUTTER_BOX_ALIGNMENT_END,
63 * "expand", TRUE,
64 * NULL);
65 * ]|
66 *
67 * #ClutterBox's clutter_box_pack() wraps the generic
68 * clutter_container_add_actor() function, but it also allows setting
69 * layout properties while adding the new child to the box.
70 */
71
72 #ifdef HAVE_CONFIG_H
73 #include "config.h"
74 #endif
75
76 #include <glib-object.h>
77 #include <gobject/gvaluecollector.h>
78
79 #define CLUTTER_DISABLE_DEPRECATION_WARNINGS
80 #include "deprecated/clutter-container.h"
81
82 #include "clutter-box.h"
83
84 #include "clutter-actor-private.h"
85 #include "clutter-color.h"
86 #include "clutter-debug.h"
87 #include "clutter-enum-types.h"
88 #include "clutter-marshal.h"
89 #include "clutter-private.h"
90
91 struct _ClutterBoxPrivate
92 {
93 ClutterLayoutManager *manager;
94
95 guint changed_id;
96 };
97
98 enum
99 {
100 PROP_0,
101
102 PROP_COLOR,
103 PROP_COLOR_SET,
104
105 PROP_LAST
106 };
107
108 static GParamSpec *obj_props[PROP_LAST] = { NULL, };
109
110 static const ClutterColor default_box_color = { 255, 255, 255, 255 };
111
112 G_DEFINE_TYPE_WITH_PRIVATE (ClutterBox, clutter_box, CLUTTER_TYPE_ACTOR)
113
114 static inline void
115 clutter_box_set_color_internal (ClutterBox *box,
116 const ClutterColor *color)
117 {
118 clutter_actor_set_background_color (CLUTTER_ACTOR (box), color);
119
120 g_object_notify_by_pspec (G_OBJECT (box), obj_props[PROP_COLOR_SET]);
121 g_object_notify_by_pspec (G_OBJECT (box), obj_props[PROP_COLOR]);
122 }
123
124 static gboolean
125 clutter_box_real_get_paint_volume (ClutterActor *actor,
126 ClutterPaintVolume *volume)
127 {
128 gboolean retval = FALSE;
129 ClutterActorIter iter;
130 ClutterActor *child;
131
132 /* if we have a background color, and an allocation, then we need to
133 * set it as the base of our paint volume
134 */
135 retval = clutter_paint_volume_set_from_allocation (volume, actor);
136
137 /* bail out early if we don't have any child */
138 if (clutter_actor_get_n_children (actor) == 0)
139 return retval;
140
141 retval = TRUE;
142
143 /* otherwise, union the paint volumes of our children, in case
144 * any one of them decides to paint outside the parent's allocation
145 */
146 clutter_actor_iter_init (&iter, actor);
147 while (clutter_actor_iter_next (&iter, &child))
148 {
149 const ClutterPaintVolume *child_volume;
150
151 /* This gets the paint volume of the child transformed into the
152 * group's coordinate space... */
153 child_volume = clutter_actor_get_transformed_paint_volume (child, actor);
154 if (!child_volume)
155 return FALSE;
156
157 clutter_paint_volume_union (volume, child_volume);
158 }
159
160 return retval;
161 }
162
163 static void
164 clutter_box_set_property (GObject *gobject,
165 guint prop_id,
166 const GValue *value,
167 GParamSpec *pspec)
168 {
169 ClutterBox *self = CLUTTER_BOX (gobject);
170
171 switch (prop_id)
172 {
173 case PROP_COLOR:
174 clutter_box_set_color_internal (self, clutter_value_get_color (value));
175 break;
176
177 default:
178 G_OBJECT_WARN_INVALID_PROPERTY_ID (gobject, prop_id, pspec);
179 break;
180 }
181 }
182
183 static void
184 clutter_box_get_property (GObject *gobject,
185 guint prop_id,
186 GValue *value,
187 GParamSpec *pspec)
188 {
189 switch (prop_id)
190 {
191 case PROP_COLOR:
192 {
193 ClutterColor color;
194
195 clutter_actor_get_background_color (CLUTTER_ACTOR (gobject),
196 &color);
197 clutter_value_set_color (value, &color);
198 }
199 break;
200
201 case PROP_COLOR_SET:
202 {
203 gboolean color_set;
204
205 g_object_get (gobject, "background-color-set", &color_set, NULL);
206 g_value_set_boolean (value, color_set);
207 }
208 break;
209
210 default:
211 G_OBJECT_WARN_INVALID_PROPERTY_ID (gobject, prop_id, pspec);
212 break;
213 }
214 }
215
216 static void
217 clutter_box_real_destroy (ClutterActor *actor)
218 {
219 ClutterActor *iter;
220
221 iter = clutter_actor_get_first_child (actor);
222 while (iter != NULL)
223 {
224 ClutterActor *next = clutter_actor_get_next_sibling (iter);
225
226 clutter_actor_destroy (iter);
227
228 iter = next;
229 }
230 }
231
232 static void
233 clutter_box_class_init (ClutterBoxClass *klass)
234 {
235 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
236 ClutterActorClass *actor_class = CLUTTER_ACTOR_CLASS (klass);
237
238 actor_class->destroy = clutter_box_real_destroy;
239 actor_class->get_paint_volume = clutter_box_real_get_paint_volume;
240
241 gobject_class->set_property = clutter_box_set_property;
242 gobject_class->get_property = clutter_box_get_property;
243
244 /**
245 * ClutterBox:color:
246 *
247 * The color to be used to paint the background of the
248 * #ClutterBox. Setting this property will set the
249 * #ClutterBox:color-set property as a side effect
250 *
251 * This property sets the #ClutterActor:background-color property
252 * internally.
253 *
254 * Since: 1.2
255 *
256 * Deprecated: 1.10: Use the #ClutterActor:background-color property
257 */
258 obj_props[PROP_COLOR] =
259 clutter_param_spec_color ("color",
260 P_("Color"),
261 P_("The background color of the box"),
262 &default_box_color,
263 CLUTTER_PARAM_READWRITE);
264
265 /**
266 * ClutterBox:color-set:
267 *
268 * Whether the #ClutterBox:color property has been set.
269 *
270 * This property reads the #ClutterActor:background-color-set property
271 * internally.
272 *
273 * Since: 1.2
274 *
275 * Deprecated: 1.10: Use the #ClutterActor:background-color-set property
276 */
277 obj_props[PROP_COLOR_SET] =
278 g_param_spec_boolean ("color-set",
279 P_("Color Set"),
280 P_("Whether the background color is set"),
281 FALSE,
282 CLUTTER_PARAM_READWRITE);
283
284 g_object_class_install_properties (gobject_class, PROP_LAST, obj_props);
285 }
286
287 static void
288 clutter_box_init (ClutterBox *self)
289 {
290 self->priv = clutter_box_get_instance_private (self);
291 }
292
293 /**
294 * clutter_box_new:
295 * @manager: a #ClutterLayoutManager
296 *
297 * Creates a new #ClutterBox. The children of the box will be layed
298 * out by the passed @manager
299 *
300 * Return value: the newly created #ClutterBox actor
301 *
302 * Since: 1.2
303 *
304 * Deprecated: 1.10: Use clutter_actor_new() instead.
305 */
306 ClutterActor *
307 clutter_box_new (ClutterLayoutManager *manager)
308 {
309 g_return_val_if_fail (CLUTTER_IS_LAYOUT_MANAGER (manager), NULL);
310
311 return g_object_new (CLUTTER_TYPE_BOX,
312 "layout-manager", manager,
313 NULL);
314 }
315
316 /**
317 * clutter_box_set_layout_manager:
318 * @box: a #ClutterBox
319 * @manager: a #ClutterLayoutManager
320 *
321 * Sets the #ClutterLayoutManager for @box
322 *
323 * A #ClutterLayoutManager is a delegate object that controls the
324 * layout of the children of @box
325 *
326 * Since: 1.2
327 *
328 * Deprecated: 1.10: Use clutter_actor_set_layout_manager() instead.
329 */
330 void
331 clutter_box_set_layout_manager (ClutterBox *box,
332 ClutterLayoutManager *manager)
333 {
334 clutter_actor_set_layout_manager (CLUTTER_ACTOR (box), manager);
335 }
336
337 /**
338 * clutter_box_get_layout_manager:
339 * @box: a #ClutterBox
340 *
341 * Retrieves the #ClutterLayoutManager instance used by @box
342 *
343 * Return value: (transfer none): a #ClutterLayoutManager. The returned
344 * #ClutterLayoutManager is owned by the #ClutterBox and it should not
345 * be unreferenced
346 *
347 * Since: 1.2
348 *
349 * Deprecated: 1.10: Use clutter_actor_get_layout_manager() instead.
350 */
351 ClutterLayoutManager *
352 clutter_box_get_layout_manager (ClutterBox *box)
353 {
354 return clutter_actor_get_layout_manager (CLUTTER_ACTOR (box));
355 }
356
357 /**
358 * clutter_box_packv:
359 * @box: a #ClutterBox
360 * @actor: a #ClutterActor
361 * @n_properties: the number of properties to set
362 * @properties: (array length=n_properties) (element-type utf8): a vector
363 * containing the property names to set
364 * @values: (array length=n_properties): a vector containing the property
365 * values to set
366 *
367 * Vector-based variant of clutter_box_pack(), intended for language
368 * bindings to use
369 *
370 * Since: 1.2
371 *
372 * Deprecated: 1.10: Use clutter_actor_add_child() instead. To set
373 * specific layout properties, use clutter_layout_manager_child_set()
374 */
375 void
376 clutter_box_packv (ClutterBox *box,
377 ClutterActor *actor,
378 guint n_properties,
379 const gchar * const properties[],
380 const GValue *values)
381 {
382 ClutterLayoutManager *manager;
383 ClutterContainer *container;
384 ClutterLayoutMeta *meta;
385 GObjectClass *klass;
386 gint i;
387
388 g_return_if_fail (CLUTTER_IS_BOX (box));
389 g_return_if_fail (CLUTTER_IS_ACTOR (actor));
390
391 container = CLUTTER_CONTAINER (box);
392 clutter_container_add_actor (container, actor);
393
394 manager = clutter_actor_get_layout_manager (CLUTTER_ACTOR (box));
395 if (manager == NULL)
396 return;
397
398 meta = clutter_layout_manager_get_child_meta (manager,
399 container,
400 actor);
401
402 if (meta == NULL)
403 return;
404
405 klass = G_OBJECT_GET_CLASS (meta);
406
407 for (i = 0; i < n_properties; i++)
408 {
409 const gchar *pname = properties[i];
410 GParamSpec *pspec;
411
412 pspec = g_object_class_find_property (klass, pname);
413 if (pspec == NULL)
414 {
415 g_warning ("%s: the layout property '%s' for managers "
416 "of type '%s' (meta type '%s') does not exist",
417 G_STRLOC,
418 pname,
419 G_OBJECT_TYPE_NAME (manager),
420 G_OBJECT_TYPE_NAME (meta));
421 break;
422 }
423
424 if (!(pspec->flags & G_PARAM_WRITABLE))
425 {
426 g_warning ("%s: the layout property '%s' for managers "
427 "of type '%s' (meta type '%s') is not writable",
428 G_STRLOC,
429 pspec->name,
430 G_OBJECT_TYPE_NAME (manager),
431 G_OBJECT_TYPE_NAME (meta));
432 break;
433 }
434
435 clutter_layout_manager_child_set_property (manager,
436 container, actor,
437 pname, &values[i]);
438 }
439 }
440
441 static inline void
442 clutter_box_set_property_valist (ClutterBox *box,
443 ClutterActor *actor,
444 const gchar *first_property,
445 va_list var_args)
446 {
447 ClutterContainer *container = CLUTTER_CONTAINER (box);
448 ClutterLayoutManager *manager;
449 ClutterLayoutMeta *meta;
450 GObjectClass *klass;
451 const gchar *pname;
452
453 manager = clutter_actor_get_layout_manager (CLUTTER_ACTOR (box));
454 if (manager == NULL)
455 return;
456
457 meta = clutter_layout_manager_get_child_meta (manager,
458 container,
459 actor);
460
461 if (meta == NULL)
462 return;
463
464 klass = G_OBJECT_GET_CLASS (meta);
465
466 pname = first_property;
467 while (pname)
468 {
469 GValue value = { 0, };
470 GParamSpec *pspec;
471 gchar *error;
472
473 pspec = g_object_class_find_property (klass, pname);
474 if (pspec == NULL)
475 {
476 g_warning ("%s: the layout property '%s' for managers "
477 "of type '%s' (meta type '%s') does not exist",
478 G_STRLOC,
479 pname,
480 G_OBJECT_TYPE_NAME (manager),
481 G_OBJECT_TYPE_NAME (meta));
482 break;
483 }
484
485 if (!(pspec->flags & G_PARAM_WRITABLE))
486 {
487 g_warning ("%s: the layout property '%s' for managers "
488 "of type '%s' (meta type '%s') is not writable",
489 G_STRLOC,
490 pspec->name,
491 G_OBJECT_TYPE_NAME (manager),
492 G_OBJECT_TYPE_NAME (meta));
493 break;
494 }
495
496 G_VALUE_COLLECT_INIT (&value, G_PARAM_SPEC_VALUE_TYPE (pspec),
497 var_args, 0,
498 &error);
499
500 if (error)
501 {
502 g_warning ("%s: %s", G_STRLOC, error);
503 g_free (error);
504 break;
505 }
506
507 clutter_layout_manager_child_set_property (manager,
508 container, actor,
509 pspec->name, &value);
510
511 g_value_unset (&value);
512
513 pname = va_arg (var_args, gchar*);
514 }
515 }
516
517 /**
518 * clutter_box_pack:
519 * @box: a #ClutterBox
520 * @actor: a #ClutterActor
521 * @first_property: the name of the first property to set, or %NULL
522 * @...: a list of property name and value pairs, terminated by %NULL
523 *
524 * Adds @actor to @box and sets layout properties at the same time,
525 * if the #ClutterLayoutManager used by @box has them
526 *
527 * This function is a wrapper around clutter_container_add_actor()
528 * and clutter_layout_manager_child_set()
529 *
530 * Language bindings should use the vector-based clutter_box_packv()
531 * variant instead
532 *
533 * Since: 1.2
534 *
535 * Deprecated: 1.10: Use clutter_actor_add_child() instead. To set
536 * specific layout properties, use clutter_layout_manager_child_set()
537 */
538 void
539 clutter_box_pack (ClutterBox *box,
540 ClutterActor *actor,
541 const gchar *first_property,
542 ...)
543 {
544 va_list var_args;
545
546 g_return_if_fail (CLUTTER_IS_BOX (box));
547 g_return_if_fail (CLUTTER_IS_ACTOR (actor));
548
549 clutter_container_add_actor (CLUTTER_CONTAINER (box), actor);
550
551 if (first_property == NULL || *first_property == '\0')
552 return;
553
554 va_start (var_args, first_property);
555 clutter_box_set_property_valist (box, actor, first_property, var_args);
556 va_end (var_args);
557 }
558
559 /**
560 * clutter_box_pack_after:
561 * @box: a #ClutterBox
562 * @actor: a #ClutterActor
563 * @sibling: (allow-none): a #ClutterActor or %NULL
564 * @first_property: the name of the first property to set, or %NULL
565 * @...: a list of property name and value pairs, terminated by %NULL
566 *
567 * Adds @actor to @box, placing it after @sibling, and sets layout
568 * properties at the same time, if the #ClutterLayoutManager used by
569 * @box supports them
570 *
571 * If @sibling is %NULL then @actor is placed at the end of the
572 * list of children, to be allocated and painted after every other child
573 *
574 * This function is a wrapper around clutter_container_add_actor(),
575 * clutter_container_raise_child() and clutter_layout_manager_child_set()
576 *
577 * Since: 1.2
578 *
579 * Deprecated: 1.10: Use clutter_actor_insert_child_above() instead.
580 * To set specific layout properties, use clutter_layout_manager_child_set()
581 */
582 void
583 clutter_box_pack_after (ClutterBox *box,
584 ClutterActor *actor,
585 ClutterActor *sibling,
586 const gchar *first_property,
587 ...)
588 {
589 va_list var_args;
590
591 g_return_if_fail (CLUTTER_IS_BOX (box));
592 g_return_if_fail (CLUTTER_IS_ACTOR (actor));
593 g_return_if_fail (sibling == NULL || CLUTTER_IS_ACTOR (sibling));
594
595 clutter_container_add_actor (CLUTTER_CONTAINER (box), actor);
596 clutter_container_raise_child (CLUTTER_CONTAINER (box), actor, sibling);
597
598 if (first_property == NULL || *first_property == '\0')
599 return;
600
601 va_start (var_args, first_property);
602 clutter_box_set_property_valist (box, actor, first_property, var_args);
603 va_end (var_args);
604 }
605
606 /**
607 * clutter_box_pack_before:
608 * @box: a #ClutterBox
609 * @actor: a #ClutterActor
610 * @sibling: (allow-none): a #ClutterActor or %NULL
611 * @first_property: the name of the first property to set, or %NULL
612 * @...: a list of property name and value pairs, terminated by %NULL
613 *
614 * Adds @actor to @box, placing it before @sibling, and sets layout
615 * properties at the same time, if the #ClutterLayoutManager used by
616 * @box supports them
617 *
618 * If @sibling is %NULL then @actor is placed at the beginning of the
619 * list of children, to be allocated and painted below every other child
620 *
621 * This function is a wrapper around clutter_container_add_actor(),
622 * clutter_container_lower_child() and clutter_layout_manager_child_set()
623 *
624 * Since: 1.2
625 *
626 * Deprecated: 1.10: Use clutter_actor_insert_child_below() instead.
627 * To set specific layout properties, use clutter_layout_manager_child_set()
628 */
629 void
630 clutter_box_pack_before (ClutterBox *box,
631 ClutterActor *actor,
632 ClutterActor *sibling,
633 const gchar *first_property,
634 ...)
635 {
636 va_list var_args;
637
638 g_return_if_fail (CLUTTER_IS_BOX (box));
639 g_return_if_fail (CLUTTER_IS_ACTOR (actor));
640 g_return_if_fail (sibling == NULL || CLUTTER_IS_ACTOR (sibling));
641
642 clutter_container_add_actor (CLUTTER_CONTAINER (box), actor);
643 clutter_container_lower_child (CLUTTER_CONTAINER (box), actor, sibling);
644
645 if (first_property == NULL || *first_property == '\0')
646 return;
647
648 va_start (var_args, first_property);
649 clutter_box_set_property_valist (box, actor, first_property, var_args);
650 va_end (var_args);
651 }
652
653 /**
654 * clutter_box_pack_at:
655 * @box: a #ClutterBox
656 * @actor: a #ClutterActor
657 * @position: the position to insert the @actor at
658 * @first_property: the name of the first property to set, or %NULL
659 * @...: a list of property name and value pairs, terminated by %NULL
660 *
661 * Adds @actor to @box, placing it at @position, and sets layout
662 * properties at the same time, if the #ClutterLayoutManager used by
663 * @box supports them
664 *
665 * If @position is a negative number, or is larger than the number of
666 * children of @box, the new child is added at the end of the list of
667 * children
668 *
669 * Since: 1.2
670 *
671 * Deprecated: 1.10: Use clutter_actor_insert_child_at_index() instead.
672 * To set specific layout properties, use clutter_layout_manager_child_set()
673 */
674 void
675 clutter_box_pack_at (ClutterBox *box,
676 ClutterActor *actor,
677 gint position,
678 const gchar *first_property,
679 ...)
680 {
681 va_list var_args;
682
683 g_return_if_fail (CLUTTER_IS_BOX (box));
684 g_return_if_fail (CLUTTER_IS_ACTOR (actor));
685
686 clutter_actor_insert_child_at_index (CLUTTER_ACTOR (box),
687 actor,
688 position);
689
690 /* we need to explicitly call this, because we're not going through
691 * the default code paths provided by clutter_container_add()
692 */
693 clutter_container_create_child_meta (CLUTTER_CONTAINER (box), actor);
694
695 g_signal_emit_by_name (box, "actor-added", actor);
696
697 if (first_property == NULL || *first_property == '\0')
698 return;
699
700 va_start (var_args, first_property);
701 clutter_box_set_property_valist (box, actor, first_property, var_args);
702 va_end (var_args);
703 }
704
705 /**
706 * clutter_box_set_color:
707 * @box: a #ClutterBox
708 * @color: (allow-none): the background color, or %NULL to unset
709 *
710 * Sets (or unsets) the background color for @box
711 *
712 * Since: 1.2
713 *
714 * Deprecated: 1.10: Use clutter_actor_set_background_color() instead.
715 */
716 void
717 clutter_box_set_color (ClutterBox *box,
718 const ClutterColor *color)
719 {
720 g_return_if_fail (CLUTTER_IS_BOX (box));
721
722 clutter_box_set_color_internal (box, color);
723 }
724
725 /**
726 * clutter_box_get_color:
727 * @box: a #ClutterBox
728 * @color: (out caller-allocates): return location for a #ClutterColor
729 *
730 * Retrieves the background color of @box
731 *
732 * If the #ClutterBox:color-set property is set to %FALSE the
733 * returned #ClutterColor is undefined
734 *
735 * Since: 1.2
736 *
737 * Deprecated: 1.10: Use clutter_actor_get_background_color() instead.
738 */
739 void
740 clutter_box_get_color (ClutterBox *box,
741 ClutterColor *color)
742 {
743 g_return_if_fail (CLUTTER_IS_BOX (box));
744 g_return_if_fail (color != NULL);
745
746 clutter_actor_get_background_color (CLUTTER_ACTOR (box), color);
747 }