## ECategories

ECategories

## Synopsis

    GList *             e_categories_get_list               (void);
    void                e_categories_add                    (const gchar *category,
                                                             const gchar *unused,
                                                             const gchar *icon_file,
                                                             gboolean searchable);
    void                e_categories_remove                 (const gchar *category);
    gboolean            e_categories_exist                  (const gchar *category);
    const gchar *       e_categories_get_icon_file_for      (const gchar *category);
    void                e_categories_set_icon_file_for      (const gchar *category,
                                                             const gchar *icon_file);
    gboolean            e_categories_is_searchable          (const gchar *category);
    void                e_categories_register_change_listener
                                                            (GCallback listener,
                                                             gpointer user_data);
    void                e_categories_unregister_change_listener
                                                            (GCallback listener,
                                                             gpointer user_data);

## Description

## Details

### e_categories_get_list ()

    GList *             e_categories_get_list               (void);

Returns a sorted list of all the category names currently configured.

Returns : | a sorted GList containing the names of the categories.The list should be freed using `g_list_free()`, but the names of the categories should not be touched at all, they are internal strings. [transfer container][element-type utf8]

### e_categories_add ()

    void                e_categories_add                    (const gchar *category,
                                                             const gchar *unused,
                                                             const gchar *icon_file,
                                                             gboolean searchable);

Adds a new category, with its corresponding icon, to the configuration database.

`category` : | name of category to add.
`unused` : | DEPRECATED! associated color. DEPRECATED!
`icon_file` : | full path of the icon associated to the category.
`searchable` : | whether the category can be used for searching in the GUI.

### e_categories_remove ()

    void                e_categories_remove                 (const gchar *category);

Removes the given category from the configuration.

`category` : | category to be removed.

### e_categories_exist ()

    gboolean            e_categories_exist                  (const gchar *category);

Checks whether the given category is available in the configuration.

`category` : | category to be searched.
Returns : | `TRUE` if the category is available, `FALSE` otherwise.

### e_categories_get_icon_file_for ()

    const gchar *       e_categories_get_icon_file_for      (const gchar *category);

Gets the icon file associated with the given category.

`category` : | category to retrieve the icon file for.
Returns : | icon file name.

### e_categories_set_icon_file_for ()

    void                e_categories_set_icon_file_for      (const gchar *category,
                                                             const gchar *icon_file);

Sets the icon file associated with the given category.

`category` : | category to set the icon file for.
`icon_file` : | icon file.

### e_categories_is_searchable ()

    gboolean            e_categories_is_searchable          (const gchar *category);

Gets whether the given calendar is to be used for searches in the GUI.

Return value; `TRUE`% if the category is searchable, `FALSE`% if not.

`category` : | category name.

### e_categories_register_change_listener ()

    void                e_categories_register_change_listener
                                                            (GCallback listener,
                                                             gpointer user_data);

Registers callback to be called on change of any category. Pair listener and user_data is used to distinguish between listeners. Listeners can be unregistered with `e_categories_unregister_change_listener`.

`listener` : | the callback to be called on any category change. [scope async]
`user_data` : | used data passed to the `listener` when called.

Since 2.24

### e_categories_unregister_change_listener ()

    void                e_categories_unregister_change_listener
                                                            (GCallback listener,
                                                             gpointer user_data);

Removes previously registered callback from the list of listeners on changes. If it was not registered, then does nothing.

`listener` : | Callback to be removed. [scope async]
`user_data` : | User data as passed with call to `e_categories_register_change_listener`.

Since 2.24