summaryrefslogtreecommitdiffstats
path: root/desktop-entry/desktop-entry-spec.xml
diff options
context:
space:
mode:
Diffstat (limited to 'desktop-entry/desktop-entry-spec.xml')
-rw-r--r--desktop-entry/desktop-entry-spec.xml130
1 files changed, 127 insertions, 3 deletions
diff --git a/desktop-entry/desktop-entry-spec.xml b/desktop-entry/desktop-entry-spec.xml
index 01638e6..bb32e10 100644
--- a/desktop-entry/desktop-entry-spec.xml
+++ b/desktop-entry/desktop-entry-spec.xml
@@ -508,6 +508,18 @@
<entry>1</entry>
</row>
<row>
+ <entry id="key-actions"><varname>Actions</varname></entry>
+ <entry>
+ Identifiers for application actions. This can be used to tell the
+ application to make a specific action, different from the default
+ behavior. The <link linkend="extra-actions">Application actions</link>
+ section describes how actions work.
+ </entry>
+ <entry>string(s)</entry>
+ <entry>NO</entry>
+ <entry>1</entry>
+ </row>
+ <row>
<entry id="key-mimetype"><varname>MimeType</varname></entry>
<entry>
The MIME type(s) supported by this application.
@@ -860,6 +872,110 @@ application/x-bar=bar.desktop;</programlisting>
</sect2>
-->
</sect1>
+ <sect1 id="extra-actions">
+ <title>Additional applications actions</title>
+ <para>
+ Desktop entries of type Application can include one or more actions. An
+ action represents an additional way to invoke the application.
+ Application launchers should expose them to the user (for example, as a
+ 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>
+ </sect1>
<sect1 id="extending">
<title>Extending the format</title>
<para>
@@ -893,9 +1009,17 @@ TryExec=fooview
Exec=fooview %F
Icon=fooview
MimeType=image/x-foo;
-X-KDE-Library=libfooview
-X-KDE-FactoryName=fooviewfactory
-X-KDE-ServiceType=FooService</programlisting>
+Actions=Gallery;Create;
+
+[Desktop Action Gallery]
+Exec=fooview --gallery
+Name=Browse Gallery
+
+[Desktop Action Create]
+Exec=fooview --create-new
+Name=Create a new Foo!
+Icon=fooview-new
+ </programlisting>
</appendix>
<appendix id="kde-items">
<title>Currently reserved for use within KDE</title>