[gtkmm] Widget::get_allocation(): Add the newer documentation from the C docs.

[Murray Cumming <murrayc src gnome org>]

commit adc6e781040b48f9df8795d85764edecc37fbb3e
Author: Murray Cumming <murrayc murrayc com>
Date:   Fri Sep 9 08:50:04 2011 +0200

    Widget::get_allocation(): Add the newer documentation from the C docs.
    
    * gtk/src/widget.hg: gtk_widget_get_allocation() now has extra hints about
    implementing containers.

 ChangeLog         |    7 +++++++
 gtk/src/widget.hg |   11 +++++++++++
 2 files changed, 18 insertions(+), 0 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 48d32e5..6a858a4 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2011-09-09  Murray Cumming  <murrayc murrayc com>
+
+	Widget::get_allocation(): Add the newer documentation from the C docs.
+
+	* gtk/src/widget.hg: gtk_widget_get_allocation() now has extra hints about 
+	implementing containers.
+	
 2011-09-07  Kjell Ahlstedt  <kjell ahlstedt bredband net>
 
 	TreeView: Make append_column_numeric_editable() work for [unsigned] short.
diff --git a/gtk/src/widget.hg b/gtk/src/widget.hg
index c1dde5a..5e4a9ac 100644
--- a/gtk/src/widget.hg
+++ b/gtk/src/widget.hg
@@ -252,6 +252,17 @@ public:
   _WRAP_METHOD(int get_allocated_height() const, gtk_widget_get_allocated_height)
 
   /** Retrieves the widget's location.
+   * Note, when implementing a Container: a widget's allocation will be its "adjusted" allocation, 
+   * that is, the widget's parent container typically calls size_allocate() with an allocation, 
+   * and that allocation is then adjusted (to handle margin and alignment for example) before 
+   * assignment to the widget. get_allocation() returns the adjusted allocation that was actually 
+   * assigned to the widget. The adjusted allocation is guaranteed to be completely contained 
+   * within the size_allocate() allocation, however. So a Container is guaranteed that its 
+   * children stay inside the assigned bounds, but not that they have exactly the bounds the 
+   * container assigned. There is no way to get the original allocation assigned by 
+   * size_allocate(), since it isn't stored. If a container implementation needs that information 
+   * it will have to track it itself. 
+   *
    * @return The widget's allocated area.
    */
   Allocation get_allocation() const;