## menu-cache

menu-cache

## Synopsis

    #define             MENU_CACHE_CHECK_VERSION            (_a,
                                                             _b,
                                                             _c)
    #define             MENU_CACHE_DIR                      (x)
    #define             MENU_CACHE_APP                      (x)
    enum                MenuCacheType;
    enum                MenuCacheShowFlag;
    enum                MenuCacheItemFlag;
    void                menu_cache_init                     (int flags);
    MenuCache *         menu_cache_lookup                   (const char *menu_name);
    MenuCache *         menu_cache_lookup_sync              (const char *menu_name);
    MenuCache *         menu_cache_ref                      (MenuCache *cache);
    void                menu_cache_unref                    (MenuCache *cache);
    gboolean            menu_cache_reload                   (MenuCache *cache);
    MenuCacheDir *      menu_cache_get_root_dir             (MenuCache *cache);
    MenuCacheDir *      menu_cache_get_dir_from_path        (MenuCache *cache,
                                                             const char *path);
    MenuCacheDir *      menu_cache_dup_root_dir             (MenuCache *cache);
    MenuCacheItem *     menu_cache_item_from_path           (MenuCache *cache,
                                                             const char *path);
    typedef             MenuCacheNotifyId;
    void                (*MenuCacheReloadNotify)            (MenuCache *cache,
                                                             gpointer user_data);
    MenuCacheNotifyId   menu_cache_add_reload_notify        (MenuCache *cache,
                                                             MenuCacheReloadNotify func,
                                                             gpointer user_data);
    void                menu_cache_remove_reload_notify     (MenuCache *cache,
                                                             MenuCacheNotifyId notify_id);
    guint32             menu_cache_get_desktop_env_flag     (MenuCache *cache,
                                                             const char *desktop_env);
    MenuCacheItem *     menu_cache_item_ref                 (MenuCacheItem *item);
    gboolean            menu_cache_item_unref               (MenuCacheItem *item);
    const char *        menu_cache_item_get_id              (MenuCacheItem *item);
    const char *        menu_cache_item_get_name            (MenuCacheItem *item);
    const char *        menu_cache_item_get_comment         (MenuCacheItem *item);
    const char *        menu_cache_item_get_icon            (MenuCacheItem *item);
    const char *        menu_cache_item_get_file_basename   (MenuCacheItem *item);
    const char *        menu_cache_item_get_file_dirname    (MenuCacheItem *item);
    char *              menu_cache_item_get_file_path       (MenuCacheItem *item);
    MenuCacheDir *      menu_cache_item_get_parent          (MenuCacheItem *item);
    GSList *            menu_cache_dir_get_children         (MenuCacheDir *dir);
    MenuCacheDir *      menu_cache_item_dup_parent          (MenuCacheItem *item);
    GSList *            menu_cache_dir_list_children        (MenuCacheDir *dir);
    MenuCacheItem *     menu_cache_find_child_by_id         (MenuCacheDir *dir,
                                                             const char *id);
    MenuCacheItem *     menu_cache_find_child_by_name       (MenuCacheDir *dir,
                                                             const char *name);
    char *              menu_cache_dir_make_path            (MenuCacheDir *dir);
    const char *        menu_cache_app_get_exec             (MenuCacheApp *app);
    const char *        menu_cache_app_get_working_dir      (MenuCacheApp *app);
    guint32             menu_cache_app_get_show_flags       (MenuCacheApp *app);
    gboolean            menu_cache_app_get_is_visible       (MenuCacheApp *app,
                                                             guint32 de_flags);
    gboolean            menu_cache_dir_is_visible           (MenuCacheDir *dir);
    gboolean            menu_cache_app_get_use_terminal     (MenuCacheApp *app);
    gboolean            menu_cache_app_get_use_sn           (MenuCacheApp *app);
    GSList *            menu_cache_list_all_apps            (MenuCache *cache);
    MenuCacheItem *     menu_cache_find_item_by_id          (MenuCache *cache,
                                                             const char *id);
                        MenuCacheApp;
                        MenuCacheItem;
                        MenuCache;
                        MenuCacheDir;

