<?xml version="1.0" encoding="UTF-8" ?>

<node name="/org/inkscape/application"

xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd"

>

<interface name="org.inkscape.application">

<!-- DESKTOP FUNCTIONS -->

<method name="desktop_new">

<arg type="s" name="desktop_name" direction="out" >

<annotation name="org.freedesktop.DBus.GLib.ReturnVal" value="error"/>

<doc:doc>

<doc:summary>This string can be used to connect to the new interface that was created.</doc:summary>

</doc:doc>

</arg>

<doc:doc>

<doc:description>

<doc:para>Create a new document interface and return its location. Only call this when Inkscape is running in GUI mode.</doc:para>

</doc:description>

</doc:doc>

</method>

<method name="get_desktop_list">

<arg type="as" name="document_list" direction="out" >

<annotation name="org.freedesktop.DBus.GLib.ReturnVal" value=""/>

<doc:doc>

<doc:summary>A list of interfaces being provided by Inkscape.</doc:summary>

</doc:doc>

</arg>

<doc:doc>

<doc:description>

<doc:para>List all the interfaces that it is possible to connect to. TODO: not implemented.</doc:para>

</doc:description>

</doc:doc>

</method>

<method name="desktop_close_all">

<doc:doc>

<doc:description>

<doc:para>Close all document interfaces without saving. TODO: not implemented.</doc:para>

</doc:description>

</doc:doc>

</method>

<method name="exit">

<doc:doc>

<doc:description>

<doc:para>Exit Inkscape without saving. Fairly straightforward.</doc:para>

</doc:description>

</doc:doc>

</method>

<!-- DOCUMENT FUNCTIONS -->

<method name="document_new">

<arg type="s" name="document_name" direction="out" >

<annotation name="org.freedesktop.DBus.GLib.ReturnVal" value="error"/>

<doc:doc>

<doc:summary>This string can be used to connect to the new interface that was created.</doc:summary>

</doc:doc>

</arg>

<doc:doc>

<doc:description>

<doc:para>Originally, there were going to be two interfaces. A desktop and a document. Desktops would be used when the user wanted to see the result of their code and documents would be used when less overhead was desired. Unfortunately as more and more of the code can to rely on the desktop and it's associated support code (including selections and verbs) the document interface was looking more and more limited. Ultimately I decided to just go with the desktop interface since I didn't have a compelling reason for keeping the other one and having two similar interfaces could be very confusing. The desktop interface inherited the document name because I believe it's more familiar to people.</doc:para>

<doc:para>Perhaps it would be best to have an option as to whether or not to create a window and fail with a good error message when they call a function that requires one. Or have a second interface for different use cases but have it be completely different, rather than a subset of the first if there are use cases that support it.</doc:para>

<doc:para>UPDATE: 3rd July 2013, Eric Greveson: After having done some initial work to attempt to decouple Inkscape "verbs" from desktops, it is now possible to run a limited subset of actions in command-line mode (with a selection model and document, but no desktop). I believe that the "single document interface" approach, with some functions that may require a GUI, is the better path, and so document interfaces without a desktop are now possible. Most functions still require the desktop to work, though, with the notable exception of selection methods and Boolean operations.</doc:para>

<doc:para>As a result, this function should ONLY be called when using Inkscape in command-line mode. Use "desktop_new" instead if running in GUI mode.</doc:para>

</doc:description>

</doc:doc>

</method>

<method name="get_active_document">

<arg type="s" name="document_name" direction="out" >

<annotation name="org.freedesktop.DBus.GLib.ReturnVal" value="error"/>

<doc:doc>

<doc:summary>This string can be used to connect to the current active document.</doc:summary>

</doc:doc>

</arg>

<doc:doc>

<doc:description>

<doc:para>Get the location of the current active document (e.g. when running in console mode, when desktops are not available).</doc:para>

</doc:description>

</doc:doc>

</method>

</interface>

</node>