Updated patch. More comments inline... Il giorno lun, 19/12/2011 alle 16.54 +0100, Vincent Untz ha scritto: > Hi, > > Le dimanche 18 décembre 2011, à 22:57 +0100, Giovanni Campagna a écrit : >[...] > > 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.
Included. > [...] > > > </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". Included > > + </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. Included. > > + </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. Ok, changed to use same rules as keys, and merged with previous paragraph. > > + 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. I see, removed (though I liked the idea to remove the standard "New window" item we place in gnome-shell when the application had a new-window action). > > + </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. Fine, included. > > + </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." I hope I clarified what should and should not be in the action name (and corrected the example). > > + </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. Ok, included. > > + 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) Fine, removed. > > + </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? Now it's mostly the same, hope it's clear enough. > > + </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). That was the idea, except that saying "OnlyShowIn=GNOME" for the app and "OnlyShowIn=KDE" for the action would hide the action. This seems probably obvious, but you never know. In any case, I reworded this description. > > + </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. Included, but I kept the advice for applications, just in case. > > + </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. Ok. > > + </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. Ok. > > + </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). I went with Gallery and Create. Hope they'll be better. Also, I removed the X-KDE stuff. Giovanni
From b7789b7bc1c8964a9b57710e9cd8a13c66bfdaee Mon Sep 17 00:00:00 2001 From: Giovanni Campagna <[email protected]> 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, 127 insertions(+), 3 deletions(-) diff --git a/desktop-entry/desktop-entry-spec.xml b/desktop-entry/desktop-entry-spec.xml index 01638e6..df8038f 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> -- 1.7.7.4
signature.asc
Description: This is a digitally signed message part
_______________________________________________ xdg mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/xdg
