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

   1 /* gtksizerequest.c
   2  * Copyright (C) 2007-2010 Openismus GmbH
   3  *
   4  * Authors:
   5  *      Mathias Hasselmann <mathias@openismus.com>
   6  *      Tristan Van Berkom <tristan.van.berkom@gmail.com>
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Library General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Library General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Library General Public
  19  * License along with this library; if not, write to the
  20  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  21  * Boston, MA 02111-1307, USA.
  22  */
  23
  24
  25 /**
  26  * SECTION:gtksizerequest
  27  * @Short_Description: Height-for-width geometry management
  28  * @Title: GtkWidget
  29  *
  30  * The GtkWidget interface is GTK+'s height-for-width (and width-for-height)
  31  * geometry management system. Height-for-width means that a widget can
  32  * change how much vertical space it needs, depending on the amount
  33  * of horizontal space that it is given (and similar for width-for-height).
  34  * The most common example is a label that reflows to fill up the available
  35  * width, wraps to fewer lines, and therefore needs less height.
  36  *
  37  * GTK+'s traditional two-pass <link linkend="size-allocation">size-allocation</link>
  38  * algorithm does not allow this flexibility. #GtkWidget provides a default
  39  * implementation of the #GtkWidget interface for existing widgets,
  40  * which always requests the same height, regardless of the available width.
  41  *
  42  * <refsect2>
  43  * <title>Implementing GtkWidget</title>
  44  * <para>
  45  * Some important things to keep in mind when implementing
  46  * the GtkWidget interface and when using it in container
  47  * implementations.
  48  *
  49  * The geometry management system will query a logical hierarchy in
  50  * only one orientation at a time. When widgets are initially queried
  51  * for their minimum sizes it is generally done in a dual pass
  52  * in the direction chosen by the toplevel.
  53  *
  54  * For instance when queried in the normal height-for-width mode:
  55  * First the default minimum and natural width for each widget
  56  * in the interface will computed and collectively returned to
  57  * the toplevel by way of gtk_widget_get_preferred_width().
  58  * Next, the toplevel will use the minimum width to query for the
  59  * minimum height contextual to that width using
  60  * gtk_widget_get_preferred_height_for_width(), which will also
  61  * be a highly recursive operation. This minimum-for-minimum size can
  62  * be used to set the minimum size constraint on the toplevel.
  63  *
  64  * When allocating, each container can use the minimum and natural
  65  * sizes reported by their children to allocate natural sizes and
  66  * expose as much content as possible with the given allocation.
  67  *
  68  * That means that the request operation at allocation time will
  69  * usually fire again in contexts of different allocated sizes than
  70  * the ones originally queried for. #GtkWidget caches a
  71  * small number of results to avoid re-querying for the same
  72  * allocated size in one allocation cycle.
  73  *
  74  * A widget that does not actually do height-for-width
  75  * or width-for-height size negotiations only has to implement
  76  * get_preferred_width() and get_preferred_height().
  77  *
  78  * If a widget does move content around to smartly use up the
  79  * allocated size, then it must support the request properly in
  80  * both orientations; even if the request only makes sense in
  81  * one orientation.
  82  *
  83  * For instance, a GtkLabel that does height-for-width word wrapping
  84  * will not expect to have get_preferred_height() called because that
  85  * call is specific to a width-for-height request, in this case the
  86  * label must return the heights contextual to its minimum possible
  87  * width. By following this rule any widget that handles height-for-width
  88  * or width-for-height requests will always be allocated at least
  89  * enough space to fit its own content.
  90  *
  91  * Often a widget needs to get its own request during size request or
  92  * allocation, for example when computing height it may need to also
  93  * compute width, or when deciding how to use an allocation the widget may
  94  * need to know its natural size. In these cases, the widget should be
  95  * careful to call its virtual methods directly, like this:
  96  * <example>
  97  *   <title>Widget calling its own size request method.</title>
  98  *   <programlisting>
  99  * GTK_WIDGET_GET_CLASS(widget)-&gt;get_preferred_width (widget), &min, &natural);
 100  *   </programlisting>
 101  * </example>
 102  *
 103  * It will not work to use the wrapper functions, such as
 104  * gtk_widget_get_preferred_width(), inside your own size request
 105  * implementation. These return a request adjusted by #GtkSizeGroup
 106  * and by the GtkWidgetClass::adjust_size_request virtual method. If a
 107  * widget used the wrappers inside its virtual method implementations,
 108  * then the adjustments (such as widget margins) would be applied
 109  * twice. GTK+ therefore does not allow this and will warn if you try
 110  * to do it.
 111  *
 112  * Of course if you are getting the size request for
 113  * <emphasis>another</emphasis> widget, such as a child of a
 114  * container, you <emphasis>must</emphasis> use the wrapper APIs;
 115  * otherwise, you would not properly consider widget margins,
 116  * #GtkSizeGroup, and so forth.
 117  * </para>
 118  * </refsect2>
 119  */
 120
 121
 122 #include <config.h>
 123 #include "gtksizerequest.h"
 124 #include "gtksizegroup.h"
 125 #include "gtkdebug.h"
 126 #include "gtkprivate.h"
 127 #include "gtkintl.h"
 128
 129 /* looks for a cached size request for this for_size. If not
 130  * found, returns the oldest entry so it can be overwritten
 131  *
 132  * Note that this caching code was directly derived from
 133  * the Clutter toolkit.
 134  */
 135 static gboolean
 136 get_cached_size (SizeRequestCache  *cache,
 137                  GtkSizeGroupMode   orientation,
 138                  gint               for_size,
 139                  SizeRequest      **result)
 140 {
 141   guint i, n_sizes;
 142   SizeRequest  *cached_sizes;
 143
 144   if (orientation == GTK_SIZE_GROUP_HORIZONTAL)
 145     {
 146       cached_sizes = cache->widths;
 147       n_sizes = cache->cached_widths;
 148     }
 149   else
 150     {
 151       cached_sizes = cache->heights;
 152       n_sizes = cache->cached_widths;
 153     }
 154
 155   /* Search for an already cached size */
 156   for (i = 0; i < n_sizes; i++)
 157     {
 158       if (cached_sizes[i].for_size == for_size)
 159         {
 160           *result = &cached_sizes[i];
 161           return TRUE;
 162         }
 163     }
 164
 165   /* If not found, pull a new size from the cache, the returned size cache
 166    * will immediately be used to cache the new computed size so we go ahead
 167    * and increment the last_cached_width/height right away */
 168   if (orientation == GTK_SIZE_GROUP_HORIZONTAL)
 169     {
 170       if (cache->cached_widths < GTK_SIZE_REQUEST_CACHED_SIZES)
 171         {
 172           cache->cached_widths++;
 173           cache->last_cached_width = cache->cached_widths - 1;
 174         }
 175       else
 176         {
 177           if (++cache->last_cached_width == GTK_SIZE_REQUEST_CACHED_SIZES)
 178             cache->last_cached_width = 0;
 179         }
 180
 181       *result = &cache->widths[cache->last_cached_width];
 182     }
 183   else /* GTK_SIZE_GROUP_VERTICAL */
 184     {
 185       if (cache->cached_heights < GTK_SIZE_REQUEST_CACHED_SIZES)
 186         {
 187           cache->cached_heights++;
 188           cache->last_cached_height = cache->cached_heights - 1;
 189         }
 190       else
 191         {
 192           if (++cache->last_cached_height == GTK_SIZE_REQUEST_CACHED_SIZES)
 193             cache->last_cached_height = 0;
 194         }
 195
 196       *result = &cache->heights[cache->last_cached_height];
 197     }
 198
 199   return FALSE;
 200 }
 201
 202 static void
 203 do_size_request (GtkWidget      *widget,
 204                  GtkRequisition *requisition)
 205 {
 206   /* Now we dont bother caching the deprecated "size-request" returns,
 207    * just unconditionally invoke here just in case we run into legacy stuff */
 208   gtk_widget_ensure_style (widget);
 209   g_signal_emit_by_name (widget, "size-request", requisition);
 210 }
 211
 212 #ifndef G_DISABLE_CHECKS
 213 static GQuark recursion_check_quark = 0;
 214 #endif /* G_DISABLE_CHECKS */
 215
 216 static void
 217 push_recursion_check (GtkWidget       *request,
 218                       GtkSizeGroupMode orientation,
 219                       gint             for_size)
 220 {
 221 #ifndef G_DISABLE_CHECKS
 222   const char *previous_method;
 223   const char *method;
 224
 225   if (recursion_check_quark == 0)
 226     recursion_check_quark = g_quark_from_static_string ("gtk-size-request-in-progress");
 227
 228   previous_method = g_object_get_qdata (G_OBJECT (request), recursion_check_quark);
 229
 230   if (orientation == GTK_SIZE_GROUP_HORIZONTAL)
 231     {
 232       method = for_size < 0 ? "get_width" : "get_width_for_height";
 233     }
 234   else
 235     {
 236       method = for_size < 0 ? "get_height" : "get_height_for_width";
 237     }
 238
 239   if (previous_method != NULL)
 240     {
 241       g_warning ("%s %p: widget tried to gtk_widget_%s inside "
 242                  " GtkWidget     ::%s implementation. "
 243                  "Should just invoke GTK_WIDGET_GET_CLASS(widget)->%s "
 244                  "directly rather than using gtk_widget_%s",
 245                  G_OBJECT_TYPE_NAME (request), request,
 246                  method, previous_method,
 247                  method, method);
 248     }
 249
 250   g_object_set_qdata (G_OBJECT (request), recursion_check_quark, (char*) method);
 251 #endif /* G_DISABLE_CHECKS */
 252 }
 253
 254 static void
 255 pop_recursion_check (GtkWidget       *request,
 256                      GtkSizeGroupMode orientation)
 257 {
 258 #ifndef G_DISABLE_CHECKS
 259   g_object_set_qdata (G_OBJECT (request), recursion_check_quark, NULL);
 260 #endif
 261 }
 262
 263 static void
 264 compute_size_for_orientation (GtkWidget         *request,
 265                               GtkSizeGroupMode   orientation,
 266                               gint               for_size,
 267                               gint              *minimum_size,
 268                               gint              *natural_size)
 269 {
 270   SizeRequestCache *cache;
 271   SizeRequest      *cached_size;
 272   GtkWidget        *widget;
 273   gboolean          found_in_cache = FALSE;
 274   int adjusted_min, adjusted_natural;
 275
 276   g_return_if_fail (GTK_IS_WIDGET (request));
 277   g_return_if_fail (minimum_size != NULL || natural_size != NULL);
 278
 279   widget = GTK_WIDGET (request);
 280   cache  = _gtk_widget_peek_request_cache (widget);
 281
 282   if (orientation == GTK_SIZE_GROUP_HORIZONTAL)
 283     {
 284       cached_size = &cache->widths[0];
 285
 286       if (!_gtk_widget_get_width_request_needed (widget))
 287         found_in_cache = get_cached_size (cache, orientation, for_size, &cached_size);
 288       else
 289         {
 290           memset (cache->widths, 0, GTK_SIZE_REQUEST_CACHED_SIZES * sizeof (SizeRequest));
 291           cache->cached_widths = 1;
 292           cache->last_cached_width = 0;
 293         }
 294     }
 295   else
 296     {
 297       cached_size = &cache->heights[0];
 298
 299       if (!_gtk_widget_get_height_request_needed (widget))
 300         found_in_cache = get_cached_size (cache, orientation, for_size, &cached_size);
 301       else
 302         {
 303           memset (cache->heights, 0, GTK_SIZE_REQUEST_CACHED_SIZES * sizeof (SizeRequest));
 304           cache->cached_heights = 1;
 305           cache->last_cached_height = 0;
 306         }
 307     }
 308
 309   if (!found_in_cache)
 310     {
 311       GtkRequisition requisition = { 0, 0 };
 312       gint min_size = 0, nat_size = 0;
 313       gint requisition_size;
 314
 315       /* Unconditional size request runs but is often unhandled. */
 316       do_size_request (widget, &requisition);
 317
 318       push_recursion_check (request, orientation, for_size);
 319       if (orientation == GTK_SIZE_GROUP_HORIZONTAL)
 320         {
 321           requisition_size = requisition.width;
 322
 323           if (for_size < 0)
 324             GTK_WIDGET_GET_CLASS (request)->get_preferred_width (request, &min_size, &nat_size);
 325           else
 326             GTK_WIDGET_GET_CLASS (request)->get_preferred_width_for_height (request, for_size,
 327                                                                                   &min_size, &nat_size);
 328         }
 329       else
 330         {
 331           requisition_size = requisition.height;
 332
 333           if (for_size < 0)
 334             GTK_WIDGET_GET_CLASS (request)->get_preferred_height (request, &min_size, &nat_size);
 335           else
 336             GTK_WIDGET_GET_CLASS (request)->get_preferred_height_for_width (request, for_size,
 337                                                                                   &min_size, &nat_size);
 338         }
 339       pop_recursion_check (request, orientation);
 340
 341       if (min_size > nat_size)
 342         {
 343           g_warning ("%s %p reported min size %d and natural size %d; natural size must be >= min size",
 344                      G_OBJECT_TYPE_NAME (request), request, min_size, nat_size);
 345         }
 346
 347       /* Support for dangling "size-request" signal implementations on
 348        * legacy widgets
 349        */
 350       min_size = MAX (min_size, requisition_size);
 351       nat_size = MAX (nat_size, requisition_size);
 352
 353       cached_size->minimum_size = min_size;
 354       cached_size->natural_size = nat_size;
 355       cached_size->for_size     = for_size;
 356
 357       if (orientation == GTK_SIZE_GROUP_HORIZONTAL)
 358           _gtk_widget_set_width_request_needed (widget, FALSE);
 359       else
 360           _gtk_widget_set_height_request_needed (widget, FALSE);
 361
 362       adjusted_min = cached_size->minimum_size;
 363       adjusted_natural = cached_size->natural_size;
 364       GTK_WIDGET_GET_CLASS (request)->adjust_size_request (GTK_WIDGET (request),
 365                                                            orientation == GTK_SIZE_GROUP_HORIZONTAL ?
 366                                                            GTK_ORIENTATION_HORIZONTAL :
 367                                                            GTK_ORIENTATION_VERTICAL,
 368                                                            cached_size->for_size,
 369                                                            &adjusted_min,
 370                                                            &adjusted_natural);
 371
 372       if (adjusted_min < cached_size->minimum_size ||
 373           adjusted_natural < cached_size->natural_size)
 374         {
 375           g_warning ("%s %p adjusted size %s min %d natural %d must not decrease below min %d natural %d",
 376                      G_OBJECT_TYPE_NAME (request), request,
 377                      orientation == GTK_SIZE_GROUP_VERTICAL ? "vertical" : "horizontal",
 378                      adjusted_min, adjusted_natural,
 379                      cached_size->minimum_size, cached_size->natural_size);
 380           /* don't use the adjustment */
 381         }
 382       else if (adjusted_min > adjusted_natural)
 383         {
 384           g_warning ("%s %p adjusted size %s min %d natural %d original min %d natural %d has min greater than natural",
 385                      G_OBJECT_TYPE_NAME (request), request,
 386                      orientation == GTK_SIZE_GROUP_VERTICAL ? "vertical" : "horizontal",
 387                      adjusted_min, adjusted_natural,
 388                      cached_size->minimum_size, cached_size->natural_size);
 389           /* don't use the adjustment */
 390         }
 391       else
 392         {
 393           /* adjustment looks good */
 394           cached_size->minimum_size = adjusted_min;
 395           cached_size->natural_size = adjusted_natural;
 396         }
 397
 398       /* Update size-groups with our request and update our cached requests
 399        * with the size-group values in a single pass.
 400        */
 401       _gtk_size_group_bump_requisition (GTK_WIDGET (request),
 402                                         orientation,
 403                                         &cached_size->minimum_size,
 404                                         &cached_size->natural_size);
 405     }
 406
 407   if (minimum_size)
 408     *minimum_size = cached_size->minimum_size;
 409
 410   if (natural_size)
 411     *natural_size = cached_size->natural_size;
 412
 413   g_assert (cached_size->minimum_size <= cached_size->natural_size);
 414
 415   GTK_NOTE (SIZE_REQUEST,
 416             g_print ("[%p] %s\t%s: %d is minimum %d and natural: %d (hit cache: %s)\n",
 417                      request, G_OBJECT_TYPE_NAME (request),
 418                      orientation == GTK_SIZE_GROUP_HORIZONTAL ?
 419                      "width for height" : "height for width" ,
 420                      for_size,
 421                      cached_size->minimum_size,
 422                      cached_size->natural_size,
 423                      found_in_cache ? "yes" : "no"));
 424
 425 }
 426
 427 /**
 428  * gtk_widget_get_request_mode:
 429  * @widget: a #GtkWidget instance
 430  *
 431  * Gets whether the widget prefers a height-for-width layout
 432  * or a width-for-height layout.
 433  *
 434  * <note><para>#GtkBin widgets generally propagate the preference of
 435  * their child, container widgets need to request something either in
 436  * context of their children or in context of their allocation
 437  * capabilities.</para></note>
 438  *
 439  * Returns: The #GtkSizeRequestMode preferred by @widget.
 440  *
 441  * Since: 3.0
 442  */
 443 GtkSizeRequestMode
 444 gtk_widget_get_request_mode (GtkWidget *widget)
 445 {
 446   GtkWidgetClass *klass;
 447
 448   g_return_val_if_fail (GTK_IS_WIDGET (widget), GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH);
 449
 450   klass = GTK_WIDGET_GET_CLASS (widget);
 451   if (klass->get_request_mode)
 452     return klass->get_request_mode (widget);
 453
 454   /* By default widgets are height-for-width. */
 455   return GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH;
 456 }
 457
 458 /**
 459  * gtk_widget_get_preferred_width:
 460  * @widget: a #GtkWidget instance
 461  * @minimum_width: (out) (allow-none): location to store the minimum width, or %NULL
 462  * @natural_width: (out) (allow-none): location to store the natural width, or %NULL
 463  *
 464  * Retrieves a widget's initial minimum and natural width.
 465  *
 466  * <note><para>This call is specific to height-for-width
 467  * requests.</para></note>
 468  *
 469  * The returned request will be modified by the
 470  * GtkWidgetClass::adjust_size_request virtual method and by any
 471  * #GtkSizeGroup that have been applied. That is, the returned request
 472  * is the one that should be used for layout, not necessarily the one
 473  * returned by the widget itself.
 474  *
 475  * Since: 3.0
 476  */
 477 void
 478 gtk_widget_get_preferred_width (GtkWidget *widget,
 479                                 gint      *minimum_width,
 480                                 gint      *natural_width)
 481 {
 482   compute_size_for_orientation (widget, GTK_SIZE_GROUP_HORIZONTAL,
 483                                 -1, minimum_width, natural_width);
 484 }
 485
 486
 487 /**
 488  * gtk_widget_get_preferred_height:
 489  * @widget: a #GtkWidget instance
 490  * @minimum_height: (out) (allow-none): location to store the minimum height, or %NULL
 491  * @natural_height: (out) (allow-none): location to store the natural height, or %NULL
 492  *
 493  * Retrieves a widget's initial minimum and natural height.
 494  *
 495  * <note><para>This call is specific to width-for-height requests.</para></note>
 496  *
 497  * The returned request will be modified by the
 498  * GtkWidgetClass::adjust_size_request virtual method and by any
 499  * #GtkSizeGroup that have been applied. That is, the returned request
 500  * is the one that should be used for layout, not necessarily the one
 501  * returned by the widget itself.
 502  *
 503  * Since: 3.0
 504  */
 505 void
 506 gtk_widget_get_preferred_height (GtkWidget *widget,
 507                                  gint      *minimum_height,
 508                                  gint      *natural_height)
 509 {
 510   compute_size_for_orientation (widget, GTK_SIZE_GROUP_VERTICAL,
 511                                 -1, minimum_height, natural_height);
 512 }
 513
 514
 515
 516 /**
 517  * gtk_widget_get_preferred_width_for_height:
 518  * @widget: a #GtkWidget instance
 519  * @height: the height which is available for allocation
 520  * @minimum_width: (out) (allow-none): location for storing the minimum width, or %NULL
 521  * @natural_width: (out) (allow-none): location for storing the natural width, or %NULL
 522  *
 523  * Retrieves a widget's minimum and natural width if it would be given
 524  * the specified @height.
 525  *
 526  * The returned request will be modified by the
 527  * GtkWidgetClass::adjust_size_request virtual method and by any
 528  * #GtkSizeGroup that have been applied. That is, the returned request
 529  * is the one that should be used for layout, not necessarily the one
 530  * returned by the widget itself.
 531  *
 532  * Since: 3.0
 533  */
 534 void
 535 gtk_widget_get_preferred_width_for_height (GtkWidget *widget,
 536                                            gint       height,
 537                                            gint      *minimum_width,
 538                                            gint      *natural_width)
 539 {
 540   compute_size_for_orientation (widget, GTK_SIZE_GROUP_HORIZONTAL,
 541                                 height, minimum_width, natural_width);
 542 }
 543
 544 /**
 545  * gtk_widget_get_preferred_height_for_width:
 546  * @widget: a #GtkWidget instance
 547  * @width: the width which is available for allocation
 548  * @minimum_height: (out) (allow-none): location for storing the minimum height, or %NULL
 549  * @natural_height: (out) (allow-none): location for storing the natural height, or %NULL
 550  *
 551  * Retrieves a widget's minimum and natural height if it would be given
 552  * the specified @width.
 553  *
 554  * The returned request will be modified by the
 555  * GtkWidgetClass::adjust_size_request virtual method and by any
 556  * #GtkSizeGroup that have been applied. That is, the returned request
 557  * is the one that should be used for layout, not necessarily the one
 558  * returned by the widget itself.
 559  *
 560  * Since: 3.0
 561  */
 562 void
 563 gtk_widget_get_preferred_height_for_width (GtkWidget *widget,
 564                                            gint       width,
 565                                            gint      *minimum_height,
 566                                            gint      *natural_height)
 567 {
 568   compute_size_for_orientation (widget, GTK_SIZE_GROUP_VERTICAL,
 569                                 width, minimum_height, natural_height);
 570 }
 571
 572 /**
 573  * gtk_widget_get_preferred_size:
 574  * @widget: a #GtkWidget instance
 575  * @minimum_size: (out) (allow-none): location for storing the minimum size, or %NULL
 576  * @natural_size: (out) (allow-none): location for storing the natural size, or %NULL
 577  *
 578  * Retrieves the minimum and natural size of a widget taking
 579  * into account the widget's preference for height-for-width management.
 580  *
 581  * This is used to retrieve a suitable size by container widgets which do
 582  * not impose any restrictions on the child placement.
 583  *
 584  * Since: 3.0
 585  */
 586 void
 587 gtk_widget_get_preferred_size (GtkWidget      *widget,
 588                                GtkRequisition *minimum_size,
 589                                GtkRequisition *natural_size)
 590 {
 591   gint min_width, nat_width;
 592   gint min_height, nat_height;
 593
 594   g_return_if_fail (GTK_IS_WIDGET (widget));
 595
 596   if (gtk_widget_get_request_mode (widget) == GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH)
 597     {
 598       gtk_widget_get_preferred_width (widget, &min_width, &nat_width);
 599
 600       if (minimum_size)
 601         {
 602           minimum_size->width = min_width;
 603           gtk_widget_get_preferred_height_for_width (widget, min_width,
 604                                                      &minimum_size->height, NULL);
 605         }
 606
 607       if (natural_size)
 608         {
 609           natural_size->width = nat_width;
 610           gtk_widget_get_preferred_height_for_width (widget, nat_width,
 611                                                      NULL, &natural_size->height);
 612         }
 613     }
 614   else /* GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT */
 615     {
 616       gtk_widget_get_preferred_height (widget, &min_height, &nat_height);
 617
 618       if (minimum_size)
 619         {
 620           minimum_size->height = min_height;
 621           gtk_widget_get_preferred_width_for_height (widget, min_height,
 622                                                      &minimum_size->width, NULL);
 623         }
 624
 625       if (natural_size)
 626         {
 627           natural_size->height = nat_height;
 628           gtk_widget_get_preferred_width_for_height (widget, nat_height,
 629                                                      NULL, &natural_size->width);
 630         }
 631     }
 632 }
 633
 634
 635 static gint
 636 compare_gap (gconstpointer p1,
 637              gconstpointer p2,
 638              gpointer      data)
 639 {
 640   GtkRequestedSize *sizes = data;
 641   const guint *c1 = p1;
 642   const guint *c2 = p2;
 643
 644   const gint d1 = MAX (sizes[*c1].natural_size -
 645                        sizes[*c1].minimum_size,
 646                        0);
 647   const gint d2 = MAX (sizes[*c2].natural_size -
 648                        sizes[*c2].minimum_size,
 649                        0);
 650
 651   gint delta = (d2 - d1);
 652
 653   if (0 == delta)
 654     delta = (*c2 - *c1);
 655
 656   return delta;
 657 }
 658
 659 /**
 660  * gtk_distribute_natural_allocation:
 661  * @extra_space: Extra space to redistribute among children after subtracting
 662  *               minimum sizes and any child padding from the overall allocation
 663  * @n_requested_sizes: Number of requests to fit into the allocation
 664  * @sizes: An array of structs with a client pointer and a minimum/natural size
 665  *         in the orientation of the allocation.
 666  *
 667  * Distributes @extra_space to child @sizes by bringing up smaller
 668  * children up to natural size first.
 669  *
 670  * The remaining space will be added to the @minimum_size member of the
 671  * GtkRequestedSize struct. If all sizes reach their natural size then
 672  * the remaining space is returned.
 673  *
 674  * Returns: The remainder of @extra_space after redistributing space
 675  * to @sizes.
 676  */
 677 gint
 678 gtk_distribute_natural_allocation (gint              extra_space,
 679                                    guint             n_requested_sizes,
 680                                    GtkRequestedSize *sizes)
 681 {
 682   guint *spreading;
 683   gint   i;
 684
 685   g_return_val_if_fail (extra_space >= 0, 0);
 686
 687   spreading = g_newa (guint, n_requested_sizes);
 688
 689   for (i = 0; i < n_requested_sizes; i++)
 690     spreading[i] = i;
 691
 692   /* Distribute the container's extra space c_gap. We want to assign
 693    * this space such that the sum of extra space assigned to children
 694    * (c^i_gap) is equal to c_cap. The case that there's not enough
 695    * space for all children to take their natural size needs some
 696    * attention. The goals we want to achieve are:
 697    *
 698    *   a) Maximize number of children taking their natural size.
 699    *   b) The allocated size of children should be a continuous
 700    *   function of c_gap.  That is, increasing the container size by
 701    *   one pixel should never make drastic changes in the distribution.
 702    *   c) If child i takes its natural size and child j doesn't,
 703    *   child j should have received at least as much gap as child i.
 704    *
 705    * The following code distributes the additional space by following
 706    * these rules.
 707    */
 708
 709   /* Sort descending by gap and position. */
 710   g_qsort_with_data (spreading,
 711                      n_requested_sizes, sizeof (guint),
 712                      compare_gap, sizes);
 713
 714   /* Distribute available space.
 715    * This master piece of a loop was conceived by Behdad Esfahbod.
 716    */
 717   for (i = n_requested_sizes - 1; extra_space > 0 && i >= 0; --i)
 718     {
 719       /* Divide remaining space by number of remaining children.
 720        * Sort order and reducing remaining space by assigned space
 721        * ensures that space is distributed equally.
 722        */
 723       gint glue = (extra_space + i) / (i + 1);
 724       gint gap = sizes[(spreading[i])].natural_size
 725         - sizes[(spreading[i])].minimum_size;
 726
 727       gint extra = MIN (glue, gap);
 728
 729       sizes[spreading[i]].minimum_size += extra;
 730
 731       extra_space -= extra;
 732     }
 733
 734   return extra_space;
 735 }
 736