[gtkmm] CellAreaContext: Correct the documentation.

[Murray Cumming <murrayc src gnome org>]

commit 6a1d8e41e8a57d65432270c4c9506996d54003be
Author: Murray Cumming <murrayc murrayc com>
Date:   Thu May 12 10:31:07 2011 +0200

    CellAreaContext: Correct the documentation.
    
    * gtk/src/cellareacontext.hg: Write overview documentation based on the C
    documentation. This was previously a completely wrong copy/paste from some
    other class.

 ChangeLog                  |    8 ++++++++
 gtk/src/cellarea.hg        |   27 +++++++++++++++------------
 gtk/src/cellareacontext.hg |   31 +++++++++++++++----------------
 3 files changed, 38 insertions(+), 28 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 073f11a..eaf0831 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2011-05-12  Murray Cumming  <murrayc murrayc com>
+
+	CellAreaContext: Correct the documentation.
+
+	* gtk/src/cellareacontext.hg: Write overview documentation based on the C
+	documentation. This was previously a completely wrong copy/paste from some
+	other class.
+
 2011-05-02  Kalev Lember  <kalev smartlink ee>
 
 	Don't build Gtk::Plug and Gtk::Socket on WIN32
diff --git a/gtk/src/cellarea.hg b/gtk/src/cellarea.hg
index c6dffc7..c005b56 100644
--- a/gtk/src/cellarea.hg
+++ b/gtk/src/cellarea.hg
@@ -42,7 +42,7 @@ namespace Gtk
  * unless they are implementing a cell layouting widget themselves.
  *
  * Requesting area sizes
- * 
+ *
  * As outlined in Gtk::Widget's
  * geometry management description, GTK+ uses a height-for-width
  * geometry management system to compute the sizes of widgets and user
@@ -76,7 +76,7 @@ namespace Gtk
  * used when rendering or processing events for that row.
  *
  * Cell Properties
- * 
+ *
  * The CellArea introduces cell propertie
  * for CellRenderers in very much the same way that Gtk::Container
  * introduces child properties
@@ -101,7 +101,7 @@ class CellArea
   _DERIVES_INITIALLY_UNOWNED()
   _IMPLEMENTS_INTERFACE(Buildable)
   _IMPLEMENTS_INTERFACE(CellLayout)
-  
+
 protected:
   _CTOR_DEFAULT
 public:
@@ -115,12 +115,12 @@ public:
   _WRAP_METHOD(void render(const Glib::RefPtr<CellAreaContext>& context, Widget& widget, const Cairo::RefPtr<Cairo::Context>& cr, const Gdk::Rectangle& background_area, const Gdk::Rectangle& cell_area, CellRendererState flags,  bool paint_focus), gtk_cell_area_render)
 
   _WRAP_METHOD(void get_cell_allocation(const Glib::RefPtr<CellAreaContext>& context, Widget& widget, CellRenderer& renderer,  const Gdk::Rectangle& cell_area, Gdk::Rectangle& allocation), gtk_cell_area_get_cell_allocation)
-  
+
   _WRAP_METHOD(CellRenderer* get_cell_at_position(const Glib::RefPtr<CellAreaContext>& context, Widget& widget, const Gdk::Rectangle& cell_area, int x, int y, Gdk::Rectangle& alloc_area), gtk_cell_area_get_cell_at_position)
   _WRAP_METHOD(const CellRenderer* get_cell_at_position(const Glib::RefPtr<CellAreaContext>& context, Widget& widget, const Gdk::Rectangle& cell_area, int x, int y, Gdk::Rectangle& alloc_area) const, gtk_cell_area_get_cell_at_position, constversion)
 
   _WRAP_METHOD(Glib::RefPtr<CellAreaContext> create_context() const, gtk_cell_area_create_context)
-  
+
   _WRAP_METHOD(Glib::RefPtr<CellAreaContext> copy_context(const Glib::RefPtr<const CellAreaContext>& context), gtk_cell_area_copy_context)
 
   _WRAP_METHOD(SizeRequestMode get_request_mode() const, gtk_cell_area_get_request_mode)
@@ -143,7 +143,7 @@ public:
   _WRAP_METHOD(bool activate(const Glib::RefPtr<CellAreaContext>& context, Widget& widget, const Gdk::Rectangle& cell_area, CellRendererState flags, bool edit_only), gtk_cell_area_activate)
   _WRAP_METHOD(bool focus(DirectionType direction), gtk_cell_area_focus)
   _WRAP_METHOD(void set_focus_cell(CellRenderer& renderer), gtk_cell_area_set_focus_cell)
-  
+
   _WRAP_METHOD(CellRenderer* get_focus_cell(), gtk_cell_area_get_focus_cell)
   _WRAP_METHOD(const CellRenderer* get_focus_cell() const, gtk_cell_area_get_focus_cell, constversion)
 
@@ -151,16 +151,16 @@ public:
   _WRAP_METHOD(void remove_focus_sibling( CellRenderer& renderer, CellRenderer& sibling), gtk_cell_area_remove_focus_sibling)
   _WRAP_METHOD(bool is_focus_sibling(CellRenderer& renderer,  CellRenderer& sibling), gtk_cell_area_is_focus_sibling)
   //TODO: _WRAP_METHOD(GList* get_focus_siblings(CellRenderer& renderer), gtk_cell_area_get_focus_siblings)
-  
+
   _WRAP_METHOD(CellRenderer* get_focus_from_sibling(CellRenderer& renderer), gtk_cell_area_get_focus_from_sibling)
   _WRAP_METHOD(const CellRenderer* get_focus_from_sibling(CellRenderer& renderer) const, gtk_cell_area_get_focus_from_sibling, constversion)
