Documented. Added a "cursor_activated" signal. Removed some unused

2001-01-25  Christopher James Lahey  <clahey@helixcode.com>

	* e-table-group-container.c, e-table-group-leaf.c,
	e-table-group.c, e-table-group.h, e-table-item.c, e-table-item.h:
	Documented.  Added a "cursor_activated" signal.  Removed some
	unused functions (e_table_group_get_count and
	e_table_group_get_ecol).

	* e-table-selection-model.c, e-table-selection-model.h: Added a
	"cursor_activated" signal.  Call it when the user changes the
	selection to match the cursor.

	* e-table.c, e-table.h: Added a "cursor_activated" signal.  Fixed
	the e_table_compute_location function to take into account the
	scrolled position.

svn path=/trunk/; revision=7808

1 files changed, 225 insertions, 42 deletions

diff --git a/widgets/table/e-table-group.c b/widgets/table/e-table-group.c
index 1568184563..d87546db0d 100644
--- a/widgets/table/e-table-group.c
+++ b/widgets/table/e-table-group.c
@@ -26,6 +26,7 @@ static GnomeCanvasGroupClass *etg_parent_class;
 
 enum {
 	CURSOR_CHANGE,
+	CURSOR_ACTIVATED,
 	DOUBLE_CLICK,
 	RIGHT_CLICK,
 	CLICK,
@@ -52,6 +53,24 @@ etg_destroy (GtkObject *object)
 		GTK_OBJECT_CLASS (etg_parent_class)->destroy (object);
 }
 
