.\" Automatically generated by Pod::Man 4.11 (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 .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "File::DesktopEntry 3pm" .TH File::DesktopEntry 3pm "2020-05-22" "perl v5.30.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" File::DesktopEntry \- Object to handle .desktop files .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use File::DesktopEntry; \& \& my $entry = File::DesktopEntry\->new(\*(Aqfirefox\*(Aq); \& \& print "Using ".$entry\->Name." to open http://perl.org\en"; \& $entry\->run(\*(Aqhttp://perl.org\*(Aq); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module is designed to work with \fI.desktop\fR files. The format of these files is specified by the freedesktop \*(L"Desktop Entry\*(R" specification. This module can parse these files but also knows how to run the applications defined by these files. .PP For this module version 1.0 of the specification was used. .PP This module was written to support File::MimeInfo::Applications. .PP Please remember: case is significant for the names of Desktop Entry keys. .SH "VARIABLES" .IX Header "VARIABLES" You can set the global variable \f(CW$File::DesktopEntry::VERBOSE\fR. If set the module prints a warning every time a command gets executed. .PP The global variable \f(CW$File::DesktopEntry::LOCALE\fR tells you what the default locale being used is. However, changing it will not change the default locale. .SH "AUTOLOAD" .IX Header "AUTOLOAD" All methods that start with a capital are autoloaded as \f(CW\*(C`get(KEY)\*(C'\fR where key is the autoloaded method name. .SH "METHODS" .IX Header "METHODS" .ie n .IP """new(FILE)""" 4 .el .IP "\f(CWnew(FILE)\fR" 4 .IX Item "new(FILE)" .PD 0 .ie n .IP """new(\e$TEXT)""" 4 .el .IP "\f(CWnew(\e$TEXT)\fR" 4 .IX Item "new($TEXT)" .ie n .IP """new(NAME)""" 4 .el .IP "\f(CWnew(NAME)\fR" 4 .IX Item "new(NAME)" .PD Constructor. \s-1FILE, NAME\s0 or \s-1TEXT\s0 are optional arguments. .Sp When a name is given (a string without '\f(CW\*(C`/\*(C'\fR', '\f(CW\*(C`\e\*(C'\fR' or '\f(CW\*(C`.\*(C'\fR') a lookup is done using File::BaseDir. If the file found in this lookup is not writable or if no file was found, the \s-1XDG_DATA_HOME\s0 path will be used when writing. .ie n .IP """lookup(NAME)""" 4 .el .IP "\f(CWlookup(NAME)\fR" 4 .IX Item "lookup(NAME)" Returns a filename for a desktop entry with desktop file id \s-1NAME.\s0 .ie n .IP """wants_uris( )""" 4 .el .IP "\f(CWwants_uris( )\fR" 4 .IX Item "wants_uris( )" Returns true if the Exec string for this desktop entry specifies that the application uses URIs instead of paths. This can be used to determine whether an application uses a \s-1VFS\s0 library. .ie n .IP """wants_list( )""" 4 .el .IP "\f(CWwants_list( )\fR" 4 .IX Item "wants_list( )" Returns true if the Exec string for this desktop entry specifies that the application can handle multiple arguments at once. .ie n .IP """run(@FILES)""" 4 .el .IP "\f(CWrun(@FILES)\fR" 4 .IX Item "run(@FILES)" Forks and runs the application specified in this Desktop Entry with arguments \s-1FILES\s0 as a background process. Returns the pid. .Sp The child process fails when this is not a Desktop Entry of type Application or if the Exec key is missing or invalid. .Sp If the desktop entry specifies that the program needs to be executed in a terminal the \f(CW$TERMINAL\fR environment variable is used. If this variable is not set \f(CW\*(C`x\-terminal\-emulator \-e\*(C'\fR is used as default on Debian systems. .Sp (On Windows this method returns a Win32::Process object.) .ie n .IP """system(@FILES)""" 4 .el .IP "\f(CWsystem(@FILES)\fR" 4 .IX Item "system(@FILES)" Like \f(CW\*(C`run()\*(C'\fR but using the \f(CW\*(C`system()\*(C'\fR system call. It only return after the application has ended. .ie n .IP """exec(@FILES)""" 4 .el .IP "\f(CWexec(@FILES)\fR" 4 .IX Item "exec(@FILES)" Like \f(CW\*(C`run()\*(C'\fR but using the \f(CW\*(C`exec()\*(C'\fR system call. This method is expected not to return but to replace the current process with the application you try to run. .Sp On Windows this method doesn't always work the way you want it to due to the \f(CW\*(C`fork()\*(C'\fR emulation on this platform. Try using \f(CW\*(C`run()\*(C'\fR or \&\f(CW\*(C`system()\*(C'\fR instead. .ie n .IP """parse_Exec(@FILES)""" 4 .el .IP "\f(CWparse_Exec(@FILES)\fR" 4 .IX Item "parse_Exec(@FILES)" Expands the Exec format in this desktop entry with. Returns a properly quoted string in scalar context or a list of words in list context. Dies when the Exec key is invalid. .Sp It supports the following fields: .Sp .Vb 8 \& %f single file \& %F multiple files \& %u single url \& %U multiple urls \& %i Icon field prefixed by \-\-icon \& %c Name field, possibly translated \& %k location of this .desktop file \& %% literal \*(Aq%\*(Aq .Ve .Sp If necessary this method tries to convert between paths and URLs but this is not perfect. .Sp Fields that are deprecated, but (still) supported by this module: .Sp .Vb 2 \& %d single directory \& %D multiple directories .Ve .Sp The fields \f(CW%n\fR, \f(CW%N\fR, \f(CW%v\fR and \f(CW%m\fR are deprecated and will cause a warning if \f(CW$VERBOSE\fR is used. Any other unknown fields will cause an error. .Sp The fields \f(CW%F\fR, \f(CW%U\fR, \f(CW%D\fR and \f(CW%i\fR can only occur as separate words because they expand to multiple arguments. .Sp Also see \*(L"\s-1LIMITATIONS\*(R"\s0. .ie n .IP """get(KEY)""" 4 .el .IP "\f(CWget(KEY)\fR" 4 .IX Item "get(KEY)" .PD 0 .ie n .IP """get(GROUP, KEY)""" 4 .el .IP "\f(CWget(GROUP, KEY)\fR" 4 .IX Item "get(GROUP, KEY)" .PD Get a value for \s-1KEY\s0 from \s-1GROUP.\s0 If \s-1GROUP\s0 is not specified 'Desktop Entry' is used. All values are treated as string, so e.g. booleans will be returned as the literal strings \*(L"true\*(R" and \*(L"false\*(R". .Sp When \s-1KEY\s0 does not contain a language code you get the translation in the current locale if available or a sensible default. The request a specific language you can add the language part. E.g. \f(CW\*(C`$entry\->get(\*(AqName[nl_NL]\*(Aq)\*(C'\fR can return either the value of the 'Name[nl_NL]', the 'Name[nl]' or the 'Name' key in the Desktop Entry file. Exact language parsing order can be found in the spec. To force you get the untranslated key use either 'Name[C]' or \&'Name[\s-1POSIX\s0]'. .ie n .IP """set(KEY => VALUE, ...)""" 4 .el .IP "\f(CWset(KEY => VALUE, ...)\fR" 4 .IX Item "set(KEY => VALUE, ...)" .PD 0 .ie n .IP """set(GROUP, KEY => VALUE, ...)""" 4 .el .IP "\f(CWset(GROUP, KEY => VALUE, ...)\fR" 4 .IX Item "set(GROUP, KEY => VALUE, ...)" .PD Set values for one or more keys. If \s-1GROUP\s0 is not given \*(L"Desktop Entry\*(R" is used. All values are treated as strings, backslashes, newlines and tabs are escaped. To set a boolean key you need to use the literal strings \*(L"true\*(R" and \*(L"false\*(R". .Sp Unlike the \f(CW\*(C`get()\*(C'\fR call languages are not handled automatically for \f(CW\*(C`set()\*(C'\fR. \&\s-1KEY\s0 should include the language part if you want to set a translation. E.g. \f(CW\*(C`$entry\->set("Name[nl_NL]" => "Tekst Verwerker")\*(C'\fR will set a Dutch translation for the Name key. Using either \*(L"Name[C]\*(R" or \*(L"Name[\s-1POSIX\s0]\*(R" will be equivalent with not giving a language argument. .Sp When setting the Exec key without specifying a group it will be parsed and quoted correctly as required by the spec. You can use quoted arguments to include whitespace in a argument, escaping whitespace does not work. To circumvent this quoting explicitly give the group name 'Desktop Entry'. .ie n .IP """text()""" 4 .el .IP "\f(CWtext()\fR" 4 .IX Item "text()" Returns the (modified) text of the file. .ie n .IP """read(FILE)""" 4 .el .IP "\f(CWread(FILE)\fR" 4 .IX Item "read(FILE)" .PD 0 .ie n .IP """read(\e$SCALAR)""" 4 .el .IP "\f(CWread(\e$SCALAR)\fR" 4 .IX Item "read($SCALAR)" .PD Read Desktop Entry data from file or memory buffer. Without argument defaults to file given at constructor. .Sp If you gave a file, text buffer or name to the constructor this method will be called automatically. .ie n .IP """read_fh(IO)""" 4 .el .IP "\f(CWread_fh(IO)\fR" 4 .IX Item "read_fh(IO)" Read Desktop Entry data from filehandle or \s-1IO\s0 object. .ie n .IP """write(FILE)""" 4 .el .IP "\f(CWwrite(FILE)\fR" 4 .IX Item "write(FILE)" Write the Desktop Entry data to \s-1FILE.\s0 Without arguments it writes to the filename given to the constructor if any. .Sp The keys Name and Type are required. Type can be either \f(CW\*(C`Application\*(C'\fR, \&\f(CW\*(C`Link\*(C'\fR or \f(CW\*(C`Directory\*(C'\fR. For an application set the optional key \f(CW\*(C`Exec\*(C'\fR. For a link set the \f(CW\*(C`URL\*(C'\fR key. .SS "Backwards Compatibility" .IX Subsection "Backwards Compatibility" Methods supported for backwards compatibility with 0.02. .ie n .IP """new_from_file(FILE)""" 4 .el .IP "\f(CWnew_from_file(FILE)\fR" 4 .IX Item "new_from_file(FILE)" Alias for \f(CW\*(C`new(FILE)\*(C'\fR. .ie n .IP """new_from_data(TEXT)""" 4 .el .IP "\f(CWnew_from_data(TEXT)\fR" 4 .IX Item "new_from_data(TEXT)" Alias for \f(CW\*(C`new(\e$TEXT)\*(C'\fR. .ie n .IP """get_value(NAME, GROUP, LANG)""" 4 .el .IP "\f(CWget_value(NAME, GROUP, LANG)\fR" 4 .IX Item "get_value(NAME, GROUP, LANG)" Identical to \f(CW\*(C`get(GROUP, "NAME[LANG]")\*(C'\fR. \&\s-1LANG\s0 defaults to 'C', \s-1GROUP\s0 is optional. .SH "NON-UNIX PLATFORMS" .IX Header "NON-UNIX PLATFORMS" This module has a few bits of code to make it work on Windows. It handles \&\f(CW\*(C`file://\*(C'\fR uri a bit different and it uses Win32::Process. On other platforms your mileage may vary. .PP Please note that the specification is targeting Unix platforms only and will only have limited relevance on other platforms. Any platform-dependent behavior in this module should be considered an extension of the spec. .SH "LIMITATIONS" .IX Header "LIMITATIONS" If you try to exec a remote file with an application that can only handle files on the local file system we should \-according to the spec\- download the file to a temp location. This is not supported. Use the \f(CW\*(C`wants_uris()\*(C'\fR method to check if an application supports urls. .PP The values of the various Desktop Entry keys are not parsed (except for the Exec key). This means that booleans will be returned as the strings \*(L"true\*(R" and \&\*(L"false\*(R" and lists will still be \*(L";\*(R" separated. .PP If the icon is given as name and not as path it should be resolved for the \f(CW%i\fR code in the Exec key. We need a separate module for the icon spec to deal with this. .PP According to the spec comments can contain any encoding. However since this module read files as utf8, invalid \s-1UTF\-8\s0 characters in a comment will cause an error. .PP There is no support for Legacy-Mixed Encoding. Everybody is using utf8 now \&... right ? .SH "AUTHOR" .IX Header "AUTHOR" Jaap Karssenberg (Pardus) .PP Maintained by Michiel Beijen .PP Copyright (c) 2005, 2007 Jaap G Karssenberg. All rights reserved. .SH "LICENSE" .IX Header "LICENSE" This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" .PP File::BaseDir and File::MimeInfo::Applications .PP X11::FreeDesktop::DesktopEntry