493 lines
12 KiB
HTML
493 lines
12 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of File::DesktopEntry</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>File::DesktopEntry</H1>
|
|
Section: User Contributed Perl Documentation (3pm)<BR>Updated: 2015-12-10<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
File::DesktopEntry - Object to handle .desktop files
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
use File::DesktopEntry;
|
|
|
|
my $entry = File::DesktopEntry->new('firefox');
|
|
|
|
print "Using ".$entry->Name." to open <A HREF="http://perl.org\n">http://perl.org\n</A>";
|
|
$entry->run('<A HREF="http://perl.org');">http://perl.org');</A>
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
This module is designed to work with <I>.desktop</I> files. The format of these files
|
|
is specified by the freedesktop ``Desktop Entry'' specification. This module can
|
|
parse these files but also knows how to run the applications defined by these
|
|
files.
|
|
<P>
|
|
|
|
For this module version 1.0 of the specification was used.
|
|
<P>
|
|
|
|
This module was written to support File::MimeInfo::Applications.
|
|
<P>
|
|
|
|
Please remember: case is significant for the names of Desktop Entry keys.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>VARIABLES</H2>
|
|
|
|
|
|
|
|
You can set the global variable <TT>$File::DesktopEntry::VERBOSE</TT>. If set the
|
|
module prints a warning every time a command gets executed.
|
|
<P>
|
|
|
|
The global variable <TT>$File::DesktopEntry::LOCALE</TT> tells you what the default
|
|
locale being used is. However, changing it will not change the default locale.
|
|
<A NAME="lbAF"> </A>
|
|
<H2>AUTOLOAD</H2>
|
|
|
|
|
|
|
|
All methods that start with a capital are autoloaded as <TT>"get(KEY)"</TT> where
|
|
key is the autoloaded method name.
|
|
<A NAME="lbAG"> </A>
|
|
<H2>METHODS</H2>
|
|
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="1">"new(FILE)"<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="2">"new(\$TEXT)"<DD>
|
|
|
|
|
|
|
|
|
|
<DT id="3">"new(NAME)"<DD>
|
|
|
|
|
|
|
|
|
|
|
|
Constructor. <FONT SIZE="-1">FILE, NAME</FONT> or <FONT SIZE="-1">TEXT</FONT> are optional arguments.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
When a name is given (a string without '<TT>"/"</TT>', '<TT>"\"</TT>' or '<TT>"."</TT>') a lookup is
|
|
done using File::BaseDir. If the file found in this lookup is not writable or
|
|
if no file was found, the <FONT SIZE="-1">XDG_DATA_HOME</FONT> path will be used when writing.
|
|
<DT id="4">"lookup(NAME)"<DD>
|
|
|
|
|
|
|
|
|
|
Returns a filename for a desktop entry with desktop file id <FONT SIZE="-1">NAME.</FONT>
|
|
<DT id="5">"wants_uris( )"<DD>
|
|
|
|
|
|
|
|
|
|
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 <FONT SIZE="-1">VFS</FONT> library.
|
|
<DT id="6">"wants_list( )"<DD>
|
|
|
|
|
|
|
|
|
|
Returns true if the Exec string for this desktop entry specifies that the
|
|
application can handle multiple arguments at once.
|
|
<DT id="7">"run(@FILES)"<DD>
|
|
|
|
|
|
|
|
|
|
Forks and runs the application specified in this Desktop Entry
|
|
with arguments <FONT SIZE="-1">FILES</FONT> as a background process. Returns the pid.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The child process fails when this is not a Desktop Entry of type Application
|
|
or if the Exec key is missing or invalid.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If the desktop entry specifies that the program needs to be executed in a
|
|
terminal the <TT>$TERMINAL</TT> environment variable is used. If this variable is not
|
|
set <TT>"xterm -e"</TT> is used as default.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
(On Windows this method returns a Win32::Process object.)
|
|
<DT id="8">"system(@FILES)"<DD>
|
|
|
|
|
|
|
|
|
|
Like <TT>"run()"</TT> but using the <TT>"system()"</TT> system call.
|
|
It only return after the application has ended.
|
|
<DT id="9">"exec(@FILES)"<DD>
|
|
|
|
|
|
|
|
|
|
Like <TT>"run()"</TT> but using the <TT>"exec()"</TT> system call. This method
|
|
is expected not to return but to replace the current process with the
|
|
application you try to run.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
On Windows this method doesn't always work the way you want it to
|
|
due to the <TT>"fork()"</TT> emulation on this platform. Try using <TT>"run()"</TT> or
|
|
<TT>"system()"</TT> instead.
|
|
<DT id="10">"parse_Exec(@FILES)"<DD>
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
It supports the following fields:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
%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 '%'
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If necessary this method tries to convert between paths and URLs but this
|
|
is not perfect.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Fields that are deprecated, but (still) supported by this module:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
%d single directory
|
|
%D multiple directories
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The fields <TT>%n</TT>, <TT>%N</TT>, <TT>%v</TT> and <TT>%m</TT> are deprecated and will cause a
|
|
warning if <TT>$VERBOSE</TT> is used. Any other unknown fields will cause an error.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The fields <TT>%F</TT>, <TT>%U</TT>, <TT>%D</TT> and <TT>%i</TT> can only occur as separate words
|
|
because they expand to multiple arguments.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Also see ``<FONT SIZE="-1">LIMITATIONS''</FONT>.
|
|
<DT id="11">"get(KEY)"<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="12">"get(GROUP, KEY)"<DD>
|
|
|
|
|
|
|
|
|
|
|
|
Get a value for <FONT SIZE="-1">KEY</FONT> from <FONT SIZE="-1">GROUP.</FONT> If <FONT SIZE="-1">GROUP</FONT> is not specified 'Desktop Entry' is
|
|
used. All values are treated as string, so e.g. booleans will be returned as
|
|
the literal strings ``true'' and ``false''.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
When <FONT SIZE="-1">KEY</FONT> 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. <TT>"$entry->get('Name[nl_NL]')"</TT>
|
|
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[<FONT SIZE="-1">POSIX</FONT>]'.
|
|
<DT id="13">"set(KEY => VALUE, ...)"<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="14">"set(GROUP, KEY => VALUE, ...)"<DD>
|
|
|
|
|
|
|
|
|
|
|
|
Set values for one or more keys. If <FONT SIZE="-1">GROUP</FONT> is not given ``Desktop Entry'' 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 ``true'' and ``false''.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Unlike the <TT>"get()"</TT> call languages are not handled automatically for <TT>"set()"</TT>.
|
|
<FONT SIZE="-1">KEY</FONT> should include the language part if you want to set a translation.
|
|
E.g. <TT>"$entry->set("Name[nl_NL]" => "Tekst Verwerker")"</TT> will set a Dutch
|
|
translation for the Name key. Using either ``Name[C]'' or ``Name[<FONT SIZE="-1">POSIX</FONT>]'' will
|
|
be equivalent with not giving a language argument.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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'.
|
|
<DT id="15">"text()"<DD>
|
|
|
|
|
|
|
|
|
|
Returns the (modified) text of the file.
|
|
<DT id="16">"read(FILE)"<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="17">"read(\$SCALAR)"<DD>
|
|
|
|
|
|
|
|
|
|
|
|
Read Desktop Entry data from file or memory buffer.
|
|
Without argument defaults to file given at constructor.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If you gave a file, text buffer or name to the constructor this method will
|
|
be called automatically.
|
|
<DT id="18">"read_fh(IO)"<DD>
|
|
|
|
|
|
|
|
|
|
Read Desktop Entry data from filehandle or <FONT SIZE="-1">IO</FONT> object.
|
|
<DT id="19">"write(FILE)"<DD>
|
|
|
|
|
|
|
|
|
|
Write the Desktop Entry data to <FONT SIZE="-1">FILE.</FONT> Without arguments it writes to
|
|
the filename given to the constructor if any.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The keys Name and Type are required. Type can be either <TT>"Application"</TT>,
|
|
<TT>"Link"</TT> or <TT>"Directory"</TT>. For an application set the optional key <TT>"Exec"</TT>. For
|
|
a link set the <TT>"URL"</TT> key.
|
|
</DL>
|
|
<A NAME="lbAH"> </A>
|
|
<H3>Backwards Compatibility</H3>
|
|
|
|
|
|
|
|
Methods supported for backwards compatibility with 0.02.
|
|
<DL COMPACT>
|
|
<DT id="20">"new_from_file(FILE)"<DD>
|
|
|
|
|
|
|
|
|
|
Alias for <TT>"new(FILE)"</TT>.
|
|
<DT id="21">"new_from_data(TEXT)"<DD>
|
|
|
|
|
|
|
|
|
|
Alias for <TT>"new(\$TEXT)"</TT>.
|
|
<DT id="22">"get_value(NAME, GROUP, LANG)"<DD>
|
|
|
|
|
|
|
|
|
|
Identical to <TT>"get(GROUP, "NAME[LANG]")"</TT>.
|
|
<FONT SIZE="-1">LANG</FONT> defaults to 'C', <FONT SIZE="-1">GROUP</FONT> is optional.
|
|
</DL>
|
|
<A NAME="lbAI"> </A>
|
|
<H2>NON-UNIX PLATFORMS</H2>
|
|
|
|
|
|
|
|
This module has a few bits of code to make it work on Windows. It handles
|
|
<TT>"file://"</TT> uri a bit different and it uses Win32::Process. On other
|
|
platforms your mileage may vary.
|
|
<P>
|
|
|
|
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.
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>LIMITATIONS</H2>
|
|
|
|
|
|
|
|
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 <TT>"wants_uris()"</TT> method to check
|
|
if an application supports urls.
|
|
<P>
|
|
|
|
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 ``true'' and
|
|
``false'' and lists will still be ``;'' separated.
|
|
<P>
|
|
|
|
If the icon is given as name and not as path it should be resolved for the <TT>%i</TT>
|
|
code in the Exec key. We need a separate module for the icon spec to deal with
|
|
this.
|
|
<P>
|
|
|
|
According to the spec comments can contain any encoding. However since this
|
|
module read files as utf8, invalid <FONT SIZE="-1">UTF-8</FONT> characters in a comment will cause
|
|
an error.
|
|
<P>
|
|
|
|
There is no support for Legacy-Mixed Encoding. Everybody is using utf8 now
|
|
... right ?
|
|
<A NAME="lbAK"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
|
|
|
|
Jaap Karssenberg (Pardus) <<A HREF="mailto:pardus@cpan.org">pardus@cpan.org</A>>
|
|
<P>
|
|
|
|
Maintained by Michiel Beijen <<A HREF="mailto:michielb@cpan.org">michielb@cpan.org</A>>
|
|
<P>
|
|
|
|
Copyright (c) 2005, 2007 Jaap G Karssenberg. All rights reserved.
|
|
<A NAME="lbAL"> </A>
|
|
<H2>LICENSE</H2>
|
|
|
|
|
|
|
|
This program is free software; you can redistribute it and/or
|
|
modify it under the same terms as Perl itself.
|
|
<A NAME="lbAM"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
|
|
|
|
<<A HREF="http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html">http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html</A>>
|
|
<P>
|
|
|
|
File::BaseDir and File::MimeInfo::Applications
|
|
<P>
|
|
|
|
X11::FreeDesktop::DesktopEntry
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="23"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="24"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="25"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="26"><A HREF="#lbAE">VARIABLES</A><DD>
|
|
<DT id="27"><A HREF="#lbAF">AUTOLOAD</A><DD>
|
|
<DT id="28"><A HREF="#lbAG">METHODS</A><DD>
|
|
<DL>
|
|
<DT id="29"><A HREF="#lbAH">Backwards Compatibility</A><DD>
|
|
</DL>
|
|
<DT id="30"><A HREF="#lbAI">NON-UNIX PLATFORMS</A><DD>
|
|
<DT id="31"><A HREF="#lbAJ">LIMITATIONS</A><DD>
|
|
<DT id="32"><A HREF="#lbAK">AUTHOR</A><DD>
|
|
<DT id="33"><A HREF="#lbAL">LICENSE</A><DD>
|
|
<DT id="34"><A HREF="#lbAM">SEE ALSO</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:43 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|