+/** 
+ * e_table_group_new
+ * @parent: The %GnomeCanvasGroup to create a child of.
+ * @full_header: The full header of the %ETable.
+ * @header: The current header of the %ETable.
+ * @model: The %ETableModel of the %ETable.
+ * @sort_info: The %ETableSortInfo of the %ETable.
+ * @n: The grouping information object to group by.
+ *
+ * %ETableGroup is a collection of rows of an %ETable.  It's a
+ * %GnomeCanvasItem.  There are two different forms.  If n < the
+ * number of groupings in the given %ETableSortInfo, then the
+ * %ETableGroup will need to contain other %ETableGroups, thus it
+ * creates an %ETableGroupContainer.  Otherwise, it will just contain
+ * an %ETableItem, and thus it creates an %ETableGroupLeaf.
+ *
+ * Returns: The new %ETableGroup.
+ */
 ETableGroup *
 e_table_group_new (GnomeCanvasGroup *parent,
 		   ETableHeader     *full_header,
@@ -70,6 +89,16 @@ e_table_group_new (GnomeCanvasGroup *parent,
 	return NULL;
 }
 
+/** 
+ * e_table_group_construct
+ * @parent: The %GnomeCanvasGroup to create a child of.
+ * @etg: The %ETableGroup to construct.
+ * @full_header: The full header of the %ETable.
+ * @header: The current header of the %ETable.
+ * @model: The %ETableModel of the %ETable.
+ *
+ * This routine does the base construction of the %ETableGroup.
+ */
 void
 e_table_group_construct (GnomeCanvasGroup *parent,
 			 ETableGroup      *etg,
@@ -86,6 +115,14 @@ e_table_group_construct (GnomeCanvasGroup *parent,
 	gnome_canvas_item_constructv (GNOME_CANVAS_ITEM (etg), parent, 0, NULL);
 }
 
+/** 
+ * e_table_group_add
+ * @etg: The %ETableGroup to add a row to
+ * @row: The row to add.
+ *
+ * This routine adds the given row from the %ETableModel to this set
+ * of rows.
+ */
 void
 e_table_group_add (ETableGroup *etg,
 		   gint row)
@@ -97,6 +134,13 @@ e_table_group_add (ETableGroup *etg,
 		ETG_CLASS (etg)->add (etg, row);
 }
 
+/** 
+ * e_table_group_add_all
+ * @etg: The %ETableGroup to add to
+ *
+ * This routine adds all the rows from the %ETableModel to this set
+ * of rows.
+ */
 void
 e_table_group_add_all (ETableGroup *etg)
 {
@@ -107,6 +151,17 @@ e_table_group_add_all (ETableGroup *etg)
 		ETG_CLASS (etg)->add_all (etg);
 }
 
+/** 
+ * e_table_group_remove
+ * @etg: The %ETableGroup to remove a row from
+ * @row: The row to remove.
+ *
+ * This routine removes the given row from the %ETableModel from this
+ * set of rows.
+ *
+ * Returns: TRUE if the row was deleted and FALSE if the row was not
+ * found.
+ */
 gboolean
 e_table_group_remove (ETableGroup *etg,
 		      gint row)
@@ -120,30 +175,16 @@ e_table_group_remove (ETableGroup *etg,
 		return FALSE;
 }
 
-gint
-e_table_group_get_count (ETableGroup *etg)
-{
-	g_return_val_if_fail (etg != NULL, 0);
-	g_return_val_if_fail (E_IS_TABLE_GROUP (etg), 0);
-
-	if (ETG_CLASS (etg)->get_count)
-		return ETG_CLASS (etg)->get_count (etg);
-	else
-		return 0;
-}
-
-gint
-e_table_group_row_count (ETableGroup *etg)
-{
-	g_return_val_if_fail (etg != NULL, 0);
-	g_return_val_if_fail (E_IS_TABLE_GROUP (etg), 0);
-
-	if (ETG_CLASS (etg)->row_count)
-		return ETG_CLASS (etg)->row_count (etg);
-	else
-		return 0;
-}
-
+/** 
+ * e_table_group_increment
+ * @etg: The %ETableGroup to increment
+ * @position: The position to increment from
+ * @amount: The amount to increment.
+ *
+ * This routine adds amount to all rows greater than or equal to
+ * position.  This is to handle when a row gets inserted into the
+ * model.
+ */
 void
 e_table_group_increment (ETableGroup *etg,
 			 gint position,
@@ -156,6 +197,16 @@ e_table_group_increment (ETableGroup *etg,
 		ETG_CLASS (etg)->increment (etg, position, amount);
 }
 
+/** 
+ * e_table_group_increment
+ * @etg: The %ETableGroup to decrement
+ * @position: The position to decrement from
+ * @amount: The amount to decrement
+ *
+ * This routine removes amount from all rows greater than or equal to
+ * position.  This is to handle when a row gets deleted from the
+ * model.
+ */
 void
 e_table_group_decrement (ETableGroup *etg,
 			 gint position,
@@ -168,18 +219,55 @@ e_table_group_decrement (ETableGroup *etg,
 		ETG_CLASS (etg)->decrement (etg, position, amount);
 }
 
+/** 
+ * e_table_group_increment
+ * @etg: The %ETableGroup to count
+ *
+ * This routine calculates the number of rows shown in this group.
+ *
+ * Returns: The number of rows.
+ */
+gint
+e_table_group_row_count (ETableGroup *etg)
+{
+	g_return_val_if_fail (etg != NULL, 0);
+	g_return_val_if_fail (E_IS_TABLE_GROUP (etg), 0);
+
+	if (ETG_CLASS (etg)->row_count)
+		return ETG_CLASS (etg)->row_count (etg);
+	else
+		return 0;
+}
+
+/** 
+ * e_table_group_set_focus
+ * @etg: The %ETableGroup to set
+ * @direction: The direction the focus is coming from.
+ * @view_col: The column to set the focus in.
+ *
+ * Sets the focus to this widget.  Places the focus in the view column
+ * coming from direction direction.
+ */
 void
 e_table_group_set_focus (ETableGroup *etg,
 			 EFocus direction,
-			 gint row)
+			 gint view_col)
 {
 	g_return_if_fail (etg != NULL);
 	g_return_if_fail (E_IS_TABLE_GROUP (etg));
 
 	if (ETG_CLASS (etg)->set_focus)
-		ETG_CLASS (etg)->set_focus (etg, direction, row);
+		ETG_CLASS (etg)->set_focus (etg, direction, view_col);
 }
 
+/** 
+ * e_table_group_get_focus
+ * @etg: The %ETableGroup to check
+ *
+ * Calculates if this group has the focus.
+ *
+ * Returns: TRUE if this group has the focus.
+ */
 gboolean
 e_table_group_get_focus (ETableGroup *etg)
 {
@@ -192,7 +280,15 @@ e_table_group_get_focus (ETableGroup *etg)
 		return FALSE;
 }
 
-gboolean
+/** 
+ * e_table_group_get_focus_column
+ * @etg: The %ETableGroup to check
+ *
+ * Calculates which column in this group has the focus.
+ *
+ * Returns: The column index (view column).
+ */
+gint
 e_table_group_get_focus_column (ETableGroup *etg)
 {
 	g_return_val_if_fail (etg != NULL, FALSE);
@@ -201,21 +297,18 @@ e_table_group_get_focus_column (ETableGroup *etg)
 	if (ETG_CLASS (etg)->get_focus_column)
 		return ETG_CLASS (etg)->get_focus_column (etg);
 	else
-		return FALSE;
-}
-
-ETableCol *
-e_table_group_get_ecol (ETableGroup *etg)
-{
-	g_return_val_if_fail (etg != NULL, NULL);
-	g_return_val_if_fail (E_IS_TABLE_GROUP (etg), NULL);
-
-	if (ETG_CLASS (etg)->get_ecol)
-		return ETG_CLASS (etg)->get_ecol (etg);
-	else
-		return NULL;
+		return -1;
 }
 
+/** 
+ * e_table_group_get_printable
+ * @etg: %ETableGroup which will be printed
+ *
+ * This routine creates and returns an %EPrintable that can be used to
+ * print the given %ETableGroup.
+ *
+ * Returns: The %EPrintable.
+ */
 EPrintable *
 e_table_group_get_printable (ETableGroup *etg)
 {
@@ -228,6 +321,20 @@ e_table_group_get_printable (ETableGroup *etg)
 		return NULL;
 }
 
+/** 
+ * e_table_group_compute_location
+ * @eti: %ETableGroup to look in.
+ * @x: A pointer to the x location to find in the %ETableGroup.
+ * @y: A pointer to the y location to find in the %ETableGroup.
+ * @row: A pointer to the location to store the found row in.
+ * @col: A pointer to the location to store the found col in.
+ *
+ * This routine locates the pixel location (*x, *y) in the
+ * %ETableGroup.  If that location is in the %ETableGroup, *row and
+ * *col are set to the view row and column where it was found.  If
+ * that location is not in the %ETableGroup, the height of the
+ * %ETableGroup is removed from the value y points to.
+ */
 void
 e_table_group_compute_location (ETableGroup *etg, int *x, int *y, int *row, int *col)
 {
@@ -238,6 +345,13 @@ e_table_group_compute_location (ETableGroup *etg, int *x, int *y, int *row, int
 		ETG_CLASS (etg)->compute_location (etg, x, y, row, col);
 }
 
+/** 
+ * e_table_group_cursor_change
+ * @eti: %ETableGroup to emit the signal on
+ * @row: The new cursor row (model row)
+ *
+ * This routine emits the "cursor_change" signal.
+ */
 void
 e_table_group_cursor_change (ETableGroup *e_table_group, gint row)
 {
@@ -249,6 +363,33 @@ e_table_group_cursor_change (ETableGroup *e_table_group, gint row)
 			 row);
 }
 
+/** 
+ * e_table_group_cursor_activated
+ * @eti: %ETableGroup to emit the signal on
+ * @row: The cursor row (model row)
+ *
+ * This routine emits the "cursor_activated" signal.
+ */
+void
+e_table_group_cursor_activated (ETableGroup *e_table_group, gint row)
+{
+	g_return_if_fail (e_table_group != NULL);
+	g_return_if_fail (E_IS_TABLE_GROUP (e_table_group));
+
+	gtk_signal_emit (GTK_OBJECT (e_table_group),
+			 etg_signals [CURSOR_ACTIVATED],
+			 row);
+}
+
+/** 
+ * e_table_group_double_click
+ * @eti: %ETableGroup to emit the signal on
+ * @row: The row clicked on (model row)
+ * @col: The col clicked on (model col)
+ * @event: The event that caused this signal
+ *
+ * This routine emits the "double_click" signal.
+ */
 void
 e_table_group_double_click (ETableGroup *e_table_group, gint row, gint col, GdkEvent *event)
 {
@@ -260,6 +401,15 @@ e_table_group_double_click (ETableGroup *e_table_group, gint row, gint col, GdkE
 			 row, col, event);
 }
 
+/** 
+ * e_table_group_right_click
+ * @eti: %ETableGroup to emit the signal on
+ * @row: The row clicked on (model row)
+ * @col: The col clicked on (model col)
+ * @event: The event that caused this signal
+ *
+ * This routine emits the "right_click" signal.
+ */
 gint
 e_table_group_right_click (ETableGroup *e_table_group, gint row, gint col, GdkEvent *event)
 {
@@ -275,6 +425,15 @@ e_table_group_right_click (ETableGroup *e_table_group, gint row, gint col, GdkEv
 	return return_val;
 }
 
+/** 
+ * e_table_group_click
+ * @eti: %ETableGroup to emit the signal on
+ * @row: The row clicked on (model row)
+ * @col: The col clicked on (model col)
+ * @event: The event that caused this signal
+ *
+ * This routine emits the "click" signal.
+ */
 gint
 e_table_group_click (ETableGroup *e_table_group, gint row, gint col, GdkEvent *event)
 {
@@ -290,6 +449,15 @@ e_table_group_click (ETableGroup *e_table_group, gint row, gint col, GdkEvent *e
 	return return_val;
 }
 
+/** 
+ * e_table_group_key_press
+ * @eti: %ETableGroup to emit the signal on
+ * @row: The cursor row (model row)
+ * @col: The cursor col (model col)
+ * @event: The event that caused this signal
+ *
+ * This routine emits the "key_press" signal.
+ */
 gint
 e_table_group_key_press (ETableGroup *e_table_group, gint row, gint col, GdkEvent *event)
 {
@@ -305,6 +473,14 @@ e_table_group_key_press (ETableGroup *e_table_group, gint row, gint col, GdkEven
 	return return_val;
 }
 
+/** 
+ * e_table_group_get_header
+ * @eti: %ETableGroup to check
+ *
+ * This routine returns the %ETableGroup's header.
+ *
+ * Returns: The %ETableHeader.
+ */
 ETableHeader *
 e_table_group_get_header (ETableGroup *etg)
 {
@@ -354,6 +530,7 @@ etg_class_init (GtkObjectClass *object_class)
 	item_class->event = etg_event;
 
 	klass->cursor_change = NULL;
+	klass->cursor_activated = NULL;
 	klass->double_click = NULL;
 	klass->right_click = NULL;
 	klass->click = NULL;
@@ -362,13 +539,11 @@ etg_class_init (GtkObjectClass *object_class)
 	klass->add = NULL;
 	klass->add_all = NULL;
 	klass->remove = NULL;
-	klass->get_count  = NULL;
 	klass->row_count  = NULL;
 	klass->increment  = NULL;
 	klass->decrement  = NULL;
 	klass->set_focus  = NULL;
 	klass->get_focus = etg_get_focus;
-	klass->get_ecol = NULL;
 	klass->get_printable = NULL;
 	klass->compute_location = NULL;
 
@@ -382,6 +557,14 @@ etg_class_init (GtkObjectClass *object_class)
 				gtk_marshal_NONE__INT,
 				GTK_TYPE_NONE, 1, GTK_TYPE_INT);
 
+	etg_signals [CURSOR_ACTIVATED] =
+		gtk_signal_new ("cursor_activated",
+				GTK_RUN_LAST,
+				object_class->type,
+				GTK_SIGNAL_OFFSET (ETableGroupClass, cursor_activated),
+				gtk_marshal_NONE__INT,
+				GTK_TYPE_NONE, 1, GTK_TYPE_INT);
+
 	etg_signals [DOUBLE_CLICK] =
 		gtk_signal_new ("double_click",
 				GTK_RUN_LAST,