You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
374 lines
30 KiB
374 lines
30 KiB
----------------------------------------------------------------------------------------------------------------------------
|
|
|
|
Desktop Entry Standard
|
|
|
|
Preston Brown
|
|
|
|
<pbrown@kde.org>
|
|
|
|
Jonathan Blandford
|
|
|
|
<jrb@redhat.com>
|
|
|
|
Owen Taylor
|
|
|
|
<otaylor@gtk.org>
|
|
|
|
Version 0.9.4
|
|
|
|
----------------------------------------------------------------------------------------------------------------------------
|
|
|
|
Table of Contents
|
|
|
|
Introduction
|
|
|
|
Basic format of the file
|
|
|
|
Possible value types
|
|
|
|
Recognized desktop entry keys
|
|
|
|
Character set encoding of the file
|
|
|
|
List of valid Exec parameter variables
|
|
|
|
Detailed discussion of supporting MIME types
|
|
|
|
Extending the format
|
|
|
|
A. Example Desktop Entry File
|
|
|
|
B. Currently reserved for use within KDE
|
|
|
|
C. Deprecated Items
|
|
|
|
D. The Legacy-Mixed encoding (Deprecated)
|
|
|
|
Introduction
|
|
|
|
Both the KDE and GNOME desktop environments have adopted a similar format for "desktop entries," or configuration files
|
|
describing how a particular program is to be launched, how it appears in menus, etc. It is to the larger community's benefit
|
|
that a unified standard be agreed upon by all parties such that interoperation between the two environments, and indeed any
|
|
additional environments that implement the specification, becomes simpler.
|
|
|
|
Basic format of the file
|
|
|
|
These desktop entry files should have the extension ".desktop". Determining file type on basis of extension makes determining
|
|
the file type very easy and quick. When no file extension is present, the desktop system should fall back to recognition via
|
|
"magic detection." Desktop entries which describe how a directory is to be formatted/displayed should be simply called
|
|
".directory".
|
|
|
|
The basic format of the desktop entry file requires that there be a "group" header named "[Desktop Entry]". This "group" entry
|
|
denotes that all {key,value} pairs following it belong in the Desktop Entry group. There may be other groups present in the file
|
|
(see MIME types discussion below), but this is the most important group which explicitly needs to be supported. This group
|
|
should also be used as the "magic key" for automatic mime type detection. There should be nothing proceeding this group in the
|
|
desktop entry file but possibly one or more comments (see below).
|
|
|
|
Group headers may not contain the characters '[' and ']' as those delimit the header.
|
|
|
|
Lines beginning with a "#" and blank lines are considered comments and will be ignored, however they should be preserved across
|
|
reads / writes of the desktop entry file.
|
|
|
|
Compliant implementations MUST not remove any fields from the file, even if they don't support them. Such fields must be
|
|
maintained in a list somewhere, and if the file is "rewritten," they will be included. This ensures that any desktop-specific
|
|
extensions will be preserved even if another system accesses and changes the file.
|
|
|
|
Entries in the file are {key,value} pairs in the format:
|
|
|
|
Name=Value
|
|
|
|
Space before and after the equals sign should be ignored; the "=" sign is the actual delimiter.
|
|
|
|
The escape sequences \s, \n, \t, \r, and \\ are supported, meaning ASCII space, newline, tab, carriage return, and backslash,
|
|
respectively.
|
|
|
|
Possible value types
|
|
|
|
The value types recognized are string, localestring, regexp, boolean (encoded as the string true/false), and numeric.
|
|
|
|
The difference between string and localestring is that the value for a string key must contain only ASCII characters and while
|
|
the value of a localestring key may contain UTF-8 characters. (See section 5.)
|
|
|
|
Some keys can have multiple values; these should be separated by a semicolon. Those keys which have several values should have a
|
|
semicolon as the trailing character. For lists of strings, semicolons are simply not allowed in the strings, there is no escape
|
|
mechanism.
|
|
|
|
Recognized desktop entry keys
|
|
|
|
Keys with type localestring may be postfixed by [LOCALE], where LOCALE is the locale type of the entry. LOCALE must be of the
|
|
form lang[_COUNTRY][ ENCODING][ MODIFIER], where _COUNTRY, .ENCODING, and @MODIFIER may be omitted. If a postfixed key occurs,
|
|
the same key must be also present without the postfix.
|
|
|
|
When reading in the desktop entry file, the value of the key is selected by matching the current POSIX locale for the
|
|
LC_MESSAGES category against the locale postfixes of all occurrences of the key, with the .ENCODING part stripped. The .ENCODING
|
|
field is used only when the Encoding key for the desktop entry file is Legacy-Mixed, (see Appendix D.)
|
|
|
|
The matching of is done as follows. If LC_MESSAGES is of the form LANG_COUNTRY.ENCODING@MODIFIER, then it will match a key of
|
|
the form LANG_COUNTRY@MODIFIER. If such a key does not exist, it will attempt to match LANG_COUNTRY followed by LANG@MODIFIER.
|
|
Then, a match against LANG by itself will be attempted. Finally, if no matching key is found the required key without a locale
|
|
specified is used. The encoding from the LC_MESSAGES value is ignored when matching.
|
|
|
|
If LC_MESSAGES does not have a MODIFIER field, then no key with a modifier will be matched. Similarly, if LC_MESSAGES does not
|
|
have a COUNTRY field, then no key with a country specified will be matched. If LC_MESSAGES just has a LANG field, then it will
|
|
do a straight match to a key with a similar value. The following table lists possible matches of various LC_MESSAGES in the
|
|
order in which they are matched. Note that the ENCODING field isn't shown.
|
|
|
|
Table 1. Locale Matching
|
|
|
|
+-------------------------------------------------------------------------------------------------+
|
|
| LC_MESSAGES Value | Possible Keys in Order of Matching |
|
|
|-----------------------+-------------------------------------------------------------------------|
|
|
| LANG_COUNTRY@MODIFIER | LANG_COUNTRY@MODIFIER, LANG_COUNTRY, LANG@MODIFIER, LANG, Default Value |
|
|
|-----------------------+-------------------------------------------------------------------------|
|
|
| LANG_COUNTRY | LANG_COUNTRY, LANG, Default Value |
|
|
|-----------------------+-------------------------------------------------------------------------|
|
|
| LANG@MODIFIER | LANG@MODIFIER, LANG, Default Value |
|
|
|-----------------------+-------------------------------------------------------------------------|
|
|
| LANG | LANG, Default Value |
|
|
+-------------------------------------------------------------------------------------------------+
|
|
|
|
For example, if the current value of the LC_MESSAGES category is sr_YU Latn and the desktop file includes:
|
|
|
|
Name=Foo
|
|
Name[sr_YU]=...
|
|
Name[sr Latn]=
|
|
Name[sr]=...
|
|
|
|
then the value of the Name keyed by "sr_YU" is used.
|
|
|
|
Case is significant. The keys "Name" and "NAME" are not equivalent. The same holds for group names. Key values are case
|
|
sensitive as well.
|
|
|
|
Keys are either OPTIONAL or REQUIRED. If a key is optional it may or may not be present in the file. However, if it isn't, the
|
|
implementation of the standard should not blow up, it must provide some sane defaults. Additionally, keys either MUST or MAY be
|
|
supported by a particular implementation.
|
|
|
|
Some keys only make sense in the context when another particular key is also present.
|
|
|
|
Some example keys: Name[C], Comment[it].
|
|
|
|
Table 2. Standard Keys
|
|
|
|
+------------------------------------------------------------------------------------------------------------------------------+
|
|
| Key | Description | Value Type | REQ? | MUST? | Type |
|
|
|------------------------+----------------------------------------------------------------+--------------+------+-------+------|
|
|
| Type | There are 4 types of desktop entries: Application(1), Link(2), | string | YES | YES | |
|
|
| | FSDevice(3) and Directory(4). | | | | |
|
|
|------------------------+----------------------------------------------------------------+--------------+------+-------+------|
|
|
| | Version of Desktop Entry Specification (While the version | | | | |
|
|
| | field is not required to be present, it should be in all newer | | | | |
|
|
| Version | implementations of the Desktop Entry specification. If the | numeric | NO | YES | 1-4 |
|
|
| | version number is not present, a "pre-standard" desktop entry | | | | |
|
|
| | file is to be assumed). | | | | |
|
|
|------------------------+----------------------------------------------------------------+--------------+------+-------+------|
|
|
| Encoding | Encoding of the whole desktop entry file (UTF-8 or | string | YES | YES | 1-4 |
|
|
| | LegacyMixed). | | | | |
|
|
|------------------------+----------------------------------------------------------------+--------------+------+-------+------|
|
|
| Name | Specific name of the application, for example "Mozilla". | localestring | YES | YES | 1-4 |
|
|
|------------------------+----------------------------------------------------------------+--------------+------+-------+------|
|
|
| GenericName | Generic name of the application, for example "Web Browser". | localestring | NO | YES | 1-4 |
|
|
|------------------------+----------------------------------------------------------------+--------------+------+-------+------|
|
|
| | NoDisplay means "this application exists, but don't display it | | | | |
|
|
| | in the menus". This can be useful to e.g. associate this | | | | |
|
|
| NoDisplay | application with mimetypes, so that it gets launched from a | boolean | NO | NO | 1-4 |
|
|
| | file manager (or other apps), without having a menu entry for | | | | |
|
|
| | it (there are tons of good reasons for this, including e.g. | | | | |
|
|
| | the netscape -remote, or kfmclient openURL kind of stuff). | | | | |
|
|
|------------------------+----------------------------------------------------------------+--------------+------+-------+------|
|
|
| Comment | Tooltip for the entry, for example "View sites on the | localestring | NO | YES | 1-4 |
|
|
| | Internet"; should not be redundant with Name or GenericName. | | | | |
|
|
|------------------------+----------------------------------------------------------------+--------------+------+-------+------|
|
|
| | Icon to display in file manager, menus, etc. If the name is an | | | | |
|
|
| | absolute path, the given file will be used. If the name is not | | | | |
|
|
| Icon | an absolute path, an implementation-dependent search algorithm | string | NO | YES | 1-4 |
|
|
| | will be used to locate the icon. Icons may be localized with | | | | |
|
|
| | the Icon[xx]= syntax. | | | | |
|
|
|------------------------+----------------------------------------------------------------+--------------+------+-------+------|
|
|
| | Hidden should have been called Deleted. It means the user | | | | |
|
|
| | deleted (at his level) something that was present (at an upper | | | | |
|
|
| | level, e.g. in the system dirs). It's strictly equivalent to | | | | |
|
|
| Hidden | the .desktop file not existing at all, as far as that user is | boolean | NO | NO | 1-4 |
|
|
| | concerned. This can also be used to "uninstall" existing files | | | | |
|
|
| | (e.g. due to a renaming) - by letting "make install" install a | | | | |
|
|
| | file with Hidden=true in it. | | | | |
|
|
|------------------------+----------------------------------------------------------------+--------------+------+-------+------|
|
|
| | A list of regular expressions to match against for a file | | | | |
|
|
| FilePattern | manager to determine if this entry's icon should be displayed. | regexp(s) | NO | NO | 1 |
|
|
| | Usually simply the name of the main executable and friends. | | | | |
|
|
|------------------------+----------------------------------------------------------------+--------------+------+-------+------|
|
|
| | Filename of a binary on disk used to determine if the program | | | | |
|
|
| TryExec | is actually installed. If not, entry may not show in menus, | string | NO | NO | 1 |
|
|
| | etc. | | | | |
|
|
|------------------------+----------------------------------------------------------------+--------------+------+-------+------|
|
|
| Exec | Program to execute, possibly with arguments. | string | NO | YES | 1 |
|
|
|------------------------+----------------------------------------------------------------+--------------+------+-------+------|
|
|
| Path | If entry is type Application, the working directory to run the | string | NO | YES | 1 |
|
|
| | program in. | | | | |
|
|
|------------------------+----------------------------------------------------------------+--------------+------+-------+------|
|
|
| Terminal | Whether the program runs in a terminal window | boolean | NO | YES | 1 |
|
|
|------------------------+----------------------------------------------------------------+--------------+------+-------+------|
|
|
| SwallowTitle | If entry is swallowed onto the panel, this should be the title | localestring | NO | NO | 1 |
|
|
| | of window | | | | |
|
|
|------------------------+----------------------------------------------------------------+--------------+------+-------+------|
|
|
| SwallowExec | Program to exec if swallowed app is clicked. | string | NO | NO | 1 |
|
|
|------------------------+----------------------------------------------------------------+--------------+------+-------+------|
|
|
| Actions | Additional actions possible, see MIME type discussion in the | string(s) | NO | YES | 1 |
|
|
| | section called "Detailed discussion of supporting MIME types". | | | | |
|
|
|------------------------+----------------------------------------------------------------+--------------+------+-------+------|
|
|
| MimeType | The MIME type(s) supported by this entry. | regexp(s) | NO | NO | 1 |
|
|
|------------------------+----------------------------------------------------------------+--------------+------+-------+------|
|
|
| SortOrder | This may specify the order in which to display files. | string(s) | NO | NO | 4 |
|
|
|------------------------+----------------------------------------------------------------+--------------+------+-------+------|
|
|
| Dev | The device to mount. | string | NO | NO | 3 |
|
|
|------------------------+----------------------------------------------------------------+--------------+------+-------+------|
|
|
| FSType | The type of filesystem to try to mount. | string | NO | NO | 3 |
|
|
|------------------------+----------------------------------------------------------------+--------------+------+-------+------|
|
|
| MountPoint | The mount point of the device in question. | string | NO | NO | 3 |
|
|
|------------------------+----------------------------------------------------------------+--------------+------+-------+------|
|
|
| ReadOnly | Specifies whether or not the device is read-only. | boolean | NO | NO | 3 |
|
|
|------------------------+----------------------------------------------------------------+--------------+------+-------+------|
|
|
| | Icon to display when device is not mounted Mounted devices | | | | |
|
|
| UnmountIcon | display icon from Icon key. UnmountIcons may be localized with | string | NO | NO | 3 |
|
|
| | the UnmountIcon[xx]= syntax. | | | | |
|
|
|------------------------+----------------------------------------------------------------+--------------+------+-------+------|
|
|
| URL | If entry is Link type, the URL to access. | string | NO | YES | 2 |
|
|
|------------------------+----------------------------------------------------------------+--------------+------+-------+------|
|
|
| Categories | Categories in which the entry should be shown in a menu (for | string(s) | NO | NO | 1 |
|
|
| | possible values see the xdg-menu specification). | | | | |
|
|
|------------------------+----------------------------------------------------------------+--------------+------+-------+------|
|
|
| | A list of strings identifying the environments that should | | | | |
|
|
| OnlyShowIn / NotShowIn | display/not display a given .desktop item. Only one of these | string(s) | NO | NO | 1-4 |
|
|
| | keys, either OnlyShowIn or NotShowIn, may appear in a Group. | | | | |
|
|
| | (for possible values see the xdg-menu specification) | | | | |
|
|
|------------------------+----------------------------------------------------------------+--------------+------+-------+------|
|
|
| | If true, it is KNOWN that the application will send a "remove" | | | | |
|
|
| StartupNotify | message when started with the DESKTOP_LAUNCH_ID environment | boolean | NO | NO | 1 |
|
|
| | variable set (see the startup notification spec for more | | | | |
|
|
| | details). | | | | |
|
|
|------------------------+----------------------------------------------------------------+--------------+------+-------+------|
|
|
| | If true, it is KNOWN that the application will map at least | | | | |
|
|
| StartupWMClass | one window with the given string as its WM class or WM name | string | NO | NO | 1 |
|
|
| | hint (see the startup notification spec for more details). | | | | |
|
|
+------------------------------------------------------------------------------------------------------------------------------+
|
|
|
|
Character set encoding of the file
|
|
|
|
Desktop entry files are encoded as lines of 8-bit characters separated by LF characters.
|
|
|
|
o Key names must contain only the characters 'A-Za-z0-9-'
|
|
|
|
o Group names may contain all ASCII characters except for control characters and '[' and ']'.
|
|
|
|
o Values of type string may contain all ASCII characters except for control characters.
|
|
|
|
o Values of type boolean must either be the string 'true' or 'false'.
|
|
|
|
o Numeric values must be a valid floating point number as recognized by the %f specifier for scanf.
|
|
|
|
Comment lines are uninterpreted and may contain any character (except for LF). However, using UTF-8 for comment lines that
|
|
contain characters not in ASCII is encouraged.
|
|
|
|
The encoding for values of type localestring is determined by the Encoding field.
|
|
|
|
List of valid Exec parameter variables
|
|
|
|
Each "Exec" field may take a number of arguments which will be expanded by the file manager or program launcher and passed to
|
|
the program if necessary.
|
|
|
|
Literal % characters must be escaped as %%, and adding new format characters is not allowed. It's a fatal error to have an Exec
|
|
field with a format character not given in the spec (exception to this are the deprecated format characters which can be
|
|
ignored, that is expanded to no parameters, by the implementation). Again for emphasis: nonstandard extensions are not allowed
|
|
here - you must add an X-Foo-Exec field if you have nonstandard Exec lines.
|
|
|
|
The escaping of the exec parameters is done in the way the mailcap specification describes. Take a look at RFC 1524 for more
|
|
information.
|
|
|
|
Recognized fields are as follows:
|
|
|
|
+------------------------------------------------------------------------------------------------------------------------------+
|
|
| | a single file name, even if multiple files are selected. The system reading the Desktop Entry should recognize that the |
|
|
| | program in question cannot handle multiple file arguments, and it should should probably spawn and execute multiple |
|
|
| %f | copies of a program for each selected file if the program is not able to handle additional file arguments. If files are |
|
|
| | not on the local file system (i.e. HTTP or FTP locations), the files will be copied to the local file system and %f |
|
|
| | will be expanded to point at the temporary file. Used for programs that do not understand URL syntax. |
|
|
|----+-------------------------------------------------------------------------------------------------------------------------|
|
|
| %F | a list of files. Use for apps that can open several local files at once. |
|
|
|----+-------------------------------------------------------------------------------------------------------------------------|
|
|
| %u | a single URL. |
|
|
|----+-------------------------------------------------------------------------------------------------------------------------|
|
|
| %U | a list of URLs. |
|
|
|----+-------------------------------------------------------------------------------------------------------------------------|
|
|
| %d | directory containing the file that would be passed in a %f field |
|
|
|----+-------------------------------------------------------------------------------------------------------------------------|
|
|
| %D | list of directories containing the files that would be passed in to a %F field |
|
|
|----+-------------------------------------------------------------------------------------------------------------------------|
|
|
| %n | a single filename (without path) |
|
|
|----+-------------------------------------------------------------------------------------------------------------------------|
|
|
| %N | a list of filenames (without path) |
|
|
|----+-------------------------------------------------------------------------------------------------------------------------|
|
|
| %i | the Icon field of the desktop entry expanded as two parameters, first "--icon" and then the contents of the Icon field |
|
|
| | (should not expand as any prameters if the Icon field is empty or missing) |
|
|
|----+-------------------------------------------------------------------------------------------------------------------------|
|
|
| %c | the translated Name field associated with the desktop entry |
|
|
|----+-------------------------------------------------------------------------------------------------------------------------|
|
|
| %k | the location of the desktop file as either a uri (if for example gotten from the vfolder system) or a local filename or |
|
|
| | empty if no location is known |
|
|
|----+-------------------------------------------------------------------------------------------------------------------------|
|
|
| %v | the name of the Device entry in the desktop file |
|
|
+------------------------------------------------------------------------------------------------------------------------------+
|
|
|
|
Detailed discussion of supporting MIME types
|
|
|
|
It is in every desktop's best interest to have thorough support for mime types. The old /etc/mailcap and /etc/mime.types files
|
|
are rather limited in scope and frankly, are outdated. Various desktop systems have come up with different ways of extending
|
|
this original system, but none are compatible with each other. The Desktop Entry Standard hopes to be able to provide the
|
|
beginnings of a solution to this problem.
|
|
|
|
At a very basic level, the "Exec" key provides the default action to take when the program described by a desktop entry is used
|
|
to open a document or data file. Usually this consists of some action along the lines of "kedit %f" or "ee %f". This is a good
|
|
start, but it isn't as flexible as it can be.
|
|
|
|
Let us first establish that a program which supports a MIME type or multiple mime types may be able to support multiple actions
|
|
on those MIME types as well. The desktop entry may want to define additional actions in addition to the default. The toplevel
|
|
"Exec" key describes the default action; Let us define this action to also be known as the "Open" action. Additional actions
|
|
which might be possible include View, Edit, Play, etc. A further revision of this document will probably specify several
|
|
"standard" actions in addition to the default "Open" action, but in all cases, the number of actions is arbitrary.
|
|
|
|
Let us use a sound player as a simple example. Call it sp. The default Exec (Open) action for this program would likely look
|
|
something like:
|
|
|
|
Exec=sp %u
|
|
|
|
However, imagine the sound player also supports editing of sound files in a graphical manner. We might wish to define an
|
|
additional action which could accomodate this. Adding the action would be performed like this:
|
|
|
|
Actions=Edit;
|
|
|
|
[Desktop Action Edit]
|
|
Exec=sp -edit %u
|
|
|
|
As you can see, defining the action "edit" will enable an additional group of the name [Desktop Action actionname] to be read.
|
|
This group can contain an additional Exec line, as well as possibly other information like a new Name, Comment, Icon, and Path.
|
|
Thus right-clicking on a .wav file will show both the default "Open" action and this "Edit" action to both be displayed as
|
|
choices in the context-menu. A left click (double or single, whichever the file manager implements) would cause the default
|
|
action to take place. These are implementation-specific details which are up to the implementer, and are not enforced by this
|
|
standard.
|
|
|
|
If no DefaultApp is specified for a particular MIME type, any one of the programs registered which claim to be able to handle
|
|
the MIME type may become the default handler. This behaviour is undefined and implementation-specific. KDE doesn't use a
|
|
DefaultApp anymore, but assigns a Preference number to each program, so that the highest number is the one chosen for handling
|
|
the MIME type.
|
|
|
|
Extending the format
|
|
|
|
If the standard is to be amended with a new {key,value} pair which should be applicable to all supporting parties, a group
|
|
discussion will take place. This is the preferred method for introducing changes. If one particular party wishes to add a field
|
|
for personal use, they should prefix the key with the string "X-PRODUCT", i.e. "X-NewDesktop-Foo", following the precedent set
|
|
by other IETF and RFC standards.
|
|
|
|
Alternatively, fields can be placed in their own group, where they may then have arbitrary key names. If this is the case, the
|
|
group should follow the scheme outlined above, i.e. [X-PRODUCT GROUPNAME] or something similar. These steps will avoid namespace
|
|
clashes between different yet similar environments.
|
|
|
|
----------------------------------------------------------------------------------------------------------------------------
|