Documented.

2000-11-25  Miguel de Icaza  <miguel@helixcode.com>

	* e-cell.c: Documented.

2000-11-24  Miguel de Icaza  <miguel@helixcode.com>

	* e-cell-toggle.c (etog_queue_redraw): Documented.

	* e-cell-text.c: Removed list of unused arguments.  Add docs.

	* e-cell-checkbox.c (e_cell_checkbox_new): Add docs.

	* e-table-simple.c (e_table_simple_new): Add docs.

svn path=/trunk/; revision=6665

6 files changed, 212 insertions, 29 deletions

diff --git a/widgets/table/e-cell-checkbox.c b/widgets/table/e-cell-checkbox.c
index 4d31b53784..cb0c66df94 100644
--- a/widgets/table/e-cell-checkbox.c
+++ b/widgets/table/e-cell-checkbox.c
@@ -4,7 +4,7 @@
  * Author:
  *   Miguel de Icaza (miguel@kernel.org)
  *
- * (C) 1999 Helix Code, Inc
+ * (C) 1999, 2000 Helix Code, Inc
  */
 #include <config.h>
 #include <gtk/gtkenums.h>
@@ -33,6 +33,15 @@ e_cell_checkbox_class_init (GtkObjectClass *object_class)
 
 E_MAKE_TYPE(e_cell_checkbox, "ECellCheckbox", ECellCheckbox, e_cell_checkbox_class_init, NULL, PARENT_TYPE);
 
