src/extension/dbus/application-interface.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!--
   3  * This is the master description of the DBus application interface.
   4  * The interface is mostly just for creating new document instances.
   5  *
   6  * This file is used to generate both glue code and documentation.
   7  * The methods are in the same order as the .cpp/.h and the sections are labeled.
   8  *
   9  * Any change to method prototypes in application-interface.cpp MUST be reflected here.
  10  *
  11  * This file is the proverbial gold standard for the application interface.
  12  *
  13  * Authors:
  14  *   Soren Berg <Glimmer07@gmail.com>
  15  *
  16  * Copyright (C) 2009 Soren Berg
  17  *
  18  * Released under GNU GPL, read the file 'COPYING' for more information
  19 -->
  20 <node name="/org/inkscape/application"
  21   xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd"
  22 >
  23   <interface name="org.inkscape.application">
  24
  25     <!-- DESKTOP FUNCTIONS -->
  26     <method name="desktop_new">
  27       <arg type="s" name="desktop_name" direction="out" >
  28         <annotation name="org.freedesktop.DBus.GLib.ReturnVal" value="error"/>
  29         <doc:doc>
  30           <doc:summary>This string can be used to connect to the new interface that was created.</doc:summary>
  31         </doc:doc>
  32       </arg>
  33       <doc:doc>
  34         <doc:description>
  35           <doc:para>Create a new document interface and return it's location.</doc:para>
  36         </doc:description>
  37       </doc:doc>
  38     </method>
  39     <method name="get_desktop_list">
  40       <arg type="as" name="document_list" direction="out" >
  41         <annotation name="org.freedesktop.DBus.GLib.ReturnVal" value=""/>
  42         <doc:doc>
  43           <doc:summary>A list of interfaces being provided by Inkscape.</doc:summary>
  44         </doc:doc>
  45       </arg>
  46       <doc:doc>
  47         <doc:description>
  48           <doc:para>List all the interfaces that it is possible to connect to.</doc:para>
  49         </doc:description>
  50       </doc:doc>
  51     </method>
  52     <method name="desktop_close_all">
  53       <doc:doc>
  54         <doc:description>
  55           <doc:para>Close all document interfaces without saving.</doc:para>
  56         </doc:description>
  57       </doc:doc>
  58     </method>
  59     <method name="exit">
  60       <doc:doc>
  61         <doc:description>
  62           <doc:para>Exit Inkscape without saving.  Fairly straightforward. </doc:para>
  63         </doc:description>
  64       </doc:doc>
  65     </method>
  66
  67     <!-- DOCUMENT FUNCTIONS -->
  68     <method name="document_new">
  69       <arg type="s" name="document_name" direction="out" >
  70         <annotation name="org.freedesktop.DBus.GLib.ReturnVal" value="error"/>
  71         <doc:doc>
  72           <doc:summary>This string can be used to connect to the new interface that was created.</doc:summary>
  73         </doc:doc>
  74       </arg>
  75       <doc:doc>
  76         <doc:description>
  77           <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>
  78           <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>
  79         </doc:description>
  80       </doc:doc>
  81     </method>
  82   </interface>
  83 </node>