![]() |
![]() |
![]() |
libmenu-cache Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#define MENU_CACHE_APP (x) #define MENU_CACHE_CHECK_VERSION (_a, _b, _c) #define MENU_CACHE_DIR (x) MenuCache; MenuCacheApp; MenuCacheDir; MenuCacheItem; enum MenuCacheItemFlag; typedef MenuCacheNotifyId; void (*MenuCacheReloadNotify) (MenuCache *cache
,gpointer user_data
); enum MenuCacheShowFlag; enum MenuCacheType; MenuCacheNotifyId menu_cache_add_reload_notify (MenuCache *cache
,MenuCacheReloadNotify func
,gpointer user_data
); const char * const * menu_cache_app_get_categories (MenuCacheApp *app
); const char * menu_cache_app_get_exec (MenuCacheApp *app
); const char * menu_cache_app_get_generic_name (MenuCacheApp *app
); gboolean menu_cache_app_get_is_visible (MenuCacheApp *app
,guint32 de_flags
); guint32 menu_cache_app_get_show_flags (MenuCacheApp *app
); gboolean menu_cache_app_get_use_sn (MenuCacheApp *app
); gboolean menu_cache_app_get_use_terminal (MenuCacheApp *app
); const char * menu_cache_app_get_working_dir (MenuCacheApp *app
); GSList * menu_cache_dir_get_children (MenuCacheDir *dir
); gboolean menu_cache_dir_is_visible (MenuCacheDir *dir
); GSList * menu_cache_dir_list_children (MenuCacheDir *dir
); char * menu_cache_dir_make_path (MenuCacheDir *dir
); MenuCacheDir * menu_cache_dup_root_dir (MenuCache *cache
); MenuCacheItem * menu_cache_find_child_by_id (MenuCacheDir *dir
,const char *id
); MenuCacheItem * menu_cache_find_child_by_name (MenuCacheDir *dir
,const char *name
); MenuCacheItem * menu_cache_find_item_by_id (MenuCache *cache
,const char *id
); guint32 menu_cache_get_desktop_env_flag (MenuCache *cache
,const char *desktop_env
); MenuCacheDir * menu_cache_get_dir_from_path (MenuCache *cache
,const char *path
); MenuCacheDir * menu_cache_get_root_dir (MenuCache *cache
); void menu_cache_init (int flags
); MenuCacheDir * menu_cache_item_dup_parent (MenuCacheItem *item
); MenuCacheItem * menu_cache_item_from_path (MenuCache *cache
,const char *path
); const char * menu_cache_item_get_comment (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
); const char * menu_cache_item_get_icon (MenuCacheItem *item
); const char * menu_cache_item_get_id (MenuCacheItem *item
); const char * menu_cache_item_get_name (MenuCacheItem *item
); MenuCacheDir * menu_cache_item_get_parent (MenuCacheItem *item
); MenuCacheItem * menu_cache_item_ref (MenuCacheItem *item
); gboolean menu_cache_item_unref (MenuCacheItem *item
); GSList * menu_cache_list_all_apps (MenuCache *cache
); GSList * menu_cache_list_all_for_category (MenuCache *cache
,const char *category
); GSList * menu_cache_list_all_for_keyword (MenuCache *cache
,const char *keyword
); MenuCache * menu_cache_lookup (const char *menu_name
); MenuCache * menu_cache_lookup_sync (const char *menu_name
); MenuCache * menu_cache_ref (MenuCache *cache
); gboolean menu_cache_reload (MenuCache *cache
); void menu_cache_remove_reload_notify (MenuCache *cache
,MenuCacheNotifyId notify_id
); void menu_cache_unref (MenuCache *cache
);
typedef enum { FLAG_USE_TERMINAL = 1 << 0, FLAG_USE_SN = 1 << 1, FLAG_IS_NODISPLAY = 1 << 2 } MenuCacheItemFlag;
flags for application run.
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.
typedef enum { MENU_CACHE_TYPE_NONE, MENU_CACHE_TYPE_DIR, MENU_CACHE_TYPE_APP, MENU_CACHE_TYPE_SEP } MenuCacheType;
type of MenuCacheItem.
invalid type | |
item MenuCacheDir | |
item MenuCacheApp | |
menu separator |
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.
|
a menu cache instance |
|
callback to call when menu cache is reloaded |
|
user data provided for func
|
Returns : |
an ID of added callback. |
Since 0.1.0
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.
|
a menu cache item |
Returns : |
list of categories or NULL . [transfer none]
|
Since 1.0.0
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.
|
a menu cache item |
Returns : |
item execution string or NULL . [transfer none]
|
Since 0.1.0
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.
|
a menu cache item |
Returns : |
app's generic name or NULL . [transfer none]
|
Since 1.0.3
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
.
|
a menu cache item |
|
bit mask of DE to test |
Returns : |
TRUE if app is visible. |
Since 0.2.0
guint32 menu_cache_app_get_show_flags (MenuCacheApp *app
);
Retrieves list of desktop environments where app
should be visible.
|
a menu cache item |
Returns : |
bit mask of DE. |
Since 0.2.0
gboolean menu_cache_app_get_use_sn (MenuCacheApp *app
);
Checks if app
wants startup notification.
|
a menu cache item |
Returns : |
TRUE if app wants startup notification. |
Since 0.1.0
gboolean menu_cache_app_get_use_terminal (MenuCacheApp *app
);
Checks if app
should be ran in terminal.
|
a menu cache item |
Returns : |
TRUE if app requires terminal to run. |
Since 0.1.0
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.
|
a menu cache item |
Returns : |
item working directory or NULL . [transfer none]
|
Since 0.1.0
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.
|
a menu cache item |
Returns : |
list of items. [transfer none][element-type MenuCacheItem] |
Since 0.1.0
gboolean menu_cache_dir_is_visible (MenuCacheDir *dir
);
Checks if dir
should be visible.
|
a menu cache item |
Returns : |
TRUE if dir is visible. |
Since 0.5.0
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.
|
a menu cache item |
Returns : |
list of items. [transfer full][element-type MenuCacheItem] |
Since 0.4.0
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.
|
a menu cache item |
Returns : |
item path. [transfer full] |
Since 0.1.0
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.
|
a menu cache instance |
Returns : |
root item or NULL in case of error. [transfer full]
|
Since 0.3.4
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.
|
a menu cache item |
|
a string to find |
Returns : |
found item or NULL . [transfer full]
|
Since 0.5.0
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.
|
a menu cache item |
|
a string to find |
Returns : |
found item or NULL . [transfer full]
|
Since 0.5.0
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.
|
a menu cache descriptor |
|
item ID (name such as 'application.desktop') |
Returns : |
found item or NULL . [transfer full]
|
Since 0.5.0
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.
|
a menu cache descriptor |
|
desktop environment name |
Returns : |
DE bit mask. |
Since 0.2.0
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.
|
a menu cache instance |
|
item path |
Since 0.1.0
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.
|
a menu cache instance |
Since 0.1.0
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.
|
a menu item |
Returns : |
parent item or NULL in case of error. [transfer full]
|
Since 0.3.4
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 to inspect |
|
item path |
Returns : |
found item or NULL if no item found. [transfer full]
|
Since 0.3.4
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.
|
a menu cache item |
Returns : |
item comment or NULL . [transfer none]
|
Since 0.1.0
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.
|
a menu cache item |
Returns : |
item file basename or NULL . [transfer none]
|
Since 0.2.0
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.
|
a menu cache item |
Returns : |
item file parent directory path or NULL . [transfer none]
|
Since 0.2.0
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.
|
a menu cache item |
Returns : |
item file path or NULL . [transfer full]
|
Since 0.2.0
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.
|
a menu cache item |
Returns : |
item icon name or NULL . [transfer none]
|
Since 0.1.0
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.
|
a menu cache item |
Returns : |
item ID. [transfer none] |
Since 0.1.0
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.
|
a menu cache item |
Returns : |
item display name or NULL . [transfer none]
|
Since 0.1.0
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.
|
a menu cache item |
Since 0.1.0
MenuCacheItem * menu_cache_item_ref (MenuCacheItem *item
);
Increases reference counter on item
.
|
a menu cache item |
Returns : |
item . |
Since 0.1.0
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.
|
a menu cache item |
Returns : |
FALSE (since 0.5.0) |
Since 0.1.0
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.
|
a menu cache descriptor |
Returns : |
list of items. [transfer full][element-type MenuCacheItem] |
Since 0.1.2
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.
|
a menu cache descriptor |
|
category to list items |
Returns : |
list of items. [transfer full][element-type MenuCacheItem] |
Since 1.0.0
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.
|
a menu cache descriptor |
|
a keyword to search |
Returns : |
list of items. [transfer full][element-type MenuCacheItem] |
Since 1.0.0
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()
.
|
a menu name |
Returns : |
menu cache descriptor. [transfer full] |
Since 0.1.0
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.
|
a menu name |
Returns : |
menu cache descriptor. [transfer full] |
Since 0.3.1
MenuCache * menu_cache_ref (MenuCache *cache
);
Increases reference counter on cache
.
|
a menu cache descriptor |
Returns : |
cache . |
Since 0.1.0
gboolean menu_cache_reload (MenuCache *cache
);
Reloads menu cache from file generated by menu-cached.
|
a menu cache instance |
Returns : |
TRUE if reload was successful. |
Since 0.1.0
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()
.
|
a menu cache instance |
|
an ID of callback |
Since 0.1.0
void menu_cache_unref (MenuCache *cache
);
Descreases reference counter on cache
. When reference count becomes 0
then resources associated with cache
will be freed.
|
a menu cache descriptor |
Since 0.1.0