## Description

## Details

### MENU_CACHE_CHECK_VERSION()

    #define             MENU_CACHE_CHECK_VERSION(_a,_b,_c)

### MENU_CACHE_DIR()

    #define    MENU_CACHE_DIR(x)    ((MenuCacheDir*)x)

### MENU_CACHE_APP()

    #define    MENU_CACHE_APP(x)    ((MenuCacheApp*)x)

### enum MenuCacheType

    typedef enum {
        MENU_CACHE_TYPE_NONE,
        MENU_CACHE_TYPE_DIR,
        MENU_CACHE_TYPE_APP,
        MENU_CACHE_TYPE_SEP
    } MenuCacheType;

type of MenuCacheItem.

`MENU_CACHE_TYPE_NONE` | invalid type
`MENU_CACHE_TYPE_DIR` | item MenuCacheDir
`MENU_CACHE_TYPE_APP` | item MenuCacheApp
`MENU_CACHE_TYPE_SEP` | menu separator

### enum MenuCacheShowFlag

    typedef enum {
        SHOW_IN_LXDE = 1 << 0,
        SHOW_IN_GNOME = 1 << 1,
        SHOW_IN_KDE = 1 << 2,
        SHOW_IN_XFCE = 1 << 3,
        SHOW_IN_ROX = 1 << 4,
    } MenuCacheShowFlag;

bitmask of desktop environments where the item should be visible.

`SHOW_IN_LXDE` | show in LXDE
`SHOW_IN_GNOME` | show in GNOME
`SHOW_IN_KDE` | show in KDE
`SHOW_IN_XFCE` | show in XFCE
`SHOW_IN_ROX` | show in ROX

### enum MenuCacheItemFlag

    typedef enum {
        FLAG_USE_TERMINAL = 1 << 0,
        FLAG_USE_SN = 1 << 1,
        FLAG_IS_NODISPLAY = 1 << 2
    } MenuCacheItemFlag;

flags for application run.

`FLAG_USE_TERMINAL` | run this application in terminal
`FLAG_USE_SN` | use Startup Notify for this application
`FLAG_IS_NODISPLAY` | application is hidden from menu

### menu_cache_init ()

    void                menu_cache_init                     (int flags);

### menu_cache_lookup ()

    MenuCache *         menu_cache_lookup                   (const char *menu_name);

Searches for connection to menu-cached for `menu_name`. If no such connection exists then creates new one. Caller can be notified when cache is ready by adding callback.

See also: `menu_cache_add_reload_notify()`.

`menu_name` : | a menu cache root
Returns : | menu cache descriptor. [transfer full]

Since 0.1.0

### menu_cache_lookup_sync ()

    MenuCache *         menu_cache_lookup_sync              (const char *menu_name);

Searches for data from menu-cached for `menu_name`. If no connection exists yet then creates new one and retrieves all data.

`menu_name` : | a menu cache root
Returns : | menu cache descriptor. [transfer full]

Since 0.3.1

### menu_cache_ref ()

    MenuCache *         menu_cache_ref                      (MenuCache *cache);

Increases reference counter on `cache`.

`cache` : | a menu cache descriptor
Returns : | `cache`.

Since 0.1.0

### menu_cache_unref ()

    void                menu_cache_unref                    (MenuCache *cache);

Descreases reference counter on `cache`. When reference count becomes 0 then resources associated with `cache` will be freed.

`cache` : | a menu cache descriptor

Since 0.1.0

### menu_cache_reload ()

    gboolean            menu_cache_reload                   (MenuCache *cache);

Reloads menu cache from file generated by menu-cached.

`cache` : | a menu cache instance
Returns : | `TRUE` if reload was successful.

Since 0.1.0

### menu_cache_get_root_dir ()

    MenuCacheDir *      menu_cache_get_root_dir             (MenuCache *cache);

### Warning

`menu_cache_get_root_dir` has been deprecated since version 0.3.4 and should not be used in newly-written code. Use `menu_cache_dup_root_dir()` instead.

