[gtk+/treeview-refactor] Adding more documentation to GtkCellArea, documented GtkCellAreaClass structure.

[Tristan Van Berkom <tvb src gnome org>]

commit a7ad110fe9beb0a3458b38574b2e74ac7b76d109
Author: Tristan Van Berkom <tristan van berkom gmail com>
Date:   Fri Dec 3 00:29:22 2010 +0900

    Adding more documentation to GtkCellArea, documented GtkCellAreaClass structure.

 gtk/gtkcellarea.c |    2 +-
 gtk/gtkcellarea.h |   64 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 63 insertions(+), 3 deletions(-)
---
diff --git a/gtk/gtkcellarea.c b/gtk/gtkcellarea.c
index 9f5616b..dcf0007 100644
--- a/gtk/gtkcellarea.c
+++ b/gtk/gtkcellarea.c
@@ -210,7 +210,7 @@
  * Note that the cached height in this example really depends on how the layouting
  * widget works. The layouting widget might decide to give every row it's minimum
  * or natural height or if the model content is expected to fit inside the layouting
- * widget with not scrolled window it would make sense to calculate the allocation
+ * widget with no scrolled window it would make sense to calculate the allocation
  * for each row at #GtkWidget.size_allocate() time using gtk_distribute_natural_allocation().
  * </para>
  * </refsect2>
diff --git a/gtk/gtkcellarea.h b/gtk/gtkcellarea.h
index abc73d0..f857e19 100644
--- a/gtk/gtkcellarea.h
+++ b/gtk/gtkcellarea.h
@@ -65,11 +65,70 @@ struct _GtkCellArea
   GtkCellAreaPrivate *priv;
 };
 
+
+/**
+ * GtkCellAreaClass:
+ * @add: adds a #GtkCellRenderer to the area.
+ * @remove: removes a #GtkCellRenderer from the area.
+ * @forall: Calls the #GtkCellCallback function on every #GtkCellRenderer in the area
+ * with the provided user data.
+ * @get_cell_allocation: Gets the position (relative to the passed @cell_area rectangle) 
+ * and size of a #GtkCellRenderer.
+ * @event: Handle an event in the area, this is generally used to activate a cell
+ * at the event location for button events but can also be used to generically pass
+ * events to #GtkWidgets drawn onto the area.
+ * @render: Actually render the area's cells to the specified rectangle, @background_area
+ * should be correctly distributed to the cells coresponding background areas.
+ * @apply_attributes: Apply the cell attributes to the cells. This is implemented as a signal and 
+ * generally #GtkCellArea subclasses dont need to implement this since it's handled by the base 
+ * class but can be overridden to apply some custom attributes.
+ * @create_context: Creates and returns a class specific #GtkCellAreaContext to store cell 
+ * alignment and allocation details for a said #GtkCellArea class.
+ * @get_request_mode: This allows an area to tell its layouting widget whether it prefers to 
+ * be allocated in %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH or %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT mode.
+ * @get_preferred_width: Calculates the minimum and natural width of the area's cells
+ * with the current attributes applied while considering the particular layouting details
+ * of the said #GtkCellArea. While requests are performed over a series of rows, alignments
+ * and overall minimum and natural sizes should be stored in the corresponding #GtkCellAreaContext.
+ * @get_preferred_height_for_width: Calculates the minimum and natural height for the area
+ * if the passed @context would be allocated the given width. When implementing this virtual
+ * method it is safe to assume that @context has already stored the aligned cell widths
+ * for every #GtkTreeModel row that @context will be allocated for since this information
+ * was stored at #GtkCellAreaClass.get_preferred_width() time. This virtual method should
+ * also store any necessary alignments of cell heights for the case that the context is
+ * allocated a height.
+ * @get_preferred_height: Calculates the minimum and natural height of the area's cells
+ * with the current attributes applied. Essentially this is the same as 
+ * #GtkCellAreaClass.get_preferred_width() only for areas that are being requested as
+ * %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT.
+ * @get_preferred_width_for_height: Calculates the minimum and natural width for the area
+ * if the passed @context would be allocated the given height. The same as 
+ * #GtkCellAreaClass.get_preferred_height_for_width() only for handling requests in the
+ * %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT mode.
+ * @set_cell_property: This should be implemented to handle changes in child cell properties
+ * for a given #GtkCellRenderer that were previously installed on the #GtkCellAreaClass with 
+ * gtk_cell_area_class_install_cell_property().
+ * @get_cell_property: This should be implemented to report the values of child cell properties
+ * for a given child #GtkCellRenderer.
+ * @focus: This virtual method should be implemented to navigate focus from cell to cell
+ * inside the #GtkCellArea. The #GtkCellArea should move focus from cell to cell inside
+ * the area and return %FALSE if focus logically leaves the area with the following exceptions:
+ * When the area contains no activatable cells, the entire area recieves focus. Focus should not
+ * be given to cells that are actually "focus siblings" of other sibling cells 
+ * (see gtk_cell_area_get_focus_from_sibling()). Focus is set by calling gtk_cell_area_set_focus_cell().
+ * @is_activatable: Returns whether the #GtkCellArea can respond to #GtkCellAreaClass.activate(), 
+ * usually this does not need to be implemented since the base class takes care of this however
+ * it can be enhanced if the #GtkCellArea subclass can handle activation in other ways than
+ * activating its #GtkCellRenderers.
+ * @activate: This is called when the layouting widget rendering the #GtkCellArea activates
+ * the focus cell (see gtk_cell_area_get_focus_cell()).
+ */
 struct _GtkCellAreaClass
 {
+  /*< private >*/
   GInitiallyUnownedClass parent_class;
 
-  /* vtable - not signals */
+  /*< public >*/
 
   /* Basic methods */
   void               (* add)                             (GtkCellArea             *area,
@@ -144,15 +203,16 @@ struct _GtkCellAreaClass
 							  GParamSpec              *pspec);
 
   /* Focus */
-  gboolean           (* is_activatable)                  (GtkCellArea             *area);
   gboolean           (* focus)                           (GtkCellArea             *area,
 							  GtkDirectionType         direction);
+  gboolean           (* is_activatable)                  (GtkCellArea             *area);
   gboolean           (* activate)                        (GtkCellArea             *area,
 							  GtkCellAreaContext      *context,
 							  GtkWidget               *widget,
 							  const GdkRectangle      *cell_area,
 							  GtkCellRendererState     flags);
 
+  /*< private >*/
 
   /* Padding for future expansion */
   void (*_gtk_reserved1) (void);