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.