diff options
| -rw-r--r-- | desktop-entry/desktop-entry-spec.xml | 101 |
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> |