---
name: "X11::FreeDesktop::DesktopEntry"
section: "3pm"
platform: "linux"
package: "libx11-freedesktop-desktopentry-perl"
version: "0.04-5"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/X11::FreeDesktop::DesktopEntry"
---

# X11::FreeDesktop::DesktopEntry(3pm)

an interface to Freedesktop.org .desktop files.

## NAME

X11::FreeDesktop::DesktopEntry - an interface to Freedesktop.org .desktop files.

## SYNOPSIS

```
        use X11::FreeDesktop::DesktopEntry;
        my $entry = X11::FreeDesktop::DesktopEntry->new_from_data($data);
        print $entry->get_value('Name');
        print $entry->Exec;
        $entry->set_value('Name', 'Example Program');
        print $entry->as_string;
        $entry->reset;
```

## DESCRIPTION

This module provides an object-oriented interface to files that comply with the Freedesktop.org desktop entry specification. You can query the file for available values, modify them, and also get locale information as well.

## CONSTRUCTOR

X11::FreeDesktop::DesktopEntry doesn't have the standard `"new()"` constructor. This allows subclasses to implement their own backend-specific constructor without needing to re-implement the constructor, which can be a pain *(for an* *example subclass that uses Gnome2::VFS as a backend, see the "PerlPanel::DesktopEntry"* *module in the PerlPanel distribution)*.

```
        my $entry = X11::FreeDesktop::DesktopEntry->new_from_data($data);
```

If there is an error reading or parsing the data, the constructor will `"carp()"` and return an undefined value.

## METHODS

```
        $entry->is_valid($locale);
```

Returns a true or false valid depending on whether the required keys exist for the given `$locale`. A list of the required keys can be found in the Freedesktop.org specification. If `$locale` is omitted, it will default to '`"C"`'.

```
        my @groups = $entry->groups;
```

This returns an array of scalars containing the *group names* included in the file. Groups are defined by a line like the following in the file itself:

```
        [Desktop Entry]
```

A valid desktop entry file will always have one of these, at the top.

```
        $entry->has_group($group);
```

Returns true or false depending on whether the file has a section with the name of `$group`.

```
        my @keys = $entry->keys($group, $locale);
```

Returns an array of the available keys in `$group` and the `$locale` locale. Both these values revert to defaults if they're undefined. When `$locale` is defined, the array will be folded in with the keys from '`"C"`', since locales inherit keys from the default locale. See the `"get_value()"` method for another example of this inheritance.

```
        $entry->has_key($key, $group);
```

Returns true or false depending on whether the file has a key with the name of `$key` in the `$group` section. If `$group` is omitted, then the default group (`'Desktop Entry'`) will be used.

```
        my @locales = $entry->locales($key, $group);
```

Returns an array of strings naming all the available locales for the given `$key`. If `$key` or `$group` don't exist in the file, this method will `"carp()"` and return undef. There should always be at least one locale in the returned array - the default locale, '`"C"`'.

```
        my $string = $entry->get_value($key, $group, $locale);
```

Returns the value of the key named by `$key`. `$group` is optional, and will be set to the default if omitted (see above). `$locale` is also optional, and defines the locale for the string (defaults to '`"C"`' if omitted). If the requested key does not exist for a non-default `$locale` of the form `"xx_YY"`, then the module will search for a value for the `"xx"` locale. If nothing is found, this method will attempt to return the value for the '`"C"`' locale. If this value does not exist, this method will return undef.

```
        $entry->set_value($key, $value, $locale, $group);
```

This method sets the value of the `$key` key in the `$locale` locale and `$group` group to be `$value`. If `$locale` and `$group` are omitted, the defaults are used. `$value` is always interpreted as a string. This method always returns true.

```
        my $data = $entry->as_string;
```

This method returns a scalar containing the full entry in .desktop format. This data can then be used to write the entry to disk.

```
        $entry->reset;
```

This method restores the entry to its initial state - it undoes any changes made to the values stored in the entry.

## CONVENIENCE METHODS

```
        my $name                = $entry->Name($locale);
        my $generic_name        = $entry->GenericName($locale);
        my $comment             = $entry->Comment($locale);
        my $type                = $entry->Type($locale);
        my $icon                = $entry->Icon($locale);
        my $exec                = $entry->Exec($locale);
        my $url                 = $entry->URL($locale);
        my $startup_notify      = $entry->StartupNotify($locale);
```

These methods are shortcuts for the mostly commonly accessed fields from a desktop entry file. If undefined, `$locale` reverts to the default.

## NOTES

Please note that according to the Freedesktop.org spec, key names are case-sensitive.

## SEE ALSO

The Freedesktop.org Desktop Entry Specification at \<http://www.freedesktop.org/Standards/desktop-entry-spec\>.

## AUTHOR

Gavin Brown \<gavin.brown@uk.com\>.

## COPYRIGHT

Copyright (c) 2005 Gavin Brown. This program is free software, you can use it and/or modify it under the same terms as Perl itself.