ETable: Evolution Utilities Reference Manual

## ETable ETable |

## Functions

ETable * | e_table_construct ()
GtkWidget * | e_table_new ()
void | e_table_save_state ()
ETableState * | e_table_get_state_object ()
void | e_table_set_state_object ()
void | e_table_load_state ()
void | e_table_set_cursor_row ()
gint | e_table_get_cursor_row ()
void | e_table_selected_row_foreach ()
gint | e_table_selected_count ()
EPrintable * | e_table_get_printable ()
gint | e_table_get_next_row ()
gint | e_table_get_prev_row ()
gint | e_table_model_to_view_row ()
gint | e_table_view_to_model_row ()
void | e_table_get_cell_at ()
void | e_table_get_mouse_over_cell ()
void | e_table_get_cell_geometry ()
ESelectionModel * | e_table_get_selection_model ()
void | e_table_drag_get_data ()
void | e_table_drag_highlight ()
void | e_table_drag_unhighlight ()
void | e_table_drag_dest_set ()
void | e_table_drag_dest_set_proxy ()
void | e_table_drag_dest_unset ()
void | e_table_drag_source_set ()
void | e_table_drag_source_unset ()
GdkDragContext * | e_table_drag_begin ()
void | e_table_select_all ()
void | e_table_right_click_up ()
void | e_table_commit_click_to_add ()
void | e_table_freeze_state_change ()
void | e_table_thaw_state_change ()
gboolean | e_table_is_editing ()
void | e_table_customize_view ()
void | e_table_set_info_message ()

## Properties

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

## Signals

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

## Types and Values

enum | ETableCursorLoc
| ETableDragSourceSite

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── GtkGrid
                        ╰── ETable

## Description

## Functions

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

Returns the x, y, width, and height of the given cell. These can all be NULL and they just won't be set.

#### Parameters

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

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

### e_table_customize_view ()

    void
    e_table_customize_view (ETable *table);

### e_table_set_info_message ()

    void
    e_table_set_info_message (ETable *table,
                              const gchar *info_message);

Creates an info message in table area, or removes old.

#### Parameters

table | ETable instance |
info_message | Message to set. Can be NULL. |

## Types and Values

### enum ETableCursorLoc

#### Members

E_TABLE_CURSOR_LOC_NONE |  |
E_TABLE_CURSOR_LOC_ETCTA |  |
E_TABLE_CURSOR_LOC_TABLE |  |

### ETableDragSourceSite

    typedef struct _ETableDragSourceSite ETableDragSourceSite;

## Property Details

### The `“always-search”` property

      “always-search”            gboolean

Owner: ETable

Flags: Read / Write

Default value: FALSE

### The `“is-editing”` property

      “is-editing”               gboolean

Whether is in an editing mode.

Owner: ETable

Flags: Read

Default value: FALSE

### The `“length-threshold”` property

      “length-threshold”         int

Owner: ETable

Flags: Write

Allowed values: >= 0

Default value: 0

### The `“model”` property

      “model”                    ETableModel *

Owner: ETable

Flags: Read

### The `“uniform-row-height”` property

      “uniform-row-height”       gboolean

Owner: ETable

Flags: Read / Write

Default value: FALSE

### The `“use-click-to-add”` property

      “use-click-to-add”         gboolean

Owner: ETable

Flags: Read / Write

Default value: FALSE

## Signal Details

### The `“click”` signal

    gboolean
    user_function (ETable   *etable,
                   int       arg1,
                   int       arg2,
                   GdkEvent *arg3,
                   gpointer  user_data)

Flags: Run Last

### The `“cursor-activated”` signal

    void
    user_function (ETable  *etable,
                   int      arg1,
                   gpointer user_data)

Flags: Run Last

### The `“cursor-change”` signal

    void
    user_function (ETable  *etable,
                   int      arg1,
                   gpointer user_data)

Flags: Run Last

### The `“double-click”` signal

    void
    user_function (ETable   *etable,
                   int       arg1,
                   int       arg2,
                   GdkEvent *arg3,
                   gpointer  user_data)

Flags: Run Last

### The `“key-press”` signal

    gboolean
    user_function (ETable   *etable,
                   int       arg1,
                   int       arg2,
                   GdkEvent *arg3,
                   gpointer  user_data)

Flags: Run Last

### The `“right-click”` signal

    gboolean
    user_function (ETable   *etable,
                   int       arg1,
                   int       arg2,
                   GdkEvent *arg3,
                   gpointer  user_data)

Flags: Run Last

### The `“selection-change”` signal

    void
    user_function (ETable  *etable,
                   gpointer user_data)

Flags: Run Last

### The `“start-drag”` signal

    gboolean
    user_function (ETable   *etable,
                   int       arg1,
                   int       arg2,
                   GdkEvent *arg3,
                   gpointer  user_data)

Flags: Run Last

### The `“state-change”` signal

    void
    user_function (ETable  *etable,
                   gpointer user_data)

Flags: Run Last

### The `“table-drag-begin”` signal

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

Flags: Run Last

### The `“table-drag-data-delete”` signal

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

Flags: Run Last

### The `“table-drag-data-get”` signal

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

Flags: Run Last

### The `“table-drag-data-received”` signal

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

Flags: Run Last

### The `“table-drag-drop”` signal

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

Flags: Run Last

### The `“table-drag-end”` signal

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

Flags: Run Last

### The `“table-drag-leave”` signal

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

Flags: Run Last

### The `“table-drag-motion”` signal

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

Flags: Run Last

### The `“white-space-event”` signal

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

Flags: Run Last