We are pleased to announce the latest development release of Nautilus-Actions. It is the third development release which will lead to the upcoming 2.30.

What is new in this release ?

This is mainly a bugfix release:

• Let the user define new action and menu, even when starting from an empty list (reported by Miler).
• Use correct printf format (reported by Miler);
  use -Wformat=2 gcc option to prevent future same bugs.

Other enhancements are:

• Display the writability status in the status bar; the image itself comes with a dynamic tooltip which describes the origin of the status.
• Homogeneize syslog initialization messages.
• Let the I/O provider set specific data into NAObjectItem.

Please note, that for now, the new Desktop I/O provider is only available in maintainer mode, as it is far to being ready for a production use.

Version 2.29.3
==============

        Release date 2010-01-05

        Enhancements:

                - Display the writability status in the status bar; the image
                  itself comes with a dynamic tooltip which describes the origin
                  of the status.
                - Homogeneize syslog initialization messages.
                - Let the I/O provider set specific data into NAObjectItem.
                - Make the toolbars detacheable.

        Bug fixes:

                - Fix write/delete operations in NAIIODesktopProvider.
                - No more display the Export icon in the toolbar (no icon).

We are pleased to announce the last development release of Nautilus-Actions. It is the second development release which will lead to the upcoming 2.30.

What is new in this release ?

Lot of bugfixes and major enhancements :

