diff options
| -rw-r--r-- | desktop-entry/desktop-entry-spec.xml | 60 |
1 files changed, 60 insertions, 0 deletions
diff --git a/desktop-entry/desktop-entry-spec.xml b/desktop-entry/desktop-entry-spec.xml index d3879f2..0bdb83a 100644 --- a/desktop-entry/desktop-entry-spec.xml +++ b/desktop-entry/desktop-entry-spec.xml @@ -602,6 +602,17 @@ <entry>1</entry> </row> <row> + <entry id="key-implements"><varname>Implements</varname></entry> + <entry> + A list of interfaces that this application implements. By default, a desktop file implements no + interfaces. See <link linkend="interfaces">Interfaces</link> for more information on how this + works. + </entry> + <entry>string(s)</entry> + <entry>NO</entry> + <entry></entry> + </row> + <row> <entry id="key-keywords"><varname>Keywords</varname></entry> <entry> A list of strings which may be used in addition to other @@ -908,6 +919,55 @@ Specification</ulink>. </para> </sect1> + <sect1 id="interfaces"> + <title>Interfaces</title> + <para> + The <varname>Implements</varname> key can be used to declare one or more interfaces that a desktop file + implements. + </para> + <para> + Each interface name must follow the rules used for D-Bus interface names, but other than that, they have + no particular meaning. For instance, listing an interface here does not necessarily mean that this + application implements that D-Bus interface or even that such a D-Bus interface exists. It is entirely up + to the entity who defined a particular interface to define what it means to implement it. + </para> + <para> + Although it is entirely up to the designer of the interface to decide what a given interface name means, + here are some recommended "best practices": + </para> + <itemizedlist> + <listitem> + <para> + interfaces should require that application is DBusActivatable, including the requirement that the + application's desktop file is named using the D-Bus "reverse DNS" convention + </para> + </listitem> + <listitem> + <para> + the interface name should correspond to a D-Bus interface that the application exports on the same + object path as it exports the org.freedesktop.Application interface + </para> + </listitem> + <listitem> + <para> + if the interface wishes to allow for details about the implementation, it should do so by specifying + that implementers add a group in their desktop file with the same name as the interface (eg: + "[org.freedesktop.ImageAcquire]") + </para> + </listitem> + </itemizedlist> + <para> + Recommendations notwithstanding, interfaces could specify almost any imaginable requirement including such + (ridiculous) things as "when launched via the Exec line, the application is expected to present a window + with the _FOO_IDENTIFIER property set, at which point an X client message will be sent to that window". + Another example is "all implementations of this interface are expected to be marked NoDisplay and, on + launch, will present no windows and will delete all of the user's files without confirmation". + </para> + <para> + Interface definers should take care to keep issues of backward and forward compatibility in mind when + designing their interfaces. + </para> + </sect1> <sect1 id="mime-types"> <title>Registering MIME Types</title> <para> |