## ETable

ETable

## Synopsis

                        ETableDragSourceSite;
    enum                ETableCursorLoc;
    struct              ETable;
    ETable *            e_table_construct                   (ETable *e_table,
                                                             ETableModel *etm,
                                                             ETableExtras *ete,
                                                             ETableSpecification *specification);
    GtkWidget *         e_table_new                         (ETableModel *etm,
                                                             ETableExtras *ete,
                                                             ETableSpecification *specification);
    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_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,
                                                             gint row);
    gint                e_table_get_cursor_row              (ETable *e_table);
    void                e_table_selected_row_foreach        (ETable *e_table,
                                                             EForeachFunc 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_get_cell_at                 (ETable *table,
                                                             gint x,
                                                             gint y,
                                                             gint *row_return,
                                                             gint *col_return);
    void                e_table_get_mouse_over_cell         (ETable *table,
                                                             gint *row,
                                                             gint *col);
    void                e_table_get_cell_geometry           (ETable *table,
                                                             gint row,
                                                             gint col,
                                                             gint *x_return,
                                                             gint *y_return,
                                                             gint *width_return,
                                                             gint *height_return);
    ESelectionModel *   e_table_get_selection_model         (ETable *table);
    void                e_table_drag_get_data               (ETable *table,
                                                             gint row,
                                                             gint col,
                                                             GdkDragContext *context,
                                                             GdkAtom target,
                                                             guint32 time);
    void                e_table_drag_highlight              (ETable *table,
                                                             gint row,
                                                             gint 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,
                                                             gint row,
                                                             gint col,
                                                             GtkTargetList *targets,
                                                             GdkDragAction actions,
                                                             gint button,
                                                             GdkEvent *event);
    void                e_table_select_all                  (ETable *table);
    void                e_table_right_click_up              (ETable *table);
    void                e_table_commit_click_to_add         (ETable *table);
    void                e_table_freeze_state_change         (ETable *table);
    void                e_table_thaw_state_change           (ETable *table);
    gboolean            e_table_is_editing                  (ETable *table);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkWidget
                   +----GtkContainer
                         +----GtkTable
                               +----ETable

## Implemented Interfaces

ETable implements AtkImplementorIface, GtkBuildable and GtkScrollable.

## Properties

      "always-search"            gboolean              : Read / Write
      "is-editing"               gboolean              : Read
      "length-threshold"         gint                  : Write
      "model"                    ETableModel*          : Read
      "uniform-row-height"       gboolean              : Read / Write
      "use-click-to-add"         gboolean              : Read / Write

## Style Properties

      "vertical-spacing"         gint                  : Read

## Signals

      "click"                                          : Run Last
      "cursor-activated"                               : Run Last
      "cursor-change"                                  : Run Last
      "double-click"                                   : Run Last
      "key-press"                                      : Run Last
      "right-click"                                    : Run Last
      "selection-change"                               : Run Last
      "start-drag"                                     : Run Last
      "state-change"                                   : Run Last
      "table-drag-begin"                               : Run Last
      "table-drag-data-delete"                         : Run Last
      "table-drag-data-get"                            : Run Last
      "table-drag-data-received"                       : Run Last
      "table-drag-drop"                                : Run Last
      "table-drag-end"                                 : Run Last
      "table-drag-leave"                               : Run Last
      "table-drag-motion"                              : Run Last
      "white-space-event"                              : Run Last

## Description

## Details

### 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_CURSOR_LOC_NONE` |
`E_TABLE_CURSOR_LOC_ETCTA` |
`E_TABLE_CURSOR_LOC_TABLE` |

### struct ETable

    struct ETable;

### e_table_construct ()

    ETable *            e_table_construct                   (ETable *e_table,
                                                             ETableModel *etm,
                                                             ETableExtras *ete,
                                                             ETableSpecification *specification);

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.)
`specification` : | an ETableSpecification
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,
                                                             ETableSpecification *specification);

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

`specification` 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.

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

### 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_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,
                                                             gint 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 ()

    gint                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,
                                                             EForeachFunc 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_get_cell_at ()

    void                e_table_get_cell_at                 (ETable *table,
                                                             gint x,
                                                             gint y,
                                                             gint *row_return,
                                                             gint *col_return);

Return the row and column for the cell in which the pixel at (`x`, `y`) is contained.

`table` : | An ETable widget
`x` : | X coordinate for the pixel
`y` : | Y coordinate for the pixel
`row_return` : | Pointer to return the row value
`col_return` : | Pointer to return the column value

### e_table_get_mouse_over_cell ()

    void                e_table_get_mouse_over_cell         (ETable *table,
                                                             gint *row,
                                                             gint *col);

Similar to e_table_get_cell_at, only here we check based on the mouse motion information in the group.

### e_table_get_cell_geometry ()

    void                e_table_get_cell_geometry           (ETable *table,
                                                             gint row,
                                                             gint col,
                                                             gint *x_return,
                                                             gint *y_return,
                                                             gint *width_return,
                                                             gint *height_return);

