Pileus Git - ~andy/gtk/blob - gtk/gtkcontainer.c

   1 /* GTK - The GIMP Toolkit
   2  * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
   3  *
   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.
   8  *
   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.
  13  *
  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.
  18  */
  19
  20 /*
  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/.
  25  */
  26
  27 #include <stdarg.h>
  28 #include <string.h>
  29 #include <stdlib.h>
  30
  31 #include "gtkcontainer.h"
  32 #include "gtkprivate.h"
  33 #include "gtkmain.h"
  34 #include "gtkmarshalers.h"
  35 #include "gtkwindow.h"
  36 #include "gtkintl.h"
  37 #include <gobject/gobjectnotifyqueue.c>
  38 #include <gobject/gvaluecollector.h>
  39
  40
  41 enum {
  42   ADD,
  43   REMOVE,
  44   CHECK_RESIZE,
  45   SET_FOCUS_CHILD,
  46   LAST_SIGNAL
  47 };
  48
  49 enum {
  50   PROP_0,
  51   PROP_BORDER_WIDTH,
  52   PROP_RESIZE_MODE,
  53   PROP_CHILD
  54 };
  55
  56 #define PARAM_SPEC_PARAM_ID(pspec)              ((pspec)->param_id)
  57 #define PARAM_SPEC_SET_PARAM_ID(pspec, id)      ((pspec)->param_id = (id))
  58
  59
  60 /* --- prototypes --- */
  61 static void     gtk_container_base_class_init      (GtkContainerClass *klass);
  62 static void     gtk_container_base_class_finalize  (GtkContainerClass *klass);
  63 static void     gtk_container_class_init           (GtkContainerClass *klass);
  64 static void     gtk_container_init                 (GtkContainer      *container);
  65 static void     gtk_container_destroy              (GtkObject         *object);
  66 static void     gtk_container_set_property         (GObject         *object,
  67                                                     guint            prop_id,
  68                                                     const GValue    *value,
  69                                                     GParamSpec      *pspec);
  70 static void     gtk_container_get_property         (GObject         *object,
  71                                                     guint            prop_id,
  72                                                     GValue          *value,
  73                                                     GParamSpec      *pspec);
  74 static void     gtk_container_add_unimplemented    (GtkContainer      *container,
  75                                                     GtkWidget         *widget);
  76 static void     gtk_container_remove_unimplemented (GtkContainer      *container,
  77                                                     GtkWidget         *widget);
  78 static void     gtk_container_real_check_resize    (GtkContainer      *container);
  79 static gboolean gtk_container_focus                (GtkWidget         *widget,
  80                                                     GtkDirectionType   direction);
  81 static void     gtk_container_real_set_focus_child (GtkContainer      *container,
  82                                                     GtkWidget         *widget);
  83
  84 static gboolean gtk_container_focus_move           (GtkContainer      *container,
  85                                                     GList             *children,
  86                                                     GtkDirectionType   direction);
  87 static void     gtk_container_children_callback    (GtkWidget         *widget,
  88                                                     gpointer           client_data);
  89 static void     gtk_container_show_all             (GtkWidget         *widget);
  90 static void     gtk_container_hide_all             (GtkWidget         *widget);
  91 static gint     gtk_container_expose               (GtkWidget         *widget,
  92                                                     GdkEventExpose    *event);
  93 static void     gtk_container_map                  (GtkWidget         *widget);
  94 static void     gtk_container_unmap                (GtkWidget         *widget);
  95
  96 static gchar* gtk_container_child_default_composite_name (GtkContainer *container,
  97                                                           GtkWidget    *child);
  98
  99
 100 /* --- variables --- */
 101 static const gchar          *vadjustment_key = "gtk-vadjustment";
 102 static guint                 vadjustment_key_id = 0;
 103 static const gchar          *hadjustment_key = "gtk-hadjustment";
 104 static guint                 hadjustment_key_id = 0;
 105 static GSList               *container_resize_queue = NULL;
 106 static guint                 container_signals[LAST_SIGNAL] = { 0 };
 107 static GtkWidgetClass       *parent_class = NULL;
 108 extern GParamSpecPool       *_gtk_widget_child_property_pool;
 109 extern GObjectNotifyContext *_gtk_widget_child_property_notify_context;
 110
 111
 112 /* --- functions --- */
 113 GType
 114 gtk_container_get_type (void)
 115 {
 116   static GType container_type = 0;
 117
 118   if (!container_type)
 119     {
 120       static const GTypeInfo container_info =
 121       {
 122         sizeof (GtkContainerClass),
 123         (GBaseInitFunc) gtk_container_base_class_init,
 124         (GBaseFinalizeFunc) gtk_container_base_class_finalize,
 125         (GClassInitFunc) gtk_container_class_init,
 126         NULL        /* class_finalize */,
 127         NULL        /* class_data */,
 128         sizeof (GtkContainer),
 129         0           /* n_preallocs */,
 130         (GInstanceInitFunc) gtk_container_init,
 131         NULL,       /* value_table */
 132       };
 133
 134       container_type =
 135         g_type_register_static (GTK_TYPE_WIDGET, "GtkContainer",
 136                                 &container_info, G_TYPE_FLAG_ABSTRACT);
 137     }
 138
 139   return container_type;
 140 }
 141
 142 static void
 143 gtk_container_base_class_init (GtkContainerClass *class)
 144 {
 145   /* reset instance specifc class fields that don't get inherited */
 146   class->set_child_property = NULL;
 147   class->get_child_property = NULL;
 148 }
 149
 150 static void
 151 gtk_container_base_class_finalize (GtkContainerClass *class)
 152 {
 153   GList *list, *node;
 154
 155   list = g_param_spec_pool_list_owned (_gtk_widget_child_property_pool, G_OBJECT_CLASS_TYPE (class));
 156   for (node = list; node; node = node->next)
 157     {
 158       GParamSpec *pspec = node->data;
 159
 160       g_param_spec_pool_remove (_gtk_widget_child_property_pool, pspec);
 161       PARAM_SPEC_SET_PARAM_ID (pspec, 0);
 162       g_param_spec_unref (pspec);
 163     }
 164   g_list_free (list);
 165 }
 166
 167 static void
 168 gtk_container_class_init (GtkContainerClass *class)
 169 {
 170   GObjectClass *gobject_class = G_OBJECT_CLASS (class);
 171   GtkObjectClass *object_class = GTK_OBJECT_CLASS (class);
 172   GtkWidgetClass *widget_class = GTK_WIDGET_CLASS (class);
 173
 174   parent_class = g_type_class_peek_parent (class);
 175
 176   vadjustment_key_id = g_quark_from_static_string (vadjustment_key);
 177   hadjustment_key_id = g_quark_from_static_string (hadjustment_key);
 178
 179   gobject_class->set_property = gtk_container_set_property;
 180   gobject_class->get_property = gtk_container_get_property;
 181
 182   object_class->destroy = gtk_container_destroy;
 183
 184   widget_class->show_all = gtk_container_show_all;
 185   widget_class->hide_all = gtk_container_hide_all;
 186   widget_class->expose_event = gtk_container_expose;
 187   widget_class->map = gtk_container_map;
 188   widget_class->unmap = gtk_container_unmap;
 189   widget_class->focus = gtk_container_focus;
 190
 191   class->add = gtk_container_add_unimplemented;
 192   class->remove = gtk_container_remove_unimplemented;
 193   class->check_resize = gtk_container_real_check_resize;
 194   class->forall = NULL;
 195   class->set_focus_child = gtk_container_real_set_focus_child;
 196   class->child_type = NULL;
 197   class->composite_name = gtk_container_child_default_composite_name;
 198
 199   g_object_class_install_property (gobject_class,
 200                                    PROP_RESIZE_MODE,
 201                                    g_param_spec_enum ("resize_mode",
 202                                                       _("Resize mode"),
 203                                                       _("Specify how resize events are handled"),
 204                                                       GTK_TYPE_RESIZE_MODE,
 205                                                       GTK_RESIZE_PARENT,
 206                                                       G_PARAM_READWRITE));
 207   g_object_class_install_property (gobject_class,
 208                                    PROP_BORDER_WIDTH,
 209                                    g_param_spec_uint ("border_width",
 210                                                       _("Border width"),
 211                                                       _("The width of the empty border outside the containers children"),
 212                                                       0,
 213                                                       G_MAXINT,
 214                                                       0,
 215                                                       G_PARAM_READWRITE));
 216   g_object_class_install_property (gobject_class,
 217                                    PROP_CHILD,
 218                                    g_param_spec_object ("child",
 219                                                       _("Child"),
 220                                                       _("Can be used to add a new child to the container"),
 221                                                       GTK_TYPE_WIDGET,
 222                                                       G_PARAM_WRITABLE));
 223   container_signals[ADD] =
 224     g_signal_new ("add",
 225                   G_OBJECT_CLASS_TYPE (object_class),
 226                   G_SIGNAL_RUN_FIRST,
 227                   G_STRUCT_OFFSET (GtkContainerClass, add),
 228                   NULL, NULL,
 229                   _gtk_marshal_VOID__OBJECT,
 230                   G_TYPE_NONE, 1,
 231                   GTK_TYPE_WIDGET);
 232   container_signals[REMOVE] =
 233     g_signal_new ("remove",
 234                   G_OBJECT_CLASS_TYPE (object_class),
 235                   G_SIGNAL_RUN_FIRST,
 236                   G_STRUCT_OFFSET (GtkContainerClass, remove),
 237                   NULL, NULL,
 238                   _gtk_marshal_VOID__OBJECT,
 239                   G_TYPE_NONE, 1,
 240                   GTK_TYPE_WIDGET);
 241   container_signals[CHECK_RESIZE] =
 242     g_signal_new ("check_resize",
 243                   G_OBJECT_CLASS_TYPE (object_class),
 244                   G_SIGNAL_RUN_LAST,
 245                   G_STRUCT_OFFSET (GtkContainerClass, check_resize),
 246                   NULL, NULL,
 247                   _gtk_marshal_VOID__VOID,
 248                   G_TYPE_NONE, 0);
 249   container_signals[SET_FOCUS_CHILD] =
 250     g_signal_new ("set-focus-child",
 251                   G_OBJECT_CLASS_TYPE (object_class),
 252                   G_SIGNAL_RUN_FIRST,
 253                   G_STRUCT_OFFSET (GtkContainerClass, set_focus_child),
 254                   NULL, NULL,
 255                   _gtk_marshal_VOID__OBJECT,
 256                   G_TYPE_NONE, 1,
 257                   GTK_TYPE_WIDGET);
 258 }
 259
 260 /**
 261  * gtk_container_child_type:
 262  * @container: a #GtkContainer.
 263  *
 264  * Returns the type of the children supported by the container.
 265  *
 266  * Note that this may return %G_TYPE_NONE to indicate that no more
 267  * children can be added, e.g. for a #GtkPaned which already has two
 268  * children.
 269  *
 270  * Return value: a #GType.
 271  **/
 272 GType
 273 gtk_container_child_type (GtkContainer *container)
 274 {
 275   GType slot;
 276   GtkContainerClass *class;
 277
 278   g_return_val_if_fail (GTK_IS_CONTAINER (container), 0);
 279
 280   class = GTK_CONTAINER_GET_CLASS (container);
 281   if (class->child_type)
 282     slot = class->child_type (container);
 283   else
 284     slot = G_TYPE_NONE;
 285
 286   return slot;
 287 }
 288
 289 /* --- GtkContainer child property mechanism --- */
 290 static inline void
 291 container_get_child_property (GtkContainer *container,
 292                               GtkWidget    *child,
 293                               GParamSpec   *pspec,
 294                               GValue       *value)
 295 {
 296   GtkContainerClass *class = g_type_class_peek (pspec->owner_type);
 297
 298   class->get_child_property (container, child, PARAM_SPEC_PARAM_ID (pspec), value, pspec);
 299 }
 300
 301 static inline void
 302 container_set_child_property (GtkContainer       *container,
 303                               GtkWidget          *child,
 304                               GParamSpec         *pspec,
 305                               const GValue       *value,
 306                               GObjectNotifyQueue *nqueue)
 307 {
 308   GValue tmp_value = { 0, };
 309   GtkContainerClass *class = g_type_class_peek (pspec->owner_type);
 310
 311   /* provide a copy to work from, convert (if necessary) and validate */
 312   g_value_init (&tmp_value, G_PARAM_SPEC_VALUE_TYPE (pspec));
 313   if (!g_value_transform (value, &tmp_value))
 314     g_warning ("unable to set child property `%s' of type `%s' from value of type `%s'",
 315                pspec->name,
 316                g_type_name (G_PARAM_SPEC_VALUE_TYPE (pspec)),
 317                G_VALUE_TYPE_NAME (value));
 318   else if (g_param_value_validate (pspec, &tmp_value) && !(pspec->flags & G_PARAM_LAX_VALIDATION))
 319     {
 320       gchar *contents = g_strdup_value_contents (value);
 321
 322       g_warning ("value \"%s\" of type `%s' is invalid for property `%s' of type `%s'",
 323                  contents,
 324                  G_VALUE_TYPE_NAME (value),
 325                  pspec->name,
 326                  g_type_name (G_PARAM_SPEC_VALUE_TYPE (pspec)));
 327       g_free (contents);
 328     }
 329   else
 330     {
 331       class->set_child_property (container, child, PARAM_SPEC_PARAM_ID (pspec), &tmp_value, pspec);
 332       g_object_notify_queue_add (G_OBJECT (child), nqueue, pspec);
 333     }
 334   g_value_unset (&tmp_value);
 335 }
 336
 337 /**
 338  * gtk_container_child_get_valist:
 339  * @container: a #GtkContainer
 340  * @child: a widget which is a child of @container
 341  * @first_prop_name: the name of the first property to get
 342  * @va_list: a %NULL-terminated list of property names and #GValue*,
 343  *           starting with @first_prop_name.
 344  *
 345  * Gets the values of one or more child properties for @child and @container.
 346  **/
 347 void
 348 gtk_container_child_get_valist (GtkContainer *container,
 349                                 GtkWidget    *child,
 350                                 const gchar  *first_property_name,
 351                                 va_list       var_args)
 352 {
 353   const gchar *name;
 354
 355   g_return_if_fail (GTK_IS_CONTAINER (container));
 356   g_return_if_fail (GTK_IS_WIDGET (child));
 357   g_return_if_fail (child->parent == GTK_WIDGET (container));
 358
 359   g_object_ref (container);
 360   g_object_ref (child);
 361
 362   name = first_property_name;
 363   while (name)
 364     {
 365       GValue value = { 0, };
 366       GParamSpec *pspec;
 367       gchar *error;
 368
 369       pspec = g_param_spec_pool_lookup (_gtk_widget_child_property_pool,
 370                                         name,
 371                                         G_OBJECT_TYPE (container),
 372                                         TRUE);
 373       if (!pspec)
 374         {
 375           g_warning ("%s: container class `%s' has no child property named `%s'",
 376                      G_STRLOC,
 377                      G_OBJECT_TYPE_NAME (container),
 378                      name);
 379           break;
 380         }
 381       if (!(pspec->flags & G_PARAM_READABLE))
 382         {
 383           g_warning ("%s: child property `%s' of container class `%s' is not readable",
 384                      G_STRLOC,
 385                      pspec->name,
 386                      G_OBJECT_TYPE_NAME (container));
 387           break;
 388         }
 389       g_value_init (&value, G_PARAM_SPEC_VALUE_TYPE (pspec));
 390       container_get_child_property (container, child, pspec, &value);
 391       G_VALUE_LCOPY (&value, var_args, 0, &error);
 392       if (error)
 393         {
 394           g_warning ("%s: %s", G_STRLOC, error);
 395           g_free (error);
 396           g_value_unset (&value);
 397           break;
 398         }
 399       g_value_unset (&value);
 400       name = va_arg (var_args, gchar*);
 401     }
 402
 403   g_object_unref (child);
 404   g_object_unref (container);
 405 }
 406
 407 /**
 408  * gtk_container_child_get_property:
 409  * @container: a #GtkContainer
 410  * @child: a widget which is a child of @container
 411  * @property_name: the name of the property to get
 412  * @value: a location to return the value
 413  *
 414  * Gets the value of a child property for @child and @container.
 415  **/
 416 void
 417 gtk_container_child_get_property (GtkContainer *container,
 418                                   GtkWidget    *child,
 419                                   const gchar  *property_name,
 420                                   GValue       *value)
 421 {
 422   GParamSpec *pspec;
 423
 424   g_return_if_fail (GTK_IS_CONTAINER (container));
 425   g_return_if_fail (GTK_IS_WIDGET (child));
 426   g_return_if_fail (child->parent == GTK_WIDGET (container));
 427   g_return_if_fail (property_name != NULL);
 428   g_return_if_fail (G_IS_VALUE (value));
 429
 430   g_object_ref (container);
 431   g_object_ref (child);
 432   pspec = g_param_spec_pool_lookup (_gtk_widget_child_property_pool, property_name,
 433                                     G_OBJECT_TYPE (container), TRUE);
 434   if (!pspec)
 435     g_warning ("%s: container class `%s' has no child property named `%s'",
 436                G_STRLOC,
 437                G_OBJECT_TYPE_NAME (container),
 438                property_name);
 439   else if (!(pspec->flags & G_PARAM_READABLE))
 440     g_warning ("%s: child property `%s' of container class `%s' is not readable",
 441                G_STRLOC,
 442                pspec->name,
 443                G_OBJECT_TYPE_NAME (container));
 444   else
 445     {
 446       GValue *prop_value, tmp_value = { 0, };
 447
 448       /* auto-conversion of the callers value type
 449        */
 450       if (G_VALUE_TYPE (value) == G_PARAM_SPEC_VALUE_TYPE (pspec))
 451         {
 452           g_value_reset (value);
 453           prop_value = value;
 454         }
 455       else if (!g_value_type_transformable (G_PARAM_SPEC_VALUE_TYPE (pspec), G_VALUE_TYPE (value)))
 456         {
 457           g_warning ("can't retrieve child property `%s' of type `%s' as value of type `%s'",
 458                      pspec->name,
 459                      g_type_name (G_PARAM_SPEC_VALUE_TYPE (pspec)),
 460                      G_VALUE_TYPE_NAME (value));
 461           g_object_unref (child);
 462           g_object_unref (container);
 463           return;
 464         }
 465       else
 466         {
 467           g_value_init (&tmp_value, G_PARAM_SPEC_VALUE_TYPE (pspec));
 468           prop_value = &tmp_value;
 469         }
 470       container_get_child_property (container, child, pspec, prop_value);
 471       if (prop_value != value)
 472         {
 473           g_value_transform (prop_value, value);
 474           g_value_unset (&tmp_value);
 475         }
 476     }
 477   g_object_unref (child);
 478   g_object_unref (container);
 479 }
 480
 481 /**
 482  * gtk_container_child_set_valist:
 483  * @container: a #GtkContainer
 484  * @child: a widget which is a child of @container
 485  * @first_prop_name: the name of the first property to set
 486  * @va_list: a %NULL-terminated list of property names and values, starting
 487  *           with @first_prop_name.
 488  *
 489  * Sets one or more child properties for @child and @container.
 490  **/
 491 void
 492 gtk_container_child_set_valist (GtkContainer *container,
 493                                 GtkWidget    *child,
 494                                 const gchar  *first_property_name,
 495                                 va_list       var_args)
 496 {
 497   GObject *object;
 498   GObjectNotifyQueue *nqueue;
 499   const gchar *name;
 500
 501   g_return_if_fail (GTK_IS_CONTAINER (container));
 502   g_return_if_fail (GTK_IS_WIDGET (child));
 503   g_return_if_fail (child->parent == GTK_WIDGET (container));
 504
 505   g_object_ref (container);
 506   g_object_ref (child);
 507
 508   object = G_OBJECT (container);
 509   nqueue = g_object_notify_queue_freeze (G_OBJECT (child), _gtk_widget_child_property_notify_context);
 510   name = first_property_name;
 511   while (name)
 512     {
 513       GValue value = { 0, };
 514       gchar *error = NULL;
 515       GParamSpec *pspec = g_param_spec_pool_lookup (_gtk_widget_child_property_pool,
 516                                                     name,
 517                                                     G_OBJECT_TYPE (container),
 518                                                     TRUE);
 519       if (!pspec)
 520         {
 521           g_warning ("%s: container class `%s' has no child property named `%s'",
 522                      G_STRLOC,
 523                      G_OBJECT_TYPE_NAME (container),
 524                      name);
 525           break;
 526         }
 527       if (!(pspec->flags & G_PARAM_WRITABLE))
 528         {
 529           g_warning ("%s: child property `%s' of container class `%s' is not writable",
 530                      G_STRLOC,
 531                      pspec->name,
 532                      G_OBJECT_TYPE_NAME (container));
 533           break;
 534         }
 535       g_value_init (&value, G_PARAM_SPEC_VALUE_TYPE (pspec));
 536       G_VALUE_COLLECT (&value, var_args, 0, &error);
 537       if (error)
 538         {
 539           g_warning ("%s: %s", G_STRLOC, error);
 540           g_free (error);
 541
 542           /* we purposely leak the value here, it might not be
 543            * in a sane state if an error condition occoured
 544            */
 545           break;
 546         }
 547       container_set_child_property (container, child, pspec, &value, nqueue);
 548       g_value_unset (&value);
 549       name = va_arg (var_args, gchar*);
 550     }
 551   g_object_notify_queue_thaw (G_OBJECT (child), nqueue);
 552
 553   g_object_unref (container);
 554   g_object_unref (child);
 555 }
 556
 557 /**
 558  * gtk_container_child_set_property:
 559  * @container: a #GtkContainer
 560  * @child: a widget which is a child of @container
 561  * @property_name: the name of the property to set
 562  * @value: the value to set the property to
 563  *
 564  * Sets a child property for @child and @container.
 565  **/
 566 void
 567 gtk_container_child_set_property (GtkContainer *container,
 568                                   GtkWidget    *child,
 569                                   const gchar  *property_name,
 570                                   const GValue *value)
 571 {
 572   GObject *object;
 573   GObjectNotifyQueue *nqueue;
 574   GParamSpec *pspec;
 575
 576   g_return_if_fail (GTK_IS_CONTAINER (container));
 577   g_return_if_fail (GTK_IS_WIDGET (child));
 578   g_return_if_fail (child->parent == GTK_WIDGET (container));
 579   g_return_if_fail (property_name != NULL);
 580   g_return_if_fail (G_IS_VALUE (value));
 581
 582   g_object_ref (container);
 583   g_object_ref (child);
 584
 585   object = G_OBJECT (container);
 586   nqueue = g_object_notify_queue_freeze (G_OBJECT (child), _gtk_widget_child_property_notify_context);
 587   pspec = g_param_spec_pool_lookup (_gtk_widget_child_property_pool, property_name,
 588                                     G_OBJECT_TYPE (container), TRUE);
 589   if (!pspec)
 590     g_warning ("%s: container class `%s' has no child property named `%s'",
 591                G_STRLOC,
 592                G_OBJECT_TYPE_NAME (container),
 593                property_name);
 594   else if (!(pspec->flags & G_PARAM_WRITABLE))
 595     g_warning ("%s: child property `%s' of container class `%s' is not writable",
 596                G_STRLOC,
 597                pspec->name,
 598                G_OBJECT_TYPE_NAME (container));
 599   else
 600     {
 601       container_set_child_property (container, child, pspec, value, nqueue);
 602     }
 603   g_object_notify_queue_thaw (G_OBJECT (child), nqueue);
 604   g_object_unref (container);
 605   g_object_unref (child);
 606 }
 607
 608 /**
 609  * gtk_container_add_with_properties:
 610  * @container: a #GtkContainer
 611  * @widget: a widget to be placed inside @container
 612  * @first_prop_name: the name of the first child property to set
 613  * @Varargs: a %NULL-terminated list of property names and values, starting
 614  *           with @first_prop_name.
 615  *
 616  * Adds @widget to @container, setting child properties at the same time.
 617  * See gtk_container_add() and gtk_container_child_set() for more details.
 618  **/
 619 void
 620 gtk_container_add_with_properties (GtkContainer *container,
 621                                    GtkWidget    *widget,
 622                                    const gchar  *first_prop_name,
 623                                    ...)
 624 {
 625   g_return_if_fail (GTK_IS_CONTAINER (container));
 626   g_return_if_fail (GTK_IS_WIDGET (widget));
 627   g_return_if_fail (widget->parent == NULL);
 628
 629   g_object_ref (container);
 630   g_object_ref (widget);
 631   gtk_widget_freeze_child_notify (widget);
 632
 633   g_signal_emit (container, container_signals[ADD], 0, widget);
 634   if (widget->parent)
 635     {
 636       va_list var_args;
 637
 638       va_start (var_args, first_prop_name);
 639       gtk_container_child_set_valist (container, widget, first_prop_name, var_args);
 640       va_end (var_args);
 641     }
 642
 643   gtk_widget_thaw_child_notify (widget);
 644   g_object_unref (widget);
 645   g_object_unref (container);
 646 }
 647
 648 /**
 649  * gtk_container_child_set:
 650  * @container: a #GtkContainer
 651  * @child: a widget which is a child of @container
 652  * @first_prop_name: the name of the first property to set
 653  * @Varargs: a %NULL-terminated list of property names and values, starting
 654  *           with @first_prop_name.
 655  *
 656  * Sets one or more child properties for @child and @container.
 657  **/
 658 void
 659 gtk_container_child_set (GtkContainer      *container,
 660                          GtkWidget         *child,
 661                          const gchar       *first_prop_name,
 662                          ...)
 663 {
 664   va_list var_args;
 665
 666   g_return_if_fail (GTK_IS_CONTAINER (container));
 667   g_return_if_fail (GTK_IS_WIDGET (child));
 668   g_return_if_fail (child->parent == GTK_WIDGET (container));
 669
 670   va_start (var_args, first_prop_name);
 671   gtk_container_child_set_valist (container, child, first_prop_name, var_args);
 672   va_end (var_args);
 673 }
 674
 675 /**
 676  * gtk_container_child_get:
 677  * @container: a #GtkContainer
 678  * @child: a widget which is a child of @container
 679  * @first_prop_name: the name of the first property to get
 680  * @Varargs: a %NULL-terminated list of property names and #GValue*,
 681  *           starting with @first_prop_name.
 682  *
 683  * Gets the values of one or more child properties for @child and @container.
 684  **/
 685 void
 686 gtk_container_child_get (GtkContainer      *container,
 687                          GtkWidget         *child,
 688                          const gchar       *first_prop_name,
 689                          ...)
 690 {
 691   va_list var_args;
 692
 693   g_return_if_fail (GTK_IS_CONTAINER (container));
 694   g_return_if_fail (GTK_IS_WIDGET (child));
 695   g_return_if_fail (child->parent == GTK_WIDGET (container));
 696
 697   va_start (var_args, first_prop_name);
 698   gtk_container_child_get_valist (container, child, first_prop_name, var_args);
 699   va_end (var_args);
 700 }
 701
 702 /**
 703  * gtk_container_class_install_child_property:
 704  * @cclass: a #GtkContainerClass
 705  * @property_id: the id for the property
 706  * @pspec: the #GParamSpec for the property
 707  *
 708  * Installs a child property on a container class.
 709  **/
 710 void
 711 gtk_container_class_install_child_property (GtkContainerClass *cclass,
 712                                             guint              property_id,
 713                                             GParamSpec        *pspec)
 714 {
 715   g_return_if_fail (GTK_IS_CONTAINER_CLASS (cclass));
 716   g_return_if_fail (G_IS_PARAM_SPEC (pspec));
 717   if (pspec->flags & G_PARAM_WRITABLE)
 718     g_return_if_fail (cclass->set_child_property != NULL);
 719   if (pspec->flags & G_PARAM_READABLE)
 720     g_return_if_fail (cclass->get_child_property != NULL);
 721   g_return_if_fail (property_id > 0);
 722   g_return_if_fail (PARAM_SPEC_PARAM_ID (pspec) == 0);  /* paranoid */
 723   if (pspec->flags & (G_PARAM_CONSTRUCT | G_PARAM_CONSTRUCT_ONLY))
 724     g_return_if_fail ((pspec->flags & (G_PARAM_CONSTRUCT | G_PARAM_CONSTRUCT_ONLY)) == 0);
 725
 726   if (g_param_spec_pool_lookup (_gtk_widget_child_property_pool, pspec->name, G_OBJECT_CLASS_TYPE (cclass), FALSE))
 727     {
 728       g_warning (G_STRLOC ": class `%s' already contains a child property named `%s'",
 729                  G_OBJECT_CLASS_NAME (cclass),
 730                  pspec->name);
 731       return;
 732     }
 733   g_param_spec_ref (pspec);
 734   g_param_spec_sink (pspec);
 735   PARAM_SPEC_SET_PARAM_ID (pspec, property_id);
 736   g_param_spec_pool_insert (_gtk_widget_child_property_pool, pspec, G_OBJECT_CLASS_TYPE (cclass));
 737 }
 738
 739 /**
 740  * gtk_container_class_find_child_property:
 741  * @cclass: a #GtkContainerClass
 742  * @property_name: the name of the child property to find
 743  * @returns: the #GParamSpec of the child property or %NULL if @class has no
 744  *   child property with that name.
 745  *
 746  * Finds a child property of a container class by name.
 747  */
 748 GParamSpec*
 749 gtk_container_class_find_child_property (GObjectClass *cclass,
 750                                          const gchar  *property_name)
 751 {
 752   g_return_val_if_fail (GTK_IS_CONTAINER_CLASS (cclass), NULL);
 753   g_return_val_if_fail (property_name != NULL, NULL);
 754
 755   return g_param_spec_pool_lookup (_gtk_widget_child_property_pool,
 756                                    property_name,
 757                                    G_OBJECT_CLASS_TYPE (cclass),
 758                                    TRUE);
 759 }
 760
 761 /**
 762  * gtk_container_class_list_child_properties:
 763  * @cclass: a #GtkContainerClass
 764  * @n_properties: location to return the number of child properties found
 765  * @returns: a newly allocated array of #GParamSpec*. The array must be
 766  *           freed with g_free().
 767  *
 768  * Returns all child properties of a container class.
 769  */
 770 GParamSpec**
 771 gtk_container_class_list_child_properties (GObjectClass *cclass,
 772                                            guint        *n_properties)
 773 {
 774   GParamSpec **pspecs;
 775   guint n;
 776
 777   g_return_val_if_fail (GTK_IS_CONTAINER_CLASS (cclass), NULL);
 778
 779   pspecs = g_param_spec_pool_list (_gtk_widget_child_property_pool,
 780                                    G_OBJECT_CLASS_TYPE (cclass),
 781                                    &n);
 782   if (n_properties)
 783     *n_properties = n;
 784
 785   return pspecs;
 786 }
 787
 788 static void
 789 gtk_container_add_unimplemented (GtkContainer     *container,
 790                                  GtkWidget        *widget)
 791 {
 792   g_warning ("GtkContainerClass::add not implemented for `%s'", g_type_name (G_TYPE_FROM_INSTANCE (container)));
 793 }
 794
 795 static void
 796 gtk_container_remove_unimplemented (GtkContainer     *container,
 797                                     GtkWidget        *widget)
 798 {
 799   g_warning ("GtkContainerClass::remove not implemented for `%s'", g_type_name (G_TYPE_FROM_INSTANCE (container)));
 800 }
 801
 802 static void
 803 gtk_container_init (GtkContainer *container)
 804 {
 805   container->focus_child = NULL;
 806   container->border_width = 0;
 807   container->need_resize = FALSE;
 808   container->resize_mode = GTK_RESIZE_PARENT;
 809   container->reallocate_redraws = FALSE;
 810 }
 811
 812 static void
 813 gtk_container_destroy (GtkObject *object)
 814 {
 815   GtkContainer *container = GTK_CONTAINER (object);
 816
 817   if (GTK_CONTAINER_RESIZE_PENDING (container))
 818     _gtk_container_dequeue_resize_handler (container);
 819
 820   /* do this before walking child widgets, to avoid
 821    * removing children from focus chain one by one.
 822    */
 823   if (container->has_focus_chain)
 824     gtk_container_unset_focus_chain (container);
 825
 826   gtk_container_foreach (container, (GtkCallback) gtk_widget_destroy, NULL);
 827
 828   if (GTK_OBJECT_CLASS (parent_class)->destroy)
 829     (* GTK_OBJECT_CLASS (parent_class)->destroy) (object);
 830 }
 831
 832 static void
 833 gtk_container_set_property (GObject         *object,
 834                             guint            prop_id,
 835                             const GValue    *value,
 836                             GParamSpec      *pspec)
 837 {
 838   GtkContainer *container = GTK_CONTAINER (object);
 839
 840   switch (prop_id)
 841     {
 842     case PROP_BORDER_WIDTH:
 843       gtk_container_set_border_width (container, g_value_get_uint (value));
 844       break;
 845     case PROP_RESIZE_MODE:
 846       gtk_container_set_resize_mode (container, g_value_get_enum (value));
 847       break;
 848     case PROP_CHILD:
 849       gtk_container_add (container, GTK_WIDGET (g_value_get_object (value)));
 850       break;
 851     default:
 852       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 853       break;
 854     }
 855 }
 856
 857 static void
 858 gtk_container_get_property (GObject         *object,
 859                             guint            prop_id,
 860                             GValue          *value,
 861                             GParamSpec      *pspec)
 862 {
 863   GtkContainer *container = GTK_CONTAINER (object);
 864
 865   switch (prop_id)
 866     {
 867     case PROP_BORDER_WIDTH:
 868       g_value_set_uint (value, container->border_width);
 869       break;
 870     case PROP_RESIZE_MODE:
 871       g_value_set_enum (value, container->resize_mode);
 872       break;
 873     default:
 874       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 875       break;
 876     }
 877 }
 878
 879 /**
 880  * gtk_container_set_border_width:
 881  * @container: a #GtkContainer
 882  * @border_width: amount of blank space to leave <emphasis>outside</emphasis> the container.
 883  *   Valid values are in the range 0-65535 pixels.
 884  *
 885  * Sets the border width of the container.
 886  *
 887  * The border width of a container is the amount of space to leave
 888  * around the outside of the container. The only exception to this is
 889  * #GtkWindow; because toplevel windows can't leave space outside,
 890  * they leave the space inside. The border is added on all sides of
 891  * the container. To add space to only one side, one approach is to
 892  * create a #GtkAlignment widget, call gtk_widget_set_usize() to give
 893  * it a size, and place it on the side of the container as a spacer.
 894  **/
 895 void
 896 gtk_container_set_border_width (GtkContainer *container,
 897                                 guint         border_width)
 898 {
 899   g_return_if_fail (GTK_IS_CONTAINER (container));
 900
 901   if (container->border_width != border_width)
 902     {
 903       container->border_width = border_width;
 904       g_object_notify (G_OBJECT (container), "border_width");
 905
 906       if (GTK_WIDGET_REALIZED (container))
 907         gtk_widget_queue_resize (GTK_WIDGET (container));
 908     }
 909 }
 910
 911 /**
 912  * gtk_container_get_border_width:
 913  * @container: a #GtkContainer
 914  *
 915  * Retrieves the border width of the container. See
 916  * gtk_container_set_border_width().
 917  *
 918  * Return value: the current border width
 919  **/
 920 guint
 921 gtk_container_get_border_width (GtkContainer *container)
 922 {
 923   g_return_val_if_fail (GTK_IS_CONTAINER (container), 0);
 924
 925   return container->border_width;
 926 }
 927
 928 /**
 929  * gtk_container_add:
 930  * @container: a #GtkContainer
 931  * @widget: a widget to be placed inside @container
 932  *
 933  * Adds @widget to @container. Typically used for simple containers
 934  * such as #GtkWindow, #GtkFrame, or #GtkButton; for more complicated
 935  * layout containers such as #GtkBox or #GtkTable, this function will
 936  * pick default packing parameters that may not be correct.  So
 937  * consider functions such as gtk_box_pack_start() and
 938  * gtk_table_attach() as an alternative to gtk_container_add() in
 939  * those cases. A widget may be added to only one container at a time;
 940  * you can't place the same widget inside two different containers.
 941  **/
 942 void
 943 gtk_container_add (GtkContainer *container,
 944                    GtkWidget    *widget)
 945 {
 946   g_return_if_fail (GTK_IS_CONTAINER (container));
 947   g_return_if_fail (GTK_IS_WIDGET (widget));
 948
 949   if (widget->parent != NULL)
 950     {
 951       g_warning ("Attempting to add a widget with type %s to a container of "
 952                  "type %s, but the widget is already inside a container of type %s, "
 953                  "the GTK+ FAQ at http://www.gtk.org/faq/ explains how to reparent a widget.",
 954                  g_type_name (G_OBJECT_TYPE (widget)),
 955                  g_type_name (G_OBJECT_TYPE (container)),
 956                  g_type_name (G_OBJECT_TYPE (widget->parent)));
 957       return;
 958     }
 959
 960   g_signal_emit (container, container_signals[ADD], 0, widget);
 961 }
 962
 963 /**
 964  * gtk_container_remove:
 965  * @container: a #GtkContainer
 966  * @widget: a current child of @container
 967  *
 968  * Removes @widget from @container. @widget must be inside @container.
 969  * Note that @container will own a reference to @widget, and that this
 970  * may be the last reference held; so removing a widget from its
 971  * container can destroy that widget. If you want to use @widget
 972  * again, you need to add a reference to it while it's not inside
 973  * a container, using g_object_ref().
 974  **/
 975 void
 976 gtk_container_remove (GtkContainer *container,
 977                       GtkWidget    *widget)
 978 {
 979   g_return_if_fail (GTK_IS_CONTAINER (container));
 980   g_return_if_fail (GTK_IS_WIDGET (widget));
 981   g_return_if_fail (widget->parent == GTK_WIDGET (container));
 982
 983   g_signal_emit (container, container_signals[REMOVE], 0, widget);
 984 }
 985
 986 void
 987 _gtk_container_dequeue_resize_handler (GtkContainer *container)
 988 {
 989   g_return_if_fail (GTK_IS_CONTAINER (container));
 990   g_return_if_fail (GTK_CONTAINER_RESIZE_PENDING (container));
 991
 992   container_resize_queue = g_slist_remove (container_resize_queue, container);
 993   GTK_PRIVATE_UNSET_FLAG (container, GTK_RESIZE_PENDING);
 994 }
 995
 996 /**
 997  * gtk_container_set_resize_mode:
 998  * @container: a #GtkContainer.
 999  * @resize_mode: the new resize mode.
1000  *
1001  * Sets the resize mode for the container.
1002  *
1003  * The resize mode of a container determines whether a resize request
1004  * will be passed to the container's parent, queued for later execution
1005  * or executed immediately.
1006  **/
1007 void
1008 gtk_container_set_resize_mode (GtkContainer  *container,
1009                                GtkResizeMode  resize_mode)
1010 {
1011   g_return_if_fail (GTK_IS_CONTAINER (container));
1012   g_return_if_fail (resize_mode <= GTK_RESIZE_IMMEDIATE);
1013
1014   if (GTK_WIDGET_TOPLEVEL (container) &&
1015       resize_mode == GTK_RESIZE_PARENT)
1016     {
1017       resize_mode = GTK_RESIZE_QUEUE;
1018     }
1019
1020   if (container->resize_mode != resize_mode)
1021     {
1022       container->resize_mode = resize_mode;
1023
1024       gtk_widget_queue_resize (GTK_WIDGET (container));
1025       g_object_notify (G_OBJECT (container), "resize_mode");
1026     }
1027 }
1028
1029 /**
1030  * gtk_container_get_resize_mode:
1031  * @container: a #GtkContainer
1032  *
1033  * Returns the resize mode for the container. See
1034  * gtk_container_set_resize_mode ().
1035  *
1036  * Return value: the current resize mode
1037  **/
1038 GtkResizeMode
1039 gtk_container_get_resize_mode (GtkContainer *container)
1040 {
1041   g_return_val_if_fail (GTK_IS_CONTAINER (container), GTK_RESIZE_PARENT);
1042
1043   return container->resize_mode;
1044 }
1045
1046 /**
1047  * gtk_container_set_reallocate_redraws:
1048  * @container: a #GtkContainer.
1049  * @needs_redraws: the new value for the container's @reallocate_redraws flag.
1050  *
1051  * Sets the @reallocate_redraws flag of the container to the given value.
1052  *
1053  * Containers requesting reallocation redraws get automatically
1054  * redrawn if any of their children changed allocation.
1055  **/
1056 void
1057 gtk_container_set_reallocate_redraws (GtkContainer *container,
1058                                       gboolean      needs_redraws)
1059 {
1060   g_return_if_fail (GTK_IS_CONTAINER (container));
1061
1062   container->reallocate_redraws = needs_redraws ? TRUE : FALSE;
1063 }
1064
1065 static GtkContainer*
1066 gtk_container_get_resize_container (GtkContainer *container)
1067 {
1068   GtkWidget *widget = GTK_WIDGET (container);
1069
1070   while (widget->parent)
1071     {
1072       widget = widget->parent;
1073       if (GTK_IS_RESIZE_CONTAINER (widget))
1074         break;
1075     }
1076
1077   return GTK_IS_RESIZE_CONTAINER (widget) ? (GtkContainer*) widget : NULL;
1078 }
1079
1080 static gboolean
1081 gtk_container_idle_sizer (gpointer data)
1082 {
1083   GDK_THREADS_ENTER ();
1084
1085   /* we may be invoked with a container_resize_queue of NULL, because
1086    * queue_resize could have been adding an extra idle function while
1087    * the queue still got processed. we better just ignore such case
1088    * than trying to explicitely work around them with some extra flags,
1089    * since it doesn't cause any actual harm.
1090    */
1091   while (container_resize_queue)
1092     {
1093       GSList *slist;
1094       GtkWidget *widget;
1095
1096       slist = container_resize_queue;
1097       container_resize_queue = slist->next;
1098       widget = slist->data;
1099       g_slist_free_1 (slist);
1100
1101       GTK_PRIVATE_UNSET_FLAG (widget, GTK_RESIZE_PENDING);
1102       gtk_container_check_resize (GTK_CONTAINER (widget));
1103     }
1104
1105   gdk_window_process_all_updates ();
1106
1107   GDK_THREADS_LEAVE ();
1108
1109   return FALSE;
1110 }
1111
1112 void
1113 _gtk_container_queue_resize (GtkContainer *container)
1114 {
1115   GtkContainer *resize_container;
1116   GtkWidget *widget;
1117
1118   g_return_if_fail (GTK_IS_CONTAINER (container));
1119
1120   widget = GTK_WIDGET (container);
1121   resize_container = gtk_container_get_resize_container (container);
1122
1123   while (!GTK_WIDGET_ALLOC_NEEDED (widget) || !GTK_WIDGET_REQUEST_NEEDED (widget))
1124     {
1125       GTK_PRIVATE_SET_FLAG (widget, GTK_ALLOC_NEEDED);
1126       GTK_PRIVATE_SET_FLAG (widget, GTK_REQUEST_NEEDED);
1127       if ((resize_container && widget == GTK_WIDGET (resize_container)) ||
1128           !widget->parent)
1129         break;
1130
1131       widget = widget->parent;
1132     }
1133
1134   if (resize_container)
1135     {
1136       if (GTK_WIDGET_VISIBLE (resize_container) &&
1137           (GTK_WIDGET_TOPLEVEL (resize_container) || GTK_WIDGET_REALIZED (resize_container)))
1138         {
1139           switch (resize_container->resize_mode)
1140             {
1141             case GTK_RESIZE_QUEUE:
1142               if (!GTK_CONTAINER_RESIZE_PENDING (resize_container))
1143                 {
1144                   GTK_PRIVATE_SET_FLAG (resize_container, GTK_RESIZE_PENDING);
1145                   if (container_resize_queue == NULL)
1146                     gtk_idle_add_priority (GTK_PRIORITY_RESIZE,
1147                                            gtk_container_idle_sizer,
1148                                            NULL);
1149                   container_resize_queue = g_slist_prepend (container_resize_queue, resize_container);
1150                 }
1151               break;
1152
1153             case GTK_RESIZE_IMMEDIATE:
1154               gtk_container_check_resize (resize_container);
1155               break;
1156
1157             case GTK_RESIZE_PARENT:
1158               g_assert_not_reached ();
1159               break;
1160             }
1161         }
1162       else
1163         {
1164           /* we need to let hidden resize containers know that something
1165            * changed while they where hidden (currently only evaluated by
1166            * toplevels).
1167            */
1168           resize_container->need_resize = TRUE;
1169         }
1170     }
1171 }
1172
1173 void
1174 gtk_container_check_resize (GtkContainer *container)
1175 {
1176   g_return_if_fail (GTK_IS_CONTAINER (container));
1177
1178   g_signal_emit (container, container_signals[CHECK_RESIZE], 0);
1179 }
1180
1181 static void
1182 gtk_container_real_check_resize (GtkContainer *container)
1183 {
1184   GtkWidget *widget = GTK_WIDGET (container);
1185   GtkRequisition requisition;
1186
1187   gtk_widget_size_request (widget, &requisition);
1188
1189   if (requisition.width > widget->allocation.width ||
1190       requisition.height > widget->allocation.height)
1191     {
1192       if (GTK_IS_RESIZE_CONTAINER (container))
1193         gtk_widget_size_allocate (GTK_WIDGET (container),
1194                                   &GTK_WIDGET (container)->allocation);
1195       else
1196         gtk_widget_queue_resize (widget);
1197     }
1198   else
1199     {
1200       gtk_container_resize_children (container);
1201     }
1202 }
1203
1204 /* The container hasn't changed size but one of its children
1205  *  queued a resize request. Which means that the allocation
1206  *  is not sufficient for the requisition of some child.
1207  *  We've already performed a size request at this point,
1208  *  so we simply need to reallocate and let the allocation
1209  *  trickle down via GTK_WIDGET_ALLOC_NEEDED flags.
1210  */
1211 void
1212 gtk_container_resize_children (GtkContainer *container)
1213 {
1214   GtkWidget *widget;
1215
1216   /* resizing invariants:
1217    * toplevels have *always* resize_mode != GTK_RESIZE_PARENT set.
1218    * containers that have an idle sizer pending must be flagged with
1219    * RESIZE_PENDING.
1220    */
1221   g_return_if_fail (GTK_IS_CONTAINER (container));
1222
1223   widget = GTK_WIDGET (container);
1224   gtk_widget_size_allocate (widget, &widget->allocation);
1225 }
1226
1227 /**
1228  * gtk_container_forall:
1229  * @container: a #GtkContainer
1230  * @callback: a callback
1231  * @callback_data: callback user data
1232  *
1233  * Invokes @callback on each child of @container, including children
1234  * that are considered "internal" (implementation details of the
1235  * container). "Internal" children generally weren't added by the user
1236  * of the container, but were added by the container implementation
1237  * itself.  Most applications should use gtk_container_foreach(),
1238  * rather than gtk_container_forall().
1239  **/
1240 void
1241 gtk_container_forall (GtkContainer *container,
1242                       GtkCallback   callback,
1243                       gpointer      callback_data)
1244 {
1245   GtkContainerClass *class;
1246
1247   g_return_if_fail (GTK_IS_CONTAINER (container));
1248   g_return_if_fail (callback != NULL);
1249
1250   class = GTK_CONTAINER_GET_CLASS (container);
1251
1252   if (class->forall)
1253     class->forall (container, TRUE, callback, callback_data);
1254 }
1255
1256 /**
1257  * gtk_container_foreach:
1258  * @container: a #GtkContainer
1259  * @callback: a callback
1260  * @callback_data: callback user data
1261  *
1262  * Invokes @callback on each non-internal child of @container.  See
1263  * gtk_container_forall() for details on what constitutes an
1264  * "internal" child.  Most applications should use
1265  * gtk_container_foreach(), rather than gtk_container_forall().
1266  **/
1267 void
1268 gtk_container_foreach (GtkContainer *container,
1269                        GtkCallback   callback,
1270                        gpointer      callback_data)
1271 {
1272   GtkContainerClass *class;
1273
1274   g_return_if_fail (GTK_IS_CONTAINER (container));
1275   g_return_if_fail (callback != NULL);
1276
1277   class = GTK_CONTAINER_GET_CLASS (container);
1278
1279   if (class->forall)
1280     class->forall (container, FALSE, callback, callback_data);
1281 }
1282
1283 typedef struct _GtkForeachData  GtkForeachData;
1284 struct _GtkForeachData
1285 {
1286   GtkObject         *container;
1287   GtkCallbackMarshal callback;
1288   gpointer           callback_data;
1289 };
1290
1291 static void
1292 gtk_container_foreach_unmarshal (GtkWidget *child,
1293                                  gpointer data)
1294 {
1295   GtkForeachData *fdata = (GtkForeachData*) data;
1296   GtkArg args[2];
1297
1298   /* first argument */
1299   args[0].name = NULL;
1300   args[0].type = G_TYPE_FROM_INSTANCE (child);
1301   GTK_VALUE_OBJECT (args[0]) = GTK_OBJECT (child);
1302
1303   /* location for return value */
1304   args[1].name = NULL;
1305   args[1].type = G_TYPE_NONE;
1306
1307   fdata->callback (fdata->container, fdata->callback_data, 1, args);
1308 }
1309
1310 void
1311 gtk_container_foreach_full (GtkContainer       *container,
1312                             GtkCallback         callback,
1313                             GtkCallbackMarshal  marshal,
1314                             gpointer            callback_data,
1315                             GtkDestroyNotify    notify)
1316 {
1317   g_return_if_fail (GTK_IS_CONTAINER (container));
1318
1319   if (marshal)
1320     {
1321       GtkForeachData fdata;
1322
1323       fdata.container     = GTK_OBJECT (container);
1324       fdata.callback      = marshal;
1325       fdata.callback_data = callback_data;
1326
1327       gtk_container_foreach (container, gtk_container_foreach_unmarshal, &fdata);
1328     }
1329   else
1330     {
1331       g_return_if_fail (callback != NULL);
1332
1333       gtk_container_foreach (container, callback, &callback_data);
1334     }
1335
1336   if (notify)
1337     notify (callback_data);
1338 }
1339
1340 void
1341 gtk_container_set_focus_child (GtkContainer *container,
1342                                GtkWidget    *widget)
1343 {
1344   g_return_if_fail (GTK_IS_CONTAINER (container));
1345   if (widget)
1346     g_return_if_fail (GTK_IS_WIDGET (widget));
1347
1348   g_signal_emit (container, container_signals[SET_FOCUS_CHILD], 0, widget);
1349 }
1350
1351 /**
1352  * gtk_container_get_children:
1353  * @container: a #GtkContainer.
1354  *
1355  * Returns the the container's non-internal children. See
1356  * gtk_container_forall() for details on what constitutes an "internal" child.
1357  *
1358  * Return value: a newly-allocated list of the container's non-internal children.
1359  **/
1360 GList*
1361 gtk_container_get_children (GtkContainer *container)
1362 {
1363   GList *children = NULL;
1364
1365   gtk_container_foreach (container,
1366                          gtk_container_children_callback,
1367                          &children);
1368
1369   return g_list_reverse (children);
1370 }
1371
1372 static void
1373 gtk_container_child_position_callback (GtkWidget *widget,
1374                                        gpointer   client_data)
1375 {
1376   struct {
1377     GtkWidget *child;
1378     guint i;
1379     guint index;
1380   } *data = client_data;
1381
1382   data->i++;
1383   if (data->child == widget)
1384     data->index = data->i;
1385 }
1386
1387 static gchar*
1388 gtk_container_child_default_composite_name (GtkContainer *container,
1389                                             GtkWidget    *child)
1390 {
1391   struct {
1392     GtkWidget *child;
1393     guint i;
1394     guint index;
1395   } data;
1396   gchar *name;
1397
1398   /* fallback implementation */
1399   data.child = child;
1400   data.i = 0;
1401   data.index = 0;
1402   gtk_container_forall (container,
1403                         gtk_container_child_position_callback,
1404                         &data);
1405
1406   name = g_strdup_printf ("%s-%u",
1407                           g_type_name (G_TYPE_FROM_INSTANCE (child)),
1408                           data.index);
1409
1410   return name;
1411 }
1412
1413 gchar*
1414 _gtk_container_child_composite_name (GtkContainer *container,
1415                                     GtkWidget    *child)
1416 {
1417   g_return_val_if_fail (GTK_IS_CONTAINER (container), NULL);
1418   g_return_val_if_fail (GTK_IS_WIDGET (child), NULL);
1419   g_return_val_if_fail (child->parent == GTK_WIDGET (container), NULL);
1420
1421   if (GTK_WIDGET_COMPOSITE_CHILD (child))
1422     {
1423       static GQuark quark_composite_name = 0;
1424       gchar *name;
1425
1426       if (!quark_composite_name)
1427         quark_composite_name = g_quark_from_static_string ("gtk-composite-name");
1428
1429       name = g_object_get_qdata (G_OBJECT (child), quark_composite_name);
1430       if (!name)
1431         {
1432           GtkContainerClass *class;
1433
1434           class = GTK_CONTAINER_GET_CLASS (container);
1435           if (class->composite_name)
1436             name = class->composite_name (container, child);
1437         }
1438       else
1439         name = g_strdup (name);
1440
1441       return name;
1442     }
1443
1444   return NULL;
1445 }
1446
1447 static void
1448 gtk_container_real_set_focus_child (GtkContainer     *container,
1449                                     GtkWidget        *child)
1450 {
1451   g_return_if_fail (GTK_IS_CONTAINER (container));
1452   if (child)
1453     g_return_if_fail (GTK_IS_WIDGET (child));
1454
1455   if (child != container->focus_child)
1456     {
1457       if (container->focus_child)
1458         g_object_unref (container->focus_child);
1459       container->focus_child = child;
1460       if (container->focus_child)
1461         g_object_ref (container->focus_child);
1462     }
1463
1464
1465   /* check for h/v adjustments
1466    */
1467   if (container->focus_child)
1468     {
1469       GtkAdjustment *adjustment;
1470
1471       adjustment = g_object_get_qdata (G_OBJECT (container), vadjustment_key_id);
1472       if (adjustment)
1473         gtk_adjustment_clamp_page (adjustment,
1474                                    container->focus_child->allocation.y,
1475                                    (container->focus_child->allocation.y +
1476                                     container->focus_child->allocation.height));
1477
1478       adjustment = g_object_get_qdata (G_OBJECT (container), hadjustment_key_id);
1479       if (adjustment)
1480         gtk_adjustment_clamp_page (adjustment,
1481                                    container->focus_child->allocation.x,
1482                                    (container->focus_child->allocation.x +
1483                                     container->focus_child->allocation.width));
1484     }
1485 }
1486
1487 static GList*
1488 get_focus_chain (GtkContainer *container)
1489 {
1490   return g_object_get_data (G_OBJECT (container), "gtk-container-focus-chain");
1491 }
1492
1493 /* same as gtk_container_get_children, except it includes internals
1494  */
1495 static GList *
1496 gtk_container_get_all_children (GtkContainer *container)
1497 {
1498   GList *children = NULL;
1499
1500   gtk_container_forall (container,
1501                          gtk_container_children_callback,
1502                          &children);
1503
1504   return children;
1505 }
1506
1507 static gboolean
1508 gtk_container_focus (GtkWidget        *widget,
1509                      GtkDirectionType  direction)
1510 {
1511   GList *children;
1512   GList *sorted_children;
1513   gint return_val;
1514   GtkContainer *container;
1515
1516   g_return_val_if_fail (GTK_IS_CONTAINER (widget), FALSE);
1517
1518   container = GTK_CONTAINER (widget);
1519
1520   return_val = FALSE;
1521
1522   if (GTK_WIDGET_CAN_FOCUS (container))
1523     {
1524       if (!GTK_WIDGET_HAS_FOCUS (container))
1525         {
1526           gtk_widget_grab_focus (GTK_WIDGET (container));
1527           return_val = TRUE;
1528         }
1529     }
1530   else
1531     {
1532       /* Get a list of the containers children, allowing focus
1533        * chain to override.
1534        */
1535       if (container->has_focus_chain)
1536         children = g_list_copy (get_focus_chain (container));
1537       else
1538         children = gtk_container_get_all_children (container);
1539
1540       if (container->has_focus_chain &&
1541           (direction == GTK_DIR_TAB_FORWARD ||
1542            direction == GTK_DIR_TAB_BACKWARD))
1543         {
1544           sorted_children = g_list_copy (children);
1545
1546           if (direction == GTK_DIR_TAB_BACKWARD)
1547             sorted_children = g_list_reverse (sorted_children);
1548         }
1549       else
1550         sorted_children = _gtk_container_focus_sort (container, children, direction, NULL);
1551
1552       return_val = gtk_container_focus_move (container, sorted_children, direction);
1553
1554       g_list_free (sorted_children);
1555       g_list_free (children);
1556     }
1557
1558   return return_val;
1559 }
1560
1561 static gint
1562 tab_compare (gconstpointer a,
1563              gconstpointer b)
1564 {
1565   const GtkWidget *child1 = a;
1566   const GtkWidget *child2 = b;
1567
1568   gint y1 = child1->allocation.y + child1->allocation.height / 2;
1569   gint y2 = child2->allocation.y + child2->allocation.height / 2;
1570
1571   if (y1 == y2)
1572     {
1573       gint x1 = child1->allocation.x + child1->allocation.width / 2;
1574       gint x2 = child2->allocation.x + child2->allocation.width / 2;
1575
1576       return (x1 < x2) ? -1 : ((x1 == x2) ? 0 : 1);
1577     }
1578   else
1579     return (y1 < y2) ? -1 : 1;
1580 }
1581
1582 static GList *
1583 gtk_container_focus_sort_tab (GtkContainer     *container,
1584                               GList            *children,
1585                               GtkDirectionType  direction,
1586                               GtkWidget        *old_focus)
1587 {
1588   children = g_list_sort (children, tab_compare);
1589
1590   /* if we are going backwards then reverse the order
1591    *  of the children.
1592    */
1593   if (direction == GTK_DIR_TAB_BACKWARD)
1594     children = g_list_reverse (children);
1595
1596   return children;
1597 }
1598
1599 /* Get coordinates of @widget's allocation with respect to
1600  * allocation of @container.
1601  */
1602 static gboolean
1603 get_allocation_coords (GtkContainer  *container,
1604                        GtkWidget     *widget,
1605                        GdkRectangle  *allocation)
1606 {
1607   *allocation = widget->allocation;
1608
1609   return gtk_widget_translate_coordinates (widget, GTK_WIDGET (container),
1610                                            0, 0, &allocation->x, &allocation->y);
1611 }
1612
1613 /* Look for a child in @children that is intermediate between
1614  * the focus widget and container. This widget, if it exists,
1615  * acts as the starting widget for focus navigation.
1616  */
1617 static GtkWidget *
1618 find_old_focus (GtkContainer *container,
1619                 GList        *children)
1620 {
1621   GList *tmp_list = children;
1622   while (tmp_list)
1623     {
1624       GtkWidget *child = tmp_list->data;
1625       GtkWidget *widget = child;
1626
1627       while (widget && widget != (GtkWidget *)container)
1628         {
1629           GtkWidget *parent = widget->parent;
1630           if (parent && ((GtkContainer *)parent)->focus_child != widget)
1631             goto next;
1632
1633           widget = parent;
1634         }
1635
1636       return child;
1637
1638     next:
1639       tmp_list = tmp_list->next;
1640     }
1641
1642   return NULL;
1643 }
1644
1645 static gboolean
1646 old_focus_coords (GtkContainer *container,
1647                   GdkRectangle *old_focus_rect)
1648 {
1649   GtkWidget *widget = GTK_WIDGET (container);
1650   GtkWidget *toplevel = gtk_widget_get_toplevel (widget);
1651
1652   if (toplevel && GTK_IS_WINDOW (toplevel) && GTK_WINDOW (toplevel)->focus_widget)
1653     {
1654       GtkWidget *old_focus = GTK_WINDOW (toplevel)->focus_widget;
1655
1656       return get_allocation_coords (container, old_focus, old_focus_rect);
1657     }
1658   else
1659     return FALSE;
1660 }
1661
1662 typedef struct _CompareInfo CompareInfo;
1663
1664 struct _CompareInfo
1665 {
1666   GtkContainer *container;
1667   gint x;
1668   gint y;
1669   gboolean reverse;
1670 };
1671
1672 static gint
1673 up_down_compare (gconstpointer a,
1674                  gconstpointer b,
1675                  gpointer      data)
1676 {
1677   GdkRectangle allocation1;
1678   GdkRectangle allocation2;
1679   CompareInfo *compare = data;
1680   gint y1, y2;
1681
1682   if (!get_allocation_coords (compare->container, (GtkWidget *)a, &allocation1))
1683     return 0;
1684   if (!get_allocation_coords (compare->container, (GtkWidget *)b, &allocation2))
1685     return 0;
1686
1687   y1 = allocation1.y + allocation1.height / 2;
1688   y2 = allocation2.y + allocation2.height / 2;
1689
1690   if (y1 == y2)
1691     {
1692       gint x1 = abs (allocation1.x + allocation1.width / 2 - compare->x);
1693       gint x2 = abs (allocation2.x + allocation2.width / 2 - compare->x);
1694
1695       if (compare->reverse)
1696         return (x1 < x2) ? 1 : ((x1 == x2) ? 0 : -1);
1697       else
1698         return (x1 < x2) ? -1 : ((x1 == x2) ? 0 : 1);
1699     }
1700   else
1701     return (y1 < y2) ? -1 : 1;
1702 }
1703
1704 static GList *
1705 gtk_container_focus_sort_up_down (GtkContainer     *container,
1706                                   GList            *children,
1707                                   GtkDirectionType  direction,
1708                                   GtkWidget        *old_focus)
1709 {
1710   CompareInfo compare;
1711   GList *tmp_list;
1712   GdkRectangle old_allocation;
1713
1714   compare.container = container;
1715   compare.reverse = (direction == GTK_DIR_UP);
1716
1717   if (!old_focus)
1718       old_focus = find_old_focus (container, children);
1719
1720   if (old_focus && get_allocation_coords (container, old_focus, &old_allocation))
1721     {
1722       gint compare_x1;
1723       gint compare_x2;
1724       gint compare_y;
1725
1726       /* Delete widgets from list that don't match minimum criteria */
1727
1728       compare_x1 = old_allocation.x;
1729       compare_x2 = old_allocation.x + old_allocation.width;
1730
1731       if (direction == GTK_DIR_UP)
1732         compare_y = old_allocation.y;
1733       else
1734         compare_y = old_allocation.y + old_allocation.height;
1735
1736       tmp_list = children;
1737       while (tmp_list)
1738         {
1739           GtkWidget *child = tmp_list->data;
1740           GList *next = tmp_list->next;
1741           gint child_x1, child_x2;
1742           GdkRectangle child_allocation;
1743
1744           if (child != old_focus)
1745             {
1746               if (get_allocation_coords (container, child, &child_allocation))
1747                 {
1748                   child_x1 = child_allocation.x;
1749                   child_x2 = child_allocation.x + child_allocation.width;
1750
1751                   if ((child_x2 <= compare_x1 || child_x1 >= compare_x2) /* No horizontal overlap */ ||
1752                       (direction == GTK_DIR_DOWN && child_allocation.y + child_allocation.height < compare_y) || /* Not below */
1753                       (direction == GTK_DIR_UP && child_allocation.y > compare_y)) /* Not above */
1754                     {
1755                       children = g_list_delete_link (children, tmp_list);
1756                     }
1757                 }
1758               else
1759                 children = g_list_delete_link (children, tmp_list);
1760             }
1761
1762           tmp_list = next;
1763         }
1764
1765       compare.x = (compare_x1 + compare_x2) / 2;
1766       compare.y = old_allocation.y + old_allocation.height / 2;
1767     }
1768   else
1769     {
1770       /* No old focus widget, need to figure out starting x,y some other way
1771        */
1772       GtkWidget *widget = GTK_WIDGET (container);
1773       GdkRectangle old_focus_rect;
1774
1775       if (old_focus_coords (container, &old_focus_rect))
1776         {
1777           compare.x = old_focus_rect.x + old_focus_rect.width / 2;
1778         }
1779       else
1780         {
1781           if (GTK_WIDGET_NO_WINDOW (widget))
1782             compare.x = widget->allocation.x + widget->allocation.width / 2;
1783           else
1784             compare.x = widget->allocation.width / 2;
1785         }
1786
1787       if (GTK_WIDGET_NO_WINDOW (widget))
1788         compare.y = (direction == GTK_DIR_DOWN) ? widget->allocation.y : widget->allocation.y + widget->allocation.height;
1789       else
1790         compare.y = (direction == GTK_DIR_DOWN) ? 0 : + widget->allocation.height;
1791     }
1792
1793   children = g_list_sort_with_data (children, up_down_compare, &compare);
1794
1795   if (compare.reverse)
1796     children = g_list_reverse (children);
1797
1798   return children;
1799 }
1800
1801 static gint
1802 left_right_compare (gconstpointer a,
1803                     gconstpointer b,
1804                     gpointer      data)
1805 {
1806   GdkRectangle allocation1;
1807   GdkRectangle allocation2;
1808   CompareInfo *compare = data;
1809   gint x1, x2;
1810
1811   if (!get_allocation_coords (compare->container, (GtkWidget *)a, &allocation1))
1812     return 0;
1813   if (!get_allocation_coords (compare->container, (GtkWidget *)b, &allocation2))
1814     return 0;
1815
1816   x1 = allocation1.x + allocation1.width / 2;
1817   x2 = allocation2.x + allocation2.width / 2;
1818
1819   if (x1 == x2)
1820     {
1821       gint y1 = abs (allocation1.y + allocation1.height / 2 - compare->y);
1822       gint y2 = abs (allocation2.y + allocation2.height / 2 - compare->y);
1823
1824       if (compare->reverse)
1825         return (y1 < y2) ? 1 : ((y1 == y2) ? 0 : -1);
1826       else
1827         return (y1 < y2) ? -1 : ((y1 == y2) ? 0 : 1);
1828     }
1829   else
1830     return (x1 < x2) ? -1 : 1;
1831 }
1832
1833 static GList *
1834 gtk_container_focus_sort_left_right (GtkContainer     *container,
1835                                      GList            *children,
1836                                      GtkDirectionType  direction,
1837                                      GtkWidget        *old_focus)
1838 {
1839   CompareInfo compare;
1840   GList *tmp_list;
1841   GdkRectangle old_allocation;
1842
1843   compare.container = container;
1844   compare.reverse = (direction == GTK_DIR_LEFT);
1845
1846   if (!old_focus)
1847     old_focus = find_old_focus (container, children);
1848
1849   if (old_focus && get_allocation_coords (container, old_focus, &old_allocation))
1850     {
1851       gint compare_y1;
1852       gint compare_y2;
1853       gint compare_x;
1854
1855       /* Delete widgets from list that don't match minimum criteria */
1856
1857       compare_y1 = old_allocation.y;
1858       compare_y2 = old_allocation.y + old_allocation.height;
1859
1860       if (direction == GTK_DIR_LEFT)
1861         compare_x = old_allocation.x;
1862       else
1863         compare_x = old_allocation.x + old_allocation.width;
1864
1865       tmp_list = children;
1866       while (tmp_list)
1867         {
1868           GtkWidget *child = tmp_list->data;
1869           GList *next = tmp_list->next;
1870           gint child_y1, child_y2;
1871           GdkRectangle child_allocation;
1872
1873           if (child != old_focus)
1874             {
1875               if (get_allocation_coords (container, child, &child_allocation))
1876                 {
1877                   child_y1 = child_allocation.y;
1878                   child_y2 = child_allocation.y + child_allocation.height;
1879
1880                   if ((child_y2 <= compare_y1 || child_y1 >= compare_y2) /* No vertical overlap */ ||
1881                       (direction == GTK_DIR_RIGHT && child_allocation.x + child_allocation.width < compare_x) || /* Not to left */
1882                       (direction == GTK_DIR_LEFT && child_allocation.x > compare_x)) /* Not to right */
1883                     {
1884                       children = g_list_delete_link (children, tmp_list);
1885                     }
1886                 }
1887               else
1888                 children = g_list_delete_link (children, tmp_list);
1889             }
1890
1891           tmp_list = next;
1892         }
1893
1894       compare.y = (compare_y1 + compare_y2) / 2;
1895       compare.x = old_allocation.x + old_allocation.width / 2;
1896     }
1897   else
1898     {
1899       /* No old focus widget, need to figure out starting x,y some other way
1900        */
1901       GtkWidget *widget = GTK_WIDGET (container);
1902       GdkRectangle old_focus_rect;
1903
1904       if (old_focus_coords (container, &old_focus_rect))
1905         {
1906           compare.y = old_focus_rect.y + old_focus_rect.height / 2;
1907         }
1908       else
1909         {
1910           if (GTK_WIDGET_NO_WINDOW (widget))
1911             compare.y = widget->allocation.y + widget->allocation.height / 2;
1912           else
1913             compare.y = widget->allocation.height / 2;
1914         }
1915
1916       if (GTK_WIDGET_NO_WINDOW (widget))
1917         compare.x = (direction == GTK_DIR_RIGHT) ? widget->allocation.x : widget->allocation.x + widget->allocation.width;
1918       else
1919         compare.x = (direction == GTK_DIR_RIGHT) ? 0 : widget->allocation.width;
1920     }
1921
1922   children = g_list_sort_with_data (children, left_right_compare, &compare);
1923
1924   if (compare.reverse)
1925     children = g_list_reverse (children);
1926
1927   return children;
1928 }
1929
1930 /**
1931  * gtk_container_focus_sort:
1932  * @container: a #GtkContainer
1933  * @children:  a list of descendents of @container (they don't
1934  *             have to be direct children.
1935  * @direction: focus direction
1936  * @old_focus: widget to use for the starting position, or %NULL
1937  *             to determine this automatically.
1938  *             [ Note, this argument isn't used for GTK_DIR_TAB_*,
1939  *               which is the only @direction we use currently,
1940  *               so perhaps this argument should be removed ]
1941  *
1942  * Sorts @children in the correct order for focusing with
1943  * direction type @direction.
1944  *
1945  * Return value: a copy of @children, sorted in correct focusing order,
1946  *   with children that aren't suitable for focusing in this direction
1947  *   removed.
1948  **/
1949 GList *
1950 _gtk_container_focus_sort (GtkContainer     *container,
1951                            GList            *children,
1952                            GtkDirectionType  direction,
1953                            GtkWidget        *old_focus)
1954 {
1955   children = g_list_copy (children);
1956
1957   switch (direction)
1958     {
1959     case GTK_DIR_TAB_FORWARD:
1960     case GTK_DIR_TAB_BACKWARD:
1961       return gtk_container_focus_sort_tab (container, children, direction, old_focus);
1962     case GTK_DIR_UP:
1963     case GTK_DIR_DOWN:
1964       return gtk_container_focus_sort_up_down (container, children, direction, old_focus);
1965     case GTK_DIR_LEFT:
1966     case GTK_DIR_RIGHT:
1967       return gtk_container_focus_sort_left_right (container, children, direction, old_focus);
1968     }
1969
1970   g_assert_not_reached ();
1971
1972   return NULL;
1973 }
1974
1975 static gboolean
1976 gtk_container_focus_move (GtkContainer     *container,
1977                           GList            *children,
1978                           GtkDirectionType  direction)
1979 {
1980   GtkWidget *focus_child;
1981   GtkWidget *child;
1982
1983   focus_child = container->focus_child;
1984
1985   while (children)
1986     {
1987       child = children->data;
1988       children = children->next;
1989
1990       if (!child)
1991         continue;
1992
1993       if (focus_child)
1994         {
1995           if (focus_child == child)
1996             {
1997               focus_child = NULL;
1998
1999                 if (gtk_widget_child_focus (child, direction))
2000                   return TRUE;
2001             }
2002         }
2003       else if (GTK_WIDGET_DRAWABLE (child) &&
2004                gtk_widget_is_ancestor (child, GTK_WIDGET (container)))
2005         {
2006           if (gtk_widget_child_focus (child, direction))
2007             return TRUE;
2008         }
2009     }
2010
2011   return FALSE;
2012 }
2013
2014
2015 static void
2016 gtk_container_children_callback (GtkWidget *widget,
2017                                  gpointer   client_data)
2018 {
2019   GList **children;
2020
2021   children = (GList**) client_data;
2022   *children = g_list_prepend (*children, widget);
2023 }
2024
2025 static void
2026 chain_widget_destroyed (GtkWidget *widget,
2027                         gpointer   user_data)
2028 {
2029   GtkContainer *container;
2030   GList *chain;
2031
2032   container = GTK_CONTAINER (user_data);
2033
2034   chain = g_object_get_data (G_OBJECT (container),
2035                              "gtk-container-focus-chain");
2036
2037   chain = g_list_remove (chain, widget);
2038
2039   g_signal_handlers_disconnect_by_func (widget,
2040                                         chain_widget_destroyed,
2041                                         user_data);
2042
2043   g_object_set_data (G_OBJECT (container),
2044                      "gtk-container-focus-chain",
2045                      chain);
2046 }
2047
2048 /**
2049  * gtk_container_set_focus_chain:
2050  * @container: a #GtkContainer.
2051  * @focusable_widgets: the new focus chain.
2052  *
2053  * Sets a focus chain, overriding the one computed automatically by GTK+.
2054  *
2055  * In principle each widget in the chain should be a descendant of the
2056  * container, but this is not enforced by this method, since it's allowed
2057  * to set the focus chain before you pack the widgets, or have a widget
2058  * in the chain that isn't always packed. The necessary checks are done
2059  * when the focus chain is actually traversed.
2060  **/
2061 void
2062 gtk_container_set_focus_chain (GtkContainer *container,
2063                                GList        *focusable_widgets)
2064 {
2065   GList *chain;
2066   GList *tmp_list;
2067
2068   g_return_if_fail (GTK_IS_CONTAINER (container));
2069
2070   if (container->has_focus_chain)
2071     gtk_container_unset_focus_chain (container);
2072
2073   container->has_focus_chain = TRUE;
2074
2075   chain = NULL;
2076   tmp_list = focusable_widgets;
2077   while (tmp_list != NULL)
2078     {
2079       g_return_if_fail (GTK_IS_WIDGET (tmp_list->data));
2080
2081       /* In principle each widget in the chain should be a descendant
2082        * of the container, but we don't want to check that here, it's
2083        * expensive and also it's allowed to set the focus chain before
2084        * you pack the widgets, or have a widget in the chain that isn't
2085        * always packed. So we check for ancestor during actual traversal.
2086        */
2087
2088       chain = g_list_prepend (chain, tmp_list->data);
2089
2090       g_signal_connect (tmp_list->data,
2091                         "destroy",
2092                         G_CALLBACK (chain_widget_destroyed),
2093                         container);
2094
2095       tmp_list = g_list_next (tmp_list);
2096     }
2097
2098   chain = g_list_reverse (chain);
2099
2100   g_object_set_data (G_OBJECT (container),
2101                      "gtk-container-focus-chain",
2102                      chain);
2103 }
2104
2105 /**
2106  * gtk_container_get_focus_chain:
2107  * @container:         a #GtkContainer
2108  * @focusable_widgets: location to store the focus chain of the
2109  *                     container, or %NULL. You should free this list
2110  *                     using g_list_free() when you are done with it, however
2111  *                     no additional reference count is added to the
2112  *                     individual widgets in the focus chain.
2113  *
2114  * Retrieves the focus chain of the container, if one has been
2115  * set explicitly. If no focus chain has been explicitly
2116  * set, GTK+ computes the focus chain based on the positions
2117  * of the children. In that case, GTK+ stores %NULL in
2118  * @focusable_widgets and returns %FALSE.
2119  *
2120  * Return value: %TRUE if the focus chain of the container
2121  * has been set explicitly.
2122  **/
2123 gboolean
2124 gtk_container_get_focus_chain (GtkContainer *container,
2125                                GList       **focus_chain)
2126 {
2127   g_return_val_if_fail (GTK_IS_CONTAINER (container), FALSE);
2128
2129   if (focus_chain)
2130     {
2131       if (container->has_focus_chain)
2132         *focus_chain = g_list_copy (get_focus_chain (container));
2133       else
2134         *focus_chain = NULL;
2135     }
2136
2137   return container->has_focus_chain;
2138 }
2139
2140 /**
2141  * gtk_container_unset_focus_chain:
2142  * @container: a #GtkContainer.
2143  *
2144  * Removes a focus chain explicitly set with gtk_container_set_focus_chain().
2145  **/
2146 void
2147 gtk_container_unset_focus_chain (GtkContainer  *container)
2148 {
2149   g_return_if_fail (GTK_IS_CONTAINER (container));
2150
2151   if (container->has_focus_chain)
2152     {
2153       GList *chain;
2154       GList *tmp_list;
2155
2156       chain = get_focus_chain (container);
2157
2158       container->has_focus_chain = FALSE;
2159
2160       g_object_set_data (G_OBJECT (container), "gtk-container-focus-chain",
2161                          NULL);
2162
2163       tmp_list = chain;
2164       while (tmp_list != NULL)
2165         {
2166           g_signal_handlers_disconnect_by_func (tmp_list->data,
2167                                                 chain_widget_destroyed,
2168                                                 container);
2169
2170           tmp_list = g_list_next (tmp_list);
2171         }
2172
2173       g_list_free (chain);
2174     }
2175 }
2176
2177 void
2178 gtk_container_set_focus_vadjustment (GtkContainer  *container,
2179                                      GtkAdjustment *adjustment)
2180 {
2181   g_return_if_fail (GTK_IS_CONTAINER (container));
2182   if (adjustment)
2183     g_return_if_fail (GTK_IS_ADJUSTMENT (adjustment));
2184
2185   if (adjustment)
2186     g_object_ref (adjustment);
2187
2188   g_object_set_qdata_full (G_OBJECT (container),
2189                            vadjustment_key_id,
2190                            adjustment,
2191                            g_object_unref);
2192 }
2193
2194 /**
2195  * gtk_container_get_focus_vadjustment:
2196  * @container: a #GtkContainer
2197  *
2198  * Retrieves the vertical focus adjustment for the container. See
2199  * gtk_container_set_focus_vadjustment ().
2200  *
2201  * Return value: the vertical focus adjustment, or %NULL if
2202  *   none has been set.
2203  **/
2204 GtkAdjustment *
2205 gtk_container_get_focus_vadjustment (GtkContainer *container)
2206 {
2207   GtkAdjustment *vadjustment;
2208
2209   g_return_val_if_fail (GTK_IS_CONTAINER (container), NULL);
2210
2211   vadjustment = g_object_get_qdata (G_OBJECT (container), vadjustment_key_id);
2212
2213   return vadjustment;
2214 }
2215
2216 void
2217 gtk_container_set_focus_hadjustment (GtkContainer  *container,
2218                                      GtkAdjustment *adjustment)
2219 {
2220   g_return_if_fail (GTK_IS_CONTAINER (container));
2221   if (adjustment)
2222     g_return_if_fail (GTK_IS_ADJUSTMENT (adjustment));
2223
2224   if (adjustment)
2225     g_object_ref (adjustment);
2226
2227   g_object_set_qdata_full (G_OBJECT (container),
2228                            hadjustment_key_id,
2229                            adjustment,
2230                            g_object_unref);
2231 }
2232
2233 /**
2234  * gtk_container_get_focus_hadjustment:
2235  * @container: a #GtkContainer
2236  *
2237  * Retrieves the horizontal focus adjustment for the container. See
2238  * gtk_container_set_focus_hadjustment ().
2239  *
2240  * Return value: the horizontal focus adjustment, or %NULL if
2241  *   none has been set.
2242  **/
2243 GtkAdjustment *
2244 gtk_container_get_focus_hadjustment (GtkContainer *container)
2245 {
2246   GtkAdjustment *hadjustment;
2247
2248   g_return_val_if_fail (GTK_IS_CONTAINER (container), NULL);
2249
2250   hadjustment = g_object_get_qdata (G_OBJECT (container), hadjustment_key_id);
2251
2252   return hadjustment;
2253 }
2254
2255
2256 static void
2257 gtk_container_show_all (GtkWidget *widget)
2258 {
2259   g_return_if_fail (GTK_IS_CONTAINER (widget));
2260
2261   gtk_container_foreach (GTK_CONTAINER (widget),
2262                          (GtkCallback) gtk_widget_show_all,
2263                          NULL);
2264   gtk_widget_show (widget);
2265 }
2266
2267 static void
2268 gtk_container_hide_all (GtkWidget *widget)
2269 {
2270   g_return_if_fail (GTK_IS_CONTAINER (widget));
2271
2272   gtk_widget_hide (widget);
2273   gtk_container_foreach (GTK_CONTAINER (widget),
2274                          (GtkCallback) gtk_widget_hide_all,
2275                          NULL);
2276 }
2277
2278
2279 static void
2280 gtk_container_expose_child (GtkWidget *child,
2281                             gpointer   client_data)
2282 {
2283   struct {
2284     GtkWidget *container;
2285     GdkEventExpose *event;
2286   } *data = client_data;
2287
2288   gtk_container_propagate_expose (GTK_CONTAINER (data->container),
2289                                   child,
2290                                   data->event);
2291 }
2292
2293 static gint
2294 gtk_container_expose (GtkWidget      *widget,
2295                       GdkEventExpose *event)
2296 {
2297   struct {
2298     GtkWidget *container;
2299     GdkEventExpose *event;
2300   } data;
2301
2302   g_return_val_if_fail (GTK_IS_CONTAINER (widget), FALSE);
2303   g_return_val_if_fail (event != NULL, FALSE);
2304
2305
2306   if (GTK_WIDGET_DRAWABLE (widget))
2307     {
2308       data.container = widget;
2309       data.event = event;
2310
2311       gtk_container_forall (GTK_CONTAINER (widget),
2312                             gtk_container_expose_child,
2313                             &data);
2314     }
2315
2316   return FALSE;
2317 }
2318
2319 static void
2320 gtk_container_map_child (GtkWidget *child,
2321                          gpointer   client_data)
2322 {
2323   if (GTK_WIDGET_VISIBLE (child) &&
2324       GTK_WIDGET_CHILD_VISIBLE (child) &&
2325       !GTK_WIDGET_MAPPED (child))
2326     gtk_widget_map (child);
2327 }
2328
2329 static void
2330 gtk_container_map (GtkWidget *widget)
2331 {
2332   GTK_WIDGET_SET_FLAGS (widget, GTK_MAPPED);
2333
2334   gtk_container_forall (GTK_CONTAINER (widget),
2335                         gtk_container_map_child,
2336                         NULL);
2337
2338   if (!GTK_WIDGET_NO_WINDOW (widget))
2339     gdk_window_show (widget->window);
2340 }
2341
2342 static void
2343 gtk_container_unmap (GtkWidget *widget)
2344 {
2345   GTK_WIDGET_UNSET_FLAGS (widget, GTK_MAPPED);
2346
2347   if (!GTK_WIDGET_NO_WINDOW (widget))
2348     gdk_window_hide (widget->window);
2349   else
2350     gtk_container_forall (GTK_CONTAINER (widget),
2351                           (GtkCallback)gtk_widget_unmap,
2352                           NULL);
2353 }
2354
2355 /**
2356  * gtk_container_propagate_expose:
2357  * @container: a #GtkContainer
2358  * @child: a child of @container
2359  * @event: a expose event sent to container
2360  *
2361  * When a container receives an expose event, it must send synthetic
2362  * expose events to all children that don't have their own #GdkWindows.
2363  * This function provides a convenient way of doing this. A container,
2364  * when it receives an expose event, calls gtk_container_propagate_expose()
2365  * once for each child, passing in the event the container received.
2366  *
2367  * gtk_container_propagate_expose() takes care of deciding whether
2368  * an expose event needs to be sent to the child, intersecting
2369  * the event's area with the child area, and sending the event.
2370  *
2371  * In most cases, a container can simply either simply inherit the
2372  * ::expose implementation from #GtkContainer, or, do some drawing
2373  * and then chain to the ::expose implementation from #GtkContainer.
2374  **/
2375 void
2376 gtk_container_propagate_expose (GtkContainer   *container,
2377                                 GtkWidget      *child,
2378                                 GdkEventExpose *event)
2379 {
2380   GdkEvent *child_event;
2381
2382   g_return_if_fail (GTK_IS_CONTAINER (container));
2383   g_return_if_fail (GTK_IS_WIDGET (child));
2384   g_return_if_fail (event != NULL);
2385
2386   g_assert (child->parent == GTK_WIDGET (container));
2387
2388   if (GTK_WIDGET_DRAWABLE (child) &&
2389       GTK_WIDGET_NO_WINDOW (child) &&
2390       (child->window == event->window))
2391     {
2392       child_event = gdk_event_new (GDK_EXPOSE);
2393       child_event->expose = *event;
2394       g_object_ref (child_event->expose.window);
2395
2396       child_event->expose.region = gtk_widget_region_intersect (child, event->region);
2397       if (!gdk_region_empty (child_event->expose.region))
2398         {
2399           gdk_region_get_clipbox (child_event->expose.region, &child_event->expose.area);
2400           gtk_widget_send_expose (child, child_event);
2401         }
2402       gdk_event_free (child_event);
2403     }
2404 }