+/**
+ * e_cell_checkbox_new:
+ *
+ * Creates a new ECell renderer that can be used to render check
+ * boxes.  the data provided from the model is cast to an integer.
+ * zero is used for the off display, and non-zero for checked status.
+ * 
+ * Returns: an ECell object that can be used to render checkboxes.
+ */
 ECell *
 e_cell_checkbox_new (void)
 {
diff --git a/widgets/table/e-cell-text.c b/widgets/table/e-cell-text.c
index 0fe721f0ec..2a7eae1d70 100644
--- a/widgets/table/e-cell-text.c
+++ b/widgets/table/e-cell-text.c
@@ -4,8 +4,10 @@
  *
  * Authors: Miguel de Icaza <miguel@helixcode.com>
  *          Chris Lahey <clahey@helixcode.com>
- *         
- * A majority of code taken from:
+ *
+ * (C) 1999, 2000 Helix Code, Inc.
+ *
+ * A lot of code taken from:
  *
  * Text item type for GnomeCanvas widget
  *
@@ -58,27 +60,7 @@ struct line {
 /* Object argument IDs */
 enum {
 	ARG_0,
-	ARG_TEXT, /* UTF-8 */
-	ARG_X,
-	ARG_Y,
-	ARG_FONT,
-        ARG_FONTSET,
-	ARG_FONT_GDK,
-	ARG_ANCHOR,
-	ARG_JUSTIFICATION,
-	ARG_CLIP_WIDTH,
-	ARG_CLIP_HEIGHT,
-	ARG_CLIP,
-	ARG_X_OFFSET,
-	ARG_Y_OFFSET,
-	ARG_FILL_COLOR,
-	ARG_FILL_COLOR_GDK,
-	ARG_FILL_COLOR_RGBA,
-	ARG_FILL_STIPPLE,
-	ARG_TEXT_WIDTH,
-	ARG_TEXT_HEIGHT,
-	ARG_USE_ELLIPSIS,
-	ARG_ELLIPSIS,
+
 	ARG_STRIKEOUT_COLUMN,
 	ARG_BOLD_COLUMN,
 	ARG_TEXT_FILTER,
@@ -1610,6 +1592,30 @@ e_cell_text_init (ECellText *ect)
 
 E_MAKE_TYPE(e_cell_text, "ECellText", ECellText, e_cell_text_class_init, e_cell_text_init, PARENT_TYPE);
 
+/**
+ * e_cell_text_new:
+ * @fontname: font to be used to render on the screen
+ * @justify: Justification of the string in the cell.
+ *
+ * Creates a new ECell renderer that can be used to render strings that
+ * that come from the model.  The value returned from the model is
+ * interpreted as being a char *.
+ *
+ * The ECellText object support a large set of properties that can be
+ * configured through the Gtk argument system and allows the user to have
+ * a finer control of the way the string is displayed.  The arguments supported
+ * allow the control of strikeout, bold, color and a text filter.
+ *
+ * The arguments "strikeout_column", "bold_column" and "color_column" set
+ * and return an integer that points to a column in the model that controls
+ * these settings.  So controlling the way things are rendered is achieved
+ * by having special columns in the model that will be used to flag whether
+ * the text should be rendered with strikeout, or bolded.   In the case of
+ * the "color_column" argument, the column in the model is expected to have
+ * a string that can be parsed by gdk_color_parse().
+ * 
+ * Returns: an ECell object that can be used to render strings.
+ */
 ECell *
 e_cell_text_new (const char *fontname, GtkJustification justify)
 {
@@ -2289,7 +2295,8 @@ _selection_received (GtkInvisible *invisible,
 	}
 }
 
-static void e_cell_text_view_supply_selection (CellEdit *edit, guint time, GdkAtom selection, char *data, gint length)
+static void
+e_cell_text_view_supply_selection (CellEdit *edit, guint time, GdkAtom selection, char *data, gint length)
 {
 	gboolean successful;
 	GtkWidget *invisible;
diff --git a/widgets/table/e-cell-toggle.c b/widgets/table/e-cell-toggle.c
index 0dd4fe8d20..9c5f7b391b 100644
--- a/widgets/table/e-cell-toggle.c
+++ b/widgets/table/e-cell-toggle.c
@@ -280,6 +280,16 @@ e_cell_toggle_class_init (GtkObjectClass *object_class)
 
 E_MAKE_TYPE(e_cell_toggle, "ECellToggle", ECellToggle, e_cell_toggle_class_init, NULL, PARENT_TYPE);
 
+/**
+ * e_cell_toggle_construct:
+ * @etog: a fresh ECellToggle object
+ * @border: number of pixels used as a border
+ * @n_states: number of states the toggle will have
+ * @images: a collection of @n_states images, one for each state.
+ *
+ * Constructs the @etog object with the @border, @n_staes, and @images
+ * arguments.
+ */
 void
 e_cell_toggle_construct (ECellToggle *etog, int border, int n_states, GdkPixbuf **images)
 {
@@ -302,6 +312,20 @@ e_cell_toggle_construct (ECellToggle *etog, int border, int n_states, GdkPixbuf
 	etog->height = max_height;
 }
 
+/**
+ * e_cell_checkbox_new:
+ * @border: number of pixels used as a border
+ * @n_states: number of states the toggle will have
+ * @images: a collection of @n_states images, one for each state.
+ *
+ * Creates a new ECell renderer that can be used to render toggle
+ * buttons with the images specified in @images.  The value returned 
+ * by ETableModel::get_value is typecase into an integer and clamped
+ * to the [0..n_states) range.  That will select the image rendered.
+ * 
+ * Returns: an ECell object that can be used to render multi-state
+ * toggle cells.
+ */
 ECell *
 e_cell_toggle_new (int border, int n_states, GdkPixbuf **images)
 {
diff --git a/widgets/table/e-cell-tree.c b/widgets/table/e-cell-tree.c
index a465d3b290..32ae9ca1f7 100644
--- a/widgets/table/e-cell-tree.c
+++ b/widgets/table/e-cell-tree.c
@@ -9,7 +9,7 @@
  * the ECellText renderer.
  *
  * Copyright (C) 1998 The Free Software Foundation
- *
+ * Copyright (C) 1999, 2000 Helix Code, Inc.
  */
 
 #include <config.h>
diff --git a/widgets/table/e-cell.c b/widgets/table/e-cell.c
index 8fe664f7e1..53aba7c625 100644
--- a/widgets/table/e-cell.c
+++ b/widgets/table/e-cell.c
@@ -124,7 +124,18 @@ e_cell_init (GtkObject *object)
 
 E_MAKE_TYPE(e_cell, "ECell", ECell, e_cell_class_init, e_cell_init, PARENT_TYPE);
 
-	
+/**
+ * e_cell_event:
+ * @ecell_view: The ECellView where the event will be dispatched
+ * @event: The GdkEvent.
+ * @model_col: the column in the model
+ * @view_col: the column in the view
+ * @row: the row
+ *
+ * Dispatches the event @event to the @ecell_view for.
+ *
+ * Returns: processing state from the GdkEvent handling.
+ */
 gint
 e_cell_event (ECellView *ecell_view, GdkEvent *event, int model_col, int view_col, int row)
 {
@@ -132,6 +143,21 @@ e_cell_event (ECellView *ecell_view, GdkEvent *event, int model_col, int view_co
 		ecell_view, event, model_col, view_col, row);
 }
 
+/** 
+ * e_cell_new_view:
+ * @ecell: the Ecell that will create the new view
+ * @table_model: the table model the ecell is bound to
+ * @e_table_item_view: An ETableItem object (the CanvasItem that reprensents the view of the table)
+ *
+ * ECell renderers new to be bound to a table_model and to the actual view
+ * during their life time to actually render the data.  This method is invoked
+ * by the ETableItem canvas item to instatiate a new view of the ECell.
+ *
+ * This is invoked when the ETableModel is attached to the ETableItem (a CanvasItem
+ * that can render ETableModels in the screen).
+ *
+ * Returns: a new ECellView for this @ecell on the @table_model displayed on the @e_table_item_view.
+ */
 ECellView *
 e_cell_new_view (ECell *ecell, ETableModel *table_model, void *e_table_item_view)
 {
@@ -139,24 +165,65 @@ e_cell_new_view (ECell *ecell, ETableModel *table_model, void *e_table_item_view
 		ecell, table_model, e_table_item_view);
 }
 
+/**
+ * e_cell_realize:
+ * @ecell_view: The ECellView to be realized.
+ *
+ * This function is invoked to give a chance to the ECellView to allocate
+ * any resources it needs from Gdk, equivalent to the GtkWidget::realize
+ * signal.
+ */
 void
 e_cell_realize (ECellView *ecell_view)
 {
 	return E_CELL_CLASS (GTK_OBJECT (ecell_view->ecell)->klass)->realize (ecell_view);
 }
 
+/**
+ * e_cell_kill_view:
+ * @ecell_view: view to be destroyed.
+ *
+ * This method it used to destroy a view of an ECell renderer
+ */
 void
 e_cell_kill_view (ECellView *ecell_view)
 {
 	E_CELL_CLASS (GTK_OBJECT (ecell_view->ecell)->klass)->kill_view (ecell_view);
 }
 
+/**
+ * e_cell_unrealize:
+ * @ecell_view: The ECellView to be unrealized.
+ *
+ * This function is invoked to give a chance to the ECellView to
+ * release any resources it allocated during the realize method,
+ * equivalent to the GtkWidget::unrealize signal.
+ */
 void
 e_cell_unrealize (ECellView *ecell_view)
 {
 	E_CELL_CLASS (GTK_OBJECT (ecell_view->ecell)->klass)->unrealize (ecell_view);
 }
 
+/**
+ * e_cell_draw:
+ * @ecell_view: the ECellView to redraw
+ * @drawable: draw desination
+ * @model_col: the column in the model being drawn.
+ * @view_col: the column in the view being drawn (what the model maps to).
+ * @row: the row being drawn
+ * @flags: rendering flags.
+ * @x1: boudary for the rendering
+ * @y1: boudary for the rendering
+ * @x2: boudary for the rendering
+ * @y2: boudary for the rendering
+ *
+ * This instructs the ECellView to render itself into the drawable.  The
+ * region to be drawn in given by (x1,y1)-(x2,y2).
+ *
+ * The most important flags are %E_CELL_SELECTED and %E_CELL_FOCUSED, other
+ * flags include alignments and justifications.
+ */
 void
 e_cell_draw (ECellView *ecell_view, GdkDrawable *drawable,
 	     int model_col, int view_col, int row, ECellFlags flags, int x1, int y1, int x2, int y2)
@@ -165,6 +232,11 @@ e_cell_draw (ECellView *ecell_view, GdkDrawable *drawable,
 		ecell_view, drawable, model_col, view_col, row, flags, x1, y1, x2, y2);
 }
 
+/**
+ * e_cell_print:
+ *
+ * FIXME:
+ */
 void
 e_cell_print (ECellView *ecell_view, GnomePrintContext *context, 
 	      int model_col, int view_col, int row,
@@ -174,6 +246,11 @@ e_cell_print (ECellView *ecell_view, GnomePrintContext *context,
 		(ecell_view, context, model_col, view_col, row, width, height);
 }
 
+/**
+ * e_cell_print:
+ *
+ * FIXME:
+ */
 gdouble
 e_cell_print_height (ECellView *ecell_view, GnomePrintContext *context, 
 		     int model_col, int view_col, int row,
@@ -186,6 +263,16 @@ e_cell_print_height (ECellView *ecell_view, GnomePrintContext *context,
 		return 0.0;
 }
 
+/**
+ * e_cell_height:
+ * @ecell_view: the ECellView.
+ * @model_col: the column in the model
+ * @view_col: the column in the view.
+ * @row: the row to me measured
+ *
+ * Returns: the height of the cell at @model_col, @row rendered at
+ * @view_col, @row.
+ */
 int
 e_cell_height (ECellView *ecell_view, int model_col, int view_col, int row)
 {
@@ -193,6 +280,16 @@ e_cell_height (ECellView *ecell_view, int model_col, int view_col, int row)
 		ecell_view, model_col, view_col, row);
 }
 
+/**
+ * e_cell_enter_edit:
+ * @ecell_view: the ECellView that will enter editing
+ * @model_col: the column in the model
+ * @view_col: the column in the view
+ * @row: the row
+ *
+ * Notifies the ECellView that it is about to enter editing mode for
+ * @model_col, @row rendered at @view_col, @row.
+ */
 void *
 e_cell_enter_edit (ECellView *ecell_view, int model_col, int view_col, int row)
 {
@@ -200,6 +297,16 @@ e_cell_enter_edit (ECellView *ecell_view, int model_col, int view_col, int row)
 		ecell_view, model_col, view_col, row);
 }
 
+/**
+ * e_cell_leave_edit:
+ * @ecell_view: the ECellView that will leave editing
+ * @model_col: the column in the model
+ * @view_col: the column in the view
+ * @row: the row
+ *
+ * Notifies the ECellView that editing is finished at @model_col, @row
+ * rendered at @view_col, @row.
+ */
 void
 e_cell_leave_edit (ECellView *ecell_view, int model_col, int view_col, int row, void *edit_context)
 {
@@ -207,6 +314,15 @@ e_cell_leave_edit (ECellView *ecell_view, int model_col, int view_col, int row,
 		ecell_view, model_col, view_col, row, edit_context);
 }
 
+/**
+ * e_cell_max_width:
+ * @ecell_view: the ECellView that will leave editing
+ * @model_col: the column in the model
+ * @view_col: the column in the view.
+ *
+ * Returns: the maximum width for the ECellview at @model_col which
+ * is being rendered as @view_col
+ */
 int
 e_cell_max_width (ECellView *ecell_view, int model_col, int view_col)
 {
diff --git a/widgets/table/e-table-simple.c b/widgets/table/e-table-simple.c
index 8c8ed87b70..2144091d17 100644
--- a/widgets/table/e-table-simple.c
+++ b/widgets/table/e-table-simple.c
@@ -7,7 +7,7 @@
  * Author:
  *   Miguel de Icaza (miguel@gnu.org)
  *
- * (C) 1999 Helix Code, Inc.
+ * (C) 1999, 2000 Helix Code, Inc.
  */
 
 #include <config.h>
@@ -209,6 +209,33 @@ e_table_simple_get_type (void)
 	return type;
 }
 
+/**
+ * e_table_simple_new:
+ * @col_count:
+ * @row_count:
+ * @value_at:
+ * @set_value_at:
+ * @is_cell_editable:
+ * @duplicate_value:
+ * @free_value:
+ * @initialize_value:
+ * @value_is_empty:
+ * @value_to_string:
+ * @data: closure pointer.
+ *
+ * This initializes a new ETableSimpleModel object.  ETableSimpleModel is
+ * an implementaiton of the abstract class ETableModel.  The ETableSimpleModel
+ * is designed to allow people to easily create ETableModels without having
+ * to create a new GtkType derived from ETableModel every time they need one.
+ *
+ * Instead, ETableSimpleModel uses a setup based in callback functions, every
+ * callback function signature mimics the signature of each ETableModel method
+ * and passes the extra @data pointer to each one of the method to provide them
+ * with any context they might want to use. 
+ *
+ * Returns: An ETableSimpleModel object (which is also an ETableModel
+ * object).
+ */
 ETableModel *
 e_table_simple_new (ETableSimpleColumnCountFn col_count,
 		    ETableSimpleRowCountFn row_count,
@@ -239,4 +266,4 @@ e_table_simple_new (ETableSimpleColumnCountFn col_count,
 	et->data = data;
 	
 	return (ETableModel *) et;
-}
+ }