summaryrefslogtreecommitdiffstats
path: root/desktop-entry
diff options
context:
space:
mode:
authorVincent Untz <vuntz@gnome.org>2012-01-24 17:15:02 +0100
committerVincent Untz <vuntz@gnome.org>2012-01-24 17:17:42 +0100
commit72019d5685c1126c5f967aa5c05549131aa6a09f (patch)
treee295c7766f6796f9abe36ac35a05945de1247c85 /desktop-entry
parentb5ea0b0fb9eb57f2878007d2899682dacbc816d6 (diff)
downloadxdg-specs-72019d5685c1126c5f967aa5c05549131aa6a09f.tar.xz
desktop-entry: Improvements to specification of actions
Structure and reorganize the text with subsections, and reword for clarifications. Also make the Icon key a localestring, like it is for Desktop Entry. Add a link to the Exec key section in the description of [Desktop Entry]/Exec.
Diffstat (limited to 'desktop-entry')
-rw-r--r--desktop-entry/desktop-entry-spec.xml207
1 files changed, 112 insertions, 95 deletions
diff --git a/desktop-entry/desktop-entry-spec.xml b/desktop-entry/desktop-entry-spec.xml
index bb32e10..7d99d0a 100644
--- a/desktop-entry/desktop-entry-spec.xml
+++ b/desktop-entry/desktop-entry-spec.xml
@@ -483,7 +483,9 @@
<row>
<entry id="key-exec"><varname>Exec</varname></entry>
<entry>
- Program to execute, possibly with arguments.
+ Program to execute, possibly with arguments. See the <link
+ linkend="exec-variables"><varname>Exec</varname> key</link> for
+ details on how this key works.
</entry>
<entry>string</entry>
<entry>YES</entry>
@@ -881,100 +883,115 @@ application/x-bar=bar.desktop;</programlisting>
submenu) within the context of the application. This is used to build
so called "Quicklists" or "Jumplists".
</para>
- <para>
- Application actions should be supported by implementors. However, in
- case they are not supported, implementors can simply ignore the
- <varname>Actions</varname> key and the associated <varname>Desktop
- Action</varname> action groups, and keep using the <varname>Desktop
- Entry</varname> group. Therefore, the primary way to invoke the application
- should be through the main Exec line, as well as the primary Name and Icon.
- </para>
- <para>
- Also, it is not expected that other desktop components showing app lists
- (eg. software installers) will provide any UI for these actions, therefore
- applications must only include actions that make sense as general launchers.
- </para>
- <para>
- Each action action is identified by a string, following the same rules
- as key names (see <xref linkend="entries"/>). Each identifier is associated
- with an action group that must be present in the <filename>.desktop</filename>
- file. The action group is a group named <varname>Desktop Action %s</varname>,
- where <varname>%s</varname> is the action identifier.
- </para>
- <para>
- It is not valid to have an action group for an action identifier not
- mentioned in the <varname>Actions</varname> key. Such an action group
- must be ignored by implementors.
- </para>
- <para>
- The following keys are supported within each action group. If a
- REQUIRED key is not present in an action group, then the implementor
- should ignore this action.
- </para>
- <table>
- <title>Action group keys</title>
- <tgroup cols="5">
- <thead>
- <row>
- <entry>Key</entry>
- <entry>Description</entry>
- <entry>Value Type</entry>
- <entry>REQ?</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry id="key-action-group-name"><varname>Name</varname></entry>
- <entry>
- The label that will be shown to the user. Since actions will be
- always shown in the context of a specific application (that is, as
- a submenu of a launcher), this only needs to be unambiguous within
- one app and should not include the application name.
- </entry>
- <entry>localestring</entry>
- <entry>YES</entry>
- </row>
- <row>
- <entry id="key-action-group-exec"><varname>Exec</varname></entry>
- <entry>
- Program to execute for this action, possibly with arguments. See <link
- linkend="XXX">the Exec key</link> for details on how this key works.
- </entry>
- <entry>string</entry>
- <entry>YES</entry>
- </row>
- <row>
- <entry id="key-action-group-icon"><varname>Icon</varname></entry>
- <entry>
- The icon to be shown togheter with the action. If the name is
- an absolute path, the given file will be used. If the name is not
- an absolute path, the algorithm described in the <ulink
- url="http://freedesktop.org/wiki/Standards/icon-theme-spec">Icon
- Theme Specification</ulink> will be used to locate the icon.
- A string to be interpreted as [Desktop Entry]/Icon, that is,
- according to the icon theme. Implementations may choose to ignore it.
- </entry>
- <entry>string</entry>
- <entry>NO</entry>
- </row>
- <row>
- <entry id="key-action-group-osi-nsi">
- <varname>OnlyShowIn</varname>, <varname>NotShowIn</varname>
- </entry>
- <entry>
- A list of strings to be interpreted according to the <ulink
- url="http://www.freedesktop.org/Standards/menu-spec">Desktop
- Menu Specification</ulink>, but affect only the visibility of
- the specific action. These are to be interpreted in addition to,
- and not to replace, the keys in the main group with the same
- name.
- </entry>
- <entry>string(s)</entry>
- <entry>NO</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
+ <sect2 id="extra-actions-identifier">
+ <title>Action identifier</title>
+ <para>
+ Each action is identified by a string, following the same format
+ as key names (see <xref linkend="entries"/>). Each identifier is associated
+ with an action group that must be present in the <filename>.desktop</filename>
+ file. The action group is a group named <varname>Desktop Action %s</varname>,
+ where <varname>%s</varname> is the action identifier.
+ </para>
+ <para>
+ It is not valid to have an action group for an action identifier not
+ mentioned in the <varname>Actions</varname> key. Such an action group
+ must be ignored by implementors.
+ </para>
+ </sect2>
+ <sect2 id="extra-actions-keys">
+ <title>Action keys</title>
+ <para>
+ The following keys are supported within each action group. If a
+ REQUIRED key is not present in an action group, then the implementor
+ should ignore this action.
+ </para>
+ <table>
+ <title>Action Specific Keys</title>
+ <tgroup cols="5">
+ <thead>
+ <row>
+ <entry>Key</entry>
+ <entry>Description</entry>
+ <entry>Value Type</entry>
+ <entry>REQ?</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry id="key-action-group-name"><varname>Name</varname></entry>
+ <entry>
+ Label that will be shown to the user. Since actions are
+ always shown in the context of a specific application (that is, as
+ a submenu of a launcher), this only needs to be unambiguous within
+ one application and should not include the application name.
+ </entry>
+ <entry>localestring</entry>
+ <entry>YES</entry>
+ </row>
+ <row>
+ <entry id="key-action-group-icon"><varname>Icon</varname></entry>
+ <entry>
+ Icon to be shown togheter with the action. If the name is
+ an absolute path, the given file will be used. If the name is not
+ an absolute path, the algorithm described in the <ulink
+ url="http://freedesktop.org/wiki/Standards/icon-theme-spec">Icon
+ Theme Specification</ulink> will be used to locate the icon.
+ Implementations may choose to ignore it.
+ </entry>
+ <entry>localestring</entry>
+ <entry>NO</entry>
+ </row>
+ <row>
+ <entry id="key-action-group-osi-nsi">
+ <varname>OnlyShowIn</varname>, <varname>NotShowIn</varname>
+ </entry>
+ <entry>
+ A list of strings identifying the environments that should
+ display/not display this specific action. These keys are to be
+ interpreted in addition to the <varname>OnlyShowIn</varname>
+ and <varname>NotShowIn</varname> keys of the <varname>Desktop
+ Entry</varname> group, and are not replacing them. Only one of
+ these keys, either <varname>OnlyShowIn</varname> or
+ <varname>NotShowIn</varname>, may appear in each action group
+ (for possible values see the <ulink
+ url="http://www.freedesktop.org/Standards/menu-spec">Desktop
+ Menu Specification</ulink>).
+ </entry>
+ <entry>string(s)</entry>
+ <entry>NO</entry>
+ </row>
+ <row>
+ <entry id="key-action-group-exec"><varname>Exec</varname></entry>
+ <entry>
+ Program to execute for this action, possibly with arguments.
+ See the <link linkend="exec-variables"><varname>Exec</varname>
+ key</link> for details on how this key works.
+ </entry>
+ <entry>string</entry>
+ <entry>YES</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </sect2>
+ <sect2 id="extra-actions-implementation-notes">
+ <title>Implementation notes</title>
+ <para>
+ Application actions should be supported by implementors. However, in
+ case they are not supported, implementors can simply ignore the
+ <varname>Actions</varname> key and the associated <varname>Desktop
+ Action</varname> action groups, and keep using the <varname>Desktop
+ Entry</varname> group: the primary way to describe and invoke the
+ application is through the Name, Icon and Exec keys from the
+ <varname>Desktop Entry</varname> group.
+ </para>
+ <para>
+ It is not expected that other desktop components showing application
+ lists (software installers, for instance) will provide any user
+ interface for these actions. Therefore applications must only include
+ actions that make sense as general launchers.
+ </para>
+ </sect2>
</sect1>
<sect1 id="extending">
<title>Extending the format</title>