1 /* GTK - The GIMP Toolkit
2 * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
21 * Modified by the GTK+ Team and others 1997-2000. See the AUTHORS
22 * file for a list of people on the GTK+ Team. See the ChangeLog
23 * files for a list of changes. These files are distributed with
24 * GTK+ at ftp://ftp.gtk.org/pub/gtk/.
29 #include "gtkcontainer.h"
35 #include "gtkbuildable.h"
36 #include "gtkbuilderprivate.h"
37 #include "gtkprivate.h"
39 #include "gtkmarshalers.h"
40 #include "gtksizerequest.h"
41 #include "gtkwindow.h"
43 #include "gtktoolbar.h"
44 #include <gobject/gobjectnotifyqueue.c>
45 #include <gobject/gvaluecollector.h>
49 * SECTION:gtkcontainer
50 * @Short_description: Base class for widgets which contain other widgets
51 * @Title: GtkContainer
53 * A GTK+ user interface is constructed by nesting widgets inside widgets.
54 * Container widgets are the inner nodes in the resulting tree of widgets:
55 * they contain other widgets. So, for example, you might have a #GtkWindow
56 * containing a #GtkFrame containing a #GtkLabel. If you wanted an image instead
57 * of a textual label inside the frame, you might replace the #GtkLabel widget
58 * with a #GtkImage widget.
60 * There are two major kinds of container widgets in GTK+. Both are subclasses
61 * of the abstract GtkContainer base class.
63 * The first type of container widget has a single child widget and derives
64 * from #GtkBin. These containers are <emphasis>decorators</emphasis>, which
65 * add some kind of functionality to the child. For example, a #GtkButton makes
66 * its child into a clickable button; a #GtkFrame draws a frame around its child
67 * and a #GtkWindow places its child widget inside a top-level window.
69 * The second type of container can have more than one child; its purpose is to
70 * manage <emphasis>layout</emphasis>. This means that these containers assign
71 * sizes and positions to their children. For example, a #GtkHBox arranges its
72 * children in a horizontal row, and a #GtkTable arranges the widgets it contains
73 * in a two-dimensional grid.
75 * GTK+ uses a height-for-width (and width-for-height) geometry management system.
76 * Height-for-width means that a widget can change how much vertical space it needs,
77 * depending on the amount of horizontal space that it is given (and similar for
79 * See <link linkend="geometry-management">GtkWidget's geometry management section</link>
80 * to learn more about height-for-width geometry management.
81 * <refsect2 id="child-properties">
82 * <title>Child properties</title>
84 * GtkContainer introduces <emphasis>child properties</emphasis>.
85 * These are object properties that are not specific
86 * to either the container or the contained widget, but rather to their relation.
87 * Typical examples of child properties are the position or pack-type of a widget
88 * which is contained in a #GtkBox.
90 * Use gtk_container_class_install_child_property() to install child properties
91 * for a container class and gtk_container_class_find_child_property() or
92 * gtk_container_class_list_child_properties() to get information about existing
95 * To set the value of a child property, use gtk_container_child_set_property(),
96 * gtk_container_child_set() or gtk_container_child_set_valist().
97 * To obtain the value of a child property, use
98 * gtk_container_child_get_property(), gtk_container_child_get() or
99 * gtk_container_child_get_valist(). To emit notification about child property
100 * changes, use gtk_widget_child_notify().
103 * <refsect2 id="GtkContainer-BUILDER-UI">
104 * <title>GtkContainer as GtkBuildable</title>
106 * The GtkContainer implementation of the GtkBuildable interface
107 * supports a <packing> element for children, which can
108 * contain multiple <property> elements that specify
109 * child properties for the child.
111 * <title>Child properties in UI definitions</title>
112 * <programlisting><![CDATA[
113 * <object class="GtkVBox">
115 * <object class="GtkLabel"/>
117 * <property name="pack-type">start</property>
121 * ]]></programlisting>
123 * Since 2.16, child properties can also be marked as translatable using
124 * the same "translatable", "comments" and "context" attributes that are used
125 * for regular properties.
131 struct _GtkContainerPrivate
133 GtkWidget *focus_child;
135 guint border_width : 16;
137 guint has_focus_chain : 1;
138 guint need_resize : 1;
139 guint reallocate_redraws : 1;
140 guint resize_mode : 2;
158 #define PARAM_SPEC_PARAM_ID(pspec) ((pspec)->param_id)
159 #define PARAM_SPEC_SET_PARAM_ID(pspec, id) ((pspec)->param_id = (id))
162 /* --- prototypes --- */
163 static void gtk_container_base_class_init (GtkContainerClass *klass);
164 static void gtk_container_base_class_finalize (GtkContainerClass *klass);
165 static void gtk_container_class_init (GtkContainerClass *klass);
166 static void gtk_container_init (GtkContainer *container);
167 static void gtk_container_destroy (GtkWidget *widget);
168 static void gtk_container_set_property (GObject *object,
172 static void gtk_container_get_property (GObject *object,
176 static void gtk_container_add_unimplemented (GtkContainer *container,
178 static void gtk_container_remove_unimplemented (GtkContainer *container,
180 static void gtk_container_real_check_resize (GtkContainer *container);
181 static gboolean gtk_container_focus (GtkWidget *widget,
182 GtkDirectionType direction);
183 static void gtk_container_real_set_focus_child (GtkContainer *container,
186 static gboolean gtk_container_focus_move (GtkContainer *container,
188 GtkDirectionType direction);
189 static void gtk_container_children_callback (GtkWidget *widget,
190 gpointer client_data);
191 static void gtk_container_show_all (GtkWidget *widget);
192 static void gtk_container_hide_all (GtkWidget *widget);
193 static gint gtk_container_draw (GtkWidget *widget,
195 static void gtk_container_map (GtkWidget *widget);
196 static void gtk_container_unmap (GtkWidget *widget);
197 static void gtk_container_adjust_size_request (GtkWidget *widget,
198 GtkOrientation orientation,
202 static void gtk_container_adjust_size_allocation (GtkWidget *widget,
203 GtkAllocation *allocation);
205 static gchar* gtk_container_child_default_composite_name (GtkContainer *container,
209 static void gtk_container_buildable_init (GtkBuildableIface *iface);
210 static void gtk_container_buildable_add_child (GtkBuildable *buildable,
214 static gboolean gtk_container_buildable_custom_tag_start (GtkBuildable *buildable,
217 const gchar *tagname,
218 GMarkupParser *parser,
220 static void gtk_container_buildable_custom_tag_end (GtkBuildable *buildable,
223 const gchar *tagname,
227 /* --- variables --- */
228 static const gchar vadjustment_key[] = "gtk-vadjustment";
229 static guint vadjustment_key_id = 0;
230 static const gchar hadjustment_key[] = "gtk-hadjustment";
231 static guint hadjustment_key_id = 0;
232 static GSList *container_resize_queue = NULL;
233 static guint container_signals[LAST_SIGNAL] = { 0 };
234 static GtkWidgetClass *parent_class = NULL;
235 extern GParamSpecPool *_gtk_widget_child_property_pool;
236 extern GObjectNotifyContext *_gtk_widget_child_property_notify_context;
237 static GtkBuildableIface *parent_buildable_iface;
240 /* --- functions --- */
242 gtk_container_get_type (void)
244 static GType container_type = 0;
248 const GTypeInfo container_info =
250 sizeof (GtkContainerClass),
251 (GBaseInitFunc) gtk_container_base_class_init,
252 (GBaseFinalizeFunc) gtk_container_base_class_finalize,
253 (GClassInitFunc) gtk_container_class_init,
254 NULL /* class_finalize */,
255 NULL /* class_data */,
256 sizeof (GtkContainer),
258 (GInstanceInitFunc) gtk_container_init,
259 NULL, /* value_table */
262 const GInterfaceInfo buildable_info =
264 (GInterfaceInitFunc) gtk_container_buildable_init,
270 g_type_register_static (GTK_TYPE_WIDGET, I_("GtkContainer"),
271 &container_info, G_TYPE_FLAG_ABSTRACT);
273 g_type_add_interface_static (container_type,
279 return container_type;
283 gtk_container_base_class_init (GtkContainerClass *class)
285 /* reset instance specifc class fields that don't get inherited */
286 class->set_child_property = NULL;
287 class->get_child_property = NULL;
291 gtk_container_base_class_finalize (GtkContainerClass *class)
295 list = g_param_spec_pool_list_owned (_gtk_widget_child_property_pool, G_OBJECT_CLASS_TYPE (class));
296 for (node = list; node; node = node->next)
298 GParamSpec *pspec = node->data;
300 g_param_spec_pool_remove (_gtk_widget_child_property_pool, pspec);
301 PARAM_SPEC_SET_PARAM_ID (pspec, 0);
302 g_param_spec_unref (pspec);
308 gtk_container_class_init (GtkContainerClass *class)
310 GObjectClass *gobject_class = G_OBJECT_CLASS (class);
311 GtkWidgetClass *widget_class = GTK_WIDGET_CLASS (class);
313 parent_class = g_type_class_peek_parent (class);
315 vadjustment_key_id = g_quark_from_static_string (vadjustment_key);
316 hadjustment_key_id = g_quark_from_static_string (hadjustment_key);
318 gobject_class->set_property = gtk_container_set_property;
319 gobject_class->get_property = gtk_container_get_property;
321 widget_class->destroy = gtk_container_destroy;
322 widget_class->show_all = gtk_container_show_all;
323 widget_class->hide_all = gtk_container_hide_all;
324 widget_class->draw = gtk_container_draw;
325 widget_class->map = gtk_container_map;
326 widget_class->unmap = gtk_container_unmap;
327 widget_class->focus = gtk_container_focus;
329 widget_class->adjust_size_request = gtk_container_adjust_size_request;
330 widget_class->adjust_size_allocation = gtk_container_adjust_size_allocation;
332 class->add = gtk_container_add_unimplemented;
333 class->remove = gtk_container_remove_unimplemented;
334 class->check_resize = gtk_container_real_check_resize;
335 class->forall = NULL;
336 class->set_focus_child = gtk_container_real_set_focus_child;
337 class->child_type = NULL;
338 class->composite_name = gtk_container_child_default_composite_name;
340 g_object_class_install_property (gobject_class,
342 g_param_spec_enum ("resize-mode",
344 P_("Specify how resize events are handled"),
345 GTK_TYPE_RESIZE_MODE,
347 GTK_PARAM_READWRITE));
348 g_object_class_install_property (gobject_class,
350 g_param_spec_uint ("border-width",
352 P_("The width of the empty border outside the containers children"),
356 GTK_PARAM_READWRITE));
357 g_object_class_install_property (gobject_class,
359 g_param_spec_object ("child",
361 P_("Can be used to add a new child to the container"),
363 GTK_PARAM_WRITABLE));
364 container_signals[ADD] =
365 g_signal_new (I_("add"),
366 G_OBJECT_CLASS_TYPE (gobject_class),
368 G_STRUCT_OFFSET (GtkContainerClass, add),
370 _gtk_marshal_VOID__OBJECT,
373 container_signals[REMOVE] =
374 g_signal_new (I_("remove"),
375 G_OBJECT_CLASS_TYPE (gobject_class),
377 G_STRUCT_OFFSET (GtkContainerClass, remove),
379 _gtk_marshal_VOID__OBJECT,
382 container_signals[CHECK_RESIZE] =
383 g_signal_new (I_("check-resize"),
384 G_OBJECT_CLASS_TYPE (gobject_class),
386 G_STRUCT_OFFSET (GtkContainerClass, check_resize),
388 _gtk_marshal_VOID__VOID,
390 container_signals[SET_FOCUS_CHILD] =
391 g_signal_new (I_("set-focus-child"),
392 G_OBJECT_CLASS_TYPE (gobject_class),
394 G_STRUCT_OFFSET (GtkContainerClass, set_focus_child),
396 _gtk_marshal_VOID__OBJECT,
400 g_type_class_add_private (class, sizeof (GtkContainerPrivate));
404 gtk_container_buildable_init (GtkBuildableIface *iface)
406 parent_buildable_iface = g_type_interface_peek_parent (iface);
407 iface->add_child = gtk_container_buildable_add_child;
408 iface->custom_tag_start = gtk_container_buildable_custom_tag_start;
409 iface->custom_tag_end = gtk_container_buildable_custom_tag_end;
413 gtk_container_buildable_add_child (GtkBuildable *buildable,
420 GTK_BUILDER_WARN_INVALID_CHILD_TYPE (buildable, type);
422 else if (GTK_IS_WIDGET (child) &&
423 gtk_widget_get_parent (GTK_WIDGET (child)) == NULL)
425 gtk_container_add (GTK_CONTAINER (buildable), GTK_WIDGET (child));
428 g_warning ("Cannot add an object of type %s to a container of type %s",
429 g_type_name (G_OBJECT_TYPE (child)), g_type_name (G_OBJECT_TYPE (buildable)));
433 gtk_container_buildable_set_child_property (GtkContainer *container,
440 GValue gvalue = { 0, };
441 GError *error = NULL;
443 pspec = gtk_container_class_find_child_property
444 (G_OBJECT_GET_CLASS (container), name);
447 g_warning ("%s does not have a property called %s",
448 g_type_name (G_OBJECT_TYPE (container)), name);
452 if (!gtk_builder_value_from_string (builder, pspec, value, &gvalue, &error))
454 g_warning ("Could not read property %s:%s with value %s of type %s: %s",
455 g_type_name (G_OBJECT_TYPE (container)),
458 g_type_name (G_PARAM_SPEC_VALUE_TYPE (pspec)),
460 g_error_free (error);
464 gtk_container_child_set_property (container, child, name, &gvalue);
465 g_value_unset (&gvalue);
470 GtkContainer *container;
472 gchar *child_prop_name;
474 gboolean translatable;
475 } PackingPropertiesData;
478 attributes_start_element (GMarkupParseContext *context,
479 const gchar *element_name,
481 const gchar **values,
485 PackingPropertiesData *parser_data = (PackingPropertiesData*)user_data;
488 if (strcmp (element_name, "property") == 0)
490 for (i = 0; names[i]; i++)
491 if (strcmp (names[i], "name") == 0)
492 parser_data->child_prop_name = g_strdup (values[i]);
493 else if (strcmp (names[i], "translatable") == 0)
495 if (!_gtk_builder_boolean_from_string (values[1],
496 &parser_data->translatable,
500 else if (strcmp (names[i], "comments") == 0)
501 ; /* for translators */
502 else if (strcmp (names[i], "context") == 0)
503 parser_data->context = g_strdup (values[1]);
505 g_warning ("Unsupported attribute for GtkContainer Child "
506 "property: %s\n", names[i]);
508 else if (strcmp (element_name, "packing") == 0)
511 g_warning ("Unsupported tag for GtkContainer: %s\n", element_name);
515 attributes_text_element (GMarkupParseContext *context,
521 PackingPropertiesData *parser_data = (PackingPropertiesData*)user_data;
524 if (!parser_data->child_prop_name)
527 if (parser_data->translatable && text_len)
530 domain = gtk_builder_get_translation_domain (parser_data->builder);
532 value = _gtk_builder_parser_translate (domain,
533 parser_data->context,
538 value = g_strdup (text);
541 gtk_container_buildable_set_child_property (parser_data->container,
542 parser_data->builder,
544 parser_data->child_prop_name,
547 g_free (parser_data->child_prop_name);
548 g_free (parser_data->context);
550 parser_data->child_prop_name = NULL;
551 parser_data->context = NULL;
552 parser_data->translatable = FALSE;
555 static const GMarkupParser attributes_parser =
557 attributes_start_element,
559 attributes_text_element,
563 gtk_container_buildable_custom_tag_start (GtkBuildable *buildable,
566 const gchar *tagname,
567 GMarkupParser *parser,
570 PackingPropertiesData *parser_data;
572 if (parent_buildable_iface->custom_tag_start (buildable, builder, child,
573 tagname, parser, data))
576 if (child && strcmp (tagname, "packing") == 0)
578 parser_data = g_slice_new0 (PackingPropertiesData);
579 parser_data->builder = builder;
580 parser_data->container = GTK_CONTAINER (buildable);
581 parser_data->child = GTK_WIDGET (child);
582 parser_data->child_prop_name = NULL;
584 *parser = attributes_parser;
593 gtk_container_buildable_custom_tag_end (GtkBuildable *buildable,
596 const gchar *tagname,
599 if (strcmp (tagname, "packing") == 0)
601 g_slice_free (PackingPropertiesData, (gpointer)data);
606 if (parent_buildable_iface->custom_tag_end)
607 parent_buildable_iface->custom_tag_end (buildable, builder,
608 child, tagname, data);
613 * gtk_container_child_type:
614 * @container: a #GtkContainer
616 * Returns the type of the children supported by the container.
618 * Note that this may return %G_TYPE_NONE to indicate that no more
619 * children can be added, e.g. for a #GtkPaned which already has two
622 * Return value: a #GType.
625 gtk_container_child_type (GtkContainer *container)
628 GtkContainerClass *class;
630 g_return_val_if_fail (GTK_IS_CONTAINER (container), 0);
632 class = GTK_CONTAINER_GET_CLASS (container);
633 if (class->child_type)
634 slot = class->child_type (container);
641 /* --- GtkContainer child property mechanism --- */
643 container_get_child_property (GtkContainer *container,
648 GtkContainerClass *class = g_type_class_peek (pspec->owner_type);
650 class->get_child_property (container, child, PARAM_SPEC_PARAM_ID (pspec), value, pspec);
654 container_set_child_property (GtkContainer *container,
658 GObjectNotifyQueue *nqueue)
660 GValue tmp_value = { 0, };
661 GtkContainerClass *class = g_type_class_peek (pspec->owner_type);
663 /* provide a copy to work from, convert (if necessary) and validate */
664 g_value_init (&tmp_value, G_PARAM_SPEC_VALUE_TYPE (pspec));
665 if (!g_value_transform (value, &tmp_value))
666 g_warning ("unable to set child property `%s' of type `%s' from value of type `%s'",
668 g_type_name (G_PARAM_SPEC_VALUE_TYPE (pspec)),
669 G_VALUE_TYPE_NAME (value));
670 else if (g_param_value_validate (pspec, &tmp_value) && !(pspec->flags & G_PARAM_LAX_VALIDATION))
672 gchar *contents = g_strdup_value_contents (value);
674 g_warning ("value \"%s\" of type `%s' is invalid for property `%s' of type `%s'",
676 G_VALUE_TYPE_NAME (value),
678 g_type_name (G_PARAM_SPEC_VALUE_TYPE (pspec)));
683 class->set_child_property (container, child, PARAM_SPEC_PARAM_ID (pspec), &tmp_value, pspec);
684 g_object_notify_queue_add (G_OBJECT (child), nqueue, pspec);
686 g_value_unset (&tmp_value);
690 * gtk_container_child_get_valist:
691 * @container: a #GtkContainer
692 * @child: a widget which is a child of @container
693 * @first_property_name: the name of the first property to get
694 * @var_args: return location for the first property, followed
695 * optionally by more name/return location pairs, followed by %NULL
697 * Gets the values of one or more child properties for @child and @container.
700 gtk_container_child_get_valist (GtkContainer *container,
702 const gchar *first_property_name,
707 g_return_if_fail (GTK_IS_CONTAINER (container));
708 g_return_if_fail (GTK_IS_WIDGET (child));
709 g_return_if_fail (gtk_widget_get_parent (child) == GTK_WIDGET (container));
711 g_object_ref (container);
712 g_object_ref (child);
714 name = first_property_name;
717 GValue value = { 0, };
721 pspec = g_param_spec_pool_lookup (_gtk_widget_child_property_pool,
723 G_OBJECT_TYPE (container),
727 g_warning ("%s: container class `%s' has no child property named `%s'",
729 G_OBJECT_TYPE_NAME (container),
733 if (!(pspec->flags & G_PARAM_READABLE))
735 g_warning ("%s: child property `%s' of container class `%s' is not readable",
738 G_OBJECT_TYPE_NAME (container));
741 g_value_init (&value, G_PARAM_SPEC_VALUE_TYPE (pspec));
742 container_get_child_property (container, child, pspec, &value);
743 G_VALUE_LCOPY (&value, var_args, 0, &error);
746 g_warning ("%s: %s", G_STRLOC, error);
748 g_value_unset (&value);
751 g_value_unset (&value);
752 name = va_arg (var_args, gchar*);
755 g_object_unref (child);
756 g_object_unref (container);
760 * gtk_container_child_get_property:
761 * @container: a #GtkContainer
762 * @child: a widget which is a child of @container
763 * @property_name: the name of the property to get
764 * @value: a location to return the value
766 * Gets the value of a child property for @child and @container.
769 gtk_container_child_get_property (GtkContainer *container,
771 const gchar *property_name,
776 g_return_if_fail (GTK_IS_CONTAINER (container));
777 g_return_if_fail (GTK_IS_WIDGET (child));
778 g_return_if_fail (gtk_widget_get_parent (child) == GTK_WIDGET (container));
779 g_return_if_fail (property_name != NULL);
780 g_return_if_fail (G_IS_VALUE (value));
782 g_object_ref (container);
783 g_object_ref (child);
784 pspec = g_param_spec_pool_lookup (_gtk_widget_child_property_pool, property_name,
785 G_OBJECT_TYPE (container), TRUE);
787 g_warning ("%s: container class `%s' has no child property named `%s'",
789 G_OBJECT_TYPE_NAME (container),
791 else if (!(pspec->flags & G_PARAM_READABLE))
792 g_warning ("%s: child property `%s' of container class `%s' is not readable",
795 G_OBJECT_TYPE_NAME (container));
798 GValue *prop_value, tmp_value = { 0, };
800 /* auto-conversion of the callers value type
802 if (G_VALUE_TYPE (value) == G_PARAM_SPEC_VALUE_TYPE (pspec))
804 g_value_reset (value);
807 else if (!g_value_type_transformable (G_PARAM_SPEC_VALUE_TYPE (pspec), G_VALUE_TYPE (value)))
809 g_warning ("can't retrieve child property `%s' of type `%s' as value of type `%s'",
811 g_type_name (G_PARAM_SPEC_VALUE_TYPE (pspec)),
812 G_VALUE_TYPE_NAME (value));
813 g_object_unref (child);
814 g_object_unref (container);
819 g_value_init (&tmp_value, G_PARAM_SPEC_VALUE_TYPE (pspec));
820 prop_value = &tmp_value;
822 container_get_child_property (container, child, pspec, prop_value);
823 if (prop_value != value)
825 g_value_transform (prop_value, value);
826 g_value_unset (&tmp_value);
829 g_object_unref (child);
830 g_object_unref (container);
834 * gtk_container_child_set_valist:
835 * @container: a #GtkContainer
836 * @child: a widget which is a child of @container
837 * @first_property_name: the name of the first property to set
838 * @var_args: a %NULL-terminated list of property names and values, starting
839 * with @first_prop_name
841 * Sets one or more child properties for @child and @container.
844 gtk_container_child_set_valist (GtkContainer *container,
846 const gchar *first_property_name,
849 GObjectNotifyQueue *nqueue;
852 g_return_if_fail (GTK_IS_CONTAINER (container));
853 g_return_if_fail (GTK_IS_WIDGET (child));
854 g_return_if_fail (gtk_widget_get_parent (child) == GTK_WIDGET (container));
856 g_object_ref (container);
857 g_object_ref (child);
859 nqueue = g_object_notify_queue_freeze (G_OBJECT (child), _gtk_widget_child_property_notify_context);
860 name = first_property_name;
863 GValue value = { 0, };
865 GParamSpec *pspec = g_param_spec_pool_lookup (_gtk_widget_child_property_pool,
867 G_OBJECT_TYPE (container),
871 g_warning ("%s: container class `%s' has no child property named `%s'",
873 G_OBJECT_TYPE_NAME (container),
877 if (!(pspec->flags & G_PARAM_WRITABLE))
879 g_warning ("%s: child property `%s' of container class `%s' is not writable",
882 G_OBJECT_TYPE_NAME (container));
885 g_value_init (&value, G_PARAM_SPEC_VALUE_TYPE (pspec));
886 G_VALUE_COLLECT (&value, var_args, 0, &error);
889 g_warning ("%s: %s", G_STRLOC, error);
892 /* we purposely leak the value here, it might not be
893 * in a sane state if an error condition occoured
897 container_set_child_property (container, child, pspec, &value, nqueue);
898 g_value_unset (&value);
899 name = va_arg (var_args, gchar*);
901 g_object_notify_queue_thaw (G_OBJECT (child), nqueue);
903 g_object_unref (container);
904 g_object_unref (child);
908 * gtk_container_child_set_property:
909 * @container: a #GtkContainer
910 * @child: a widget which is a child of @container
911 * @property_name: the name of the property to set
912 * @value: the value to set the property to
914 * Sets a child property for @child and @container.
917 gtk_container_child_set_property (GtkContainer *container,
919 const gchar *property_name,
922 GObjectNotifyQueue *nqueue;
925 g_return_if_fail (GTK_IS_CONTAINER (container));
926 g_return_if_fail (GTK_IS_WIDGET (child));
927 g_return_if_fail (gtk_widget_get_parent (child) == GTK_WIDGET (container));
928 g_return_if_fail (property_name != NULL);
929 g_return_if_fail (G_IS_VALUE (value));
931 g_object_ref (container);
932 g_object_ref (child);
934 nqueue = g_object_notify_queue_freeze (G_OBJECT (child), _gtk_widget_child_property_notify_context);
935 pspec = g_param_spec_pool_lookup (_gtk_widget_child_property_pool, property_name,
936 G_OBJECT_TYPE (container), TRUE);
938 g_warning ("%s: container class `%s' has no child property named `%s'",
940 G_OBJECT_TYPE_NAME (container),
942 else if (!(pspec->flags & G_PARAM_WRITABLE))
943 g_warning ("%s: child property `%s' of container class `%s' is not writable",
946 G_OBJECT_TYPE_NAME (container));
949 container_set_child_property (container, child, pspec, value, nqueue);
951 g_object_notify_queue_thaw (G_OBJECT (child), nqueue);
952 g_object_unref (container);
953 g_object_unref (child);
957 * gtk_container_add_with_properties:
958 * @container: a #GtkContainer
959 * @widget: a widget to be placed inside @container
960 * @first_prop_name: the name of the first child property to set
961 * @Varargs: a %NULL-terminated list of property names and values, starting
962 * with @first_prop_name
964 * Adds @widget to @container, setting child properties at the same time.
965 * See gtk_container_add() and gtk_container_child_set() for more details.
968 gtk_container_add_with_properties (GtkContainer *container,
970 const gchar *first_prop_name,
973 g_return_if_fail (GTK_IS_CONTAINER (container));
974 g_return_if_fail (GTK_IS_WIDGET (widget));
975 g_return_if_fail (gtk_widget_get_parent (widget) == NULL);
977 g_object_ref (container);
978 g_object_ref (widget);
979 gtk_widget_freeze_child_notify (widget);
981 g_signal_emit (container, container_signals[ADD], 0, widget);
982 if (gtk_widget_get_parent (widget))
986 va_start (var_args, first_prop_name);
987 gtk_container_child_set_valist (container, widget, first_prop_name, var_args);
991 gtk_widget_thaw_child_notify (widget);
992 g_object_unref (widget);
993 g_object_unref (container);
997 * gtk_container_child_set:
998 * @container: a #GtkContainer
999 * @child: a widget which is a child of @container
1000 * @first_prop_name: the name of the first property to set
1001 * @Varargs: a %NULL-terminated list of property names and values, starting
1002 * with @first_prop_name
1004 * Sets one or more child properties for @child and @container.
1007 gtk_container_child_set (GtkContainer *container,
1009 const gchar *first_prop_name,
1014 g_return_if_fail (GTK_IS_CONTAINER (container));
1015 g_return_if_fail (GTK_IS_WIDGET (child));
1016 g_return_if_fail (gtk_widget_get_parent (child) == GTK_WIDGET (container));
1018 va_start (var_args, first_prop_name);
1019 gtk_container_child_set_valist (container, child, first_prop_name, var_args);
1024 * gtk_container_child_get:
1025 * @container: a #GtkContainer
1026 * @child: a widget which is a child of @container
1027 * @first_prop_name: the name of the first property to get
1028 * @Varargs: return location for the first property, followed
1029 * optionally by more name/return location pairs, followed by %NULL
1031 * Gets the values of one or more child properties for @child and @container.
1034 gtk_container_child_get (GtkContainer *container,
1036 const gchar *first_prop_name,
1041 g_return_if_fail (GTK_IS_CONTAINER (container));
1042 g_return_if_fail (GTK_IS_WIDGET (child));
1043 g_return_if_fail (gtk_widget_get_parent (child) == GTK_WIDGET (container));
1045 va_start (var_args, first_prop_name);
1046 gtk_container_child_get_valist (container, child, first_prop_name, var_args);
1051 * gtk_container_class_install_child_property:
1052 * @cclass: a #GtkContainerClass
1053 * @property_id: the id for the property
1054 * @pspec: the #GParamSpec for the property
1056 * Installs a child property on a container class.
1059 gtk_container_class_install_child_property (GtkContainerClass *cclass,
1063 g_return_if_fail (GTK_IS_CONTAINER_CLASS (cclass));
1064 g_return_if_fail (G_IS_PARAM_SPEC (pspec));
1065 if (pspec->flags & G_PARAM_WRITABLE)
1066 g_return_if_fail (cclass->set_child_property != NULL);
1067 if (pspec->flags & G_PARAM_READABLE)
1068 g_return_if_fail (cclass->get_child_property != NULL);
1069 g_return_if_fail (property_id > 0);
1070 g_return_if_fail (PARAM_SPEC_PARAM_ID (pspec) == 0); /* paranoid */
1071 if (pspec->flags & (G_PARAM_CONSTRUCT | G_PARAM_CONSTRUCT_ONLY))
1072 g_return_if_fail ((pspec->flags & (G_PARAM_CONSTRUCT | G_PARAM_CONSTRUCT_ONLY)) == 0);
1074 if (g_param_spec_pool_lookup (_gtk_widget_child_property_pool, pspec->name, G_OBJECT_CLASS_TYPE (cclass), FALSE))
1076 g_warning (G_STRLOC ": class `%s' already contains a child property named `%s'",
1077 G_OBJECT_CLASS_NAME (cclass),
1081 g_param_spec_ref (pspec);
1082 g_param_spec_sink (pspec);
1083 PARAM_SPEC_SET_PARAM_ID (pspec, property_id);
1084 g_param_spec_pool_insert (_gtk_widget_child_property_pool, pspec, G_OBJECT_CLASS_TYPE (cclass));
1088 * gtk_container_class_find_child_property:
1089 * @cclass: a #GtkContainerClass
1090 * @property_name: the name of the child property to find
1091 * @returns: (allow-none): the #GParamSpec of the child property or %NULL if @class has no
1092 * child property with that name.
1094 * Finds a child property of a container class by name.
1097 gtk_container_class_find_child_property (GObjectClass *cclass,
1098 const gchar *property_name)
1100 g_return_val_if_fail (GTK_IS_CONTAINER_CLASS (cclass), NULL);
1101 g_return_val_if_fail (property_name != NULL, NULL);
1103 return g_param_spec_pool_lookup (_gtk_widget_child_property_pool,
1105 G_OBJECT_CLASS_TYPE (cclass),
1110 * gtk_container_class_list_child_properties:
1111 * @cclass: a #GtkContainerClass
1112 * @n_properties: location to return the number of child properties found
1113 * @returns: a newly allocated %NULL-terminated array of #GParamSpec*.
1114 * The array must be freed with g_free().
1116 * Returns all child properties of a container class.
1119 gtk_container_class_list_child_properties (GObjectClass *cclass,
1120 guint *n_properties)
1122 GParamSpec **pspecs;
1125 g_return_val_if_fail (GTK_IS_CONTAINER_CLASS (cclass), NULL);
1127 pspecs = g_param_spec_pool_list (_gtk_widget_child_property_pool,
1128 G_OBJECT_CLASS_TYPE (cclass),
1137 gtk_container_add_unimplemented (GtkContainer *container,
1140 g_warning ("GtkContainerClass::add not implemented for `%s'", g_type_name (G_TYPE_FROM_INSTANCE (container)));
1144 gtk_container_remove_unimplemented (GtkContainer *container,
1147 g_warning ("GtkContainerClass::remove not implemented for `%s'", g_type_name (G_TYPE_FROM_INSTANCE (container)));
1151 gtk_container_init (GtkContainer *container)
1153 GtkContainerPrivate *priv;
1155 container->priv = G_TYPE_INSTANCE_GET_PRIVATE (container,
1157 GtkContainerPrivate);
1158 priv = container->priv;
1160 priv->focus_child = NULL;
1161 priv->border_width = 0;
1162 priv->need_resize = FALSE;
1163 priv->resize_mode = GTK_RESIZE_PARENT;
1164 priv->reallocate_redraws = FALSE;
1168 gtk_container_destroy (GtkWidget *widget)
1170 GtkContainer *container = GTK_CONTAINER (widget);
1171 GtkContainerPrivate *priv = container->priv;
1173 if (_gtk_widget_get_resize_pending (GTK_WIDGET (container)))
1174 _gtk_container_dequeue_resize_handler (container);
1176 if (priv->focus_child)
1178 g_object_unref (priv->focus_child);
1179 priv->focus_child = NULL;
1182 /* do this before walking child widgets, to avoid
1183 * removing children from focus chain one by one.
1185 if (priv->has_focus_chain)
1186 gtk_container_unset_focus_chain (container);
1188 gtk_container_foreach (container, (GtkCallback) gtk_widget_destroy, NULL);
1190 GTK_WIDGET_CLASS (parent_class)->destroy (widget);
1194 gtk_container_set_property (GObject *object,
1196 const GValue *value,
1199 GtkContainer *container = GTK_CONTAINER (object);
1203 case PROP_BORDER_WIDTH:
1204 gtk_container_set_border_width (container, g_value_get_uint (value));
1206 case PROP_RESIZE_MODE:
1207 gtk_container_set_resize_mode (container, g_value_get_enum (value));
1210 gtk_container_add (container, GTK_WIDGET (g_value_get_object (value)));
1213 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
1219 gtk_container_get_property (GObject *object,
1224 GtkContainer *container = GTK_CONTAINER (object);
1225 GtkContainerPrivate *priv = container->priv;
1229 case PROP_BORDER_WIDTH:
1230 g_value_set_uint (value, priv->border_width);
1232 case PROP_RESIZE_MODE:
1233 g_value_set_enum (value, priv->resize_mode);
1236 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
1242 * gtk_container_set_border_width:
1243 * @container: a #GtkContainer
1244 * @border_width: amount of blank space to leave <emphasis>outside</emphasis>
1245 * the container. Valid values are in the range 0-65535 pixels.
1247 * Sets the border width of the container.
1249 * The border width of a container is the amount of space to leave
1250 * around the outside of the container. The only exception to this is
1251 * #GtkWindow; because toplevel windows can't leave space outside,
1252 * they leave the space inside. The border is added on all sides of
1253 * the container. To add space to only one side, one approach is to
1254 * create a #GtkAlignment widget, call gtk_widget_set_size_request()
1255 * to give it a size, and place it on the side of the container as
1259 gtk_container_set_border_width (GtkContainer *container,
1262 GtkContainerPrivate *priv;
1264 g_return_if_fail (GTK_IS_CONTAINER (container));
1266 priv = container->priv;
1268 if (priv->border_width != border_width)
1270 priv->border_width = border_width;
1271 g_object_notify (G_OBJECT (container), "border-width");
1273 if (gtk_widget_get_realized (GTK_WIDGET (container)))
1274 gtk_widget_queue_resize (GTK_WIDGET (container));
1279 * gtk_container_get_border_width:
1280 * @container: a #GtkContainer
1282 * Retrieves the border width of the container. See
1283 * gtk_container_set_border_width().
1285 * Return value: the current border width
1288 gtk_container_get_border_width (GtkContainer *container)
1290 g_return_val_if_fail (GTK_IS_CONTAINER (container), 0);
1292 return container->priv->border_width;
1296 * gtk_container_add:
1297 * @container: a #GtkContainer
1298 * @widget: a widget to be placed inside @container
1300 * Adds @widget to @container. Typically used for simple containers
1301 * such as #GtkWindow, #GtkFrame, or #GtkButton; for more complicated
1302 * layout containers such as #GtkBox or #GtkTable, this function will
1303 * pick default packing parameters that may not be correct. So
1304 * consider functions such as gtk_box_pack_start() and
1305 * gtk_table_attach() as an alternative to gtk_container_add() in
1306 * those cases. A widget may be added to only one container at a time;
1307 * you can't place the same widget inside two different containers.
1310 gtk_container_add (GtkContainer *container,
1315 g_return_if_fail (GTK_IS_CONTAINER (container));
1316 g_return_if_fail (GTK_IS_WIDGET (widget));
1318 parent = gtk_widget_get_parent (widget);
1322 g_warning ("Attempting to add a widget with type %s to a container of "
1323 "type %s, but the widget is already inside a container of type %s, "
1324 "the GTK+ FAQ at http://library.gnome.org/devel/gtk-faq/stable/ "
1325 "explains how to reparent a widget.",
1326 g_type_name (G_OBJECT_TYPE (widget)),
1327 g_type_name (G_OBJECT_TYPE (container)),
1328 g_type_name (G_OBJECT_TYPE (parent)));
1332 g_signal_emit (container, container_signals[ADD], 0, widget);
1336 * gtk_container_remove:
1337 * @container: a #GtkContainer
1338 * @widget: a current child of @container
1340 * Removes @widget from @container. @widget must be inside @container.
1341 * Note that @container will own a reference to @widget, and that this
1342 * may be the last reference held; so removing a widget from its
1343 * container can destroy that widget. If you want to use @widget
1344 * again, you need to add a reference to it while it's not inside
1345 * a container, using g_object_ref(). If you don't want to use @widget
1346 * again it's usually more efficient to simply destroy it directly
1347 * using gtk_widget_destroy() since this will remove it from the
1348 * container and help break any circular reference count cycles.
1351 gtk_container_remove (GtkContainer *container,
1354 g_return_if_fail (GTK_IS_CONTAINER (container));
1355 g_return_if_fail (GTK_IS_WIDGET (widget));
1356 g_return_if_fail (gtk_widget_get_parent (widget) == GTK_WIDGET (container));
1358 g_signal_emit (container, container_signals[REMOVE], 0, widget);
1362 _gtk_container_dequeue_resize_handler (GtkContainer *container)
1364 g_return_if_fail (GTK_IS_CONTAINER (container));
1365 g_return_if_fail (_gtk_widget_get_resize_pending (GTK_WIDGET (container)));
1367 container_resize_queue = g_slist_remove (container_resize_queue, container);
1368 _gtk_widget_set_resize_pending (GTK_WIDGET (container), FALSE);
1372 * gtk_container_set_resize_mode:
1373 * @container: a #GtkContainer
1374 * @resize_mode: the new resize mode
1376 * Sets the resize mode for the container.
1378 * The resize mode of a container determines whether a resize request
1379 * will be passed to the container's parent, queued for later execution
1380 * or executed immediately.
1383 gtk_container_set_resize_mode (GtkContainer *container,
1384 GtkResizeMode resize_mode)
1386 GtkContainerPrivate *priv;
1388 g_return_if_fail (GTK_IS_CONTAINER (container));
1389 g_return_if_fail (resize_mode <= GTK_RESIZE_IMMEDIATE);
1391 priv = container->priv;
1393 if (gtk_widget_is_toplevel (GTK_WIDGET (container)) &&
1394 resize_mode == GTK_RESIZE_PARENT)
1396 resize_mode = GTK_RESIZE_QUEUE;
1399 if (priv->resize_mode != resize_mode)
1401 priv->resize_mode = resize_mode;
1403 gtk_widget_queue_resize (GTK_WIDGET (container));
1404 g_object_notify (G_OBJECT (container), "resize-mode");
1409 * gtk_container_get_resize_mode:
1410 * @container: a #GtkContainer
1412 * Returns the resize mode for the container. See
1413 * gtk_container_set_resize_mode ().
1415 * Return value: the current resize mode
1418 gtk_container_get_resize_mode (GtkContainer *container)
1420 g_return_val_if_fail (GTK_IS_CONTAINER (container), GTK_RESIZE_PARENT);
1422 return container->priv->resize_mode;
1426 * gtk_container_set_reallocate_redraws:
1427 * @container: a #GtkContainer
1428 * @needs_redraws: the new value for the container's @reallocate_redraws flag
1430 * Sets the @reallocate_redraws flag of the container to the given value.
1432 * Containers requesting reallocation redraws get automatically
1433 * redrawn if any of their children changed allocation.
1436 gtk_container_set_reallocate_redraws (GtkContainer *container,
1437 gboolean needs_redraws)
1439 g_return_if_fail (GTK_IS_CONTAINER (container));
1441 container->priv->reallocate_redraws = needs_redraws ? TRUE : FALSE;
1444 static GtkContainer*
1445 gtk_container_get_resize_container (GtkContainer *container)
1448 GtkWidget *widget = GTK_WIDGET (container);
1450 while ((parent = gtk_widget_get_parent (widget)))
1453 if (GTK_IS_RESIZE_CONTAINER (widget))
1457 return GTK_IS_RESIZE_CONTAINER (widget) ? (GtkContainer*) widget : NULL;
1461 gtk_container_idle_sizer (gpointer data)
1463 /* we may be invoked with a container_resize_queue of NULL, because
1464 * queue_resize could have been adding an extra idle function while
1465 * the queue still got processed. we better just ignore such case
1466 * than trying to explicitely work around them with some extra flags,
1467 * since it doesn't cause any actual harm.
1469 while (container_resize_queue)
1474 slist = container_resize_queue;
1475 container_resize_queue = slist->next;
1476 widget = slist->data;
1477 g_slist_free_1 (slist);
1479 _gtk_widget_set_resize_pending (widget, FALSE);
1480 gtk_container_check_resize (GTK_CONTAINER (widget));
1483 gdk_window_process_all_updates ();
1489 _gtk_container_queue_resize (GtkContainer *container)
1491 GtkContainerPrivate *priv;
1492 GtkContainer *resize_container;
1496 g_return_if_fail (GTK_IS_CONTAINER (container));
1498 priv = container->priv;
1499 widget = GTK_WIDGET (container);
1501 resize_container = gtk_container_get_resize_container (container);
1505 _gtk_widget_set_alloc_needed (widget, TRUE);
1506 _gtk_widget_set_width_request_needed (widget, TRUE);
1507 _gtk_widget_set_height_request_needed (widget, TRUE);
1509 if ((resize_container && widget == GTK_WIDGET (resize_container)) ||
1510 !(parent = gtk_widget_get_parent (widget)))
1516 if (resize_container)
1518 if (gtk_widget_get_visible (GTK_WIDGET (resize_container)) &&
1519 (gtk_widget_is_toplevel (GTK_WIDGET (resize_container)) ||
1520 gtk_widget_get_realized (GTK_WIDGET (resize_container))))
1522 switch (resize_container->priv->resize_mode)
1524 case GTK_RESIZE_QUEUE:
1525 if (!_gtk_widget_get_resize_pending (GTK_WIDGET (resize_container)))
1527 _gtk_widget_set_resize_pending (GTK_WIDGET (resize_container), TRUE);
1528 if (container_resize_queue == NULL)
1529 gdk_threads_add_idle_full (GTK_PRIORITY_RESIZE,
1530 gtk_container_idle_sizer,
1532 container_resize_queue = g_slist_prepend (container_resize_queue, resize_container);
1536 case GTK_RESIZE_IMMEDIATE:
1537 gtk_container_check_resize (resize_container);
1540 case GTK_RESIZE_PARENT:
1541 g_assert_not_reached ();
1547 /* we need to let hidden resize containers know that something
1548 * changed while they where hidden (currently only evaluated by
1551 resize_container->priv->need_resize = TRUE;
1557 gtk_container_check_resize (GtkContainer *container)
1559 g_return_if_fail (GTK_IS_CONTAINER (container));
1561 g_signal_emit (container, container_signals[CHECK_RESIZE], 0);
1565 gtk_container_real_check_resize (GtkContainer *container)
1567 GtkWidget *widget = GTK_WIDGET (container);
1568 GtkAllocation allocation;
1569 GtkRequisition requisition;
1571 gtk_widget_get_preferred_size (widget,
1572 &requisition, NULL);
1573 gtk_widget_get_allocation (widget, &allocation);
1575 if (requisition.width > allocation.width ||
1576 requisition.height > allocation.height)
1578 if (GTK_IS_RESIZE_CONTAINER (container))
1580 gtk_widget_size_allocate (widget, &allocation);
1581 gtk_widget_set_allocation (widget, &allocation);
1584 gtk_widget_queue_resize (widget);
1588 gtk_container_resize_children (container);
1592 /* The container hasn't changed size but one of its children
1593 * queued a resize request. Which means that the allocation
1594 * is not sufficient for the requisition of some child.
1595 * We've already performed a size request at this point,
1596 * so we simply need to reallocate and let the allocation
1597 * trickle down via GTK_WIDGET_ALLOC_NEEDED flags.
1600 gtk_container_resize_children (GtkContainer *container)
1602 GtkAllocation allocation;
1605 /* resizing invariants:
1606 * toplevels have *always* resize_mode != GTK_RESIZE_PARENT set.
1607 * containers that have an idle sizer pending must be flagged with
1610 g_return_if_fail (GTK_IS_CONTAINER (container));
1612 widget = GTK_WIDGET (container);
1613 gtk_widget_get_allocation (widget, &allocation);
1615 gtk_widget_size_allocate (widget, &allocation);
1616 gtk_widget_set_allocation (widget, &allocation);
1620 gtk_container_adjust_size_request (GtkWidget *widget,
1621 GtkOrientation orientation,
1626 GtkContainer *container;
1628 container = GTK_CONTAINER (widget);
1630 if (GTK_CONTAINER_GET_CLASS (widget)->handle_border_width)
1634 border_width = container->priv->border_width;
1636 *minimum_size += border_width * 2;
1637 *natural_size += border_width * 2;
1640 /* chain up last so gtk_widget_set_size_request() values
1641 * will have a chance to overwrite our border width.
1643 parent_class->adjust_size_request (widget, orientation, for_size,
1644 minimum_size, natural_size);
1648 gtk_container_adjust_size_allocation (GtkWidget *widget,
1649 GtkAllocation *allocation)
1651 GtkContainer *container;
1654 container = GTK_CONTAINER (widget);
1656 parent_class->adjust_size_allocation (widget, allocation);
1658 if (!GTK_CONTAINER_GET_CLASS (widget)->handle_border_width)
1661 border_width = container->priv->border_width;
1663 allocation->width -= border_width * 2;
1664 allocation->height -= border_width * 2;
1666 /* If we get a pathological too-small allocation to hold
1667 * even the border width, leave all allocation to the actual
1668 * widget, and leave x,y unchanged. (GtkWidget's min size is
1669 * 1x1 if you're wondering why <1 and not <0)
1671 * As long as we have space, set x,y properly.
1674 if (allocation->width < 1)
1676 allocation->width += border_width * 2;
1680 allocation->x += border_width;
1683 if (allocation->height < 1)
1685 allocation->height += border_width * 2;
1689 allocation->y += border_width;
1694 * gtk_container_class_handle_border_width:
1695 * @klass: the class struct of a #GtkContainer subclass
1697 * Modifies a subclass of #GtkContainerClass to automatically add and
1698 * remove the border-width setting on GtkContainer. This allows the
1699 * subclass to ignore the border width in its size request and
1700 * allocate methods. The intent is for a subclass to invoke this
1701 * in its class_init function.
1703 * gtk_container_class_handle_border_width() is necessary because it
1704 * would break API too badly to make this behavior the default. So
1705 * subclasses must "opt in" to the parent class handling border_width
1709 gtk_container_class_handle_border_width (GtkContainerClass *klass)
1711 g_return_if_fail (GTK_IS_CONTAINER_CLASS (klass));
1713 klass->handle_border_width = TRUE;
1717 * gtk_container_forall:
1718 * @container: a #GtkContainer
1719 * @callback: a callback
1720 * @callback_data: callback user data
1722 * Invokes @callback on each child of @container, including children
1723 * that are considered "internal" (implementation details of the
1724 * container). "Internal" children generally weren't added by the user
1725 * of the container, but were added by the container implementation
1726 * itself. Most applications should use gtk_container_foreach(),
1727 * rather than gtk_container_forall().
1730 gtk_container_forall (GtkContainer *container,
1731 GtkCallback callback,
1732 gpointer callback_data)
1734 GtkContainerClass *class;
1736 g_return_if_fail (GTK_IS_CONTAINER (container));
1737 g_return_if_fail (callback != NULL);
1739 class = GTK_CONTAINER_GET_CLASS (container);
1742 class->forall (container, TRUE, callback, callback_data);
1746 * gtk_container_foreach:
1747 * @container: a #GtkContainer
1748 * @callback: (scope call): a callback
1749 * @callback_data: callback user data
1751 * Invokes @callback on each non-internal child of @container. See
1752 * gtk_container_forall() for details on what constitutes an
1753 * "internal" child. Most applications should use
1754 * gtk_container_foreach(), rather than gtk_container_forall().
1757 gtk_container_foreach (GtkContainer *container,
1758 GtkCallback callback,
1759 gpointer callback_data)
1761 GtkContainerClass *class;
1763 g_return_if_fail (GTK_IS_CONTAINER (container));
1764 g_return_if_fail (callback != NULL);
1766 class = GTK_CONTAINER_GET_CLASS (container);
1769 class->forall (container, FALSE, callback, callback_data);
1773 * gtk_container_set_focus_child:
1774 * @container: a #GtkContainer
1775 * @child: (allow-none): a #GtkWidget, or %NULL
1777 * Sets, or unsets if @child is %NULL, the focused child of @container.
1779 * This function emits the GtkContainer::set_focus_child signal of
1780 * @container. Implementations of #GtkContainer can override the
1781 * default behaviour by overriding the class closure of this signal.
1783 * This is function is mostly meant to be used by widgets. Applications can use
1784 * gtk_widget_grab_focus() to manualy set the focus to a specific widget.
1787 gtk_container_set_focus_child (GtkContainer *container,
1790 g_return_if_fail (GTK_IS_CONTAINER (container));
1792 g_return_if_fail (GTK_IS_WIDGET (child));
1794 g_signal_emit (container, container_signals[SET_FOCUS_CHILD], 0, child);
1798 * gtk_container_get_focus_child:
1799 * @container: a #GtkContainer
1801 * Returns the current focus child widget inside @container. This is not the
1802 * currently focused widget. That can be obtained by calling
1803 * gtk_window_get_focus().
1805 * Returns: The child widget which will recieve the focus inside @container when
1806 * the @conatiner is focussed, or %NULL if none is set.
1811 gtk_container_get_focus_child (GtkContainer *container)
1813 g_return_val_if_fail (GTK_IS_CONTAINER (container), NULL);
1815 return container->priv->focus_child;
1819 * gtk_container_get_children:
1820 * @container: a #GtkContainer
1822 * Returns the container's non-internal children. See
1823 * gtk_container_forall() for details on what constitutes an "internal" child.
1825 * Return value: (element-type GtkWidget) (transfer container): a newly-allocated list of the container's non-internal children.
1828 gtk_container_get_children (GtkContainer *container)
1830 GList *children = NULL;
1832 gtk_container_foreach (container,
1833 gtk_container_children_callback,
1836 return g_list_reverse (children);
1840 gtk_container_child_position_callback (GtkWidget *widget,
1841 gpointer client_data)
1847 } *data = client_data;
1850 if (data->child == widget)
1851 data->index = data->i;
1855 gtk_container_child_default_composite_name (GtkContainer *container,
1865 /* fallback implementation */
1869 gtk_container_forall (container,
1870 gtk_container_child_position_callback,
1873 name = g_strdup_printf ("%s-%u",
1874 g_type_name (G_TYPE_FROM_INSTANCE (child)),
1881 _gtk_container_child_composite_name (GtkContainer *container,
1884 gboolean composite_child;
1886 g_return_val_if_fail (GTK_IS_CONTAINER (container), NULL);
1887 g_return_val_if_fail (GTK_IS_WIDGET (child), NULL);
1888 g_return_val_if_fail (gtk_widget_get_parent (child) == GTK_WIDGET (container), NULL);
1890 g_object_get (child, "composite-child", &composite_child, NULL);
1891 if (composite_child)
1893 static GQuark quark_composite_name = 0;
1896 if (!quark_composite_name)
1897 quark_composite_name = g_quark_from_static_string ("gtk-composite-name");
1899 name = g_object_get_qdata (G_OBJECT (child), quark_composite_name);
1902 GtkContainerClass *class;
1904 class = GTK_CONTAINER_GET_CLASS (container);
1905 if (class->composite_name)
1906 name = class->composite_name (container, child);
1909 name = g_strdup (name);
1918 gtk_container_real_set_focus_child (GtkContainer *container,
1921 GtkContainerPrivate *priv;
1923 g_return_if_fail (GTK_IS_CONTAINER (container));
1924 g_return_if_fail (child == NULL || GTK_IS_WIDGET (child));
1926 priv = container->priv;
1928 if (child != priv->focus_child)
1930 if (priv->focus_child)
1931 g_object_unref (priv->focus_child);
1932 priv->focus_child = child;
1933 if (priv->focus_child)
1934 g_object_ref (priv->focus_child);
1938 /* check for h/v adjustments
1940 if (priv->focus_child)
1942 GtkAdjustment *hadj;
1943 GtkAdjustment *vadj;
1944 GtkAllocation allocation;
1945 GtkWidget *focus_child;
1948 hadj = g_object_get_qdata (G_OBJECT (container), hadjustment_key_id);
1949 vadj = g_object_get_qdata (G_OBJECT (container), vadjustment_key_id);
1953 focus_child = priv->focus_child;
1954 while (GTK_IS_CONTAINER (focus_child) && gtk_container_get_focus_child (GTK_CONTAINER (focus_child)))
1956 focus_child = gtk_container_get_focus_child (GTK_CONTAINER (focus_child));
1959 gtk_widget_translate_coordinates (focus_child, priv->focus_child,
1962 gtk_widget_get_allocation (priv->focus_child, &allocation);
1966 gtk_widget_get_allocation (focus_child, &allocation);
1969 gtk_adjustment_clamp_page (vadj, y, y + allocation.height);
1972 gtk_adjustment_clamp_page (hadj, x, x + allocation.width);
1978 get_focus_chain (GtkContainer *container)
1980 return g_object_get_data (G_OBJECT (container), "gtk-container-focus-chain");
1983 /* same as gtk_container_get_children, except it includes internals
1986 gtk_container_get_all_children (GtkContainer *container)
1988 GList *children = NULL;
1990 gtk_container_forall (container,
1991 gtk_container_children_callback,
1998 gtk_container_focus (GtkWidget *widget,
1999 GtkDirectionType direction)
2002 GList *sorted_children;
2004 GtkContainer *container;
2005 GtkContainerPrivate *priv;
2007 g_return_val_if_fail (GTK_IS_CONTAINER (widget), FALSE);
2009 container = GTK_CONTAINER (widget);
2010 priv = container->priv;
2014 if (gtk_widget_get_can_focus (widget))
2016 if (!gtk_widget_has_focus (widget))
2018 gtk_widget_grab_focus (widget);
2024 /* Get a list of the containers children, allowing focus
2025 * chain to override.
2027 if (priv->has_focus_chain)
2028 children = g_list_copy (get_focus_chain (container));
2030 children = gtk_container_get_all_children (container);
2032 if (priv->has_focus_chain &&
2033 (direction == GTK_DIR_TAB_FORWARD ||
2034 direction == GTK_DIR_TAB_BACKWARD))
2036 sorted_children = g_list_copy (children);
2038 if (direction == GTK_DIR_TAB_BACKWARD)
2039 sorted_children = g_list_reverse (sorted_children);
2042 sorted_children = _gtk_container_focus_sort (container, children, direction, NULL);
2044 return_val = gtk_container_focus_move (container, sorted_children, direction);
2046 g_list_free (sorted_children);
2047 g_list_free (children);
2054 tab_compare (gconstpointer a,
2058 GtkAllocation child1_allocation, child2_allocation;
2059 const GtkWidget *child1 = a;
2060 const GtkWidget *child2 = b;
2061 GtkTextDirection text_direction = GPOINTER_TO_INT (data);
2063 gtk_widget_get_allocation ((GtkWidget *) child1, &child1_allocation);
2064 gtk_widget_get_allocation ((GtkWidget *) child2, &child2_allocation);
2066 gint y1 = child1_allocation.y + child1_allocation.height / 2;
2067 gint y2 = child2_allocation.y + child2_allocation.height / 2;
2071 gint x1 = child1_allocation.x + child1_allocation.width / 2;
2072 gint x2 = child2_allocation.x + child2_allocation.width / 2;
2074 if (text_direction == GTK_TEXT_DIR_RTL)
2075 return (x1 < x2) ? 1 : ((x1 == x2) ? 0 : -1);
2077 return (x1 < x2) ? -1 : ((x1 == x2) ? 0 : 1);
2080 return (y1 < y2) ? -1 : 1;
2084 gtk_container_focus_sort_tab (GtkContainer *container,
2086 GtkDirectionType direction,
2087 GtkWidget *old_focus)
2089 GtkTextDirection text_direction = gtk_widget_get_direction (GTK_WIDGET (container));
2090 children = g_list_sort_with_data (children, tab_compare, GINT_TO_POINTER (text_direction));
2092 /* if we are going backwards then reverse the order
2095 if (direction == GTK_DIR_TAB_BACKWARD)
2096 children = g_list_reverse (children);
2101 /* Get coordinates of @widget's allocation with respect to
2102 * allocation of @container.
2105 get_allocation_coords (GtkContainer *container,
2107 GdkRectangle *allocation)
2109 gtk_widget_set_allocation (widget, allocation);
2111 return gtk_widget_translate_coordinates (widget, GTK_WIDGET (container),
2112 0, 0, &allocation->x, &allocation->y);
2115 /* Look for a child in @children that is intermediate between
2116 * the focus widget and container. This widget, if it exists,
2117 * acts as the starting widget for focus navigation.
2120 find_old_focus (GtkContainer *container,
2123 GList *tmp_list = children;
2126 GtkWidget *child = tmp_list->data;
2127 GtkWidget *widget = child;
2129 while (widget && widget != (GtkWidget *)container)
2133 parent = gtk_widget_get_parent (widget);
2135 if (parent && (gtk_container_get_focus_child (GTK_CONTAINER (parent)) != widget))
2144 tmp_list = tmp_list->next;
2151 old_focus_coords (GtkContainer *container,
2152 GdkRectangle *old_focus_rect)
2154 GtkWidget *widget = GTK_WIDGET (container);
2155 GtkWidget *toplevel = gtk_widget_get_toplevel (widget);
2156 GtkWidget *old_focus;
2158 if (GTK_IS_WINDOW (toplevel))
2160 old_focus = gtk_window_get_focus (GTK_WINDOW (toplevel));
2162 return get_allocation_coords (container, old_focus, old_focus_rect);
2168 typedef struct _CompareInfo CompareInfo;
2172 GtkContainer *container;
2179 up_down_compare (gconstpointer a,
2183 GdkRectangle allocation1;
2184 GdkRectangle allocation2;
2185 CompareInfo *compare = data;
2188 get_allocation_coords (compare->container, (GtkWidget *)a, &allocation1);
2189 get_allocation_coords (compare->container, (GtkWidget *)b, &allocation2);
2191 y1 = allocation1.y + allocation1.height / 2;
2192 y2 = allocation2.y + allocation2.height / 2;
2196 gint x1 = abs (allocation1.x + allocation1.width / 2 - compare->x);
2197 gint x2 = abs (allocation2.x + allocation2.width / 2 - compare->x);
2199 if (compare->reverse)
2200 return (x1 < x2) ? 1 : ((x1 == x2) ? 0 : -1);
2202 return (x1 < x2) ? -1 : ((x1 == x2) ? 0 : 1);
2205 return (y1 < y2) ? -1 : 1;
2209 gtk_container_focus_sort_up_down (GtkContainer *container,
2211 GtkDirectionType direction,
2212 GtkWidget *old_focus)
2214 CompareInfo compare;
2216 GdkRectangle old_allocation;
2218 compare.container = container;
2219 compare.reverse = (direction == GTK_DIR_UP);
2222 old_focus = find_old_focus (container, children);
2224 if (old_focus && get_allocation_coords (container, old_focus, &old_allocation))
2230 /* Delete widgets from list that don't match minimum criteria */
2232 compare_x1 = old_allocation.x;
2233 compare_x2 = old_allocation.x + old_allocation.width;
2235 if (direction == GTK_DIR_UP)
2236 compare_y = old_allocation.y;
2238 compare_y = old_allocation.y + old_allocation.height;
2240 tmp_list = children;
2243 GtkWidget *child = tmp_list->data;
2244 GList *next = tmp_list->next;
2245 gint child_x1, child_x2;
2246 GdkRectangle child_allocation;
2248 if (child != old_focus)
2250 if (get_allocation_coords (container, child, &child_allocation))
2252 child_x1 = child_allocation.x;
2253 child_x2 = child_allocation.x + child_allocation.width;
2255 if ((child_x2 <= compare_x1 || child_x1 >= compare_x2) /* No horizontal overlap */ ||
2256 (direction == GTK_DIR_DOWN && child_allocation.y + child_allocation.height < compare_y) || /* Not below */
2257 (direction == GTK_DIR_UP && child_allocation.y > compare_y)) /* Not above */
2259 children = g_list_delete_link (children, tmp_list);
2263 children = g_list_delete_link (children, tmp_list);
2269 compare.x = (compare_x1 + compare_x2) / 2;
2270 compare.y = old_allocation.y + old_allocation.height / 2;
2274 /* No old focus widget, need to figure out starting x,y some other way
2276 GtkAllocation allocation;
2277 GtkWidget *widget = GTK_WIDGET (container);
2278 GdkRectangle old_focus_rect;
2280 gtk_widget_get_allocation (widget, &allocation);
2282 if (old_focus_coords (container, &old_focus_rect))
2284 compare.x = old_focus_rect.x + old_focus_rect.width / 2;
2288 if (!gtk_widget_get_has_window (widget))
2289 compare.x = allocation.x + allocation.width / 2;
2291 compare.x = allocation.width / 2;
2294 if (!gtk_widget_get_has_window (widget))
2295 compare.y = (direction == GTK_DIR_DOWN) ? allocation.y : allocation.y + allocation.height;
2297 compare.y = (direction == GTK_DIR_DOWN) ? 0 : + allocation.height;
2300 children = g_list_sort_with_data (children, up_down_compare, &compare);
2302 if (compare.reverse)
2303 children = g_list_reverse (children);
2309 left_right_compare (gconstpointer a,
2313 GdkRectangle allocation1;
2314 GdkRectangle allocation2;
2315 CompareInfo *compare = data;
2318 get_allocation_coords (compare->container, (GtkWidget *)a, &allocation1);
2319 get_allocation_coords (compare->container, (GtkWidget *)b, &allocation2);
2321 x1 = allocation1.x + allocation1.width / 2;
2322 x2 = allocation2.x + allocation2.width / 2;
2326 gint y1 = abs (allocation1.y + allocation1.height / 2 - compare->y);
2327 gint y2 = abs (allocation2.y + allocation2.height / 2 - compare->y);
2329 if (compare->reverse)
2330 return (y1 < y2) ? 1 : ((y1 == y2) ? 0 : -1);
2332 return (y1 < y2) ? -1 : ((y1 == y2) ? 0 : 1);
2335 return (x1 < x2) ? -1 : 1;
2339 gtk_container_focus_sort_left_right (GtkContainer *container,
2341 GtkDirectionType direction,
2342 GtkWidget *old_focus)
2344 CompareInfo compare;
2346 GdkRectangle old_allocation;
2348 compare.container = container;
2349 compare.reverse = (direction == GTK_DIR_LEFT);
2352 old_focus = find_old_focus (container, children);
2354 if (old_focus && get_allocation_coords (container, old_focus, &old_allocation))
2360 /* Delete widgets from list that don't match minimum criteria */
2362 compare_y1 = old_allocation.y;
2363 compare_y2 = old_allocation.y + old_allocation.height;
2365 if (direction == GTK_DIR_LEFT)
2366 compare_x = old_allocation.x;
2368 compare_x = old_allocation.x + old_allocation.width;
2370 tmp_list = children;
2373 GtkWidget *child = tmp_list->data;
2374 GList *next = tmp_list->next;
2375 gint child_y1, child_y2;
2376 GdkRectangle child_allocation;
2378 if (child != old_focus)
2380 if (get_allocation_coords (container, child, &child_allocation))
2382 child_y1 = child_allocation.y;
2383 child_y2 = child_allocation.y + child_allocation.height;
2385 if ((child_y2 <= compare_y1 || child_y1 >= compare_y2) /* No vertical overlap */ ||
2386 (direction == GTK_DIR_RIGHT && child_allocation.x + child_allocation.width < compare_x) || /* Not to left */
2387 (direction == GTK_DIR_LEFT && child_allocation.x > compare_x)) /* Not to right */
2389 children = g_list_delete_link (children, tmp_list);
2393 children = g_list_delete_link (children, tmp_list);
2399 compare.y = (compare_y1 + compare_y2) / 2;
2400 compare.x = old_allocation.x + old_allocation.width / 2;
2404 /* No old focus widget, need to figure out starting x,y some other way
2406 GtkAllocation allocation;
2407 GtkWidget *widget = GTK_WIDGET (container);
2408 GdkRectangle old_focus_rect;
2410 gtk_widget_get_allocation (widget, &allocation);
2412 if (old_focus_coords (container, &old_focus_rect))
2414 compare.y = old_focus_rect.y + old_focus_rect.height / 2;
2418 if (!gtk_widget_get_has_window (widget))
2419 compare.y = allocation.y + allocation.height / 2;
2421 compare.y = allocation.height / 2;
2424 if (!gtk_widget_get_has_window (widget))
2425 compare.x = (direction == GTK_DIR_RIGHT) ? allocation.x : allocation.x + allocation.width;
2427 compare.x = (direction == GTK_DIR_RIGHT) ? 0 : allocation.width;
2430 children = g_list_sort_with_data (children, left_right_compare, &compare);
2432 if (compare.reverse)
2433 children = g_list_reverse (children);
2439 * gtk_container_focus_sort:
2440 * @container: a #GtkContainer
2441 * @children: a list of descendents of @container (they don't
2442 * have to be direct children)
2443 * @direction: focus direction
2444 * @old_focus: (allow-none): widget to use for the starting position, or %NULL
2445 * to determine this automatically.
2446 * (Note, this argument isn't used for GTK_DIR_TAB_*,
2447 * which is the only @direction we use currently,
2448 * so perhaps this argument should be removed)
2450 * Sorts @children in the correct order for focusing with
2451 * direction type @direction.
2453 * Return value: a copy of @children, sorted in correct focusing order,
2454 * with children that aren't suitable for focusing in this direction
2458 _gtk_container_focus_sort (GtkContainer *container,
2460 GtkDirectionType direction,
2461 GtkWidget *old_focus)
2463 GList *visible_children = NULL;
2467 if (gtk_widget_get_realized (children->data))
2468 visible_children = g_list_prepend (visible_children, children->data);
2469 children = children->next;
2474 case GTK_DIR_TAB_FORWARD:
2475 case GTK_DIR_TAB_BACKWARD:
2476 return gtk_container_focus_sort_tab (container, visible_children, direction, old_focus);
2479 return gtk_container_focus_sort_up_down (container, visible_children, direction, old_focus);
2482 return gtk_container_focus_sort_left_right (container, visible_children, direction, old_focus);
2485 g_assert_not_reached ();
2491 gtk_container_focus_move (GtkContainer *container,
2493 GtkDirectionType direction)
2495 GtkContainerPrivate *priv = container->priv;
2496 GtkWidget *focus_child;
2499 focus_child = priv->focus_child;
2503 child = children->data;
2504 children = children->next;
2511 if (focus_child == child)
2515 if (gtk_widget_child_focus (child, direction))
2519 else if (gtk_widget_is_drawable (child) &&
2520 gtk_widget_is_ancestor (child, GTK_WIDGET (container)))
2522 if (gtk_widget_child_focus (child, direction))
2532 gtk_container_children_callback (GtkWidget *widget,
2533 gpointer client_data)
2537 children = (GList**) client_data;
2538 *children = g_list_prepend (*children, widget);
2542 chain_widget_destroyed (GtkWidget *widget,
2545 GtkContainer *container;
2548 container = GTK_CONTAINER (user_data);
2550 chain = g_object_get_data (G_OBJECT (container),
2551 "gtk-container-focus-chain");
2553 chain = g_list_remove (chain, widget);
2555 g_signal_handlers_disconnect_by_func (widget,
2556 chain_widget_destroyed,
2559 g_object_set_data (G_OBJECT (container),
2560 I_("gtk-container-focus-chain"),
2565 * gtk_container_set_focus_chain:
2566 * @container: a #GtkContainer
2567 * @focusable_widgets: (transfer none) (element-type GtkWidget):
2568 * the new focus chain
2570 * Sets a focus chain, overriding the one computed automatically by GTK+.
2572 * In principle each widget in the chain should be a descendant of the
2573 * container, but this is not enforced by this method, since it's allowed
2574 * to set the focus chain before you pack the widgets, or have a widget
2575 * in the chain that isn't always packed. The necessary checks are done
2576 * when the focus chain is actually traversed.
2579 gtk_container_set_focus_chain (GtkContainer *container,
2580 GList *focusable_widgets)
2584 GtkContainerPrivate *priv;
2586 g_return_if_fail (GTK_IS_CONTAINER (container));
2588 priv = container->priv;
2590 if (priv->has_focus_chain)
2591 gtk_container_unset_focus_chain (container);
2593 priv->has_focus_chain = TRUE;
2596 tmp_list = focusable_widgets;
2597 while (tmp_list != NULL)
2599 g_return_if_fail (GTK_IS_WIDGET (tmp_list->data));
2601 /* In principle each widget in the chain should be a descendant
2602 * of the container, but we don't want to check that here, it's
2603 * expensive and also it's allowed to set the focus chain before
2604 * you pack the widgets, or have a widget in the chain that isn't
2605 * always packed. So we check for ancestor during actual traversal.
2608 chain = g_list_prepend (chain, tmp_list->data);
2610 g_signal_connect (tmp_list->data,
2612 G_CALLBACK (chain_widget_destroyed),
2615 tmp_list = g_list_next (tmp_list);
2618 chain = g_list_reverse (chain);
2620 g_object_set_data (G_OBJECT (container),
2621 I_("gtk-container-focus-chain"),
2626 * gtk_container_get_focus_chain:
2627 * @container: a #GtkContainer
2628 * @focusable_widgets: (element-type GtkWidget) (out) (transfer container): location
2629 * to store the focus chain of the
2630 * container, or %NULL. You should free this list
2631 * using g_list_free() when you are done with it, however
2632 * no additional reference count is added to the
2633 * individual widgets in the focus chain.
2635 * Retrieves the focus chain of the container, if one has been
2636 * set explicitly. If no focus chain has been explicitly
2637 * set, GTK+ computes the focus chain based on the positions
2638 * of the children. In that case, GTK+ stores %NULL in
2639 * @focusable_widgets and returns %FALSE.
2641 * Return value: %TRUE if the focus chain of the container
2642 * has been set explicitly.
2645 gtk_container_get_focus_chain (GtkContainer *container,
2646 GList **focus_chain)
2648 GtkContainerPrivate *priv;
2650 g_return_val_if_fail (GTK_IS_CONTAINER (container), FALSE);
2652 priv = container->priv;
2656 if (priv->has_focus_chain)
2657 *focus_chain = g_list_copy (get_focus_chain (container));
2659 *focus_chain = NULL;
2662 return priv->has_focus_chain;
2666 * gtk_container_unset_focus_chain:
2667 * @container: a #GtkContainer
2669 * Removes a focus chain explicitly set with gtk_container_set_focus_chain().
2672 gtk_container_unset_focus_chain (GtkContainer *container)
2674 GtkContainerPrivate *priv;
2676 g_return_if_fail (GTK_IS_CONTAINER (container));
2678 priv = container->priv;
2680 if (priv->has_focus_chain)
2685 chain = get_focus_chain (container);
2687 priv->has_focus_chain = FALSE;
2689 g_object_set_data (G_OBJECT (container),
2690 I_("gtk-container-focus-chain"),
2694 while (tmp_list != NULL)
2696 g_signal_handlers_disconnect_by_func (tmp_list->data,
2697 chain_widget_destroyed,
2700 tmp_list = g_list_next (tmp_list);
2703 g_list_free (chain);
2708 * gtk_container_set_focus_vadjustment:
2709 * @container: a #GtkContainer
2710 * @adjustment: an adjustment which should be adjusted when the focus
2711 * is moved among the descendents of @container
2713 * Hooks up an adjustment to focus handling in a container, so when a
2714 * child of the container is focused, the adjustment is scrolled to
2715 * show that widget. This function sets the vertical alignment. See
2716 * gtk_scrolled_window_get_vadjustment() for a typical way of obtaining
2717 * the adjustment and gtk_container_set_focus_hadjustment() for setting
2718 * the horizontal adjustment.
2720 * The adjustments have to be in pixel units and in the same coordinate
2721 * system as the allocation for immediate children of the container.
2724 gtk_container_set_focus_vadjustment (GtkContainer *container,
2725 GtkAdjustment *adjustment)
2727 g_return_if_fail (GTK_IS_CONTAINER (container));
2729 g_return_if_fail (GTK_IS_ADJUSTMENT (adjustment));
2732 g_object_ref (adjustment);
2734 g_object_set_qdata_full (G_OBJECT (container),
2741 * gtk_container_get_focus_vadjustment:
2742 * @container: a #GtkContainer
2744 * Retrieves the vertical focus adjustment for the container. See
2745 * gtk_container_set_focus_vadjustment().
2747 * Return value: (transfer none): the vertical focus adjustment, or %NULL if
2748 * none has been set.
2751 gtk_container_get_focus_vadjustment (GtkContainer *container)
2753 GtkAdjustment *vadjustment;
2755 g_return_val_if_fail (GTK_IS_CONTAINER (container), NULL);
2757 vadjustment = g_object_get_qdata (G_OBJECT (container), vadjustment_key_id);
2763 * gtk_container_set_focus_hadjustment:
2764 * @container: a #GtkContainer
2765 * @adjustment: an adjustment which should be adjusted when the focus is
2766 * moved among the descendents of @container
2768 * Hooks up an adjustment to focus handling in a container, so when a child
2769 * of the container is focused, the adjustment is scrolled to show that
2770 * widget. This function sets the horizontal alignment.
2771 * See gtk_scrolled_window_get_hadjustment() for a typical way of obtaining
2772 * the adjustment and gtk_container_set_focus_vadjustment() for setting
2773 * the vertical adjustment.
2775 * The adjustments have to be in pixel units and in the same coordinate
2776 * system as the allocation for immediate children of the container.
2779 gtk_container_set_focus_hadjustment (GtkContainer *container,
2780 GtkAdjustment *adjustment)
2782 g_return_if_fail (GTK_IS_CONTAINER (container));
2784 g_return_if_fail (GTK_IS_ADJUSTMENT (adjustment));
2787 g_object_ref (adjustment);
2789 g_object_set_qdata_full (G_OBJECT (container),
2796 * gtk_container_get_focus_hadjustment:
2797 * @container: a #GtkContainer
2799 * Retrieves the horizontal focus adjustment for the container. See
2800 * gtk_container_set_focus_hadjustment ().
2802 * Return value: (transfer none): the horizontal focus adjustment, or %NULL if
2803 * none has been set.
2806 gtk_container_get_focus_hadjustment (GtkContainer *container)
2808 GtkAdjustment *hadjustment;
2810 g_return_val_if_fail (GTK_IS_CONTAINER (container), NULL);
2812 hadjustment = g_object_get_qdata (G_OBJECT (container), hadjustment_key_id);
2819 gtk_container_show_all (GtkWidget *widget)
2821 g_return_if_fail (GTK_IS_CONTAINER (widget));
2823 gtk_container_foreach (GTK_CONTAINER (widget),
2824 (GtkCallback) gtk_widget_show_all,
2826 gtk_widget_show (widget);
2830 gtk_container_hide_all (GtkWidget *widget)
2832 g_return_if_fail (GTK_IS_CONTAINER (widget));
2834 gtk_widget_hide (widget);
2835 gtk_container_foreach (GTK_CONTAINER (widget),
2836 (GtkCallback) gtk_widget_hide_all,
2842 gtk_container_draw_child (GtkWidget *child,
2843 gpointer client_data)
2846 GtkWidget *container;
2848 } *data = client_data;
2850 gtk_container_propagate_draw (GTK_CONTAINER (data->container),
2856 gtk_container_draw (GtkWidget *widget,
2860 GtkWidget *container;
2864 data.container = widget;
2867 gtk_container_forall (GTK_CONTAINER (widget),
2868 gtk_container_draw_child,
2875 gtk_container_map_child (GtkWidget *child,
2876 gpointer client_data)
2878 if (gtk_widget_get_visible (child) &&
2879 gtk_widget_get_child_visible (child) &&
2880 !gtk_widget_get_mapped (child))
2881 gtk_widget_map (child);
2885 gtk_container_map (GtkWidget *widget)
2887 gtk_widget_set_mapped (widget, TRUE);
2889 gtk_container_forall (GTK_CONTAINER (widget),
2890 gtk_container_map_child,
2893 if (gtk_widget_get_has_window (widget))
2894 gdk_window_show (gtk_widget_get_window (widget));
2898 gtk_container_unmap (GtkWidget *widget)
2900 gtk_widget_set_mapped (widget, FALSE);
2902 if (gtk_widget_get_has_window (widget))
2903 gdk_window_hide (gtk_widget_get_window (widget));
2905 gtk_container_forall (GTK_CONTAINER (widget),
2906 (GtkCallback)gtk_widget_unmap,
2911 * gtk_container_propagate_draw:
2912 * @container: a #GtkContainer
2913 * @child: a child of @container
2914 * @cr: Cairo context as passed to the container. If you want to use @cr
2915 * in container's draw function, consider using cairo_save() and
2916 * cairo_restore() before calling this function.
2918 * When a container receives a call to the draw function, it must send
2919 * synthetic #GtkWidget::draw calls to all children that don't have their
2920 * own #GdkWindows. This function provides a convenient way of doing this.
2921 * A container, when it receives a call to its #GtkWidget::draw function,
2922 * calls gtk_container_propagate_draw() once for each child, passing in
2923 * the @cr the container received.
2925 * gtk_container_propagate_draw() takes care of translating the origin of @cr,
2926 * and deciding whether the draw needs to be sent to the child. It is a
2927 * convenient and optimized way of getting the same effect as calling
2928 * gtk_widget_draw() on the child directly.
2930 * In most cases, a container can simply either inherit the
2931 * #GtkWidget::draw implementation from #GtkContainer, or do some drawing
2932 * and then chain to the ::draw implementation from #GtkContainer.
2935 gtk_container_propagate_draw (GtkContainer *container,
2939 GdkEventExpose *event;
2940 GtkAllocation allocation;
2941 GdkWindow *window, *w;
2944 g_return_if_fail (GTK_IS_CONTAINER (container));
2945 g_return_if_fail (GTK_IS_WIDGET (child));
2946 g_return_if_fail (cr != NULL);
2948 g_assert (gtk_widget_get_parent (child) == GTK_WIDGET (container));
2950 event = _gtk_cairo_get_event (cr);
2953 if (gtk_widget_get_has_window (child) ||
2954 gtk_widget_get_window (child) != event->window)
2960 /* translate coordinates. Ugly business, that. */
2961 if (!gtk_widget_get_has_window (GTK_WIDGET (container)))
2963 gtk_widget_get_allocation (GTK_WIDGET (container), &allocation);
2973 window = gtk_widget_get_window (GTK_WIDGET (container));
2975 for (w = gtk_widget_get_window (child); w && w != window; w = gdk_window_get_parent (w))
2978 gdk_window_get_position (w, &wx, &wy);
2989 if (!gtk_widget_get_has_window (child))
2991 gtk_widget_get_allocation (child, &allocation);
2996 cairo_translate (cr, x, y);
2998 _gtk_widget_draw_internal (child, cr, TRUE);
3004 _gtk_container_get_need_resize (GtkContainer *container)
3006 return container->priv->need_resize;
3010 _gtk_container_set_need_resize (GtkContainer *container,
3011 gboolean need_resize)
3013 container->priv->need_resize = need_resize;
3017 _gtk_container_get_reallocate_redraws (GtkContainer *container)
3019 return container->priv->reallocate_redraws;