e-categories: Evolution-Data-Server Reference Manual

## e-categories e-categories |

## Functions

GList * | e_categories_get_list ()
GList * | e_categories_dup_list ()
void | e_categories_add ()
void | e_categories_remove ()
gboolean | e_categories_exist ()
const gchar * | e_categories_get_icon_file_for ()
gchar * | e_categories_dup_icon_file_for ()
void | e_categories_set_icon_file_for ()
gboolean | e_categories_is_searchable ()
void | e_categories_register_change_listener ()
void | e_categories_unregister_change_listener ()

## Description

## Functions

### e_categories_get_list ()

    GList *
    e_categories_get_list (void);

`e_categories_get_list` has been deprecated since version 3.16 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.16

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

`e_categories_get_icon_file_for` has been deprecated since version 3.16 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.

#### Parameters

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.

#### Parameters

category | category to retrieve the icon file for. |

#### Returns

icon file name; free with `g_free()`.

[transfer full]

Since: 3.16

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

Since: 2.24