aboutsummaryrefslogtreecommitdiffstats
path: root/widgets/table/e-table.c
diff options
context:
space:
mode:
authorChristopher James Lahey <clahey@ximian.com>2001-12-04 19:21:55 +0800
committerChris Lahey <clahey@src.gnome.org>2001-12-04 19:21:55 +0800
commit1994bab834d2b5d31608dd7c48882e673291d320 (patch)
tree53ec15da4c7acdd6631d7888f1ca847c63e04461 /widgets/table/e-table.c
parentec65c861a6b515529474629a3b04a8a2099e51e4 (diff)
downloadgsoc2013-evolution-1994bab834d2b5d31608dd7c48882e673291d320.tar.gz
gsoc2013-evolution-1994bab834d2b5d31608dd7c48882e673291d320.tar.zst
gsoc2013-evolution-1994bab834d2b5d31608dd7c48882e673291d320.zip
Merging changes:
2001-12-04 Christopher James Lahey <clahey@ximian.com> * e-table-group.c, e-table.c, e-tree.c: Changed some comments. Added a bunch of documentation here. svn path=/trunk/; revision=14861
Diffstat (limited to 'widgets/table/e-table.c')
-rw-r--r--widgets/table/e-table.c331
1 files changed, 298 insertions, 33 deletions
diff --git a/widgets/table/e-table.c b/widgets/table/e-table.c
index 8aceac1332..61e911f4ea 100644
--- a/widgets/table/e-table.c
+++ b/widgets/table/e-table.c
@@ -908,6 +908,15 @@ e_table_fill_table (ETable *e_table, ETableModel *model)
e_table_group_add_all (e_table->group);
}
+/**
+ * e_table_set_state_object:
+ * @e_table: The #ETable object to modify
+ * @state: The #ETableState to use
+ *
+ * This routine sets the state of the #ETable from the given
+ * #ETableState.
+ *
+ **/
void
e_table_set_state_object(ETable *e_table, ETableState *state)
{
@@ -958,12 +967,12 @@ e_table_set_state_object(ETable *e_table, ETableState *state)
/**
* e_table_set_state:
- * @e_table: %ETable object that will be modified
- * @state_str: a string with the XML representation of the ETableState.
+ * @e_table: The #ETable object to modify
+ * @state_str: a string representing an #ETableState
*
- * This routine sets the state (as described by %ETableState) of the
- * %ETable object.
- */
+ * This routine sets the state of the #ETable from a string.
+ *
+ **/
void
e_table_set_state (ETable *e_table,
const gchar *state_str)
@@ -985,12 +994,12 @@ e_table_set_state (ETable *e_table,
/**
* e_table_load_state:
- * @e_table: %ETable object that will be modified
- * @filename: name of the file containing the state to be loaded into the %ETable
+ * @e_table: The #ETable object to modify
+ * @filename: name of the file to use
*
- * An %ETableState will be loaded form the file pointed by @filename into the
- * @e_table object.
- */
+ * This routine sets the state of the #ETable from a file.
+ *
+ **/
void
e_table_load_state (ETable *e_table,
const gchar *filename)
@@ -1012,11 +1021,14 @@ e_table_load_state (ETable *e_table,
/**
* e_table_get_state_object:
- * @e_table: %ETable object that will be modified
+ * @e_table: #ETable object to act on
*
- * Returns: the %ETableState object that encapsulates the current
- * state of the @e_table object
- */
+ * Builds an #ETableState corresponding to the current state of the
+ * #ETable.
+ *
+ * Return value:
+ * The %ETableState object generated.
+ **/
ETableState *
e_table_get_state_object (ETable *e_table)
{
@@ -1048,6 +1060,16 @@ e_table_get_state_object (ETable *e_table)
return state;
}
+/**
+ * e_table_get_state:
+ * @e_table: The #ETable to act on.
+ *
+ * Builds a state object based on the current state and returns the
+ * string corresponding to that state.
+ *
+ * Return value:
+ * A string describing the current state of the #ETable.
+ **/
gchar *e_table_get_state (ETable *e_table)
{
ETableState *state;
@@ -1061,12 +1083,13 @@ gchar *e_table_get_state (ETable *e_table
/**
* e_table_save_state:
- * @e_table: %ETable object that will be modified
- * @filename: name of the file containing the state to be loaded into the %ETable
+ * @e_table: The #ETable to act on
+ * @filename: name of the file to save to
*
- * This routine saves the state of the @e_table object into the file pointed
- * by @filename
- */
+ * Saves the state of the @e_table object into the file pointed by
+ * @filename.
+ *
+ **/
void
e_table_save_state (ETable *e_table,
const gchar *filename)
@@ -1180,6 +1203,20 @@ et_real_construct (ETable *e_table, ETableModel *etm, ETableExtras *ete,
return e_table;
}
+/**
+ * e_table_construct:
+ * @e_table: The newly created #ETable object.
+ * @etm: The model for this table.
+ * @ete: An optional #ETableExtras. (%NULL is valid.)
+ * @spec_str: The spec.
+ * @state_str: An optional state. (%NULL is valid.)
+ *
+ * This is the internal implementation of e_table_new() for use by
+ * subclasses or language bindings. See e_table_new() for details.
+ *
+ * Return value:
+ * The passed in value @e_table or %NULL if there's an error.
+ **/
ETable *
e_table_construct (ETable *e_table, ETableModel *etm, ETableExtras *ete,
const char *spec_str, const char *state_str)
@@ -1217,6 +1254,21 @@ e_table_construct (ETable *e_table, ETableModel *etm, ETableExtras *ete,
return e_table;
}
+/**
+ * e_table_construct_from_spec_file:
+ * @e_table: The newly created #ETable object.
+ * @etm: The model for this table.
+ * @ete: An optional #ETableExtras. (%NULL is valid.)
+ * @spec_fn: The filename of the spec.
+ * @state_fn: An optional state file. (%NULL is valid.)
+ *
+ * This is the internal implementation of e_table_new_from_spec_file()
+ * for use by subclasses or language bindings. See
+ * e_table_new_from_spec_file() for details.
+ *
+ * Return value:
+ * The passed in value @e_table or %NULL if there's an error.
+ **/
ETable *
e_table_construct_from_spec_file (ETable *e_table, ETableModel *etm, ETableExtras *ete,
const char *spec_fn, const char *state_fn)
@@ -1262,6 +1314,27 @@ e_table_construct_from_spec_file (ETable *e_table, ETableModel *etm, ETableExtra
return e_table;
}
+/**
+ * e_table_new:
+ * @etm: The model for this table.
+ * @ete: An optional #ETableExtras. (%NULL is valid.)
+ * @spec: The spec.
+ * @state: An optional state. (%NULL is valid.)
+ *
+ * This function creates an #ETable from the given parameters. The
+ * #ETableModel is a table model to be represented. The #ETableExtras
+ * is an optional set of pixbufs, cells, and sorting functions to be
+ * used when interpreting the spec. If you pass in %NULL it uses the
+ * default #ETableExtras. (See e_table_extras_new()).
+ *
+ * @spec is the specification of the set of viewable columns and the
+ * default sorting state and such. @state is an optional string
+ * specifying the current sorting state and such. If @state is NULL,
+ * then the default state from the spec will be used.
+ *
+ * Return value:
+ * The newly created #ETable or %NULL if there's an error.
+ **/
GtkWidget *
e_table_new (ETableModel *etm, ETableExtras *ete, const char *spec, const char *state)
{
@@ -1279,6 +1352,26 @@ e_table_new (ETableModel *etm, ETableExtras *ete, const char *spec, const char *
return GTK_WIDGET (e_table);
}
+/**
+ * e_table_new_from_spec_file:
+ * @etm: The model for this table.
+ * @ete: An optional #ETableExtras. (%NULL is valid.)
+ * @spec_fn: The filename of the spec.
+ * @state_fn: An optional state file. (%NULL is valid.)
+ *
+ * This is very similar to e_table_new(), except instead of passing in
+ * strings you pass in the file names of the spec and state to load.
+ *
+ * @spec_fn is the filename of the spec to load. If this file doesn't
+ * exist, e_table_new_from_spec_file will return %NULL.
+ *
+ * @state_fn is the filename of the initial state to load. If this is
+ * %NULL or if the specified file doesn't exist, the default state
+ * from the spec file is used.
+ *
+ * Return value:
+ * The newly created #ETable or %NULL if there's an error.
+ **/
GtkWidget *
e_table_new_from_spec_file (ETableModel *etm, ETableExtras *ete, const char *spec_fn, const char *state_fn)
{
@@ -1434,6 +1527,13 @@ e_table_load_specification (ETable *e_table, gchar *filename)
}
#endif
+/**
+ * e_table_set_cursor_row:
+ * @e_table: The #ETable to set the cursor row of
+ * @row: The row number
+ *
+ * Sets the cursor row and the selection to the given row number.
+ **/
void
e_table_set_cursor_row (ETable *e_table, int row)
{
@@ -1446,6 +1546,15 @@ e_table_set_cursor_row (ETable *e_table, int row)
NULL);
}
+/**
+ * e_table_get_cursor_row:
+ * @e_table: The #ETable to query
+ *
+ * Calculates the cursor row. -1 means that we don't have a cursor.
+ *
+ * Return value:
+ * Cursor row
+ **/
int
e_table_get_cursor_row (ETable *e_table)
{
@@ -1459,6 +1568,19 @@ e_table_get_cursor_row (ETable *e_table)
return row;
}
+/**
+ * e_table_selected_row_foreach:
+ * @e_table: The #ETable to act on
+ * @callback: The callback function to call
+ * @closure: The value passed to the callback's closure argument
+ *
+ * Calls the given @callback function once for every selected row.
+ *
+ * If you change the selection or delete or add rows to the table
+ * during these callbacks, problems can occur. A standard thing to do
+ * is to create a list of rows or objects the function is called upon
+ * and then act upon that list. (In inverse order if it's rows.)
+ **/
void
e_table_selected_row_foreach (ETable *e_table,
EForeachFunc callback,
@@ -1472,6 +1594,15 @@ e_table_selected_row_foreach (ETable *e_table,
closure);
}
+/**
+ * e_table_selected_count:
+ * @e_table: The #ETable to query
+ *
+ * Counts the number of selected rows.
+ *
+ * Return value:
+ * The number of rows selected.
+ **/
gint
e_table_selected_count (ETable *e_table)
{
@@ -1481,6 +1612,12 @@ e_table_selected_count (ETable *e_table)
return e_selection_model_selected_count(E_SELECTION_MODEL (e_table->selection));
}
+/**
+ * e_table_select_all:
+ * @table: The #ETable to modify
+ *
+ * Selects all the rows in @table.
+ **/
void
e_table_select_all (ETable *table)
{
@@ -1490,6 +1627,12 @@ e_table_select_all (ETable *table)
e_selection_model_select_all (E_SELECTION_MODEL (table->selection));
}
+/**
+ * e_table_invert_selection:
+ * @table: The #ETable to modify
+ *
+ * Inverts the selection in @table.
+ **/
void
e_table_invert_selection (ETable *table)
{
@@ -1500,6 +1643,15 @@ e_table_invert_selection (ETable *table)
}
+/**
+ * e_table_get_printable:
+ * @e_table: #ETable to query
+ *
+ * Used for printing your #ETable.
+ *
+ * Return value:
+ * The #EPrintable to print.
+ **/
EPrintable *
e_table_get_printable (ETable *e_table)
{
@@ -1509,12 +1661,25 @@ e_table_get_printable (ETable *e_table)
return e_table_group_get_printable(e_table->group);
}
+/**
+ * e_table_right_click_up:
+ * @table: The #ETable to modify.
+ *
+ * Call this function when you're done handling the right click if you
+ * return TRUE from the "right_click" signal.
+ **/
void
e_table_right_click_up (ETable *table)
{
e_selection_model_right_click_up(E_SELECTION_MODEL(table->selection));
}
+/**
+ * e_table_commit_click_to_add:
+ * @table: The #ETable to modify
+ *
+ * Commits the current values in the click to add to the table.
+ **/
void
e_table_commit_click_to_add (ETable *table)
{
@@ -1594,6 +1759,17 @@ set_scroll_adjustments (ETable *table,
hadjustment);
}
+/**
+ * e_table_get_next_row:
+ * @e_table: The #ETable to query
+ * @model_row: The model row to go from
+ *
+ * This function is used when your table is sorted, but you're using
+ * model row numbers. It returns the next row in sorted order as a model row.
+ *
+ * Return value:
+ * The model row number.
+ **/
gint
e_table_get_next_row (ETable *e_table,
gint model_row)
@@ -1616,6 +1792,18 @@ e_table_get_next_row (ETable *e_table,
return -1;
}
+/**
+ * e_table_get_prev_row:
+ * @e_table: The #ETable to query
+ * @model_row: The model row to go from
+ *
+ * This function is used when your table is sorted, but you're using
+ * model row numbers. It returns the previous row in sorted order as
+ * a model row.
+ *
+ * Return value:
+ * The model row number.
+ **/
gint
e_table_get_prev_row (ETable *e_table,
gint model_row)
@@ -1635,6 +1823,16 @@ e_table_get_prev_row (ETable *e_table,
return model_row - 1;
}
+/**
+ * e_table_model_to_view_row:
+ * @e_table: The #ETable to query
+ * @model_row: The model row number
+ *
+ * Turns a model row into a view row.
+ *
+ * Return value:
+ * The view row number.
+ **/
gint
e_table_model_to_view_row (ETable *e_table,
gint model_row)
@@ -1648,6 +1846,16 @@ e_table_model_to_view_row (ETable *e_table,
return model_row;
}
+/**
+ * e_table_view_to_model_row:
+ * @e_table: The #ETable to query
+ * @view_row: The view row number
+ *
+ * Turns a view row into a model row.
+ *
+ * Return value:
+ * The model row number.
+ **/
gint
e_table_view_to_model_row (ETable *e_table,
gint view_row)
@@ -1663,7 +1871,7 @@ e_table_view_to_model_row (ETable *e_table,
/**
* e_table_get_cell_at:
- * @table: An ETable widget
+ * @table: An #ETable widget
* @x: X coordinate for the pixel
* @y: Y coordinate for the pixel
* @row_return: Pointer to return the row value
@@ -1692,15 +1900,16 @@ e_table_get_cell_at (ETable *table,
/**
* e_table_get_cell_geometry:
- * @table: The table.
+ * @table: The #ETable.
* @row: The row to get the geometry of.
* @col: The col to get the geometry of.
- * @x_return: Returns the x coordinate of the upper right hand corner of the cell with respect to the widget.
- * @y_return: Returns the y coordinate of the upper right hand corner of the cell with respect to the widget.
+ * @x_return: Returns the x coordinate of the upper left hand corner of the cell with respect to the widget.
+ * @y_return: Returns the y coordinate of the upper left hand corner of the cell with respect to the widget.
* @width_return: Returns the width of the cell.
* @height_return: Returns the height of the cell.
*
- * Computes the data about this cell.
+ * Returns the x, y, width, and height of the given cell. These can
+ * all be #NULL and they just won't be set.
**/
void
e_table_get_cell_geometry (ETable *table,
@@ -1711,9 +1920,6 @@ e_table_get_cell_geometry (ETable *table,
g_return_if_fail (table != NULL);
g_return_if_fail (E_IS_TABLE (table));
- /* FIXME it would be nice if it could handle a NULL row_return or
- * col_return gracefully. */
-
e_table_group_get_cell_geometry(table->group, &row, &col, x_return, y_return, width_return, height_return);
if (x_return)
@@ -1724,6 +1930,16 @@ e_table_get_cell_geometry (ETable *table,
}
}
+/**
+ * e_table_get_selection_model:
+ * @table: The #ETable to query
+ *
+ * Returns the table's #ESelectionModel in case you want to access it
+ * directly.
+ *
+ * Return value:
+ * The #ESelectionModel.
+ **/
ESelectionModel *
e_table_get_selection_model (ETable *table)
{
@@ -1802,6 +2018,18 @@ struct _GtkDragSourceInfo
/* Drag & drop stuff. */
/* Target */
+
+/**
+ * e_table_drag_get_data:
+ * @table:
+ * @row:
+ * @col:
+ * @context:
+ * @target:
+ * @time:
+ *
+ *
+ **/
void
e_table_drag_get_data (ETable *table,
int row,
@@ -1819,17 +2047,17 @@ e_table_drag_get_data (ETable *table,
context,
target,
time);
-
}
/**
* e_table_drag_highlight:
- * @table:
- * @row:
- * @col:
+ * @table: The #ETable to highlight
+ * @row: The row number of the cell to highlight
+ * @col: The column number of the cell to highlight
*
- * Set col to -1 to highlight the entire row.
- */
+ * Set col to -1 to highlight the entire row. If row is -1, this is
+ * identical to e_table_drag_unhighlight().
+ **/
void
e_table_drag_highlight (ETable *table,
int row,
@@ -1872,6 +2100,12 @@ e_table_drag_highlight (ETable *table,
}
}
+/**
+ * e_table_drag_unhighlight:
+ * @table: The #ETable to unhighlight
+ *
+ * Removes the highlight from an #ETable.
+ **/
void
e_table_drag_unhighlight (ETable *table)
{
@@ -1964,6 +2198,16 @@ et_real_start_drag (ETable *table, int row, int col, GdkEvent *event)
return FALSE;
}
+/**
+ * e_table_drag_source_set:
+ * @table: The #ETable to set up as a drag site
+ * @start_button_mask: Mask of allowed buttons to start drag
+ * @targets: Table of targets for this source
+ * @n_targets: Number of targets in @targets
+ * @actions: Actions allowed for this source
+ *
+ * Registers this table as a drag site, and possibly adds default behaviors.
+ **/
void
e_table_drag_source_set (ETable *table,
GdkModifierType start_button_mask,
@@ -2005,6 +2249,12 @@ e_table_drag_source_set (ETable *table,
site->actions = actions;
}
+/**
+ * e_table_drag_source_unset:
+ * @table: The #ETable to un set up as a drag site
+ *
+ * Unregisters this #ETable as a drag site.
+ **/
void
e_table_drag_source_unset (ETable *table)
{
@@ -2026,6 +2276,21 @@ e_table_drag_source_unset (ETable *table)
* as a GtkTargetList
*/
+/**
+ * e_table_drag_begin:
+ * @table: The #ETable to drag from
+ * @row: The row number of the cell
+ * @col: The col number of the cell
+ * @targets: The list of targets supported by the drag
+ * @actions: The available actions supported by the drag
+ * @button: The button held down for the drag
+ * @event: The event that initiated the drag
+ *
+ * Start a drag from this cell.
+ *
+ * Return value:
+ * The drag context.
+ **/
GdkDragContext *
e_table_drag_begin (ETable *table,
int row,