awn-desktop-item

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