`cache` : | a menu cache instance

Since 0.1.0

### menu_cache_get_dir_from_path ()

    MenuCacheDir *      menu_cache_get_dir_from_path        (MenuCache *cache,
                                                             const char *path);

### Warning

`menu_cache_get_dir_from_path` has been deprecated since version 0.3.4 and should not be used in newly-written code. Use `menu_cache_item_from_path()` instead.

`cache` : | a menu cache instance
`path` : | item path

Since 0.1.0

### menu_cache_dup_root_dir ()

    MenuCacheDir *      menu_cache_dup_root_dir             (MenuCache *cache);

Retrieves root directory for `cache`. Returned data should be freed with `menu_cache_item_unref()` after usage.

`cache` : | a menu cache instance
Returns : | root item or `NULL` in case of error. [transfer full]

Since 0.3.4

### menu_cache_item_from_path ()

    MenuCacheItem *     menu_cache_item_from_path           (MenuCache *cache,
                                                             const char *path);

Searches item `path` in the `cache`. The `path` consists of item IDs separated by slash ('/'). Returned data should be freed with `menu_cache_item_unref()` after usage.

`cache` : | cache to inspect
`path` : | item path
Returns : | found item or `NULL` if no item found. [transfer full]

Since 0.3.4

### MenuCacheNotifyId

    typedef struct _MenuCacheNotifyId* MenuCacheNotifyId;

### MenuCacheReloadNotify ()

    void                (*MenuCacheReloadNotify)            (MenuCache *cache,
                                                             gpointer user_data);

### menu_cache_add_reload_notify ()

    MenuCacheNotifyId   menu_cache_add_reload_notify        (MenuCache *cache,
                                                             MenuCacheReloadNotify func,
                                                             gpointer user_data);

Adds a `func` to list of callbacks that are called each time menu cache is loaded.

`cache` : | a menu cache instance
`func` : | callback to call when menu cache is reloaded
`user_data` : | user data provided for `func`
Returns : | an ID of added callback.

Since 0.1.0

### menu_cache_remove_reload_notify ()

    void                menu_cache_remove_reload_notify     (MenuCache *cache,
                                                             MenuCacheNotifyId notify_id);

Removes `notify_id` from list of callbacks added for `cache` by previous call to `menu_cache_add_reload_notify()`.

`cache` : | a menu cache instance
`notify_id` : | an ID of callback

Since 0.1.0

### menu_cache_get_desktop_env_flag ()

    guint32             menu_cache_get_desktop_env_flag     (MenuCache *cache,
                                                             const char *desktop_env);

Makes bit mask of desktop environment from its name.

`cache` : | a menu cache descriptor
`desktop_env` : | desktop environment name
Returns : | DE bit mask.

Since 0.2.0

### menu_cache_item_ref ()

    MenuCacheItem *     menu_cache_item_ref                 (MenuCacheItem *item);

Increases reference counter on `item`.

`item` : | a menu cache item
Returns : | `item`.

Since 0.1.0

### menu_cache_item_unref ()

    gboolean            menu_cache_item_unref               (MenuCacheItem *item);

Decreases reference counter on `item`. When reference count becomes 0 then resources associated with `item` will be freed.

`item` : | a menu cache item
Returns : | `FALSE` (since 0.5.0)

Since 0.1.0

### menu_cache_item_get_id ()

    const char *        menu_cache_item_get_id              (MenuCacheItem *item);

Retrieves ID (short name such as 'application.desktop') of `item`. Returned data are owned by menu cache and should be not freed by caller.

`item` : | a menu cache item
Returns : | item ID. [transfer none]

Since 0.1.0

### menu_cache_item_get_name ()

    const char *        menu_cache_item_get_name            (MenuCacheItem *item);

Retrieves display name of `item`. Returned data are owned by menu cache and should be not freed by caller.

`item` : | a menu cache item
Returns : | `item` display name or `NULL`. [transfer none]

Since 0.1.0