• An API is defined, which let us have more than one I/O provider; this prepare in particular the arrival of a desktop I/O provider.
• GConf I/O provider is now a dynamically loaded plugin.
• Gracefully manage the read-only items, whether the action has been made mandatory by a sysadmin, or the I/O provider being itself not writable at all, or locked by a sysadmin.
• Ability to assign a keyboard accelerator to a predefined action via the nautilus-actions-run new program. nautilus-actions-run will automagically take into account the current Nautilus selection and apply it to your action (#435820 reported by Frederic Ruaudel).
• Let a sysadmin lock down its configuration by setting a mandatory GConf key "/apps/nautilus-actions/mandatory/na-gcond/locked" to true (#325520 reported by Frederic Ruaudel).

Nautilus-Actions has now a plugin architecture, to read and write menus and actions.

Version 2.29.2
==============

	Release date 2009-12-16

	This version brings up several major enhancements:

		- An API is defined, which let us have more than one I/O provider;
		  this prepare in particular the arrival of a desktop I/O provider.

		- GConf I/O provider is now a dynamically loaded plugin.

		- Gracefully manage the read-only items, whether the action has
		  been made mandatory by a sysadmin, or the I/O provider
		  being itself not writable at all.

		- Ability to assign a keyboard accelerator to a predefined action
		  via the nautilus-actions-run new program.

Introduction

This specification aims to define a common format for user actions, allowing creators to share their actions between common environments.

The .desktop file has been choosen as the common format for these actions.

As we would reuse the freedesktop.org Desktop Entry Specification (DES), we have to derive this specification to suit our needs.

This specification so defines how actions and menus should be described in .desktop files, and how and where these .desktop files are searched for.

This specification doesn't handle the « level-zero » case (but see the appendix A for a proposition about that).

Such an extension, targeting action items in file manager context menu, has been widely discussed in KDE, freedesktop.org and Thunar lists.

This is version 0.6 of our draft, updated on 2010, Feb. 3rd (see ChangeLog below).

Desktop file

Desktop file format

This specification relies on the common syntax as defined in DES. We are just reminding here the reader of some main points.

• Files are UTF-8 encoded.
• All keys and values are case sensitive.
• The [Desktop Entry] group must be the first group of the file.
• Boolean values must be "true" or "false".
• Strings, in strings lists, are semicolon-separated; the list itself ends with a semicolon.

Please note that, in all tables below, Req=YES just means that the value is required to define a valid action (resp. menu, resp. profile). A management UI is free to handle invalid actions (resp. menus, resp. profiles), and in fact that might even be needed in order to be able to fix invalid items, and make them valid...

Desktop file identifiant

In the rest of this specification, when a desktop file needs to be identified, we are using the basename of the file, without the extension, calling this a desktop_file_id.

Desktop files search path

.desktop files are searched for in "XDG_DATA_DIRS/file-manager/actions" directories, as defined in freedesktop.org XDG specifications.

When building the whole hierarchy of the menus and actions to be displayed in the file manager context menu, the implementation should ensure that all used desktop_file_ids are unique. In the case where two .desktop files have the same desktop_file_id, then the first found should take precedence.

Managed objects

Actions and profiles

This specification essentially defines how actions are to be described in .desktop files in order to be displayed in a file manager context menu, and available as selectable items to be executed by the user.

An action might be defined as a group of several elements:

• the displayable part: label, tooltip, icon
• conditions which have to be met in order the item be actually displayed in the context menu; these conditions are checked against the current file manager selection; these might be mimetypes, protocols, etc.
• the command to be executed, and its parameters.

As a user might want have the very same action (same label, same icon, and so on) execute a different command depending of the current environment at runtime, we define that an action is built on one to several profiles, where each profile is defined by:

• conditions which have to be met in order the item be actually displayed in the context menu; these conditions are checked against the current file manager selection; these might be mimetypes, protocols, etc.
• the command to be executed, and its parameters.

Menus

This specification also defines how these actions may be gathered and ordered in menus, and submenus, and so on.

A menu is defined by:

• its displayable part: label, tooltip, icon
• a set of conditions which are to be met in order the menu, and recursively all of its subitems, be actuelly displayed in the file manager context menu
• the ordered list of the items in the menu.

Conditions

As we are dealing with three level of objects (menus, actions, profiles), it appears that whether a condition must be defined at one of these levels is rather an arbitrary decision.

We so say that conditions may appear in any of these levels:

• When a condition appears in a menu definition, the result of its evaluation recursively applies to all included items. If the condition is not met, then neither the menu nor any of its subitems will be displayed.
• When a condition appears in an action definition, the result of its evaluation applies to all its profiles. If the condition is not met, then the action will not be candidate; the profiles will even not be considered.

Action definition

An action must be entirely defined in one .desktop file. The action is identified by the desktop_file_id in which it is defined.

The [Desktop Entry] group has following keys:

Key	Description	Value type	Req ?
Type	This define this .desktop file as an Action definition. Defaults to "Action".	string	no
Name	The label of the action, as it should appear in the context menu. Parameters may appear in Name value, and will be substituted at runtime.	localestring	YES
Tooltip	The tooltip associated with the item in the context menu. Parameters may appear in Tooltip value, and will be substituted at runtime. Defaults to empty.	localestring	no
Icon	The name of a themed icon, or the path to an icon. Parameters may appear in Icon value, and will be substituted at runtime. Defaults to empty.	localestring	no
Description	A free description of the action, which may be used in the management UI, in a Web page, and so on. Defaults to empty.	localestring	no
SuggestedShortcut	A shortcut suggested for the action. Please note that this might be only a suggestion as the shortcut may be already reserved for another use. Implementation should not override an already existing shortcut to define this one. Defaults to empty.	string	no
TargetContext	Whether the item targets the file manager context menu. Defaults to "true".	boolean	no
TargetToolbar	Whether the item targets the toolbar, if the file manager supports this. Defaults to "false".	boolean	no
ToolbarLabel	The label to be displayed in the toolbar, if it is not the same that those displayed in context menu. Parameters may appear in ToolbarLabel value, and will be substituted at runtime. Defaults to Name value.	localestring	no
Profiles	The list of the profiles which are defined for this action. Each profile must be defined in a [X-Action-Profile profile_id] group, in this same .desktop file. It is up to the implementation to decide whether profiles defined in this .desktop file, but not identified in this list, should or not be attached to the action. It could be for example an acceptable fallback to append these « orphan » profiles at the end of the ordered list of profiles.	strings list	YES

Only valid actions are displayed in the file manager context menu.

To be valid, an action must have a non-empty label, and at least one valid profile.

Profile definition

For each profile defined in the "Profiles" key, we must have a [X-Action-Profile profile_id] group.

Key	Description	Value type	Req ?
Name	The name of the profile; this name is not displayed in the context menu, and should just be thought as a convenience for the management UI. Defaults to empty.	localestring	no
Exec	Same meaning as in DES. Parameters may appear in Exec value, and will be substituted at runtime.	string	YES
Path	The working directory the program should be started in. Parameters may appear in Path value, and will be substituted at runtime. Defaults to (first) base directory of the currently selected file(s), which happens to be the value of "%d" parameter.	string	no
ExecutionMode	Execution mode of the program. This may be choosen between following values: Normal: Starts as a standard graphical user interface Minimized: Starts the program in minimized state if possible; an acceptable fallback is Normal Maximized: Starts the program in maximized state if possible; an acceptable fallback is Normal Terminal: Starts the preferred terminal of the graphical environment, and runs the command in it; an acceptable fallback is Terminal Embedded: Makes use of a special feature of the file manager which allows a terminal to be ran inside of it; an acceptable fallback is Terminal DisplayOutput: The ran terminal may be closed at end of the command, but standard streams (stdout, stderr) should be collected and displayed; an acceptable fallback is Terminal Defaults to "Normal".	string	no
StartupNotify	Same meaning as in DES. Only relevant when ExecutionMode=Normal. Defaults to "false".	boolean	no
StartupWMClass	Same meaning as in DES. Only relevant when ExecutionMode=Normal. Defaults to empty.	string	no
ExecuteAs	The user the command must be ran as. The user may be identified by its UID or by its login. The implementation might require the presence of a well-configured subsystem (e.g. sudo). Defaults to empty: the command will be executed as the current user.	string	no
ForEach	Whether the specified command should be run only once with the space-separated list of selected items as argument (ForEach=false), or if it should be ran once for each selected item (ForEach=true). Defaults to "false".	boolean	no

When several profiles are defined for an action, the first valid profile whose conditions are met at runtime is selected to be made available in the context menu.

In order to be valid, a profile must at least have an executable command.

Menu definition

Just as an action, a menu has label, tooltip, icon.

But, where an action is intended to eventually execute a command, a menu is just a way of gathering some subitems, actions or menus, in an ordered list.

The menu is so defined as a particular case of a .desktop file, whose the [Desktop Entry] section has following keys:

Key	Description	Value type	Req ?
Type	This define this .desktop file as a Menu definition. Must be equal to "Menu".	string	YES
Name	The label of the menu, as it should appear in the context menu. Parameters may appear in Name value, and will be substituted at runtime.	localestring	YES
Tooltip	The tooltip associated with the submenu in the context menu. Parameters may appear in Tooltip value, and will be substituted at runtime. Defaults to empty.	localestring	no
Icon	The name of a themed icon, or the path to an icon, to be associated to the submenu. Parameters may appear in Icon value, and will be substituted at runtime. Defaults to empty.	localestring	no
Description	A free description of the menu, which may be used in the management UI, in a Web page, and so on. Defaults to empty.	localestring	no
SuggestedShortcut	A shortcut suggested for the menu. Please note that this might be only a suggestion as the shortcut may be already reserved for another use. Implementation should not override an already existing shortcut to define this one. Defaults to empty.	string	no
ItemsList	The list of ordered desktop_file_ids which contain the items (actions or menus) to be displayed in the submenu. The content of .desktop files not identified here, or not identified as subitems of a menu or of a submenu, should not be ignored by the implementation; instead of that, the implementation should display these « orphan » items (though in a unspecified order). The keyword _SEPARATOR_ is a special case of desktop_file_id. It may be used to define a separator in the menu. Parameters may appear in ItemsList value, and will be substituted at runtime.	strings list	no
GetItemsList	A command whose execution returns a list of strings which is to be substituted to ItemsList value. When this key is present, whether it would be empty, or define a non-executable command, or the execution of the command doesn't return anything, the "ItemsList" key is ignored.	string	no

It is the responsability of the implementation to ensure that the displayed menus are relevant, i.e. not empty, with no separator at the begin or the end of the menu, with no double separator, etc.

In order to be valid, a menu must have a non-empty name, and include at least one valid subitem.

Conditions

As a remainder of that has been said above, each one of the following conditions may appear in a menu, an action or a profile group.

Key	Description	Value type	Req ?
OnlyShowIn, NotShowIn	Same meaning as in DES. Defaults to show anywhere.	strings list	no
NoDisplay	Whether the item is candidate to be displayed in the context menu; a user might define many actions or menus, and choose to only enable some of them. Defaults to "false".	boolean	no
Hidden	Same meaning as in DES. Defaults to "false".	boolean	no
TryExec	Same meaning as in DES. Note that, when specified, only the presence and the executability status of the specified file are checked. Parameters may appear in TryExec value, and will be substituted at runtime. Defaults to successful.	string	no
ShowIfRegistered	The well-known name of a DBus service. The item will be candidate if the named service is registered on session DBus at runtime. Parameters may appear in ShowIfRegistered value, and will be substituted at runtime. Defaults to successful. Comment: This is the equivalent of KDE "X-KDE-ShowIfRunning" key.	string	no
ShowIfTrue	A command which, when executed, should output a string on stdout. The item will be candidate if the outputed string is equal to "true". Parameters may appear in ShowIfTrue value, and will be substituted at runtime. Example: [ -r %d/.svn/entries ] && echo "true" Defaults to successful. Comment: This is the equivalent of KDE "X-KDE-ShowIfDBusCall" key, extended to any command able to output a string.	string	no
ShowIfRunning	The name of a process. The item will be candidate if the process name is found in memory at runtime. Parameters may appear in ShowIfRunning value, and will be substituted at runtime. Defaults to successful.	string	no
MimeTypes	Same meaning as in DES. Each mimetype may be fully specified (e.g. "audio/mpeg;"), or as a group (e.g. "image/*;"). Mimetypes may be negated (e.g. "audio/*; !audio/mpeg;"). Some of well-known mimetypes include: "all/all": matches all items "all/allfiles": matches only files "inode/directory": matches only directories Defaults to "*;". Comment: Do we should include "allfiles" mimetype, which seems obsolete, in order to keep compatibility with some old versions of KDE ? This is the equivalent of "ServiceTypes", "X-KDE-ServiceTypes", "ExcludeServiceTypes" KDE and "MimeType" freedesktop keys.	strings list	no
Basenames	List of basenames the selection should match in order this profile be selected. Wildcards are accepted. Basenames may be negated (e.g. "!*.h;"). Defaults to "*;".	strings list	no
Matchcase	Whether the above Basenames is case sensitive. Defaults to "true".	boolean	no
SelectionCount	Whether this profile may be selected depending of the count of the selection. This is a string of the form "{'<'|'='|'>'} number". Examples of valid strings are: "=0", "> 1", "< 10". Defaults to "*".	string	no
Schemes	The list of schemes the selection must satisfy in order the item be selected. Exemples of well-known schemes are: "file" "sftp" "smb" "http" Schemes may be negated, e.g. "file; smb; !http;". Defaults to "*;". Comment: This is the equivalent of "X-KDE-Protocol" and "X-KDE-Protocols" KDE keys. Does a "Protocols" key would be better understood than a "Schemes" key ?	strings list	no
Folders	A list of URIs the current folder must be in in order the item be selected. This is only relevant when the conditions target a directory, whether the current file manager selection being empty, or that has been defined by the "MimeTypes" condition. Defaults to "/".	strings list	no
Capabilities	A list of capabilities each item of the selection must satisfy in order the item be candidate. Capabilities may be negated. Capabilities have to be choosen between following predefined ones: "Owner": current user is the owner of selected items "Readable": selected items are readable by user (probably more usefull when negated) "Writable": selected items are writable by user "Executable": selected items are executable by user "Local": selected items are local Defaults to "*;". Comment: This is the equivalent of "X-KDE-Require" KDE key. Some other relevant capabilities ?	strings list	no

Parameters

Whenever parameters are said to be accepted, they will be replaced at run-time.

Also, this specification doesn't make any assumption about whether a parameter is relevant in a given situation, or secure, or may be used several times, or so. It instead considers that this sort of check is up to the action creator.

The implementation should take care of correctly shell-escape the substituted values, so that it should not be needed for the action creator to use ansy sort of quotes to handle spaces in filenames.

Parameter	Description
%b	(first) basename
%B	space-separated list of basenames
%c	count of selected items
%d	(first) base directory
%D	space-separated list of base directory of each selected items
%f	(first) file name
%F	space-separated list of selected file names
%h	hostname of the (first) URI
%n	username of the (first) URI
%p	port number of the (first) URI
%s	scheme of the (first) URI
%u	(first) URI
%U	space-separated list of selected URIs
%w	(first) basename without the extension
%W	space-separated list of basenames without their extension
%x	(first) extension
%X	space-separated list of extensions
%%	the « % » character

Appendix A. The level-zero case

Though not strictly an action or a menu definition, the level-zero issue might be easily solved by this specification. The implementation is free to implement it or not.

Ordering the elements which have to be displayed at the level-zero of the file manager context menu is just a particular case of a menu definition.

An implementation might define a level-zero.directory file, which would contain the ordered list of level zero items identified by their desktop_file_id.

The [Desktop Entry] section of this level-zero.directory file would so have only one of the following keys:

Key	Description	Value type	Req ?
ItemsList	Same signification as above	strings list	no
GetItemsList	Same signification as above	string	no

The level-zero.directory file may be searched for in XDG_DATA_DIRS/file-manager/actions. The first one found would be used.

Not finding a level-zero.directory file should not prevent actions or menus to be displayed. Insetad, they just would be displayed in an unspecified,implementation-dependant, order.

The name "level-zero.directory" is choosen to not risk any collision with regular .desktop files.

Appendix B. Some rationales about menu definition

The KDE way

KDE defines the "X-KDE-Submenu" key. This key defines the label of a submenu the current action(s) should be included in. Order of the actions in this submenu is defined by the "Actions" key, though this might be altered by the "X-KDE-Priority" key. When several .desktop files define the same submenu, actions are merged.

What are the advantages of this solution ?

• It exists, and is widely used in KDE ServiceMenus.
• This is a down-to-top, self-contained, approach where each action says in which submenu it whishes to be included in.

What are the inconvenients of this solution ?

• It lacks of an Icon key associated to the submenu; though this certainly be added, the risk exists that several submenus with same label actually define different icons.
• It lacks of a Tooltip key associated to the submenu (though... idem as above)
• When several .desktop files define the same submenu (i.e. the same label), a merge operation is done so that all actions are included in the same submenu. The order of the actions after such a merge operation is not defined.
• There is no way to define the global order of the actions, when all .desktop files have been dealt with.
• As the menu is adressed at the action-level, one has to modifiy each action when he wants to reorganize his menus.
• Whether there is any menu or not, there is no way to define order of level-zero elements.

An alternate way

As the menu may be seen as just a particular case of action, it appears logically that its definition may directly be derived from the action definition.

What are the advantages (over the KDE way) of using this definition ?

• User/sysadmin has full control on the order of the displayed items, and on the content of the submenus.
• Defining menus outside of the actions is a conceptual advantage; this let creators of actions do their work without having to wonder in which menu the action should go.
• There is no way for an action creator to decide himself if its action is Important or should be displayed at the TopLevel.
• Associated with ad-hoc conditions, we are able to define conditional menus, thus optimizing the building of the whole contextual menu.
• This is not XML ;-)

What are the inconvenients ?

• As a top-to-down approach, just dropping a new .desktop file somewhere is not enough to get advantage of this; not referenced actions or submenus will just be displayed anywhere in the contextual menu.

References

• Desktop Entry Specification
• Desktop Menu Specification
• XDG Base Directory Specification
• Creating Konqueror Service Menus
• Krusader UserActions
• Thunar Custom Actions

Contributors

• Jonas Bähr
• David Faure
• Ted Gould
• « PCMan »
• Michael Pyne
• Liam R E Quin
• Pierre Wieser

ChangeLog

Version	Date	Changes
0.1-draft	2009-12-07	Creation
0.2-draft	2009-12-17	- Move syntax considerations to a new "Desktop file" section. - Add "Managed objects" section. - Add "Defining menus" section. - Deal with level zero items. - Define a separate "Conditions" section. - Remove "Rationales" section, moving comments to the corresponding key description. - Remove Type key - Remove all X-Action- prefix of the key names. - Add needed keys in order to provider equivalent functionalities to KDE service menus. - Current and extensions keys have been merged in the same table.
0.3-draft	2009-12-23	- No more talk about « extending », but rather of « deriving ». - Replace « fds » acronym with « DES ». - More clearly notice what this specification specifies, and what it doesn't specify. - Move the « level-zero » case to a specific appendix, as not a main part of this specification. - Move rationales about the menu description to a specific appendix. - Comment key is renamed as Tooltip in menu and action definitions. - Add Description, SuggestedShortcut keys to menu and action definitions. - Add Path, StartupNotify, StartupWMClass, ForEach keys to profile definition. - Remove SelectionCount key. - Define available parameters. - Create Contributors chapter. - Create References chapter.
0.4-draft	2010-01-07	- Remove ToolbarSameLabel action property. - Add ExecuteAs profile property. - Restore SelectionCount condition. - Add myself as a contributor. - Add a link to ChangeLog. - Fix some links.
0.5-draft	2010-01-28	- Setup a default value for Path parameter. - Update contributors.
0.6-draft	2010-02-03	- Add Type key for distinguishing Actions from Menus. - Specifies what to do with present, but not listed, profiles. - Specifies defaults for TryExec, ShowIfRegistered, ShowIfTrue, ShowIfRunning, MimeTypes, SelectionCount, Schemes, Capabilities keys.

Rationale

As of 2.29.1, Nautilus-Actions uses GConf to store its actions (and menus, and profiles, and more generally all its datas).

As we wish be able to share our actions with other file manager extensions, we should be able to retrieve and store actions from and to other sources.

Nautilus-Actions so defines a NAIIOProvider interface, which should be implemented by any source which wants provide actions to Nautilus-Actions.

NAIIOProvider interface

For a detailed description of the API, rather go to the online repository. We will describe here only general principles about multi-providers management.