[gnome-panel/wip/packed-objects: 16/17] panel: Add comments to explain how the size hints interaction works

[Vincent Untz <vuntz src gnome org>]

commit 9710f88acfb6392e41722f89b265778de2b3d2a0
Author: Vincent Untz <vuntz gnome org>
Date:   Thu Mar 31 11:13:18 2011 +0530

    panel: Add comments to explain how the size hints interaction works
    
    We use size hints in PanelToplevel to compute the size of a packed
    panel, and this is then used in size_allocate() of the PanelWidget to
    know how much size to allocate to an object with size hints.

 gnome-panel/panel-toplevel.c |   15 ++++++++++++++-
 1 files changed, 14 insertions(+), 1 deletions(-)
---
diff --git a/gnome-panel/panel-toplevel.c b/gnome-panel/panel-toplevel.c
index 5fd0176..132373c 100644
--- a/gnome-panel/panel-toplevel.c
+++ b/gnome-panel/panel-toplevel.c
@@ -2342,7 +2342,14 @@ panel_toplevel_update_size_from_hints (PanelToplevel  *toplevel,
 
 			current_bonus = bonus;
 
-			while (using_hint[i].index > 0 && applets_hints[i].hints[using_hint[i].index - 1] < using_hint[i].size + current_bonus) {
+			/* first find the (max, min) range in hints that we
+			 * will use; since we try to allocate as much size as
+			 * possible, this means we want the (max, min) range
+			 * where min is the highest possible (ie, the range
+			 * with the smaller index possible), while still
+			 * keeping min smaller than the potential new size */
+			while (using_hint[i].index > 0 &&
+			       applets_hints[i].hints[using_hint[i].index - 1] < using_hint[i].size + current_bonus) {
 				new_size = applets_hints[i].hints[using_hint[i].index - 1];
 				current_bonus = using_hint[i].size
 						+ current_bonus - new_size;
@@ -2353,6 +2360,9 @@ panel_toplevel_update_size_from_hints (PanelToplevel  *toplevel,
 				using_hint[i].size = new_size;
 			}
 
+			/* now, give the bonus, while still keeping a size that
+			 * is lower than max from the (max, min) range we've
+			 * settled for */
 			new_size = MIN (applets_hints[i].hints[using_hint[i].index],
 					using_hint[i].size + current_bonus);
 			if (new_size > using_hint[i].size) {
@@ -2360,6 +2370,9 @@ panel_toplevel_update_size_from_hints (PanelToplevel  *toplevel,
 				using_hint[i].size = new_size;
 			}
 
+
+			/* if there's some extra bonus to take, try to allocate
+			 * it too */
 			if (extra_bonus > 0) {
 				new_size = MIN (applets_hints[i].hints[using_hint[i].index],
 						using_hint[i].size + extra_bonus);