XfceDesktopEntry
3
LIBXFCE4UTIL Library

# XfceDesktopEntry

A GObject that wraps a .desktop file.

## Synopsis

    #include <libxfce4util/libxfce4util.h>

                        XfceDesktopEntry;
    XfceDesktopEntry*   xfce_desktop_entry_new              (const gchar *file,
                                                             const gchar **categories,
                                                             gint num_categories);
    XfceDesktopEntry*   xfce_desktop_entry_new_from_data    (const gchar *data,
                                                             const gchar **categories,
                                                             gint num_categories);
    const gchar*        xfce_desktop_entry_get_file         (XfceDesktopEntry *desktop_entry);
    gboolean            xfce_desktop_entry_get_string       (XfceDesktopEntry *desktop_entry,
                                                             const gchar *key,
                                                             gboolean translated,
                                                             gchar **value_return);
    gboolean            xfce_desktop_entry_get_int          (XfceDesktopEntry *desktop_entry,
                                                             const gchar *key,
                                                             gint *value_return);
    gboolean            xfce_desktop_entry_has_translated_entry
                                                            (XfceDesktopEntry *desktop_entry,
                                                             const gchar *key);

## Object Hierarchy

      GObject
       +----XfceDesktopEntry

## Description

XfceDesktopEntry is a wrapper for a so-called desktop entry file. The desktop entry format is defined on Freedesktop.org.

## Details

### XfceDesktopEntry

    typedef struct _XfceDesktopEntry XfceDesktopEntry;

All the fields in the XfceDesktopEntry structure are private to the XfceDesktopEntry implementation and should never be accessed directly. Instead, you should use the functions listed below.

### xfce_desktop_entry_new ()

    XfceDesktopEntry*   xfce_desktop_entry_new              (const gchar *file,
                                                             const gchar **categories,
                                                             gint num_categories);

Create a new XfceDesktopEntry object from a desktop entry stored in a file on disk.

The caller is responsible to free the returned object (if any) using `g_object_unref()` when no longer needed.

`file` :

  full path to the desktop entry file to use.

`categories` :

  array of categories, not necessarily NULL terminated.

`num_categories` :

  number of items in `categories`.

Returns :

  newly created XfceDesktopEntry or NULL if something goes wrong.

Since 4.2

### xfce_desktop_entry_new_from_data ()

    XfceDesktopEntry*   xfce_desktop_entry_new_from_data    (const gchar *data,
                                                             const gchar **categories,
                                                             gint num_categories);

Create a new XfceDesktopEntry object from a desktop entry stored in memory.

The caller is responsible to free the returned object (if any) using `g_object_unref()` when no longer needed.

`data` :

  pointer to the desktop entry inline data.

`categories` :

  array of categories, not necessarily NULL terminated.

`num_categories` :

  number of items in `categories`.

Returns :

  newly created XfceDesktopEntry or NULL if something goes wrong.

Since 4.2

### xfce_desktop_entry_get_file ()

    const gchar*        xfce_desktop_entry_get_file         (XfceDesktopEntry *desktop_entry);

Obtain the path to the desktop entry file associated with the XfceDesktopEntry.

`desktop_entry` :

  an XfceDesktopEntry.

Returns :

  path of the desktop entry file used to create `desktop_entry`. The return value should be considered read-only and must not be freed by the caller.

Since 4.2

### xfce_desktop_entry_get_string ()

    gboolean            xfce_desktop_entry_get_string       (XfceDesktopEntry *desktop_entry,
                                                             const gchar *key,
                                                             gboolean translated,
                                                             gchar **value_return);

Finds the value for `key`. When `translated` is TRUE the function will use the translated value (using the current locale settings) if available or the untranslated value if no translation can be found.

`desktop_entry` :

  an XfceDesktopEntry

`key` :

  category to find value for.

`translated` :

  set to TRUE if the translated value is preferred.

`value_return` :

  location for the value, which will be newly allocated.

Returns :

  TRUE on success, FALSE on failure. `value_return` must be freed.

Since 4.2

### xfce_desktop_entry_get_int ()

    gboolean            xfce_desktop_entry_get_int          (XfceDesktopEntry *desktop_entry,
                                                             const gchar *key,
                                                             gint *value_return);

Gets a value from `desktop_entry` as integer. Therefore finds the value for `key` and returns its integer representation.

`desktop_entry` :

  an XfceDesktopEntry.

`key` :

  category to find value for.

`value_return` :

  location for the value.

Returns :

  TRUE on success, FALSE on failure.

Since 4.2

### xfce_desktop_entry_has_translated_entry ()

    gboolean            xfce_desktop_entry_has_translated_entry
                                                            (XfceDesktopEntry *desktop_entry,
                                                             const gchar *key);

Checks to see if `desktop_entry` has a value for `key` translated into the current locale.

`desktop_entry` :

  an XfceDesktopEntry.

`key` :

  the key to check.

Returns :

  `TRUE` if there is a translated key, `FALSE` otherwise.

Since 4.3