From 72019d5685c1126c5f967aa5c05549131aa6a09f Mon Sep 17 00:00:00 2001 From: Vincent Untz Date: Tue, 24 Jan 2012 17:15:02 +0100 Subject: desktop-entry: Improvements to specification of actions Structure and reorganize the text with subsections, and reword for clarifications. Also make the Icon key a localestring, like it is for Desktop Entry. Add a link to the Exec key section in the description of [Desktop Entry]/Exec. --- desktop-entry/desktop-entry-spec.xml | 207 +++++++++++++++++++---------------- 1 file changed, 112 insertions(+), 95 deletions(-) diff --git a/desktop-entry/desktop-entry-spec.xml b/desktop-entry/desktop-entry-spec.xml index bb32e10..7d99d0a 100644 --- a/desktop-entry/desktop-entry-spec.xml +++ b/desktop-entry/desktop-entry-spec.xml @@ -483,7 +483,9 @@ Exec - Program to execute, possibly with arguments. + Program to execute, possibly with arguments. See the Exec key for + details on how this key works. string YES @@ -881,100 +883,115 @@ application/x-bar=bar.desktop; submenu) within the context of the application. This is used to build so called "Quicklists" or "Jumplists". - - Application actions should be supported by implementors. However, in - case they are not supported, implementors can simply ignore the - Actions key and the associated Desktop - Action action groups, and keep using the Desktop - Entry group. Therefore, the primary way to invoke the application - should be through the main Exec line, as well as the primary Name and Icon. - - - 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. - - - Each action action is identified by a string, following the same rules - as key names (see ). Each identifier is associated - with an action group that must be present in the .desktop - file. The action group is a group named Desktop Action %s, - where %s is the action identifier. - - - It is not valid to have an action group for an action identifier not - mentioned in the Actions key. Such an action group - must be ignored by implementors. - - - 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. - - - Action group keys - - - - Key - Description - Value Type - REQ? - - - - - Name - - 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. - - localestring - YES - - - Exec - - Program to execute for this action, possibly with arguments. See the Exec key for details on how this key works. - - string - YES - - - Icon - - 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 Icon - Theme Specification 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. - - string - NO - - - - OnlyShowIn, NotShowIn - - - A list of strings to be interpreted according to the Desktop - Menu Specification, 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. - - string(s) - NO - - - -
+ + Action identifier + + Each action is identified by a string, following the same format + as key names (see ). Each identifier is associated + with an action group that must be present in the .desktop + file. The action group is a group named Desktop Action %s, + where %s is the action identifier. + + + It is not valid to have an action group for an action identifier not + mentioned in the Actions key. Such an action group + must be ignored by implementors. + + + + Action keys + + 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. + + + Action Specific Keys + + + + Key + Description + Value Type + REQ? + + + + + Name + + Label that will be shown to the user. Since actions are + 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 application and should not include the application name. + + localestring + YES + + + Icon + + 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 Icon + Theme Specification will be used to locate the icon. + Implementations may choose to ignore it. + + localestring + NO + + + + OnlyShowIn, NotShowIn + + + A list of strings identifying the environments that should + display/not display this specific action. These keys are to be + interpreted in addition to the OnlyShowIn + and NotShowIn keys of the Desktop + Entry group, and are not replacing them. Only one of + these keys, either OnlyShowIn or + NotShowIn, may appear in each action group + (for possible values see the Desktop + Menu Specification). + + string(s) + NO + + + Exec + + Program to execute for this action, possibly with arguments. + See the Exec + key for details on how this key works. + + string + YES + + + +
+ + + Implementation notes + + Application actions should be supported by implementors. However, in + case they are not supported, implementors can simply ignore the + Actions key and the associated Desktop + Action action groups, and keep using the Desktop + Entry group: the primary way to describe and invoke the + application is through the Name, Icon and Exec keys from the + Desktop Entry group. + + + It is not expected that other desktop components showing application + lists (software installers, for instance) will provide any user + interface for these actions. Therefore applications must only include + actions that make sense as general launchers. + + Extending the format -- cgit v1.2.3-54-g00ecf