# ETable

## Name

ETable --

## Synopsis

    #define     E_TABLE_TYPE
    typedef     ETable;
                ETableDragSourceSite;
    enum        ETableCursorLoc;
    ETable*     e_table_construct               (ETable *e_table,
                                                 ETableModel *etm,
                                                 ETableExtras *ete,
                                                 const char *spec,
                                                 const char *state);
    GtkWidget*  e_table_new                     (ETableModel *etm,
                                                 ETableExtras *ete,
                                                 const char *spec,
                                                 const char *state);
    ETable*     e_table_construct_from_spec_file
                                                (ETable *e_table,
                                                 ETableModel *etm,
                                                 ETableExtras *ete,
                                                 const char *spec_fn,
                                                 const char *state_fn);
    GtkWidget*  e_table_new_from_spec_file      (ETableModel *etm,
                                                 ETableExtras *ete,
                                                 const char *spec_fn,
                                                 const char *state_fn);
    gchar*      e_table_get_state               (ETable *e_table);
    void        e_table_save_state              (ETable *e_table,
                                                 const gchar *filename);
    ETableState* e_table_get_state_object       (ETable *e_table);
    void        e_table_set_state               (ETable *e_table,
                                                 const gchar *state);
    void        e_table_set_state_object        (ETable *e_table,
                                                 ETableState *state);
    void        e_table_load_state              (ETable *e_table,
                                                 const gchar *filename);
    void        e_table_set_cursor_row          (ETable *e_table,
                                                 int row);
    int         e_table_get_cursor_row          (ETable *e_table);
    void        e_table_selected_row_foreach    (ETable *e_table,
                                                 ETableForeachFunc callback,
                                                 gpointer closure);
    gint        e_table_selected_count          (ETable *e_table);
    EPrintable* e_table_get_printable           (ETable *e_table);
    gint        e_table_get_next_row            (ETable *e_table,
                                                 gint model_row);
    gint        e_table_get_prev_row            (ETable *e_table,
                                                 gint model_row);
    gint        e_table_model_to_view_row       (ETable *e_table,
                                                 gint model_row);
    gint        e_table_view_to_model_row       (ETable *e_table,
                                                 gint view_row);
    void        e_table_drag_get_data           (ETable *table,
                                                 int row,
                                                 int col,
                                                 GdkDragContext *context,
                                                 GdkAtom target,
                                                 guint32 time);
    void        e_table_drag_highlight          (ETable *table,
                                                 int row,
                                                 int col);
    void        e_table_drag_unhighlight        (ETable *table);
    void        e_table_drag_dest_set           (ETable *table,
                                                 GtkDestDefaults flags,
                                                 const GtkTargetEntry *targets,
                                                 gint n_targets,
                                                 GdkDragAction actions);
    void        e_table_drag_dest_set_proxy     (ETable *table,
                                                 GdkWindow *proxy_window,
                                                 GdkDragProtocol protocol,
                                                 gboolean use_coordinates);
    void        e_table_drag_dest_unset         (GtkWidget *widget);
    void        e_table_drag_source_set         (ETable *table,
                                                 GdkModifierType start_button_mask,
                                                 const GtkTargetEntry *targets,
                                                 gint n_targets,
                                                 GdkDragAction actions);
    void        e_table_drag_source_unset       (ETable *table);
    GdkDragContext* e_table_drag_begin          (ETable *table,
                                                 int row,
                                                 int col,
                                                 GtkTargetList *targets,
                                                 GdkDragAction actions,
                                                 gint button,
                                                 GdkEvent *event);
    void        e_table_select_all              (ETable *table);
    void        e_table_invert_selection        (ETable *table);

## Object Hierarchy

      GtkObject
       +----GtkWidget
             +----GtkContainer
                   +----GtkTable
                         +----ETable

## Properties

      "drawfocus"            gboolean              : Read / Write
      "length-threshold"     gint                  : Write

