awn-desktop-item

awn-desktop-item — A desktop item-specific API wrapper.

Synopsis


#include <libawn/awn-desktop-item.h>


                    AwnDesktopItem;
#define             AWN_DESKTOP_ITEM                    (obj)
AwnDesktopItem*     awn_desktop_item_new                (gchar *filename);
AwnDesktopItem*     awn_desktop_item_copy               (const AwnDesktopItem *item);
gchar*              awn_desktop_item_get_filename       (AwnDesktopItem *item);
gchar*              awn_desktop_item_get_item_type      (AwnDesktopItem *item);
void                awn_desktop_item_set_item_type      (AwnDesktopItem *item,
                                                         gchar *item_type);
gchar*              awn_desktop_item_get_icon           (AwnDesktopItem *item,
                                                         GtkIconTheme *icon_theme);
void                awn_desktop_item_set_icon           (AwnDesktopItem *item,
                                                         gchar *icon);
gchar*              awn_desktop_item_get_name           (AwnDesktopItem *item);
void                awn_desktop_item_set_name           (AwnDesktopItem *item,
                                                         gchar *name);
gchar*              awn_desktop_item_get_exec           (AwnDesktopItem *item);
void                awn_desktop_item_set_exec           (AwnDesktopItem *item,
                                                         gchar *exec);
gchar*              awn_desktop_item_get_string         (AwnDesktopItem *item,
                                                         gchar *key);
void                awn_desktop_item_set_string         (AwnDesktopItem *item,
                                                         gchar *key,
                                                         gchar *value);
gchar*              awn_desktop_item_get_localestring   (AwnDesktopItem *item,
                                                         gchar *key);
void                awn_desktop_item_set_localestring   (AwnDesktopItem *item,
                                                         gchar *key,
                                                         gchar *locale,
                                                         gchar *value);
gboolean            awn_desktop_item_exists             (AwnDesktopItem *item);
gint                awn_desktop_item_launch             (AwnDesktopItem *item,
                                                         GSList *documents,
                                                         GError **err);
void                awn_desktop_item_save               (AwnDesktopItem *item,
                                                         gchar *new_filename,
                                                         GError **err);

Description

Contains a desktop item wrapper API whose implementation depends on the compile-time configuration.

Details

AwnDesktopItem

typedef struct _AwnDesktopItem AwnDesktopItem;

An alias for the desktop-specific .desktop file-handling structure.


AWN_DESKTOP_ITEM()

#define AWN_DESKTOP_ITEM(obj)	(G_TYPE_CHECK_INSTANCE_CAST ((obj), AWN_TYPE_DESKTOP_ITEM, AwnDesktopItem))

Casts a variable/value to be an AwnDesktopItem.

obj : The variable/value to cast

awn_desktop_item_new ()

AwnDesktopItem*     awn_desktop_item_new                (gchar *filename);

Creates a new desktop item structure. If filename exists, it attempts to parse the file at that path as a desktop file. Otherwise, it is used as the path that will be used if awn_desktop_item_save() is called.

filename : The path to the desktop file. The base name of the path does not need to exist at the time that this function is called.
Returns : a newly created item structure. When it is no longer needed, it needs to be freed via awn_desktop_item_unref().

awn_desktop_item_copy ()

AwnDesktopItem*     awn_desktop_item_copy               (const AwnDesktopItem *item);

Creates a copy of the structure.

item : The desktop item to copy.
Returns : A copy of the structure.

awn_desktop_item_get_filename ()

gchar*              awn_desktop_item_get_filename       (AwnDesktopItem *item);

Retrieves the filename that is associated with the desktop item.

item : The desktop item structure that is being queried.
Returns : The filename associated with the desktop item

awn_desktop_item_get_item_type ()

gchar*              awn_desktop_item_get_item_type      (AwnDesktopItem *item);

Retrieves the type of the desktop item, for example "Application" or "Directory".

item : The desktop item structure that is being queried.
Returns : the item type name.

awn_desktop_item_set_item_type ()

void                awn_desktop_item_set_item_type      (AwnDesktopItem *item,
                                                         gchar *item_type);

Sets the type of the desktop item, for example "Application" or "Directory".

