summaryrefslogtreecommitdiffstats
path: root/desktop-entry/desktop-entry-spec.xml
diff options
context:
space:
mode:
authorRyan Lortie <desrt@desrt.ca>2013-04-29 17:17:42 -0700
committerRyan Lortie <desrt@desrt.ca>2013-07-11 12:24:34 -0400
commit6650489387dbc2c03282831dcddfd2af8934d513 (patch)
tree971ed2536d8a143102931f01412ef947873b9305 /desktop-entry/desktop-entry-spec.xml
parent77487fc8ec771eff7492a7638e31a7226f564218 (diff)
downloadxdg-specs-6650489387dbc2c03282831dcddfd2af8934d513.tar.xz
desktop-entry: add DBusActivatable
Add a DBusActivatable key along with the recommendation that desktop files be named like "org.example.FooViewer.desktop". https://bugs.freedesktop.org/show_bug.cgi?id=64066
Diffstat (limited to 'desktop-entry/desktop-entry-spec.xml')
-rw-r--r--desktop-entry/desktop-entry-spec.xml101
1 files changed, 93 insertions, 8 deletions
diff --git a/desktop-entry/desktop-entry-spec.xml b/desktop-entry/desktop-entry-spec.xml
index 7d99d0a..ce270c5 100644
--- a/desktop-entry/desktop-entry-spec.xml
+++ b/desktop-entry/desktop-entry-spec.xml
@@ -52,6 +52,15 @@
</address>
</affiliation>
</author>
+ <author>
+ <firstname>Ryan</firstname>
+ <surname>Lortie</surname>
+ <affiliation>
+ <address>
+ <email>desrt@desrt.ca</email>
+ </address>
+ </affiliation>
+ </author>
</authorgroup>
</articleinfo>
@@ -79,6 +88,10 @@
fall back to recognition via "magic detection".
</para>
<para>
+ For applications, the part of the name of the desktop file (before the <filename>.desktop</filename>)
+ should follow the "reverse DNS" convention, e.g. <literal>org.example.FooViewer.desktop</literal>.
+ </para>
+ <para>
Desktop entry files are encoded in UTF-8. A file is interpreted as a
series of lines that are separated by linefeed characters. Case is
significant everywhere in the file.
@@ -467,6 +480,20 @@
<entry>NO</entry>
<entry>1-3</entry>
</row>
+ <row>
+ <entry id="key-dbusactivatable"><varname>DBusActivatable</varname></entry>
+ <entry>
+ A boolean value specifying if D-Bus activation is supported for this application. If this key is
+ missing, the default value is <literal>false</literal>. If the value is <literal>true</literal>
+ then implementations should ignore the <varname>Exec</varname> key and send a D-Bus message to
+ launch the application. See <link linkend="dbus">D-Bus Activation</link> for more information on
+ how this works. Applications should still include Exec= lines in their desktop files for
+ compatibility with implementations that do not understand the DBusActivatable key.
+ </entry>
+ <entry>boolean</entry>
+ <entry>NO</entry>
+ <entry></entry>
+ </row>
<row>
<entry id="key-tryexec"><varname>TryExec</varname></entry>
<entry>
@@ -483,12 +510,15 @@
<row>
<entry id="key-exec"><varname>Exec</varname></entry>
<entry>
- Program to execute, possibly with arguments. See the <link
- linkend="exec-variables"><varname>Exec</varname> key</link> for
- details on how this key works.
+ Program to execute, possibly with arguments. See the
+ <link linkend="exec-variables"><varname>Exec</varname> key</link> for details on how this key
+ works. The <varname>Exec</varname> key is required if <varname>DBusActivatable</varname> is not
+ set to <literal>true</literal>. Even if <varname>DBusActivatable</varname> is
+ <literal>true</literal>, <varname>Exec</varname> should be specified for compatibility with
+ implementations that do not understand <varname>DBusActivatable</varname>.
</entry>
<entry>string</entry>
- <entry>YES</entry>
+ <entry>NO</entry>
<entry>1</entry>
</row>
<row>
@@ -798,6 +828,57 @@
%U field codes may only be used as an argument on their own.
</para>
</sect1>
+ <sect1 id="dbus">
+ <title>D-Bus Activation</title>
+ <para>
+ Applications that support being launched by D-Bus must implement the following interface (given in D-Bus
+ introspection XML format):
+ </para>
+ <programlisting>
+<![CDATA[ <interface name='org.freedesktop.Application'>
+ <method name='Activate'>
+ <arg type='a{sv}' name='platform_data' direction='in'/>
+ </method>
+ <method name='Open'>
+ <arg type='as' name='uris' direction='in'/>
+ <arg type='a{sv}' name='platform_data' direction='in'/>
+ </method>
+ <method name='ActivateAction'>
+ <arg type='s' name='action_name' direction='in'/>
+ <arg type='av' name='parameter' direction='in'/>
+ <arg type='a{sv}' name='platform_data' direction='in'/>
+ </method>
+ </interface>]]>
+ </programlisting>
+ <para>
+ The application must name its desktop file in accordance with the naming recommendations in the
+ introduction section (e.g. the filename must be like <literal>org.example.FooViewer.desktop</literal>).
+ The application must have a D-Bus service activatable at the well-known name that is equal to the desktop
+ file name with the <filename>.desktop</filename> portion removed (for our example,
+ <literal>org.example.FooViewer</literal>). The above interface must be implemented at an object path
+ determined as follows: starting with the well-known D-Bus name of the application, change all dots to
+ slashes and prefix a slash. For our example, this is <literal>/org/example/FooViewer</literal>.
+ </para>
+ <para>
+ The <literal>Activate</literal> method is called when the application is started without files to open.
+ </para>
+ <para>
+ The <literal>Open</literal> method is called when the application is started with files. The array of
+ strings is an array of URIs, in UTF-8.
+ </para>
+ <para>
+ The <literal>ActivateAction</literal> method is called when <link linkend="extra-actions">Desktop
+ Actions</link> are activated. The <literal>action-name</literal> parameter is the name of the action.
+ </para>
+ <para>
+ All methods take a <literal>platform-data</literal> argument that is used in a similar way to how
+ environment variables might be used. Currently, only one field is defined by the specification:
+ <varname>desktop-startup-id</varname>. This should be a string of the same value as would be stored in
+ the <varname>DESKTOP_STARTUP_ID</varname> environment variable, as specified by the <ulink
+ url="http://www.freedesktop.org/Standards/startup-notification-spec">Startup Notification Protocol
+ Specification</ulink>.
+ </para>
+ </sect1>
<sect1 id="mime-types">
<title>Registering MIME Types</title>
<para>
@@ -963,12 +1044,16 @@ application/x-bar=bar.desktop;</programlisting>
<row>
<entry id="key-action-group-exec"><varname>Exec</varname></entry>
<entry>
- Program to execute for this action, possibly with arguments.
- See the <link linkend="exec-variables"><varname>Exec</varname>
- key</link> for details on how this key works.
+ Program to execute for this action, possibly with arguments. See the
+ <link linkend="exec-variables"><varname>Exec</varname> key</link> for details on how this key
+ works. The <varname>Exec</varname> key is required if <varname>DBusActivatable</varname> is not
+ set to <literal>true</literal> in the main desktop entry group. Even if
+ <varname>DBusActivatable</varname> is <literal>true</literal>, <varname>Exec</varname> should be
+ specified for compatibility with implementations that do not understand
+ <varname>DBusActivatable</varname>.
</entry>
<entry>string</entry>
- <entry>YES</entry>
+ <entry>NO</entry>
</row>
</tbody>
</tgroup>