## Signal Prototypes

    "cursor-change"
                void        user_function      (ETable *etable,
                                                gint arg1,
                                                gpointer user_data);
    "selection-change"
                void        user_function      (ETable *etable,
                                                gpointer user_data);
    "double-click"
                void        user_function      (ETable *etable,
                                                gint arg1,
                                                gint arg2,
                                                gpointer arg3,
                                                gpointer user_data);
    "right-click"
                gint        user_function      (ETable *etable,
                                                gint arg1,
                                                gint arg2,
                                                gpointer arg3,
                                                gpointer user_data);
    "click"     gint        user_function      (ETable *etable,
                                                gint arg1,
                                                gint arg2,
                                                gpointer arg3,
                                                gpointer user_data);
    "key-press" gint        user_function      (ETable *etable,
                                                gint arg1,
                                                gint arg2,
                                                gpointer arg3,
                                                gpointer user_data);
    "table-drag-begin"
                void        user_function      (ETable *etable,
                                                gint arg1,
                                                gint arg2,
                                                GdkDragContext *arg3,
                                                gpointer user_data);
    "table-drag-end"
                void        user_function      (ETable *etable,
                                                gint arg1,
                                                gint arg2,
                                                GdkDragContext *arg3,
                                                gpointer user_data);
    "table-drag-data-get"
                void        user_function      (ETable *etable,
                                                gint arg1,
                                                gint arg2,
                                                GdkDragContext *arg3,
                                                GtkSelectionData *arg4,
                                                guint arg5,
                                                guint arg6,
                                                gpointer user_data);
    "table-drag-data-delete"
                void        user_function      (ETable *etable,
                                                gint arg1,
                                                gint arg2,
                                                GdkDragContext *arg3,
                                                gpointer user_data);
    "table-drag-leave"
                void        user_function      (ETable *etable,
                                                gint arg1,
                                                gint arg2,
                                                GdkDragContext *arg3,
                                                guint arg4,
                                                gpointer user_data);
    "table-drag-motion"
                gboolean    user_function      (ETable *etable,
                                                gint arg1,
                                                gint arg2,
                                                GdkDragContext *arg3,
                                                gint arg4,
                                                gint arg5,
                                                guint arg6,
                                                gpointer user_data);
    "table-drag-drop"
                gboolean    user_function      (ETable *etable,
                                                gint arg1,
                                                gint arg2,
                                                GdkDragContext *arg3,
                                                gint arg4,
                                                gint arg5,
                                                guint arg6,
                                                gpointer user_data);
    "table-drag-data-received"
                void        user_function      (ETable *etable,
                                                gint arg1,
                                                gint arg2,
                                                GdkDragContext *arg3,
                                                gint arg4,
                                                gint arg5,
                                                GtkSelectionData *arg6,
                                                guint arg7,
                                                guint arg8,
                                                gpointer user_data);

## Description

## Details

### E_TABLE_TYPE

    #define E_TABLE_TYPE        (e_table_get_type ())

### ETable

    typedef struct {
    	GtkTable parent;

    	ETableModel *model;

    	ETableHeader *full_header, *header;

    	GnomeCanvasItem *canvas_vbox;
    	ETableGroup  *group;

    	ETableSortInfo *sort_info;
    	ETableSorter   *sorter;

    	ETableSelectionModel *selection;
    	ETableCursorLoc cursor_loc;
    	ETableSpecification *spec;

    	int table_model_change_id;
    	int table_row_change_id;
    	int table_cell_change_id;
    	int table_row_inserted_id;
    	int table_row_deleted_id;

    	int group_info_change_id;

    	int reflow_idle_id;

    	GnomeCanvas *header_canvas, *table_canvas;

    	GnomeCanvasItem *header_item, *root;

    	GnomeCanvasItem *white_item;

    	gint length_threshold;

    	gint rebuild_idle_id;
    	guint need_rebuild:1;

    	/*
    	 * Configuration settings
    	 */
    	guint draw_grid : 1;
    	guint draw_focus : 1;
    	guint row_selection_active : 1;

    	char *click_to_add_message;
    	GnomeCanvasItem *click_to_add;
    	gboolean use_click_to_add;

    	ETableCursorMode cursor_mode;

    	int drag_get_data_row;
    	int drag_get_data_col;

    	int drop_row;
    	int drop_col;

    	int drag_row;
    	int drag_col;
    	ETableDragSourceSite *site;

    	int drag_source_button_press_event_id;
    	int drag_source_motion_notify_event_id;
    } ETable;

### ETableDragSourceSite

    typedef struct _ETableDragSourceSite ETableDragSourceSite;

### enum ETableCursorLoc

    typedef enum {
    	E_TABLE_CURSOR_LOC_NONE = 0,
    	E_TABLE_CURSOR_LOC_ETCTA = 1 << 0,
    	E_TABLE_CURSOR_LOC_TABLE = 1 << 1,
    } ETableCursorLoc;

