## 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_exec ()
const char * | menu_cache_app_get_working_dir ()
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 ()
MenuCacheItem * | menu_cache_find_item_by_id ()

## Types and Values

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

## Object Hierarchy

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

#### Parameters

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.

#### Parameters

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

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

#### 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_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_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_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;

### MenuCacheApp

    typedef struct _MenuCacheApp MenuCacheApp;

### MenuCacheDir

    typedef struct _MenuCacheDir MenuCacheDir;

### MenuCache

    typedef struct _MenuCache MenuCache;