item : The desktop item structure that is being modified.
item_type : The new item type of the desktop item.

awn_desktop_item_get_icon ()

gchar*              awn_desktop_item_get_icon           (AwnDesktopItem *item,
                                                         GtkIconTheme *icon_theme);

Retrieves the icon associated with the desktop item.

item : The desktop item structre that is being queried.
icon_theme : The icon theme in which the function searches for the icon.
Returns : the absolute filename of the icon.

awn_desktop_item_set_icon ()

void                awn_desktop_item_set_icon           (AwnDesktopItem *item,
                                                         gchar *icon);

Sets the icon name of the desktop item.

item : The desktop item structure that is being modified.
icon : The name of the icon, preferably per the Freedesktop.org Icon Naming Specification.

awn_desktop_item_get_name ()

gchar*              awn_desktop_item_get_name           (AwnDesktopItem *item);

Retrieves the name of the desktop item.

item : The desktop item structure that is being queried.
Returns : the item name.

awn_desktop_item_set_name ()

void                awn_desktop_item_set_name           (AwnDesktopItem *item,
                                                         gchar *name);

Sets the name of the desktop item.

item : The desktop item structure that is being modified.
name : The new name of the desktop item.

awn_desktop_item_get_exec ()

gchar*              awn_desktop_item_get_exec           (AwnDesktopItem *item);

Retrieves the path of the desktop item.

item : The desktop item structure that is being queried.
Returns : the item path.

awn_desktop_item_set_exec ()

void                awn_desktop_item_set_exec           (AwnDesktopItem *item,
                                                         gchar *exec);

Sets the path of the desktop item.

item : The desktop item structure that is being modified.
exec : The new path of the desktop item.

awn_desktop_item_get_string ()

gchar*              awn_desktop_item_get_string         (AwnDesktopItem *item,
                                                         gchar *key);

Retrieves the value of a key in the desktop item specified.

item : The desktop item structure that is being queried.
key : The name of the key.
Returns : the value of the key if it exists, or NULL otherwise.

awn_desktop_item_set_string ()

void                awn_desktop_item_set_string         (AwnDesktopItem *item,
                                                         gchar *key,
                                                         gchar *value);

Changes the value of a key in the desktop item specified.

item : The desktop item structure that is being modified.
key : The name of the key.
value : The new value of the key.

awn_desktop_item_get_localestring ()

gchar*              awn_desktop_item_get_localestring   (AwnDesktopItem *item,
                                                         gchar *key);

Retrieves a locale-specific value for a key in the desktop item.

item : The desktop item structure that is being queried.
key : The name of the key.
Returns : the locale-specific value, if it exists, or NULL otherwise.

awn_desktop_item_set_localestring ()

void                awn_desktop_item_set_localestring   (AwnDesktopItem *item,
                                                         gchar *key,
                                                         gchar *locale,
                                                         gchar *value);

Sets a locale-specific value for a key in a desktop item.

item : The desktop item structure that is being modified.
key : The name of the key.
locale : The name of the locale. The format must correspond to the POSIX specification on locale names.
value : The new value of the locale-specific key.

awn_desktop_item_exists ()

gboolean            awn_desktop_item_exists             (AwnDesktopItem *item);

Checks to see if the path associated with the desktop item exists and is executable.

item : The desktop item structure that is being queried.
Returns : TRUE on success, FALSE otherwise.

awn_desktop_item_launch ()

gint                awn_desktop_item_launch             (AwnDesktopItem *item,
                                                         GSList *documents,
                                                         GError **err);

Launches the path of the desktop item.

item : The desktop item structure to be launched.
documents : A list of documents that is passed to the path as arguments. Can be NULL.
err : A pointer to a GError structure, which contains an error message if the function fails.
Returns : the process ID (PID) of the new process.

awn_desktop_item_save ()

void                awn_desktop_item_save               (AwnDesktopItem *item,
                                                         gchar *new_filename,
                                                         GError **err);

Saves the serialized desktop item to disk.

item : The desktop item structure to be serialized.
new_filename : the new name of the file where the serialized data is saved. If it is NULL, the filename specified in awn_desktop_item_new() is used.
err : The pointer to a GError structure, which contains an error message when the function fails.