Difference between revisions of "Development/Tutorials/Solid/Device Actions"

Jump to: navigation, search
m (moved Development/Tutorials/Plasma/Device Notifier to Development/Tutorials/Solid Device Actions: This is actually a Solid thing, so move it there.)
m (Text replace - "<code ini>" to "<syntaxhighlight lang="ini">")
Line 10: Line 10:
An Action file is a desktop configuration file similar to the following one:
An Action file is a desktop configuration file similar to the following one:
<code ini>
<syntaxhighlight lang="ini">
[Desktop Entry]
[Desktop Entry]
X-KDE-Solid-Predicate=OpticalDisc.availableContent & 'Audio'
X-KDE-Solid-Predicate=OpticalDisc.availableContent & 'Audio'

Revision as of 20:37, 29 June 2011


When a new data device is inserted or detected by Solid, the hardware awareness framework introduced in KDE Platform 4, it gets added to the Device Notifier (a Plasma widget that is responsible for handling device events), Places list and other relevant areas in the user interface.

Each device has a set of related actions which the user can perform on the device, depending on the device type and its contents. For example, when the media is an audio CD, the Device Notifier may offer to play that CD using Amarok. The default actions are not a part of Plasma Desktop, however; rather, each action is defined by a simple .desktop file that is installed by the application that handles the action (e.g. Amarok in our Audio CD example), and goes away when the application is removed.

You can add your own actions and modify existing ones using the Device Actions system setting module; however, such changes are limited to the user that requests the change. If you want to install a custom action along with your application, you have to dig a bit deeper.

Anatomy of an action

An Action file is a desktop configuration file similar to the following one:

[Desktop Entry]
X-KDE-Solid-Predicate=OpticalDisc.availableContent & 'Audio'

[Desktop Action Play]
Name=Play Audio CD with Amarok
Name[fr]=Jouer CD Audio avec Amarok
# names in other languages
Exec=amarok --cdplay %f
</code >

== Actions and devices ==

The '''Device Notifier''' gets the devices and their corresponding actions by interrogating the'''hotplug''' Plasma DataEngine.  The '''hotplug''' DataEngine gets the set of devices from '''Solid''' and the set of actions from the subdirectories {{path|./solid/actions}} relative to the application settings path in '''KDE'''.  The set of actions pertaining to each device is then obtained by evaluating the Solid Predicate specified in the action against the physical and logical properties of the device; if the predicate holds, the action is included.
This is, of course, not limited to Plasma Desktop: any application can similarly query '''Solid''' for the same actions.

== Action predicates ==
The predicate for each action is specified in the entry <TT >X-KDE-Solid-Predicate</TT >.  The syntax of the predicate allows to construct an object of class '''Solid::Predicate''' out of it.

Atomic predicates can be of the form
* <TT ><VAR >DeviceClass</VAR >.<VAR>attribute</VAR > == <VAR >value</VAR ></TT >
* <TT ><VAR >DeviceClass</VAR >.<VAR >attribute</VAR > & <VAR >value</VAR ></TT >
the latter form meaning that the Solid attribute may have a set of values, and the specified value must be a part of that set.  

For example, the predicate <TT >OpticalDisc.availableContent & 'Audio'</TT > means that the device medium is an optical disc and that it contains audio tracks and possibly something else, while the hypothetical predicate <TT >OpticalDisc.availableContent == 'Audio'</TT > means that a matching device contains audio tracks and nothing else.

Atomic predicates can be composed using the keywords <TT >AND</TT > and <TT >OR</TT > and parentheses.  In practice, it is easiest to create a custom action with '''System Settings''' and peek the description from the custom action desktop file (within the user profile directory).

== Executing actions ==
A matching action can be selected for execution by the user.  When that happens, the command line in the Exec key of the action is executed given the device as a parameter.  The location and value of the parameter is specified in the following way:
><DT ><TT >%f</TT ><DD >Device mount point location, if applicable 
<DT ><TT >%d</TT ><DD >Device special file path
<DT ><TT >%i</TT 
><DD >Device identifier, as if returned by the command <TT >solid-hardware</TT ></DL >

So you are free to choose whatever command syntax your application supports.  Note, however, that the forms <TT >%d</TT > and <TT >%i</TT > are deprecated by the Free Desktop standard and may be discontinued.

== Installing actions ==
You install system-wide actions in the directory where the '''hotplug''' data engine will look for them (see [[#Actions and devices|above]]).  The action is available immediately after installation.

Content is available under Creative Commons License SA 4.0 unless otherwise noted.