.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "X11::FreeDesktop::DesktopEntry 3pm" .TH X11::FreeDesktop::DesktopEntry 3pm "2018-07-12" "perl v5.26.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" X11::FreeDesktop::DesktopEntry \- an interface to Freedesktop.org .desktop files. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use X11::FreeDesktop::DesktopEntry; \& \& my $entry = X11::FreeDesktop::DesktopEntry\->new_from_data($data); \& \& print $entry\->get_value(\*(AqName\*(Aq); \& \& print $entry\->Exec; \& \& $entry\->set_value(\*(AqName\*(Aq, \*(AqExample Program\*(Aq); \& \& print $entry\->as_string; \& \& $entry\->reset; .Ve .SH "DESCRIPTION" .IX Header "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. .SH "CONSTRUCTOR" .IX Header "CONSTRUCTOR" X11::FreeDesktop::DesktopEntry doesn't have the standard \f(CW\*(C`new()\*(C'\fR constructor. This allows subclasses to implement their own backend-specific constructor without needing to re-implement the constructor, which can be a pain \fI(for an example subclass that uses Gnome2::VFS as a backend, see the \f(CI\*(C`PerlPanel::DesktopEntry\*(C'\fI module in the PerlPanel distribution)\fR. .PP .Vb 1 \& my $entry = X11::FreeDesktop::DesktopEntry\->new_from_data($data); .Ve .PP If there is an error reading or parsing the data, the constructor will \&\f(CW\*(C`carp()\*(C'\fR and return an undefined value. .SH "METHODS" .IX Header "METHODS" .Vb 1 \& $entry\->is_valid($locale); .Ve .PP Returns a true or false valid depending on whether the required keys exist for the given \f(CW$locale\fR. A list of the required keys can be found in the Freedesktop.org specification. If \f(CW$locale\fR is omitted, it will default to \&'\f(CW\*(C`C\*(C'\fR'. .PP .Vb 1 \& my @groups = $entry\->groups; .Ve .PP This returns an array of scalars containing the \fIgroup names\fR included in the file. Groups are defined by a line like the following in the file itself: .PP .Vb 1 \& [Desktop Entry] .Ve .PP A valid desktop entry file will always have one of these, at the top. .PP .Vb 1 \& $entry\->has_group($group); .Ve .PP Returns true or false depending on whether the file has a section with the name of \f(CW$group\fR. .PP .Vb 1 \& my @keys = $entry\->keys($group, $locale); .Ve .PP Returns an array of the available keys in \f(CW$group\fR and the \f(CW$locale\fR locale. Both these values revert to defaults if they're undefined. When \f(CW$locale\fR is defined, the array will be folded in with the keys from '\f(CW\*(C`C\*(C'\fR', since locales inherit keys from the default locale. See the \f(CW\*(C`get_value()\*(C'\fR method for another example of this inheritance. .PP .Vb 1 \& $entry\->has_key($key, $group); .Ve .PP Returns true or false depending on whether the file has a key with the name of \&\f(CW$key\fR in the \f(CW$group\fR section. If \f(CW$group\fR is omitted, then the default group (\f(CW\*(AqDesktop Entry\*(Aq\fR) will be used. .PP .Vb 1 \& my @locales = $entry\->locales($key, $group); .Ve .PP Returns an array of strings naming all the available locales for the given \&\f(CW$key\fR. If \f(CW$key\fR or \f(CW$group\fR don't exist in the file, this method will \&\f(CW\*(C`carp()\*(C'\fR and return undef. There should always be at least one locale in the returned array \- the default locale, '\f(CW\*(C`C\*(C'\fR'. .PP .Vb 1 \& my $string = $entry\->get_value($key, $group, $locale); .Ve .PP Returns the value of the key named by \f(CW$key\fR. \f(CW$group\fR is optional, and will be set to the default if omitted (see above). \f(CW$locale\fR is also optional, and defines the locale for the string (defaults to '\f(CW\*(C`C\*(C'\fR' if omitted). If the requested key does not exist for a non-default \f(CW$locale\fR of the form \f(CW\*(C`xx_YY\*(C'\fR, then the module will search for a value for the \f(CW\*(C`xx\*(C'\fR locale. If nothing is found, this method will attempt to return the value for the '\f(CW\*(C`C\*(C'\fR' locale. If this value does not exist, this method will return undef. .PP .Vb 1 \& $entry\->set_value($key, $value, $locale, $group); .Ve .PP This method sets the value of the \f(CW$key\fR key in the \f(CW$locale\fR locale and \&\f(CW$group\fR group to be \f(CW$value\fR. If \f(CW$locale\fR and \f(CW$group\fR are omitted, the defaults are used. \f(CW$value\fR is always interpreted as a string. This method always returns true. .PP .Vb 1 \& my $data = $entry\->as_string; .Ve .PP This method returns a scalar containing the full entry in .desktop format. This data can then be used to write the entry to disk. .PP .Vb 1 \& $entry\->reset; .Ve .PP This method restores the entry to its initial state \- it undoes any changes made to the values stored in the entry. .SH "CONVENIENCE METHODS" .IX Header "CONVENIENCE METHODS" .Vb 8 \& 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); .Ve .PP These methods are shortcuts for the mostly commonly accessed fields from a desktop entry file. If undefined, \f(CW$locale\fR reverts to the default. .SH "NOTES" .IX Header "NOTES" Please note that according to the Freedesktop.org spec, key names are case-sensitive. .SH "SEE ALSO" .IX Header "SEE ALSO" The Freedesktop.org Desktop Entry Specification at . .SH "AUTHOR" .IX Header "AUTHOR" Gavin Brown . .SH "COPYRIGHT" .IX Header "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.