### e_table_construct ()

    ETable*     e_table_construct               (ETable *e_table,
                                                 ETableModel *etm,
                                                 ETableExtras *ete,
                                                 const char *spec,
                                                 const char *state);

This is the internal implementation of `e_table_new()` for use by subclasses or language bindings. See `e_table_new()` for details.

`e_table` : | The newly created ETable object.
`etm` : | The model for this table.
`ete` : | An optional ETableExtras. (`NULL` is valid.)
`spec` : |
`state` : |
Returns : | The passed in value `e_table` or `NULL` if there's an error.

### e_table_new ()

    GtkWidget*  e_table_new                     (ETableModel *etm,
                                                 ETableExtras *ete,
                                                 const char *spec,
                                                 const char *state);

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.

`etm` : | The model for this table.
`ete` : | An optional ETableExtras. (`NULL` is valid.)
`spec` : | The spec.
`state` : | An optional state. (`NULL` is valid.)
Returns : | The newly created ETable or `NULL` if there's an error.

### e_table_construct_from_spec_file ()

    ETable*     e_table_construct_from_spec_file
                                                (ETable *e_table,
                                                 ETableModel *etm,
                                                 ETableExtras *ete,
                                                 const char *spec_fn,
                                                 const char *state_fn);

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.

`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.)
Returns : | The passed in value `e_table` or `NULL` if there's an error.

### e_table_new_from_spec_file ()

    GtkWidget*  e_table_new_from_spec_file      (ETableModel *etm,
                                                 ETableExtras *ete,
                                                 const char *spec_fn,
                                                 const char *state_fn);

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.

`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.)
Returns : | The newly created ETable or `NULL` if there's an error.

### e_table_get_state ()

    gchar*      e_table_get_state               (ETable *e_table);

Builds a state object based on the current state and returns the string corresponding to that state.

`e_table` : | The ETable to act on.
Returns : | A string describing the current state of the ETable.

### e_table_save_state ()

    void        e_table_save_state              (ETable *e_table,
                                                 const gchar *filename);

Saves the state of the `e_table` object into the file pointed by `filename`.

`e_table` : | The ETable to act on
`filename` : | name of the file to save to

### e_table_get_state_object ()

    ETableState* e_table_get_state_object       (ETable *e_table);

Builds an ETableState corresponding to the current state of the ETable.

`e_table` : | ETable object to act on
Returns : | The `ETableState` object generated.

### e_table_set_state ()

    void        e_table_set_state               (ETable *e_table,
                                                 const gchar *state);

This routine sets the state of the ETable from a string.

`e_table` : | The ETable object to modify
`state` : |

### e_table_set_state_object ()

    void        e_table_set_state_object        (ETable *e_table,
                                                 ETableState *state);

This routine sets the state of the ETable from the given ETableState.

`e_table` : | The ETable object to modify
`state` : | The ETableState to use

### e_table_load_state ()

    void        e_table_load_state              (ETable *e_table,
                                                 const gchar *filename);

This routine sets the state of the ETable from a file.

`e_table` : | The ETable object to modify
`filename` : | name of the file to use

### e_table_set_cursor_row ()

    void        e_table_set_cursor_row          (ETable *e_table,
                                                 int row);

Sets the cursor row and the selection to the given row number.

`e_table` : | The ETable to set the cursor row of
`row` : | The row number

### e_table_get_cursor_row ()

    int         e_table_get_cursor_row          (ETable *e_table);

Calculates the cursor row. -1 means that we don't have a cursor.

`e_table` : | The ETable to query
Returns : | Cursor row

### e_table_selected_row_foreach ()

    void        e_table_selected_row_foreach    (ETable *e_table,
                                                 ETableForeachFunc callback,
                                                 gpointer closure);

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.)

`e_table` : | The ETable to act on
`callback` : | The callback function to call
`closure` : | The value passed to the callback's closure argument

### e_table_selected_count ()

    gint        e_table_selected_count          (ETable *e_table);

Counts the number of selected rows.

`e_table` : | The ETable to query
Returns : | The number of rows selected.

### e_table_get_printable ()

    EPrintable* e_table_get_printable           (ETable *e_table);

Used for printing your ETable.

`e_table` : | ETable to query
Returns : | The EPrintable to print.

### e_table_get_next_row ()

    gint        e_table_get_next_row            (ETable *e_table,
                                                 gint model_row);

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.

`e_table` : | The ETable to query
`model_row` : | The model row to go from
Returns : | The model row number.