-  
+
   _WRAP_METHOD(CellRenderer* get_edited_cell(), gtk_cell_area_get_edited_cell)
   _WRAP_METHOD(const CellRenderer* get_edited_cell() const, gtk_cell_area_get_edited_cell, constversion)
-  
-  _WRAP_METHOD(CellEditable* get_edit_widget(), gtk_cell_area_get_edit_widget) 
+
+  _WRAP_METHOD(CellEditable* get_edit_widget(), gtk_cell_area_get_edit_widget)
   _WRAP_METHOD(const CellEditable* get_edit_widget() const, gtk_cell_area_get_edit_widget, constversion)
-  
+
   _WRAP_METHOD(bool activate_cell(Widget& widget, CellRenderer& renderer, GdkEvent* event, const Gdk::Rectangle& cell_area, CellRendererState flags), gtk_cell_area_activate_cell)
   _WRAP_METHOD(void stop_editing(bool canceled), gtk_cell_area_stop_editing)
 
@@ -171,6 +171,10 @@ public:
 protected:
   #m4 _CONVERSION(`GtkCellAreaContext*',`const Glib::RefPtr<CellAreaContext>&',`Glib::wrap($3, true)')
 
+//TODO: Wrap these vfuncs, mentioned in the GtkCellAreaContext overview documentation?
+//  GtkCellAreaContext *(* create_context)                 (GtkCellArea             *area);
+//  GtkCellAreaContext *(* copy_context)                   (GtkCellArea             *area,
+
   _WRAP_VFUNC(SizeRequestMode get_request_mode() const, get_request_mode)
   _WRAP_VFUNC(void get_preferred_width(const Glib::RefPtr<CellAreaContext>& context, Widget& widget, int& minimum_width, int& natural_width), get_preferred_width, custom_vfunc_callback)
   _WRAP_VFUNC(void get_preferred_height_for_width(const Glib::RefPtr<CellAreaContext>& context, Widget& widget, int width, int& minimum_height, int& natural_height), get_preferred_height_for_width, custom_vfunc_callback)
@@ -179,4 +183,3 @@ protected:
 };
 
 } // namespace Gtk
-
diff --git a/gtk/src/cellareacontext.hg b/gtk/src/cellareacontext.hg
index 72ef78d..5ccc42f 100644
--- a/gtk/src/cellareacontext.hg
+++ b/gtk/src/cellareacontext.hg
@@ -25,21 +25,20 @@ namespace Gtk
 
 class CellArea;
 
-/** A class representing an adjustable bounded value.
+/** This stores geometrical information for a series of rows in a CellArea.
  *
- * The Gtk::CellAreaContext object represents a value which has an associated
- * lower and upper bound, together with step and page increments, and a page
- * size.  It is used within several gtkmm widgets, including
- * Gtk::SpinButton, Gtk::Viewport, and Gtk::Range (which is a base class for
- * Gtk::HScrollbar, Gtk::VScrollbar, Gtk::HScale, and Gtk::VScale).
+ * CellAreaContext is used by widgets such as TreeView and IconView,
+ * but application developers do not usually need to be aware of it.
  *
- * The Gtk::CellAreaContext object does not update the value itself. Instead it
- * is left up to the owner of the Gtk::CellAreaContext to control the value.
- *
- * The owner of the Gtk::CellAreaContext typically calls the value_changed() and
- * changed() functions after changing the value and its bounds. This results
- * in the emission of the "value_changed" or "changed" signal respectively.
+ * The CellAreaContext object is created by a given CellArea
+ * and is used to store cell sizes and alignments for a series of
+ * TreeModel rows that are requested and rendered in the same context.
  *
+ * CellLayout widgets can create any number of contexts in which to
+ * request and render groups of data rows. However. it's important that the
+ * same context which was used to request sizes for a given TreeModel
+ * row also be used for the same row when calling other CellArea APIs
+ * such as gtk_cell_area_render() and gtk_cell_area_event().
  */
 class CellAreaContext : public Glib::Object
 {
@@ -48,12 +47,12 @@ public:
 
 
 protected:
- 
+
 public:
 
   _WRAP_METHOD(Glib::RefPtr<CellArea> get_area(), gtk_cell_area_context_get_area, refreturn)
   _WRAP_METHOD(Glib::RefPtr<const CellArea> get_area() const, gtk_cell_area_context_get_area, refreturn, constversion)
-  
+
   _WRAP_METHOD(void allocate(int width, int height), gtk_cell_area_context_allocate)
   _WRAP_METHOD(void reset(), gtk_cell_area_context_reset)
 
@@ -61,12 +60,12 @@ public:
   _WRAP_METHOD(void get_preferred_height(int& minimum_height, int& natural_height) const, gtk_cell_area_context_get_preferred_height)
   _WRAP_METHOD(void get_preferred_height_for_width(int width, int& minimum_height, int& natural_height) const, gtk_cell_area_context_get_preferred_height_for_width)
   _WRAP_METHOD(void get_preferred_width_for_height(int height, int& minimum_width, int& natural_width) const, gtk_cell_area_context_get_preferred_width_for_height)
-                                                                   
+
   _WRAP_METHOD(void get_allocation(int& width, int& height) const, gtk_cell_area_context_get_allocation)
 
   _WRAP_METHOD(void push_preferred_width(int minimum_width, int natural_width), gtk_cell_area_context_push_preferred_width)
   _WRAP_METHOD(void push_preferred_height(int minimum_height, int natural_height), gtk_cell_area_context_push_preferred_height)
- 
+
 
 };