`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 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.
Returns : | the x, y, width, and height of the given cell. These can all be NULL and they just won't be set.

### e_table_get_selection_model ()

    ESelectionModel *   e_table_get_selection_model         (ETable *table);

Returns the table's ESelectionModel in case you want to access it directly.

`table` : | The ETable to query
Returns : | The ESelectionModel.

### e_table_drag_get_data ()

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

### e_table_drag_highlight ()

    void                e_table_drag_highlight              (ETable *table,
                                                             gint row,
                                                             gint 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);

### e_table_drag_dest_set_proxy ()

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

### e_table_drag_dest_unset ()

    void                e_table_drag_dest_unset             (GtkWidget *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,
                                                             gint row,
                                                             gint 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_right_click_up ()

    void                e_table_right_click_up              (ETable *table);

Call this function when you're done handling the right click if you return TRUE from the "right_click" signal.

`table` : | The ETable to modify.

### e_table_commit_click_to_add ()

    void                e_table_commit_click_to_add         (ETable *table);

Commits the current values in the click to add to the table.

`table` : | The ETable to modify

### e_table_freeze_state_change ()

    void                e_table_freeze_state_change         (ETable *table);

### e_table_thaw_state_change ()

    void                e_table_thaw_state_change           (ETable *table);

### e_table_is_editing ()

    gboolean            e_table_is_editing                  (ETable *table);

## Property Details

### The `"always-search"` property

      "always-search"            gboolean              : Read / Write

Default value: FALSE

### The `"is-editing"` property

      "is-editing"               gboolean              : Read

Whether is in an editing mode.

Default value: FALSE

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

      "length-threshold"         gint                  : Write

Allowed values: >= 0

Default value: 0

### The `"model"` property

      "model"                    ETableModel*          : Read

### The `"uniform-row-height"` property

      "uniform-row-height"       gboolean              : Read / Write

Default value: FALSE

### The `"use-click-to-add"` property

      "use-click-to-add"         gboolean              : Read / Write

Default value: FALSE

## Style Property Details

### The `"vertical-spacing"` style property

      "vertical-spacing"         gint                  : Read

Vertical space between rows. It is added to top and to bottom of a row.

Allowed values: >= 0

Default value: 3

## Signal Details

### The `"click"` signal

    gboolean            user_function                      (ETable   *etable,
                                                            gint      arg1,
                                                            gint      arg2,
                                                            GdkEvent *arg3,
                                                            gpointer  user_data)      : Run Last

### The `"cursor-activated"` signal

    void                user_function                      (ETable  *etable,
                                                            gint     arg1,
                                                            gpointer user_data)      : Run Last

### The `"cursor-change"` signal

    void                user_function                      (ETable  *etable,
                                                            gint     arg1,
                                                            gpointer user_data)      : Run Last

### The `"double-click"` signal

    void                user_function                      (ETable   *etable,
                                                            gint      arg1,
                                                            gint      arg2,
                                                            GdkEvent *arg3,
                                                            gpointer  user_data)      : Run Last

### The `"key-press"` signal

    gboolean            user_function                      (ETable   *etable,
                                                            gint      arg1,
                                                            gint      arg2,
                                                            GdkEvent *arg3,
                                                            gpointer  user_data)      : Run Last

### The `"right-click"` signal

    gboolean            user_function                      (ETable   *etable,
                                                            gint      arg1,
                                                            gint      arg2,
                                                            GdkEvent *arg3,
                                                            gpointer  user_data)      : Run Last

### The `"selection-change"` signal

    void                user_function                      (ETable  *etable,
                                                            gpointer user_data)      : Run Last

### The `"start-drag"` signal

    gboolean            user_function                      (ETable   *etable,
                                                            gint      arg1,
                                                            gint      arg2,
                                                            GdkEvent *arg3,
                                                            gpointer  user_data)      : Run Last

### The `"state-change"` signal

    void                user_function                      (ETable  *etable,
                                                            gpointer user_data)      : Run Last

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

    void                user_function                      (ETable         *etable,
                                                            gint            arg1,
                                                            gint            arg2,
                                                            GdkDragContext *arg3,
                                                            gpointer        user_data)      : Run Last

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

    void                user_function                      (ETable         *etable,
                                                            gint            arg1,
                                                            gint            arg2,
                                                            GdkDragContext *arg3,
                                                            gpointer        user_data)      : Run Last

### 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)      : Run Last

### 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)      : Run Last

### 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)      : Run Last

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

    void                user_function                      (ETable         *etable,
                                                            gint            arg1,
                                                            gint            arg2,
                                                            GdkDragContext *arg3,
                                                            gpointer        user_data)      : Run Last

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

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

### 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)      : Run Last

### The `"white-space-event"` signal

    gboolean            user_function                      (ETable   *etable,
                                                            GdkEvent *arg1,
                                                            gpointer  user_data)      : Run Last