desktop-entry: Restore support for Desktop Actions

Reintroduce the Actions key, which was removed around version 1.1,
and give it a formal specification, detailing what actions applications
are expected to provide and who should make use of this information.
Names were taken from the original specification, since apparently
they have been in use during all this time.

Also remove X-KDE-* keys from the example, as it's unrelated to the
spec.

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>