# ETableSortInfo

## Name

ETableSortInfo -- Sorting and grouping information handling.

## Synopsis

    #define     E_TABLE_SORT_INFO_TYPE
    typedef     ETableSortInfo;
                ETableSortColumn;
    void        e_table_sort_info_freeze        (ETableSortInfo *info);
    void        e_table_sort_info_thaw          (ETableSortInfo *info);
    guint       e_table_sort_info_grouping_get_count
                                                (ETableSortInfo *info);
    void        e_table_sort_info_grouping_truncate
                                                (ETableSortInfo *info,
                                                 int length);
    ETableSortColumn e_table_sort_info_grouping_get_nth
                                                (ETableSortInfo *info,
                                                 int n);
    void        e_table_sort_info_grouping_set_nth
                                                (ETableSortInfo *info,
                                                 int n,
                                                 ETableSortColumn column);
    guint       e_table_sort_info_sorting_get_count
                                                (ETableSortInfo *info);
    void        e_table_sort_info_sorting_truncate
                                                (ETableSortInfo *info,
                                                 int length);
    ETableSortColumn e_table_sort_info_sorting_get_nth
                                                (ETableSortInfo *info,
                                                 int n);
    void        e_table_sort_info_sorting_set_nth
                                                (ETableSortInfo *info,
                                                 int n,
                                                 ETableSortColumn column);
    ETableSortInfo* e_table_sort_info_new       (void);
    void        e_table_sort_info_load_from_node
                                                (ETableSortInfo *info,
                                                 xmlNode *node);
    xmlNode*    e_table_sort_info_save_to_node  (ETableSortInfo *info,
                                                 xmlNode *parent);

## Object Hierarchy

      GtkObject
       +----ETableSortInfo

## Signal Prototypes

    "sort-info-changed"
                void        user_function      (ETableSortInfo *etablesortinfo,
                                                gpointer user_data);
    "group-info-changed"
                void        user_function      (ETableSortInfo *etablesortinfo,
                                                gpointer user_data);

## Description

The `ETableSortInfo` is typically one of the elements of an `ETableState` object.

