Extending the Desktop Entry spec for static app actions
Vincent Untz
vuntz at gnome.org
Mon Dec 19 07:54:47 PST 2011
Hi,
Le dimanche 18 décembre 2011, à 22:57 +0100, Giovanni Campagna a écrit :
> 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.
That's a good start. I have some comments below, mostly about wording.
> If this is approved, I'll prepare a patch for desktop-file-utils.
That'd be most welcome!
[...]
> From 30a7f830e67acde3114e4450d15cc642c35cd782 Mon Sep 17 00:00:00 2001
> From: Giovanni Campagna <gcampagna at 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"/>.
I suggest this:
Identifiers for application actions. This can be used to tell the
application to make a specific action, different from the default
behavior. The <xref linkend="extra-actions">Application actions</>
section describes how actions work.
[...]
> </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".
I suggest this:
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>
> + 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.
I suggest this:
Each action 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.
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>
> + Identifiers must be composed only of lowercase alphabetic characters
> + from the ASCII set, plus underscore and minus. Some implementations may
Hrm, why not use A-Za-z0-9- like for key names? Also the example
(fooview) use some uppercase characters.
Also, this paragraph should come before the one about action groups.
> + 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.
Hrm, we should either not mention this at all or reserve some action
identifier (like new-window). Else, this is a bit confusing.
> + </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.
I suggest this:
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.
There's no need to talk about extensibility here, there's a whole
paragraph later.
> + </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.
I don't think we need to mention Comment/GenericName here. But saying
something like "Action names for an application should not be ambiguous
between each other."
> + </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
I suggest this:
Program to execute for this action, possibly with arguments. See <xref
linkend="XXX">the Exec key</xref> for details on how this key works.
> + 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.
I don't think we need to write this in the spec. (And I'm not sure it'd
be okay to change from requires to optional, but that's another topic to
discuss once different mechanism are added)
> + </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.
Maybe rewrite to be a bit closer to the [Desktop Entry]/Icon
description?
> + </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.
Hrm, why would a general OnlyShowIn/NotShowIn take precedence over
these? It feels more natural to me that both should be respected. For
instance:
[Desktop Entry]
NotShowIn=KDE;
Actions=foo;
[Desktop Action foo]
OnlyShowIn=GNOME;
This allows me to hide the app in KDE, and only show the action in GNOME
(and not in Unity, or XFCE).
> + </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.
This should be mentioned earlier, and I'd rewrite this way:
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.
> + </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.
I'd move this in the first paragraph of this section, and replace should
with must.
> + </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.
Keep this out of the spec :-) It's good to know, but I don't think we
need to write this here.
> + </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>
Please remove the extension from Icon ;-)
Also, I'd choose two actions that would make sense even if no file is
passed as argument (fooview --inverse sounds completely useless without
a file).
Cheers,
Vincent
--
Les gens heureux ne sont pas pressés.
More information about the xdg
mailing list