<chapter id="connecting">
<title>Connecting to the API</title>
<sect1>
<title>Overview</title>
<para>
There are really two Dbus interfaces provided by Inkscape. One is the application interface, which is constant, and allows one to control the Inkscape application as a whole and create new documents or windows. The second is the document interface. A document interface is automatically generated for every open window, and the commands sent to that interface will affect that particular window.
</para>
<para>
So the basic way of connecting goes like this: Connect to the session bus. Connect to the application interface. Request a new document. Connect to the newly created document interface using the name returned in the last step. Manipulate the document however you want (load files, create shapes, save, etc.) After the connection example there is a shortcut that will shorten this process somewhat in certain circumstances.
</para>
</sect1>
<sect1>
<title>Connection example</title>
<para>
Here is a basic example of connecting to the Bus and getting a new document. (In python for now because it's easy to read.)
</para>
<informalexample language="python" title="simple example">
<programlisting>
import dbus
#get the session bus.
bus = dbus.SessionBus()
#get the object for the application.
inkapp = bus.get_object('org.inkscape',
#request a new desktop.
desk2 = inkapp.desktop_new(dbus_interface='org.inkscape.application')
#get the object for that desktop.
inkdoc1 = bus.get_object('org.inkscape', desk2)
#tell it what interface it is using so we don't have to type it for every method.
#use!
doc1.rectangle (0,0,100,100)
</programlisting>
</informalexample>
</sect1>
<sect1>
<title>Shortcut</title>
<para>
Here is a quicker way if you don't need multiple documents open at once. Since Inkscape starts automatically, and it always creates a blank document we can just connect to that.
</para>
<warning><para>
WARNING: This may not always work, it also might connect you to a document that is in use if Inkscape was already running. Only recommended for testing/experimenting.
</para></warning>
<informalexample language="python" title="simple example">
<programlisting>
import dbus
#get the session bus.
bus = dbus.SessionBus()
#get object
#get interface
#ta-da
doc1.rectangle (0,0,100,100)
</programlisting>
</informalexample>
</sect1>
</chapter>
<chapter id="terms">
<title>Terminology</title>
<anchor id="Coordinate System"/>
<sect1>
<title>Coordinate System</title>
<para>
The coordinate system used by this API may be different than what you are used to (although it is standard in the computer graphics industry.) Simply put the origin (0,0) is in the upper left hand corner of the document. X increases to the right and Y increases downwards. Therefore everything with positive coordinates is in the document.
</para>
<para>
For example: (100,100) would be just below and to the right of the top left corner of the document.
</para>
</sect1>
<anchor id="Selections"/>
<sect1>
<title>Selections</title>
<para>
Selections are extremely useful ways of managing groups of objects and applying effects to all of them at once. Since much of Inkscapes core functionality is built around manipulating selections they are the key to much of this APIs utility. Manipulate the list of selected objects with <link linkend="document.selection_set">selection_set()</link>, <link linkend="document.selection_add">selection_add()</link>, and <link linkend="document.selection_box">selection_box()</link> and then call whatever selection function you need.
</para>
</sect1>
<anchor id="Groups"/>
<sect1>
<title>Groups</title>
<para>
Groups are collections of objects that are treated as a single object. Groups have their own id and can be passed to any function that accepts an object, though some will not have any effect (groups ignore style for instance.) Groups can be transformed and occupy a single level in their layer. Objects within a group can still be modified using their ids, but this will not have any affect on the other group members. Functions like move_to may not work as expected if used on an object that is part of a group that has a transformation applied.
</para>
</sect1>
<anchor id="Layers and Levels"/>
<sect1>
<title>Layers and Levels</title>
<para>
The basic idea is that things on top cover up things beneath them. The potentially confusing part is that Inkscape implements this in two ways: layers and levels. Levels are what order objects are in within a single layer. So the highest level object is still below all of the objects in the layer above it. <link linkend="document.layer_change_level">layer_change_level()</link> changes the order of layers and <link linkend="document.selection_change_level">selection_change_level()</link> changes the order of objects within a layer.
</para>
<para>
Changing the level of a selection also deserves some explanation. The <link linkend="document.selection_change_level">selection_change_level()</link> function can work in two ways. It can be absolute, "to_top" and "to_bottom" work like you'd expect, sending the entire selection to the top or bottom of that layer. But it can also be relative. "raise" and "lower" only work if there is another shape overlaping above or beneath the selection at the moment. Also if you have two objects selected and they are both occluded by a third, raising the selection once will only raise the first object in the selection above the third object. In other words selections don't move as a group.
</para>
</sect1>
<anchor id="Style Strings"/>
<sect1>
<title>Style Strings</title>
<para>
Style strings look something like this: "fill:#ff0000;fill-opacity:1;stroke:#0000ff;stroke-width:5;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none". It is a string of key value pairs that determines the style of a particular object. Style strings affect most objects. They can be set all at once or specific key value pairs can be added one by one. Style strings can also be merged, with the new string replacing key/value pairs that it contains and leaving the rest as they were. One could also think of it as the new string taking any attributes it does not have and adopting them from the old string.
</para>
</sect1>
<anchor id="Paths"/>
<sect1>
<title>Paths</title>
<para>
A path is a string representing a series of points, and how the line curves between the points. It looks something like this: "m 351.42857,296.64789 a 54.285713,87.14286 0 1 1 -108.57143,0 54.285713,87.14286 0 1 1 108.57143,0 z" and is usually found as an attribute of a shape with the label "d". All shapes except rectangles have this "d" attribute.
</para>
<para>
Just because a shape has a path does not mean it IS a path however. A path object has no attributes except the path and a style. Calling <link linkend="document.object_to_path">object_to_path()</link> will convert any object to a path, stripping away any other attributes except id and style which stay the same. This will not change the visual appearance but you will no longer be able to use shape handles or affect it by changing any attributes except for "style", "d", and "transform". Some functions may require paths.
</para>
</sect1>
<anchor id="Nodes"/>
<sect1>
<title>Nodes</title>
<para>
To be written.
</para>
</sect1>
</chapter>