### e_table_get_prev_row ()

    gint        e_table_get_prev_row            (ETable *e_table,
                                                 gint model_row);

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.

`e_table` : | The ETable to query
`model_row` : | The model row to go from
Returns : | The model row number.

### e_table_model_to_view_row ()

    gint        e_table_model_to_view_row       (ETable *e_table,
                                                 gint model_row);

Turns a model row into a view row.

`e_table` : | The ETable to query
`model_row` : | The model row number
Returns : | The view row number.

### e_table_view_to_model_row ()

    gint        e_table_view_to_model_row       (ETable *e_table,
                                                 gint view_row);

Turns a view row into a model row.

`e_table` : | The ETable to query
`view_row` : | The view row number
Returns : | The model row number.

### e_table_drag_get_data ()

    void        e_table_drag_get_data           (ETable *table,
                                                 int row,
                                                 int col,
                                                 GdkDragContext *context,
                                                 GdkAtom target,
                                                 guint32 time);

`table` : |
`row` : |
`col` : |
`context` : |
`target` : |
`time` : |

### e_table_drag_highlight ()

    void        e_table_drag_highlight          (ETable *table,
                                                 int row,
                                                 int col);

Set col to -1 to highlight the entire row. If row is -1, this is identical to `e_table_drag_unhighlight()`.

`table` : | The ETable to highlight
`row` : | The row number of the cell to highlight
`col` : | The column number of the cell to highlight

### e_table_drag_unhighlight ()

    void        e_table_drag_unhighlight        (ETable *table);

Removes the highlight from an ETable.

`table` : | The ETable to unhighlight

### e_table_drag_dest_set ()

    void        e_table_drag_dest_set           (ETable *table,
                                                 GtkDestDefaults flags,
                                                 const GtkTargetEntry *targets,
                                                 gint n_targets,
                                                 GdkDragAction actions);

`table` : |
`flags` : |
`targets` : |
`n_targets` : |
`actions` : |

### e_table_drag_dest_set_proxy ()

    void        e_table_drag_dest_set_proxy     (ETable *table,
                                                 GdkWindow *proxy_window,
                                                 GdkDragProtocol protocol,
                                                 gboolean use_coordinates);

`table` : |
`proxy_window` : |
`protocol` : |
`use_coordinates` : |

### e_table_drag_dest_unset ()

    void        e_table_drag_dest_unset         (GtkWidget *widget);

`widget` : |

### e_table_drag_source_set ()

    void        e_table_drag_source_set         (ETable *table,
                                                 GdkModifierType start_button_mask,
                                                 const GtkTargetEntry *targets,
                                                 gint n_targets,
                                                 GdkDragAction actions);

Registers this table as a drag site, and possibly adds default behaviors.

`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

### e_table_drag_source_unset ()

    void        e_table_drag_source_unset       (ETable *table);

Unregisters this ETable as a drag site.

`table` : | The ETable to un set up as a drag site

### e_table_drag_begin ()

    GdkDragContext* e_table_drag_begin          (ETable *table,
                                                 int row,
                                                 int col,
                                                 GtkTargetList *targets,
                                                 GdkDragAction actions,
                                                 gint button,
                                                 GdkEvent *event);

Start a drag from this cell.

`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
Returns : | The drag context.

### e_table_select_all ()

    void        e_table_select_all              (ETable *table);

Selects all the rows in `table`.

`table` : | The ETable to modify

### e_table_invert_selection ()

    void        e_table_invert_selection        (ETable *table);

Inverts the selection in `table`.

`table` : | The ETable to modify

## Properties

### The "`drawfocus`" property

      "drawfocus"            gboolean              : Read / Write

### The "`length-threshold`" property

      "length-threshold"     gint                  : Write

## Signals

### The "cursor-change" signal

    void        user_function                  (ETable *etable,
                                                gint arg1,
                                                gpointer user_data);

`etable` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The "selection-change" signal

    void        user_function                  (ETable *etable,
                                                gpointer user_data);

`etable` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The "double-click" signal

    void        user_function                  (ETable *etable,
                                                gint arg1,
                                                gint arg2,
                                                gpointer arg3,
                                                gpointer user_data);

`etable` : | the object which received the signal.
`arg1` : |
`arg2` : |
`arg3` : |
`user_data` : | user data set when the signal handler was connected.

### The "right-click" signal

    gint        user_function                  (ETable *etable,
                                                gint arg1,
                                                gint arg2,
                                                gpointer arg3,
                                                gpointer user_data);