### menu_cache_item_get_comment ()

    const char *        menu_cache_item_get_comment         (MenuCacheItem *item);

Retrieves comment of `item`. The comment can be used to show tooltip on `item`. Returned data are owned by menu cache and should be not freed by caller.

`item` : | a menu cache item
Returns : | `item` comment or `NULL`. [transfer none]

Since 0.1.0

### menu_cache_item_get_icon ()

    const char *        menu_cache_item_get_icon            (MenuCacheItem *item);

Retrieves name of icon of `item`. Returned data are owned by menu cache and should be not freed by caller.

`item` : | a menu cache item
Returns : | `item` icon name or `NULL`. [transfer none]

Since 0.1.0

### menu_cache_item_get_file_basename ()

    const char *        menu_cache_item_get_file_basename   (MenuCacheItem *item);

Retrieves basename of `item`. This API can return `NULL` if `item` is a directory and have no directory desktop entry file. Returned data are owned by menu cache and should be not freed by caller.

`item` : | a menu cache item
Returns : | `item` file basename or `NULL`. [transfer none]

Since 0.2.0

### menu_cache_item_get_file_dirname ()

    const char *        menu_cache_item_get_file_dirname    (MenuCacheItem *item);

Retrieves path to directory where `item` desktop enrty file is located. This API can return `NULL` if `item` is a directory and have no desktop entry file. Returned data are owned by menu cache and should be not freed by caller.

`item` : | a menu cache item
Returns : | `item` file parent directory path or `NULL`. [transfer none]

Since 0.2.0

### menu_cache_item_get_file_path ()

    char *              menu_cache_item_get_file_path       (MenuCacheItem *item);

Retrieves path to `item` desktop enrty file. This API can return `NULL` if `item` is a directory and have no desktop entry file. Returned data should be freed with `g_free()` after usage.

`item` : | a menu cache item
Returns : | `item` file path or `NULL`. [transfer full]

Since 0.2.0

### menu_cache_item_get_parent ()

    MenuCacheDir *      menu_cache_item_get_parent          (MenuCacheItem *item);

### Warning

`menu_cache_item_get_parent` has been deprecated since version 0.3.4 and should not be used in newly-written code. Use `menu_cache_item_dup_parent()` instead.

`item` : | a menu cache item

Since 0.1.0

### menu_cache_dir_get_children ()

    GSList *            menu_cache_dir_get_children         (MenuCacheDir *dir);

### Warning

`menu_cache_dir_get_children` has been deprecated since version 0.4.0 and should not be used in newly-written code. Use `menu_cache_dir_list_children()` instead.

Retrieves list of items contained in `dir`. Returned data are owned by menu cache and should be not freed by caller. This API is thread unsafe and should be never called from outside of default main loop.

`dir` : | a menu cache item
Returns : | list of items. [transfer none][element-type MenuCacheItem]

Since 0.1.0

### menu_cache_item_dup_parent ()

    MenuCacheDir *      menu_cache_item_dup_parent          (MenuCacheItem *item);

Retrieves parent (directory) for `item`. Returned data should be freed with `menu_cache_item_unref()` after usage.

`item` : | a menu item
Returns : | parent item or `NULL` in case of error. [transfer full]

Since 0.3.4

### menu_cache_dir_list_children ()

    GSList *            menu_cache_dir_list_children        (MenuCacheDir *dir);

Retrieves list of items contained in `dir`. Returned data should be freed with g_slist_free_full(list, menu_cache_item_unref) after usage.

`dir` : | a menu cache item
Returns : | list of items. [transfer full][element-type MenuCacheItem]

Since 0.4.0

### menu_cache_find_child_by_id ()

    MenuCacheItem *     menu_cache_find_child_by_id         (MenuCacheDir *dir,
                                                             const char *id);

Checks if `dir` has a child with given `id`. Returned data should be freed with `menu_cache_item_unref()` when no longer needed.

`dir` : | a menu cache item
`id` : | a string to find
Returns : | found item or `NULL`. [transfer full]

Since 0.5.0

