It seems that we reached a consensus on this feature, and comments have cooled down, so here's the actual patch against current git of xdg-specs. If this is approved, I'll prepare a patch for desktop-file-utils.
Thanks, Giovanni
From 30a7f830e67acde3114e4450d15cc642c35cd782 Mon Sep 17 00:00:00 2001
From: Giovanni Campagna <gcampa...@src.gnome.org>
Date: Sun, 18 Dec 2011 22:08:28 +0100
Subject: [PATCH] desktop-entry-spec: 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.
---
desktop-entry/desktop-entry-spec.xml | 130 +++++++++++++++++++++++++++++++++-
1 files changed, 129 insertions(+), 1 deletions(-)
diff --git a/desktop-entry/desktop-entry-spec.xml b/desktop-entry/desktop-entry-spec.xml
index 34bc154..34e96c2 100644
--- a/desktop-entry/desktop-entry-spec.xml
+++ b/desktop-entry/desktop-entry-spec.xml
@@ -508,6 +508,15 @@
<entry>1</entry>
</row>
<row>
+ <entry id="key-actions"><varname>Actions</varname></entry>
+ <entry>
+ Additional actions possible, see the discussion in <xref linkend="extra-actions"/>.
+ </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.
@@ -847,6 +856,115 @@ application/x-bar=bar.desktop;</programlisting>
</sect2>
-->
</sect1>
+ <sect1 id="extra-actions">
+ <title>Additional applications actions</title>
+ <para>
+ Desktop entries of type Application can optionally include one or more
+ actions. This represent additional ways to invoke the particular
+ application; it is expected that application launchers will expose them
+ in some way (for example, as a submenu) within the context of the application,
+ to build so called "Quicklists" or "Jumplists".
+ </para>
+ <para>
+ Each action must be accompained with an "action group", that is a group
+ called <varname>[Desktop Action %s]</varname>, where %s is replaced by an
+ action ID (as specified by the Actions key). Action groups not included in
+ the Actions key must be ignored by the implementation.
+ </para>
+ <para>
+ Identifiers must be composed only of lowercase alphabetic characters
+ from the ASCII set, plus underscore and minus. Some implementations may
+ give special meanings to some identifiers (for example, replacing a
+ default new window action with a shortcut idenfied by new-window),
+ though this is not required.
+ </para>
+ <para>
+ The following keys are supported within each action group. The absence of
+ a REQUIRED key within a group makes the group invalid but does not affect
+ the validity of the overall desktop entry. Other than that, the usual
+ rules on extensibility apply.
+ </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. There is no provision
+ for Comment or GenericName, as it is expected that this is always shown
+ in the context of a specific application (that is, as a submenu of a
+ launcher) and therefore only need to be unambiguous within one app.
+ </entry>
+ <entry>localestring</entry>
+ <entry>YES</entry>
+ </row>
+ <row>
+ <entry id="key-action-group-exec"><varname>Exec</varname></entry>
+ <entry>
+ A string to be interpreted as [Desktop Entry]/Exec, including macro
+ expansion and PATH resolution. This is only way to activate the
+ action as of current version of the specification and therefore
+ it's required; future version may account for different mechanisms
+ (like activation by a DBus call) and make this optional.
+ </entry>
+ <entry>string</entry>
+ <entry>YES</entry>
+ </row>
+ <row>
+ <entry id="key-action-group-icon"><varname>Icon</varname></entry>
+ <entry>
+ 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. OnlyShowIn/NotShowIn for the whole entry
+ take precedence over these.
+ </entry>
+ <entry>string(s)</entry>
+ <entry>NO</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>
+ It is still perfectly legal for any consumer of this specification to
+ ignore secondary actions, so 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 should only include actions that make sense as general launchers.
+ </para>
+ <para>
+ Additionally, the current version of the specification does not include
+ any provision to check that the application is actually running when
+ these additional actions are invoked or shown, or to associate these
+ actions with a mime type, different or the same as the primary MimeType
+ associated with the application. A future version may be extended to
+ handled these cases too.
+ </para>
+ </sect1>
<sect1 id="extending">
<title>Extending the format</title>
<para>
@@ -880,9 +998,19 @@ TryExec=fooview
Exec=fooview %F
Icon=fooview
MimeType=image/x-foo;
+Actions=Inverse;Edit;
X-KDE-Library=libfooview
X-KDE-FactoryName=fooviewfactory
-X-KDE-ServiceType=FooService</programlisting>
+X-KDE-ServiceType=FooService
+
+[Desktop Action Inverse]
+Exec=fooview --inverse %f
+Name=Foo Viewer (inverse image)
+
+[Desktop Action Edit]
+Exec=fooview --edit %f
+Name=Foo Viewer (edit image)
+Icon=fooview-edit.png</programlisting>
</appendix>
<appendix id="kde-items">
<title>Currently reserved for use within KDE</title>
--
1.7.7.4
signature.asc
Description: This is a digitally signed message part
_______________________________________________ xdg mailing list xdg@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/xdg