`etable` : | the object which received the signal.
`arg1` : |
`arg2` : |
`arg3` : |
`user_data` : | user data set when the signal handler was connected.
Returns : |

### The "click" signal

    gint        user_function                  (ETable *etable,
                                                gint arg1,
                                                gint arg2,
                                                gpointer arg3,
                                                gpointer user_data);

`etable` : | the object which received the signal.
`arg1` : |
`arg2` : |
`arg3` : |
`user_data` : | user data set when the signal handler was connected.
Returns : |

### The "key-press" signal

    gint        user_function                  (ETable *etable,
                                                gint arg1,
                                                gint arg2,
                                                gpointer arg3,
                                                gpointer user_data);

`etable` : | the object which received the signal.
`arg1` : |
`arg2` : |
`arg3` : |
`user_data` : | user data set when the signal handler was connected.
Returns : |

### The "table-drag-begin" signal

    void        user_function                  (ETable *etable,
                                                gint arg1,
                                                gint arg2,
                                                GdkDragContext *arg3,
                                                gpointer user_data);

`etable` : | the object which received the signal.
`arg1` : |
`arg2` : |
`arg3` : |
`user_data` : | user data set when the signal handler was connected.

### The "table-drag-end" signal

    void        user_function                  (ETable *etable,
                                                gint arg1,
                                                gint arg2,
                                                GdkDragContext *arg3,
                                                gpointer user_data);

`etable` : | the object which received the signal.
`arg1` : |
`arg2` : |
`arg3` : |
`user_data` : | user data set when the signal handler was connected.

### The "table-drag-data-get" signal

    void        user_function                  (ETable *etable,
                                                gint arg1,
                                                gint arg2,
                                                GdkDragContext *arg3,
                                                GtkSelectionData *arg4,
                                                guint arg5,
                                                guint arg6,
                                                gpointer user_data);

`etable` : | the object which received the signal.
`arg1` : |
`arg2` : |
`arg3` : |
`arg4` : |
`arg5` : |
`arg6` : |
`user_data` : | user data set when the signal handler was connected.

### The "table-drag-data-delete" signal

    void        user_function                  (ETable *etable,
                                                gint arg1,
                                                gint arg2,
                                                GdkDragContext *arg3,
                                                gpointer user_data);

`etable` : | the object which received the signal.
`arg1` : |
`arg2` : |
`arg3` : |
`user_data` : | user data set when the signal handler was connected.

### The "table-drag-leave" signal

    void        user_function                  (ETable *etable,
                                                gint arg1,
                                                gint arg2,
                                                GdkDragContext *arg3,
                                                guint arg4,
                                                gpointer user_data);

`etable` : | the object which received the signal.
`arg1` : |
`arg2` : |
`arg3` : |
`arg4` : |
`user_data` : | user data set when the signal handler was connected.

### The "table-drag-motion" signal

    gboolean    user_function                  (ETable *etable,
                                                gint arg1,
                                                gint arg2,
                                                GdkDragContext *arg3,
                                                gint arg4,
                                                gint arg5,
                                                guint arg6,
                                                gpointer user_data);

`etable` : | the object which received the signal.
`arg1` : |
`arg2` : |
`arg3` : |
`arg4` : |
`arg5` : |
`arg6` : |
`user_data` : | user data set when the signal handler was connected.
Returns : |

### The "table-drag-drop" signal

    gboolean    user_function                  (ETable *etable,
                                                gint arg1,
                                                gint arg2,
                                                GdkDragContext *arg3,
                                                gint arg4,
                                                gint arg5,
                                                guint arg6,
                                                gpointer user_data);

`etable` : | the object which received the signal.
`arg1` : |
`arg2` : |
`arg3` : |
`arg4` : |
`arg5` : |
`arg6` : |
`user_data` : | user data set when the signal handler was connected.
Returns : |

### The "table-drag-data-received" signal

    void        user_function                  (ETable *etable,
                                                gint arg1,
                                                gint arg2,
                                                GdkDragContext *arg3,
                                                gint arg4,
                                                gint arg5,
                                                GtkSelectionData *arg6,
                                                guint arg7,
                                                guint arg8,
                                                gpointer user_data);

`etable` : | the object which received the signal.
`arg1` : |
`arg2` : |
`arg3` : |
`arg4` : |
`arg5` : |
`arg6` : |
`arg7` : |
`arg8` : |
`user_data` : | user data set when the signal handler was connected.