menu-cache: menu-cache Reference Manual

## menu-cache menu-cache |

## Functions

#define | MENU_CACHE_CHECK_VERSION()
#define | MENU_CACHE_DIR()
#define | MENU_CACHE_APP()
void | menu_cache_init ()
MenuCache * | menu_cache_lookup ()
MenuCache * | menu_cache_lookup_sync ()
MenuCache * | menu_cache_ref ()
void | menu_cache_unref ()
gboolean | menu_cache_reload ()
MenuCacheDir * | menu_cache_get_root_dir ()
MenuCacheDir * | menu_cache_get_dir_from_path ()
MenuCacheDir * | menu_cache_dup_root_dir ()
MenuCacheItem * | menu_cache_item_from_path ()
void | (*MenuCacheReloadNotify) ()
MenuCacheNotifyId | menu_cache_add_reload_notify ()
void | menu_cache_remove_reload_notify ()
guint32 | menu_cache_get_desktop_env_flag ()
MenuCacheItem * | menu_cache_item_ref ()
gboolean | menu_cache_item_unref ()
const char * | menu_cache_item_get_id ()
const char * | menu_cache_item_get_name ()
const char * | menu_cache_item_get_comment ()
const char * | menu_cache_item_get_icon ()
const char * | menu_cache_item_get_file_basename ()
const char * | menu_cache_item_get_file_dirname ()
char * | menu_cache_item_get_file_path ()
MenuCacheDir * | menu_cache_item_get_parent ()
GSList * | menu_cache_dir_get_children ()
MenuCacheDir * | menu_cache_item_dup_parent ()
GSList * | menu_cache_dir_list_children ()
MenuCacheItem * | menu_cache_find_child_by_id ()
MenuCacheItem * | menu_cache_find_child_by_name ()
char * | menu_cache_dir_make_path ()
const char * | menu_cache_app_get_generic_name ()
const char * | menu_cache_app_get_exec ()
const char * | menu_cache_app_get_working_dir ()
const char * const * | menu_cache_app_get_categories ()
guint32 | menu_cache_app_get_show_flags ()
gboolean | menu_cache_app_get_is_visible ()
gboolean | menu_cache_dir_is_visible ()
gboolean | menu_cache_app_get_use_terminal ()
gboolean | menu_cache_app_get_use_sn ()
GSList * | menu_cache_list_all_apps ()
GSList * | menu_cache_list_all_for_category ()
GSList * | menu_cache_list_all_for_keyword ()
MenuCacheItem * | menu_cache_find_item_by_id ()

## Types and Values

enum | MenuCacheType
enum | MenuCacheShowFlag
enum | MenuCacheItemFlag
typedef | MenuCacheNotifyId
| MenuCache
| MenuCacheApp
| MenuCacheDir

## Description

## Functions

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

### 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 there is no such connection exist then creates new one. Caller can be notified when cache is (re)loaded by adding callback. Caller should check if the cache is already loaded trying to retrieve its root.

See also: `menu_cache_add_reload_notify()`, `menu_cache_item_dup_parent()`.

#### Parameters

menu_name | a menu name |

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

#### Parameters

menu_name | a menu name |

#### Returns

menu cache descriptor.

[transfer full]

Since: 0.3.1

### menu_cache_ref ()

    MenuCache *
    menu_cache_ref (MenuCache *cache);

Increases reference counter on `cache` .

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

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

#### Parameters

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

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

cache | cache to inspect |
path | item path |

#### Returns

found item or `NULL` if no item found.

[transfer full]

Since: 0.3.4

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

#### Parameters

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

#### Parameters

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. The `desktop_env` may be simple string or colon separated list of compatible session names according to XDG_CURRENT_DESKTOP freedesktop.org specification.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

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

#### Parameters

item | a menu cache item |

Since: 0.1.0

### menu_cache_dir_get_children ()

    GSList *
    menu_cache_dir_get_children (MenuCacheDir *dir);

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

dir | a menu cache item |

#### Returns

item path.

[transfer full]

Since: 0.1.0

### menu_cache_app_get_generic_name ()

    const char *
    menu_cache_app_get_generic_name (MenuCacheApp *app);

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

#### Parameters

app | a menu cache item |

#### Returns

app's generic name or `NULL`.

[transfer none]

Since: 1.0.3

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

#### Parameters

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.

#### Parameters

app | a menu cache item |

#### Returns

item working directory or `NULL`.

[transfer none]

Since: 0.1.0

### menu_cache_app_get_categories ()

    const char * const *
    menu_cache_app_get_categories (MenuCacheApp *app);

Retrieves list of categories for `app` . Returned data are owned by menu cache and should be not freed by caller.

#### Parameters

app | a menu cache item |

#### Returns

list of categories or `NULL`.

[transfer none]

Since: 1.0.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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

cache | a menu cache descriptor |

#### Returns

list of items.

[transfer full][element-type MenuCacheItem]

Since: 0.1.2

### menu_cache_list_all_for_category ()

    GSList *
    menu_cache_list_all_for_category (MenuCache *cache,
                                      const char *category);

Retrieves list of applications in menu cache which have `category` in their list of categories. The search is case-sensitive. Returned list should be freed with g_slist_free_full(list, menu_cache_item_unref) after usage.

#### Parameters

cache | a menu cache descriptor |
category | category to list items |

#### Returns

list of items.

[transfer full][element-type MenuCacheItem]

Since: 1.0.0

### menu_cache_list_all_for_keyword ()

    GSList *
    menu_cache_list_all_for_keyword (MenuCache *cache,
                                     const char *keyword);

Retrieves list of applications in menu cache which have a `keyword` as either a word or part of word in exec command, name, generic name or defined keywords. The search is case-insensitive. Returned list should be freed with g_slist_free_full(list, menu_cache_item_unref) after usage.

#### Parameters

cache | a menu cache descriptor |
keyword | a keyword to search |

#### Returns

list of items.

[transfer full][element-type MenuCacheItem]

Since: 1.0.0

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

#### Parameters

cache | a menu cache descriptor |
id | item ID (name such as 'application.desktop') |

#### Returns

found item or `NULL`.

[transfer full]

Since: 0.5.0

## Types and Values

### enum MenuCacheType

type of MenuCacheItem.

#### Members

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

bitmask of desktop environments where the item should be visible.

#### Members

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

flags for application run.

#### Members

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 |

### MenuCacheNotifyId

    typedef struct _MenuCacheNotifyId* MenuCacheNotifyId;

### MenuCache

    typedef struct _MenuCache MenuCache;

### MenuCacheApp

    typedef struct _MenuCacheApp MenuCacheApp;

### MenuCacheDir

    typedef struct _MenuCacheDir MenuCacheDir;