The `ETableSortInfo` object is used to maintain the multi-level sorting and multi-level grouping information that is used by the ETable widget. By appending sorting criterias (using the `e_table_sort_info_grouping_set_nth()` and e_table_sort_info_sorting_set_nth you can append new criteria about how sorting and grouping should take place in the ETable.

This object emits the `sort_info_changed' and `group_info_changed' signals when grouping and sorting are added, modified or removed.

You can at any point reduce the criteria by using the "truncate" functions; You can modify any criteria by using the "set" functions, and you can get the individual state information by using the "get" functions.

## Details

### E_TABLE_SORT_INFO_TYPE

    #define E_TABLE_SORT_INFO_TYPE        (e_table_sort_info_get_type ())

### ETableSortInfo

    typedef struct {
    	GtkObject   base;

    	gint group_count;
    	ETableSortColumn *groupings;
    	gint sort_count;
    	ETableSortColumn *sortings;

    	guint frozen : 1;
    	guint sort_info_changed : 1;
    	guint group_info_changed : 1;
    } ETableSortInfo;

### ETableSortColumn

    typedef struct {
    	guint column : 31;
    	guint ascending : 1;
    } ETableSortColumn;

The bit field ascending is interpreted as a boolean value that will trigger ascending ordering. The column is an integer that reflects the column.

### e_table_sort_info_freeze ()

    void        e_table_sort_info_freeze        (ETableSortInfo *info);

This functions allows the programmer to cluster various changes to the ETableSortInfo (grouping and sorting) without having the object emit "group_info_changed" or "sort_info_changed" signals on each change.

To thaw, invoke the `e_table_sort_info_thaw()` function, which will trigger any signals that might have been queued.

`info` : | The ETableSortInfo object

### e_table_sort_info_thaw ()

    void        e_table_sort_info_thaw          (ETableSortInfo *info);

This functions allows the programmer to cluster various changes to the ETableSortInfo (grouping and sorting) without having the object emit "group_info_changed" or "sort_info_changed" signals on each change.

This function will flush any pending signals that might be emited by this object.

`info` : | The ETableSortInfo object

### e_table_sort_info_grouping_get_count ()

    guint       e_table_sort_info_grouping_get_count
                                                (ETableSortInfo *info);

`info` : | The ETableSortInfo object
Returns : | the number of grouping criteria in the object.

### e_table_sort_info_grouping_truncate ()

    void        e_table_sort_info_grouping_truncate
                                                (ETableSortInfo *info,
                                                 int length);

This routine can be used to reduce or grow the number of grouping criteria in the object.

`info` : | The ETableSortInfo object
`length` : |

### e_table_sort_info_grouping_get_nth ()

    ETableSortColumn e_table_sort_info_grouping_get_nth
                                                (ETableSortInfo *info,
                                                 int n);

`info` : | The ETableSortInfo object
`n` : | Item information to fetch.
Returns : | the description of the `n`-th grouping criteria in the `info` object.

### e_table_sort_info_grouping_set_nth ()

    void        e_table_sort_info_grouping_set_nth
                                                (ETableSortInfo *info,
                                                 int n,
                                                 ETableSortColumn column);

Sets the grouping criteria for index `n` to be given by `column` (a column number and whether it is ascending or descending).

`info` : | The ETableSortInfo object
`n` : | Item information to fetch.
`column` : | new values for the grouping

### e_table_sort_info_sorting_get_count ()

    guint       e_table_sort_info_sorting_get_count
                                                (ETableSortInfo *info);

`info` : |
Returns : |

### e_table_sort_info_sorting_truncate ()

    void        e_table_sort_info_sorting_truncate
                                                (ETableSortInfo *info,
                                                 int length);

This routine can be used to reduce or grow the number of sort criteria in the object.

`info` : | The ETableSortInfo object
`length` : |

### e_table_sort_info_sorting_get_nth ()

    ETableSortColumn e_table_sort_info_sorting_get_nth
                                                (ETableSortInfo *info,
                                                 int n);

Sets the sorting criteria for index `n` to be given by `column` (a column number and whether it is ascending or descending).

`info` : | The ETableSortInfo object
`n` : | Item information to fetch.
Returns : |

### e_table_sort_info_sorting_set_nth ()

    void        e_table_sort_info_sorting_set_nth
                                                (ETableSortInfo *info,
                                                 int n,
                                                 ETableSortColumn column);

`info` : |
`n` : |
`column` : |

### e_table_sort_info_new ()

    ETableSortInfo* e_table_sort_info_new       (void);

This creates a new e_table_sort_info object that contains no grouping and no sorting defined as of yet. This object is used to keep track of multi-level sorting and multi-level grouping of the ETable.

Returns : | A new `ETableSortInfo` object

### e_table_sort_info_load_from_node ()

    void        e_table_sort_info_load_from_node
                                                (ETableSortInfo *info,
                                                 xmlNode *node);

This loads the state for the `ETableSortInfo` object `info` from the xml node `node`.

`info` : | The ETableSortInfo object
`node` : | pointer to the xmlNode that describes the sorting and grouping information

### e_table_sort_info_save_to_node ()

    xmlNode*    e_table_sort_info_save_to_node  (ETableSortInfo *info,
                                                 xmlNode *parent);

This function is used

`info` : | The ETableSortInfo object
`parent` : | xmlNode that will be hosting the saved state of the `info` object.
Returns : | the node that has been appended to `parent` as a child containing the sorting and grouping information for this ETableSortInfo object.

## Signals

### The "sort-info-changed" signal

    void        user_function                  (ETableSortInfo *etablesortinfo,
                                                gpointer user_data);

This signal is emitted when the sort information has been changed trough the API.

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

### The "group-info-changed" signal

    void        user_function                  (ETableSortInfo *etablesortinfo,
                                                gpointer user_data);

This signal is emitted when the grouping information has been changed trough the API>

## See Also

`ETable`, `ETableState`.