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);
                    MenuCache;
                    MenuCacheDir;
                    MenuCacheItem;
                    MenuCacheApp;

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


MenuCache

typedef struct _MenuCache MenuCache;

MenuCacheDir

typedef struct _MenuCacheDir MenuCacheDir;

MenuCacheItem

typedef struct _MenuCacheItem MenuCacheItem;

MenuCacheApp

typedef struct _MenuCacheApp MenuCacheApp;