summaryrefslogtreecommitdiffstats
path: root/desktop-entry/desktop-entry-spec.xml
diff options
context:
space:
mode:
authorRyan Lortie <desrt@desrt.ca>2014-01-06 00:29:30 -0500
committerRyan Lortie <desrt@desrt.ca>2014-04-10 12:21:01 -0400
commit4f734282a18a1e29b095b2c04220214af9d5bd46 (patch)
tree667acb48e1d4cd43c43f26c804f32ee360da3060 /desktop-entry/desktop-entry-spec.xml
parenta70ca606ef616fbddec15da35820cd8c8694f1f6 (diff)
downloadxdg-specs-4f734282a18a1e29b095b2c04220214af9d5bd46.tar.xz
desktop entry spec: Add support for Implements=
https://bugs.freedesktop.org/show_bug.cgi?id=73317
Diffstat (limited to 'desktop-entry/desktop-entry-spec.xml')
-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>