summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--desktop-entry/desktop-entry-spec.xml60
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>