## ECategories ECategories |

## Synopsis

    GList *             e_categories_get_list               (void);
    GList *             e_categories_dup_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);
    gchar *             e_categories_dup_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);

### Warning

`e_categories_get_list` has been deprecated since version 3.14 and should not be used in newly-written code. This function is not entirely thread safe. Use `e_categories_dup_list()` instead.

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

This function is mostly thread safe, but as the category names are not copied, they may be freed by another thread after being returned by this function. Use `e_categories_dup_list()` instead.

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_dup_list ()

    GList *             e_categories_dup_list               (void);

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

This function is thread safe.

Returns : | a sorted GList containing the names of the categories. The list should be freed using `g_list_free()`, and the names of the categories should be freed using `g_free()`. Everything can be freed simultaneously using `g_list_free_full()`. [transfer full][element-type utf8]

Since 3.14

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

This function is thread safe.

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

This function is thread safe.

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

This function is thread safe.

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

### Warning

`e_categories_get_icon_file_for` has been deprecated since version 3.14 and should not be used in newly-written code. This function is not entirely thread safe. Use `e_categories_dup_icon_file_for()` instead.

Gets the icon file associated with the given category.

This function is mostly thread safe, but as the icon file name is not copied, it may be freed by another thread after being returned by this function. Use `e_categories_dup_icon_file_for()` instead.

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

### e_categories_dup_icon_file_for ()

    gchar *             e_categories_dup_icon_file_for      (const gchar *category);

Gets the icon file associated with the given category and returns a copy of it.

This function is thread safe.

`category` : | category to retrieve the icon file for.
Returns : | icon file name; free with `g_free()`. [transfer full]

Since 3.14

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

This function is thread safe.

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

This function is thread safe.

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

This function is thread safe.

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

This function is thread safe.

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

Since 2.24