[gtk+] docs: Move documentation to inline comments: GtkCellRenderer

[Javier Jardón <jjardon src gnome org>]

commit 6cfd907290e699a9cea371259aa82519982d002f
Author: Javier Jardón <jjardon gnome org>
Date:   Sat Nov 6 17:57:23 2010 +0100

    docs: Move documentation to inline comments: GtkCellRenderer

 docs/reference/gtk/tmpl/.gitignore           |    1 +
 docs/reference/gtk/tmpl/gtkcellrenderer.sgml |  448 --------------------------
 gtk/gtkcellrenderer.c                        |   39 +++
 gtk/gtkcellrenderer.h                        |   23 ++
 4 files changed, 63 insertions(+), 448 deletions(-)
---
diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore
index 227f7d3..2ad13ef 100644
--- a/docs/reference/gtk/tmpl/.gitignore
+++ b/docs/reference/gtk/tmpl/.gitignore
@@ -8,6 +8,7 @@ gtkbuilder.sgml
 gtkbutton.sgml
 gtkcalendar.sgml
 gtkcelleditable.sgml
+gtkcellrenderer.sgml
 gtkcolorbutton.sgml
 gtkcolorsel.sgml
 gtkcombobox.sgml
diff --git a/gtk/gtkcellrenderer.c b/gtk/gtkcellrenderer.c
index 3656599..d3a6c02 100644
--- a/gtk/gtkcellrenderer.c
+++ b/gtk/gtkcellrenderer.c
@@ -24,6 +24,45 @@
 #include "gtkprivate.h"
 #include "gtktreeprivate.h"
 
+
+/**
+ * SECTION:gtkcellrenderer
+ * @Short_description: An object for rendering a single cell on a GdkDrawable
+ * @Title: GtkCellRenderer
+ * @See_also: #GtkCellRendererText, #GtkCellRendererPixbuf, #GtkCellRendererToggle
+ *
+ * The #GtkCellRenderer is a base class of a set of objects used for
+ * rendering a cell to a #GdkDrawable.  These objects are used primarily by
+ * the #GtkTreeView widget, though they aren't tied to them in any
+ * specific way.  It is worth noting that #GtkCellRenderer is not a
+ * #GtkWidget and cannot be treated as such.
+ *
+ * The primary use of a #GtkCellRenderer is for drawing a certain graphical
+ * elements on a #GdkDrawable. Typically, one cell renderer is used to
+ * draw many cells on the screen.  To this extent, it isn't expected that a
+ * CellRenderer keep any permanent state around.  Instead, any state is set
+ * just prior to use using #GObject<!-- -->s property system.  Then, the
+ * cell is measured using gtk_cell_renderer_get_size(). Finally, the cell
+ * is rendered in the correct location using gtk_cell_renderer_render().
+ *
+ * There are a number of rules that must be followed when writing a new
+ * #GtkCellRenderer.  First and formost, it's important that a certain set
+ * of properties will always yield a cell renderer of the same size,
+ * barring a #GtkStyle change.  The #GtkCellRenderer also has a number of
+ * generic properties that are expected to be honored by all children.
+ *
+ * Beyond merely rendering a cell, cell renderers can optionally
+ * provide active user interface elements. A cell renderer can be
+ * <firstterm>activatable</firstterm> like #GtkCellRendererToggle,
+ * which toggles when it gets activated by a mouse click, or it can be
+ * <firstterm>editable</firstterm> like #GtkCellRendererText, which
+ * allows the user to edit the text using a #GtkEntry.
+ * To make a cell renderer activatable or editable, you have to
+ * implement the #GtkCellRendererClass.activate or
+ * #GtkCellRendererClass.start_editing virtual functions, respectively.
+ */
+
+
 #define DEBUG_CELL_SIZE_REQUEST 0
 
 static void gtk_cell_renderer_init          (GtkCellRenderer      *cell);
diff --git a/gtk/gtkcellrenderer.h b/gtk/gtkcellrenderer.h
index 4436277..cad58df 100644
--- a/gtk/gtkcellrenderer.h
+++ b/gtk/gtkcellrenderer.h
@@ -28,6 +28,18 @@
 
 G_BEGIN_DECLS
 
+
+/**
+ * GtkCellRendererState:
+ * @GTK_CELL_RENDERER_SELECTED: The cell is currently selected, and
+ *  probably has a selection colored background to render to.
+ * @GTK_CELL_RENDERER_PRELIT: The mouse is hovering over the cell.
+ * @GTK_CELL_RENDERER_INSENSITIVE: The cell is drawn in an insensitive manner
+ * @GTK_CELL_RENDERER_SORTED: The cell is in a sorted row
+ * @GTK_CELL_RENDERER_FOCUSED: The cell is in the focus row.
+ *
+ * Tells how a cell is to be rendererd.
+ */
 typedef enum
 {
   GTK_CELL_RENDERER_SELECTED    = 1 << 0,
@@ -38,6 +50,17 @@ typedef enum
   GTK_CELL_RENDERER_FOCUSED     = 1 << 4
 } GtkCellRendererState;
 
+/**
+ * GtkCellRendererMode:
+ * @GTK_CELL_RENDERER_MODE_INERT: The cell is just for display
+ *  and cannot be interacted with.  Note that this doesn't mean that eg. the
+ *  row being drawn can't be selected -- just that a particular element of
+ *  it cannot be individually modified.
+ * @GTK_CELL_RENDERER_MODE_ACTIVATABLE: The cell can be clicked.
+ * @GTK_CELL_RENDERER_MODE_EDITABLE: The cell can be edited or otherwise modified.
+ *
+ * Identifies how the user can interact with a particular cell.
+ */
 typedef enum
 {
   GTK_CELL_RENDERER_MODE_INERT,