### menu_cache_find_child_by_name ()

    MenuCacheItem *     menu_cache_find_child_by_name       (MenuCacheDir *dir,
                                                             const char *name);

Checks if `dir` has a child with given `name`. Returned data should be freed with `menu_cache_item_unref()` when no longer needed.

`dir` : | a menu cache item
`name` : | a string to find
Returns : | found item or `NULL`. [transfer full]

Since 0.5.0

### menu_cache_dir_make_path ()

    char *              menu_cache_dir_make_path            (MenuCacheDir *dir);

Retrieves path of `dir`. The path consists of item IDs separated by slash ('/'). Returned data should be freed with `g_free()` after usage.

`dir` : | a menu cache item
Returns : | item path. [transfer full]

Since 0.1.0

### menu_cache_app_get_exec ()

    const char *        menu_cache_app_get_exec             (MenuCacheApp *app);

Retrieves execution string for `app`. Returned data are owned by menu cache and should be not freed by caller.

`app` : | a menu cache item
Returns : | item execution string or `NULL`. [transfer none]

Since 0.1.0

### menu_cache_app_get_working_dir ()

    const char *        menu_cache_app_get_working_dir      (MenuCacheApp *app);

Retrieves working directory for `app`. Returned data are owned by menu cache and should be not freed by caller.

`app` : | a menu cache item
Returns : | item working directory or `NULL`. [transfer none]

Since 0.1.0

### menu_cache_app_get_show_flags ()

    guint32             menu_cache_app_get_show_flags       (MenuCacheApp *app);

Retrieves list of desktop environments where `app` should be visible.

`app` : | a menu cache item
Returns : | bit mask of DE.

Since 0.2.0

### menu_cache_app_get_is_visible ()

    gboolean            menu_cache_app_get_is_visible       (MenuCacheApp *app,
                                                             guint32 de_flags);

Checks if `app` should be visible in any of desktop environments `de_flags`.

`app` : | a menu cache item
`de_flags` : | bit mask of DE to test
Returns : | `TRUE` if `app` is visible.

Since 0.2.0

### menu_cache_dir_is_visible ()

    gboolean            menu_cache_dir_is_visible           (MenuCacheDir *dir);

Checks if `dir` should be visible.

`dir` : | a menu cache item
Returns : | `TRUE` if `dir` is visible.

Since 0.5.0

### menu_cache_app_get_use_terminal ()

    gboolean            menu_cache_app_get_use_terminal     (MenuCacheApp *app);

Checks if `app` should be ran in terminal.

`app` : | a menu cache item
Returns : | `TRUE` if `app` requires terminal to run.

Since 0.1.0

### menu_cache_app_get_use_sn ()

    gboolean            menu_cache_app_get_use_sn           (MenuCacheApp *app);

Checks if `app` wants startup notification.

`app` : | a menu cache item
Returns : | `TRUE` if `app` wants startup notification.

Since 0.1.0

### menu_cache_list_all_apps ()

    GSList *            menu_cache_list_all_apps            (MenuCache *cache);

Retrieves full list of applications in menu cache. Returned list should be freed with g_slist_free_full(list, menu_cache_item_unref) after usage.

`cache` : | a menu cache descriptor
Returns : | list of items. [transfer full][element-type MenuCacheItem]

Since 0.1.2

### menu_cache_find_item_by_id ()

    MenuCacheItem *     menu_cache_find_item_by_id          (MenuCache *cache,
                                                             const char *id);

Searches if `id` already exists within `cache` and returns found item. Returned data should be freed with `menu_cache_item_unref()` after usage.

`cache` : | a menu cache descriptor
`id` : | item ID (name such as 'application.desktop')
Returns : | found item or `NULL`. [transfer full]

Since 0.5.0

### MenuCacheApp

    typedef struct _MenuCacheApp MenuCacheApp;

### MenuCacheItem

    typedef struct _MenuCacheItem MenuCacheItem;

### MenuCache

    typedef struct _MenuCache MenuCache;

### MenuCacheDir

    typedef struct _MenuCacheDir MenuCacheDir;