Inkscape Dbus Documentation

Soren Berg


            
          

Version 0.0 -- generated on Friday October 10 2014 from Inkscape BZR revno 13586


Table of Contents

Introduction
I. Concepts
1. Connecting to the API
Overview
Connection example
Shortcut
2. Terminology
Coordinate System
Selections
Groups
Layers and Levels
Style Strings
Paths
Nodes
II. Reference
I. D-Bus API Reference
org.inkscape.application — application interface
org.inkscape.document — document interface
org.inkscape.proposed — proposed interface
Index

Introduction

This is the documentation for scripting Inkscape using Dbus. This framework was developed to let users quickly and easily write scripts to create or manipulate images in a variety of languages. Once the API has stabilized there will also be a C library that encapsulates the Dbus functionality.

The guiding principles behind the design of this API were:

Easy to use: Use of insider terms was limited where possible, and many functions have been simplified to provide a easy entry point for beginning users. Ideally one should not need any experience with Inkscape or even vector graphics to begin using the interface. At the same time, functions that can call arbitrary verbs or manipulate nodes and their attributes directly give knowledgeable users some flexibility.

Interactive: Since Dbus ties in with the main loop, users can mix scripting and mouse driven actions seamlessly. This allows for some unique uses but more importantly makes it easier for people to learn the API since they can play around with it in a scripting console, or even a simple python shell.

Responsive: Since one of the advantages of scripting is the ability to repeat actions many times with great precision it is obvious that the system would have to be fairly fast. The amount of overhead has been limited where possible and functions have been tested for speed. A system to pause updates and only refresh the display after a large number of operations have been completed, ensures that even very complicated renders will not take too long.

Part I. Concepts

Chapter 1. Connecting to the API

Overview

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.

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.

Connection example

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.)

import dbus

#get the session bus.
bus = dbus.SessionBus()

#get the object for the application.
inkapp = bus.get_object('org.inkscape',
                       '/org/inkscape/application')

#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.
doc1 = dbus.Interface(inkdoc1, dbus_interface="org.inkscape.document")

#use!
doc1.rectangle (0,0,100,100)
    

Shortcut

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.

Warning

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.

import dbus

#get the session bus.
bus = dbus.SessionBus()

#get object
inkdoc1 = bus.get_object('org.inkscape', '/org/inkscape/desktop_0')

#get interface
doc1 = dbus.Interface(inkdoc1, dbus_interface="org.inkscape.document")

#ta-da
doc1.rectangle (0,0,100,100)
    

Chapter 2. Terminology

Coordinate System

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.

For example: (100,100) would be just below and to the right of the top left corner of the document.

Selections

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 selection_set(), selection_add(), and selection_box() and then call whatever selection function you need.

Groups

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.

Layers and Levels

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. layer_change_level() changes the order of layers and selection_change_level() changes the order of objects within a layer.

Changing the level of a selection also deserves some explanation. The selection_change_level() 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.

Style Strings

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.

Paths

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.

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 object_to_path() 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.

Nodes

To be written.

Part II. Reference

Table of Contents

I. D-Bus API Reference
org.inkscape.application — application interface
org.inkscape.document — document interface
org.inkscape.proposed — proposed interface

D-Bus API Reference


Inkscape provides a D-Bus API for programs to interactivly script vector graphics.

This API is not yet stable and is likely to change in the future.

Table of Contents

org.inkscape.application — application interface
org.inkscape.document — document interface
org.inkscape.proposed — proposed interface

Name

org.inkscape.application — application interface

Methods

desktop_new         (out 's'  desktop_name)
get_desktop_list    (out 'as' document_list)
desktop_close_all   ()
exit                ()
document_new        (out 's'  document_name)
get_active_document (out 's'  document_name)

Implemented Interfaces

Objects implementing org.inkscape.application also implements org.freedesktop.DBus.Introspectable, org.freedesktop.DBus.Properties

Description

Details

desktop_new ()

desktop_new (out 's' desktop_name)

Create a new document interface and return its location. Only call this when Inkscape is running in GUI mode.

desktop_name:
This string can be used to connect to the new interface that was created.

get_desktop_list ()

get_desktop_list (out 'as' document_list)

List all the interfaces that it is possible to connect to. TODO: not implemented.

document_list:
A list of interfaces being provided by Inkscape.

desktop_close_all ()

desktop_close_all ()

Close all document interfaces without saving. TODO: not implemented.

exit ()

exit ()

Exit Inkscape without saving. Fairly straightforward.

document_new ()

document_new (out 's' document_name)

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.

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.

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.

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.

document_name:
This string can be used to connect to the new interface that was created.

get_active_document ()

get_active_document (out 's' document_name)

Get the location of the current active document (e.g. when running in console mode, when desktops are not available).

document_name:
This string can be used to connect to the current active document.

Name

org.inkscape.document — document interface

Methods

delete_all                       ()
call_verb                        (in  's'  verbid)
rectangle                        (in  'i'  x,
                                  in  'i'  y,
                                  in  'i'  width,
                                  in  'i'  height,
                                  out 's'  object_name)
ellipse                          (in  'i'  x,
                                  in  'i'  y,
                                  in  'i'  width,
                                  in  'i'  height,
                                  out 's'  object_name)
polygon                          (in  'i'  cx,
                                  in  'i'  cy,
                                  in  'i'  radius,
                                  in  'i'  rotation,
                                  in  'i'  sides,
                                  out 's'  object_name)
star                             (in  'i'  cx,
                                  in  'i'  cy,
                                  in  'i'  r1,
                                  in  'i'  r2,
                                  in  'd'  arg1,
                                  in  'd'  arg2,
                                  in  'i'  sides,
                                  in  'd'  rounded,
                                  out 's'  object_name)
spiral                           (in  'i'  cx,
                                  in  'i'  cy,
                                  in  'i'  r,
                                  in  'i'  revolutions,
                                  out 's'  object_name)
line                             (in  'i'  x,
                                  in  'i'  y,
                                  in  'i'  x2,
                                  in  'i'  y2,
                                  out 's'  object_name)
text                             (in  'i'  x,
                                  in  'i'  y,
                                  in  's'  text,
                                  out 's'  object_name)
image                            (in  'i'  x,
                                  in  'i'  y,
                                  in  's'  text,
                                  out 's'  object_name)
import                           (in  's'  pathname,
                                  out 's'  object_name)
node                             (in  's'  svgtype,
                                  out 's'  node_name)
document_get_width               (out 'd'  val)
document_get_height              (out 'd'  val)
document_get_css                 (out 's'  css)
document_set_css                 (in  's'  stylestring)
document_merge_css               (in  's'  stylestring)
document_resize_to_fit_selection ()
document_set_display_area        (in  'd'  x0,
                                  in  'd'  y0,
                                  in  'd'  x1,
                                  in  'd'  y1,
                                  in  'd'  border)
document_get_display_area        (out 'ad' area)
set_attribute                    (in  's'  shape,
                                  in  's'  attribute,
                                  in  's'  newval)
set_text                         (in  's'  shape,
                                  in  's'  text)
text_apply_style                 (in  's'  shape,
                                  in  'i'  start,
                                  in  'i'  end,
                                  in  's'  css_attrib,
                                  in  's'  css_attrib_val)
set_int_attribute                (in  's'  shape,
                                  in  's'  attribute,
                                  in  'i'  newval)
set_double_attribute             (in  's'  shape,
                                  in  's'  attribute,
                                  in  'd'  newval)
get_attribute                    (in  's'  shape,
                                  in  's'  attribute,
                                  out 's'  val)
move                             (in  's'  shape,
                                  in  'd'  x,
                                  in  'd'  y)
move_to                          (in  's'  shape,
                                  in  'd'  x,
                                  in  'd'  y)
object_to_path                   (in  's'  objectname)
get_path                         (in  's'  shape,
                                  out 's'  val)
transform                        (in  's'  shape,
                                  in  's'  transformstr)
get_css                          (in  's'  shape,
                                  out 's'  css)
modify_css                       (in  's'  shape,
                                  in  's'  cssattrib,
                                  in  's'  newval)
merge_css                        (in  's'  shape,
                                  in  's'  stylestring)
set_color                        (in  's'  shape,
                                  in  'i'  red,
                                  in  'i'  green,
                                  in  'i'  blue,
                                  in  'b'  fill)
move_to_layer                    (in  's'  objectname,
                                  in  's'  layername)
get_node_coordinates             (in  's'  shape,
                                  out 'ai' points)
save                             ()
save_as                          (in  's'  pathname)
load                             (in  's'  pathname)
mark_as_unmodified               ()
close                            ()
exit                             ()
undo                             ()
redo                             ()
pause_updates                    ()
resume_updates                   ()
update                           ()
selection_get                    (out 'as' listy)
selection_add                    (in  's'  name)
selection_add_list               (in  'as' name)
selection_set                    (in  's'  name)
selection_set_list               (in  'as' name)
selection_rotate                 (in  'i'  angle)
selection_delete                 ()
selection_clear                  ()
select_all                       ()
select_all_in_all_layers         ()
selection_box                    (in  'i'  x,
                                  in  'i'  y,
                                  in  'i'  x2,
                                  in  'i'  y2,
                                  in  'b'  replace)
selection_invert                 ()
selection_group                  ()
selection_ungroup                ()
selection_cut                    ()
selection_copy                   ()
selection_paste                  ()
selection_scale                  (in  'd'  grow)
selection_move                   (in  'd'  x,
                                  in  'd'  y)
selection_move_to                (in  'd'  x,
                                  in  'd'  y)
selection_move_to_layer          (in  's'  layer)
selection_get_center             (out 'ad' centerpoint)
selection_to_path                ()
selection_combine                (in  's'  type,
                                  out 'as' newpaths)
selection_change_level           (in  's'  command,
                                  out 'b'  objectsmoved)
layer_new                        (out 's'  layername)
layer_set                        (in  's'  layer)
layer_get_all                    (out 'as' layers)
layer_change_level               (in  's'  command,
                                  out 'b'  layermoved)
layer_next                       ()
layer_previous                   ()
get_children                     (in  's'  type,
                                  out 'as' parentid)
get_parent                       (in  's'  type,
                                  out 's'  parentid)

Signals

ObjectMoved ('s' object_name)

Implemented Interfaces

Objects implementing org.inkscape.document also implements org.freedesktop.DBus.Introspectable, org.freedesktop.DBus.Properties

Description

Details

delete_all ()

delete_all ()

call_verb ()

call_verb (in  's' verbid)

This method allows you to call any Inkscape verb using it's associated string. Every button and menu item has an associated verb, so this allows access to some extra functionality if one is willing to do the prerequisite research. The list of verbs can be found at:

verbid:
The string id of a verb. For example: "EditSelectAll".

rectangle ()

rectangle (in  'i' x,
           in  'i' y,
           in  'i' width,
           in  'i' height,
           out 's' object_name)

This method creates a rectangle in the current layer using the current document style.

It is recommended that you save the return value if you will want to modify this particular shape later.

Additional variables include:

cx and cy: set these anywhere from zero to half the width or height respectively of the rectangle to give it rounded corners.

x:
X coordinate for the top left corner of the rectangle.
y:
Y coordinate for the top left corner of the rectangle.
width:
Width of the rectangle.
height:
Height of the rectangle.
object_name:
The name of the new rectangle.

See also: Coordinate System

ellipse ()

ellipse (in  'i' x,
         in  'i' y,
         in  'i' width,
         in  'i' height,
         out 's' object_name)

This method creates a ellipse in the current layer using the current document style.

It is recommended that you save the return value if you will want to modify this particular shape later.

Additional variables include:

"sodipodi:start" and "sodipodi:end": set these between 0 and Pi to create wedges or Pacman like shapes.

x:
X coordinate for the top left corner of the ellipse.
y:
Y coordinate for the top left corner of the ellipse.
width:
Width of the ellipse.
height:
Height of the ellipse.
object_name:
The name of the new ellipse.

See also: Coordinate System

polygon ()

polygon (in  'i' cx,
         in  'i' cy,
         in  'i' radius,
         in  'i' rotation,
         in  'i' sides,
         out 's' object_name)

This method creates a polygon in the current layer using the current document style.

It is recommended that you save the return value if you will want to modify this particular shape later.

Note: this is actually a star with "sodipodi:flatsided" set to true, which causes it to ignore the arg2 and r2 values.

cx:
X coordinate for the center of the polygon.
cy:
Y coordinate for the center of the polygon.
radius:
Radius from the center to one of the points.
rotation:
Angle in degrees to rotate. 0 will have the first point pointing straight up.
sides:
Number of sides of the polygon.
object_name:
The name of the new polygon.

See also: Coordinate System

star ()

star (in  'i' cx,
      in  'i' cy,
      in  'i' r1,
      in  'i' r2,
      in  'd' arg1,
      in  'd' arg2,
      in  'i' sides,
      in  'd' rounded,
      out 's' object_name)

This method creates a star in the current layer using the current document style.

It is recommended that you save the return value if you will want to modify this particular shape later.

Stars are quite complicated. Here is how they are represented: There are two points, represented by sodipodi:arg1 and sodipodi:arg2 for angle in radians and sodipodi:r1 and sodipodi:r2 for respective radius from the center point. The further one is a point of the star, the shorter one one of the valleys. This point and valley are repeated according to sodipodi:sides. sodipodi:rounded controls their control handles.

cx:
X coordinate for the center of the star.
cy:
Y coordinate for the center of the star.
r1:
distance from the center for the first point.
r2:
distance from the center for the second point.
arg1:
Angle in radians for the first point. 0 is 90 degrees to the right of straight up.
arg2:
Angle in radians for the second point. 0 is 90 degrees to the right of straight up.
sides:
Number of times to repeat the points around the star.
rounded:
How rounded to make the star. 0 to 1 recommended for moderate to medium curves. 10 for extreme curves.
object_name:
The name of the new star.

See also: Coordinate System

spiral ()

spiral (in  'i' cx,
        in  'i' cy,
        in  'i' r,
        in  'i' revolutions,
        out 's' object_name)

This method creates a spiral in the current layer using the current document style. However, fill is automatically set to "none". Stroke is unmodified.

It is recommended that you save the return value if you will want to modify this particular shape later.

Additional variables include:

"sodipodi:expansion": at 1 the spiral gets bigger at a constant rate. Less than one and the loops get tighter and tighter as it goes. More than one and they get looser and looser. This affects the number of revolutions so that it might not actually match the "sodipodi:revolutions" argument.

"sodipodi:t0": at 0 the entire spiral is drawn, at 0.5 it is only drawn %50 of the way (starting from the outside) etc.

"sodipodi:argument": Rotates the spiral. In radians.

cx:
X coordinate for the center of the spiral.
cy:
Y coordinate for the center of the spiral.
r:
Radius of the spiral.
revolutions:
Number of revolutions.
object_name:
The name of the new spiral.

See also: Coordinate System

line ()

line (in  'i' x,
      in  'i' y,
      in  'i' x2,
      in  'i' y2,
      out 's' object_name)

This method creates a line in the current layer using the current document style. It's a path, so the only attribute it will pay any attention to is "transform".

x:
X coordinate for the first point.
y:
Y coordinate for the first point.
x2:
X coordinate for the second point.
y2:
Y coordinate for the second point.
object_name:
The name of the new line.

See also: Coordinate System

text ()

text (in  'i' x,
      in  'i' y,
      in  's' text,
      out 's' object_name)

This method creates some text in the current layer.

x:
The x coordinate to put the text at.
y:
The y coordinate to put the text at.
text:
The text you want.
object_name:
The name of the new text.

image ()

image (in  'i' x,
       in  'i' y,
       in  's' text,
       out 's' object_name)

This method imports a non-vector image (such as a jpeg, png, etc.) and places it at the given coordinates. The resulting shape has no style or path but can be treated like a rectangle. With and height can be set explicitly (will deform image) or transform strings or selection_scale() can scale it relatively.

x:
The x coordinate to put the image at.
y:
The y coordinate to put the image at.
text:
The full path of the image you want.
object_name:
The name of the new image.

import ()

import (in  's' pathname,
        out 's' object_name)

Imports the file at pathname. Similar to the image method.

pathname:
The path to a valid svg file.
object_name:
The name of the new image.

node ()

node (in  's' svgtype,
      out 's' node_name)

Make any kind of node you want. Mostly for making paths. (May need to allow updateRepr to be called for it to show up.)

svgtype:
The type of node, probably "svg:path"
node_name:
The name of the new node.

document_get_width ()

document_get_width (out 'd' val)

Retrieve the width of the current document. anything outside the boundary will not be printed or exported but will be saved.

val:
Document width.

document_get_height ()

document_get_height (out 'd' val)

Retrieve the height of the current document. anything outside the boundary will not be printed or exported but will be saved.

val:
Document height.

document_get_css ()

document_get_css (out 's' css)

Get the current style for the document. All new shapes will use this style if it exists.

css:
CSS attribute string for the document.

See also: Style Strings

document_set_css ()

document_set_css (in  's' stylestring)

Set the current style for the document. All new shapes will use this style if it exists.

stylestring:
A new CSS attribute string for the document.

See also: Style Strings

document_merge_css ()

document_merge_css (in  's' stylestring)

Merge this this string with the current style for the document. All new shapes will use this style if it exists.

stylestring:
A new CSS attribute string for the document.

See also: Style Strings, merge_css()

document_resize_to_fit_selection ()

document_resize_to_fit_selection ()

Resize the document to contain all of the currently selected objects.

This ensures that the image is not clipped when printing or exporting.

document_set_display_area ()

document_set_display_area (in  'd' x0,
                           in  'd' y0,
                           in  'd' x1,
                           in  'd' y1,
                           in  'd' border)

Set display area.

x0:
y0:
x1:
y1:
border:

document_get_display_area ()

document_get_display_area (out 'ad' area)

Get display area.

area:
area

set_attribute ()

set_attribute (in  's' shape,
               in  's' attribute,
               in  's' newval)

Set any attribute, the available attributes depend on what kind of shape the object node represents. See shape creation functions for more details.

shape:
The id of an object.
attribute:
The name of the attribute.
newval:
The new value of the attribute. This will overwrite anything already set. To merge styles, see merge_css().

set_text ()

set_text (in  's' shape,
          in  's' text)

set text of text object.

shape:
The id of an object.
text:
The text you want.

text_apply_style ()

text_apply_style (in  's' shape,
                  in  'i' start,
                  in  'i' end,
                  in  's' css_attrib,
                  in  's' css_attrib_val)

set styling of partial text object.

shape:
The id of an object.
start:
start text pos.
end:
end text pos.
css_attrib:
css attribute.
css_attrib_val:
css attribute value.

set_int_attribute ()

set_int_attribute (in  's' shape,
                   in  's' attribute,
                   in  'i' newval)

Set any attribute, the available attributes depend on what kind of shape the object node represents. See shape creation functions for more details.

This is a convenience function for set_attribute().

shape:
The id of an object.
attribute:
The name of the attribute.
newval:
The new value of the attribute. This will overwrite anything already set.

set_double_attribute ()

set_double_attribute (in  's' shape,
                      in  's' attribute,
                      in  'd' newval)

Set any attribute, the available attributes depend on what kind of shape the node represents. See shape creation functions for more details.

This is a convenience function for set_attribute().

shape:
The id of an object.
attribute:
The name of the attribute.
newval:
The new value of the attribute. This will overwrite anything already set.

get_attribute ()

get_attribute (in  's' shape,
               in  's' attribute,
               out 's' val)

Get the value of any attribute. Not all objects will have every attribute their type supports, some are optional. See shape creation functions for more details.

shape:
The id of an object.
attribute:
The name of the attribute.
val:
The current value of the attribute. String is a copy and must be freed.

move ()

move (in  's' shape,
      in  'd' x,
      in  'd' y)

This will move a shape (or any object) relative to it's current location.

This may be accomplished with transformation attributes or by changing x and y attributes depending on the state of the object.

shape:
The id of an object.
x:
Distance to move along the x axis.
y:
Distance to move along the y axis.

See also: Coordinate System

move_to ()

move_to (in  's' shape,
         in  'd' x,
         in  'd' y)

This will move a shape (or any object) to an absolute location. The point moved is the center of the bounding box, which is usually similar to the center of the shape.

Note that creating a rectangle or ellipse at 100,100 and calling move_to to move it to 100,100 will not produce the same results.

This may be accomplished with transformation attributes or by changing x and y attributes depending on the state of the object.

shape:
The id of an object.
x:
the x coordinate of the desired location.
y:
the y coordinate of the desired location.

See also: Coordinate System

object_to_path ()

object_to_path (in  's' objectname)

Turns an object into a path. Most objects contain paths (except rectangles) but are not paths themselves.

This will remove every attribute except d (the path attribute) style and id. id will not change. The appearance will be the same as well, it essentially encodes all information about the shape into the path.

After doing this you will no longer be able to modify the shape using shape specific attributes (cx, radius etc.) except transform

Required for certain functions that work on paths (not yet present in this API.)

objectname:
The id of an object.

See also: Paths

get_path ()

get_path (in  's' shape,
          out 's' val)

Get the path value of an object. Equivilent to calling get_attribte() with argument "d". Will not turn object into a path if it is not already.

shape:
The id of an object.
val:
The path of the object. NULL if the object has no path.

See also: Paths

transform ()

transform (in  's' shape,
           in  's' transformstr)

Takes a transformation string ("matrix(0.96629885,0.25742286,-0.25742286,0.96629885,0,0)" or "rotate(45)") and applies it to any shape or path.

Will merge with existing transformations.

shape:
The id of any node or object.
transformstr:
A string that represents a transformation.

get_css ()

get_css (in  's' shape,
         out 's' css)

Retrieve the style of a object. Equivalent to calling get_attribute() for "style".

shape:
Any object with a style attribute.
css:
A CSS Style string

See also: Style Strings

modify_css ()

modify_css (in  's' shape,
            in  's' cssattrib,
            in  's' newval)

Set a particular attribute of a style string. Overwrites just that part of the style.

shape:
Any object with a style attribute.
cssattrib:
An attribute such as "fill" or "stroke-width".
newval:
The new value.

See also: Style Strings

merge_css ()

merge_css (in  's' shape,
           in  's' stylestring)

Takes a CSS Style string and merges it with the objects current style, overwriting only the elements present in stylestring.

shape:
Any object with a style attribute.
stylestring:
A full or partial CSS Style string.

See also: Style Strings

set_color ()

set_color (in  's' shape,
           in  'i' red,
           in  'i' green,
           in  'i' blue,
           in  'b' fill)

Modifies the fill or stroke color of an object (or the document style) based on RGB values.

Red green and blue must be between 0-255 inclusive.

shape:
Any object, or 'document' to apply to document style.
red:
The red component.
green:
The green component.
blue:
The blue component.
fill:
True to change fill color, false for stroke color.

move_to_layer ()

move_to_layer (in  's' objectname,
               in  's' layername)

Moves an object to a different layer.

Will error if layer does not exist.

objectname:
The id of an object.
layername:
A layer name.

See also: layer_new()

get_node_coordinates ()

get_node_coordinates (in  's'  shape,
                      out 'ai' points)

Returns an array of all of the X,Y coordinates of the points in the objects path.

If the path is a closed loop the first point is repeated at the end.

shape:
A object that contains a path ("d") attribute.
points:
An array of points.

save ()

save ()

Saves the current document with current name or a default name if has not been saved before.

Will overwrite without confirmation.

save_as ()

save_as (in  's' pathname)

Saves the current document as pathname.

Will overwrite without confirmation.

pathname:
The path for the file to be saved as.

load ()

load (in  's' pathname)

Loads the file at pathname.

Will lose all unsaved work in current document.

pathname:
The path to a valid svg file.

mark_as_unmodified ()

mark_as_unmodified ()

Marks the document as unmodified/saved.

Will prevent save confirmation on close if called at end of script.

close ()

close ()

Close this document.

You will not be able to send any more commands on this interface.

exit ()

exit ()

Exit Inkscape.

You will not be able to send any more commands on any interface.

undo ()

undo ()

Undo the last action.

redo ()

redo ()

Redo the last undone action.

pause_updates ()

pause_updates ()

When updates are paused Inkscape will not draw every change as it is made. Also you will not be able to undo individual actions made while updates were paused and will only be able to undo them in a group. Inkscape may refresh the screen every couple of seconds even with updates off.

The advantage is a 2-5x speed increase, depending on the type of functions being called. This is most useful when creating large numbers of shapes.

resume_updates ()

resume_updates ()

Resume updates after they have been paused. If undo is called at this point it will undo everything that happened since pause_updates() was called.

This will update the display to show any changes that happened while updates were paused, a separate call to update() is not necessary.

update ()

update ()

This will update the document once if updates are paused but it will not resume updates.

This could be used to check on the progress of a complex drawing function, or to add in undo steps at certain points in a render.

selection_get ()

selection_get (out 'as' listy)

Returns the current selection in the form of a list of ids of selected objects.

Manipulating this list will not affect the selection.

listy:
List of the ids of currently selected objects.

selection_add ()

selection_add (in  's' name)

Adds a single object to the selection.

name:
A object to add to the selection.

selection_add_list ()

selection_add_list (in  'as' name)

Adds a list of objects to the selection.

name:
An array of object ids to add to the selection.

selection_set ()

selection_set (in  's' name)

Replaces the selection with one containing just this object.

name:
A object to select.

selection_set_list ()

selection_set_list (in  'as' name)

Replaces the selection with one containing just these objects.

name:
A list of objects to select.

selection_rotate ()

selection_rotate (in  'i' angle)

Rotates the selection around the center of it's bounding box.

angle:
Angle in degrees to rotate.

selection_delete ()

selection_delete ()

Delete all objects in the selection.

selection_clear ()

selection_clear ()

Deselect everything. Selection will be empty.

select_all ()

select_all ()

Select all objects in current layer.

select_all_in_all_layers ()

select_all_in_all_layers ()

Select all objects in every layer.

selection_box ()

selection_box (in  'i' x,
               in  'i' y,
               in  'i' x2,
               in  'i' y2,
               in  'b' replace)

This method finds all of the objects inside the box and adds them to the current selection. If replace is true it will clear the old selection first.

x:
X coordinate for the first point.
y:
Y coordinate for the first point.
x2:
X coordinate for the second point.
y2:
Y coordinate for the second point.
replace:
True to replace selection, false to add to selection.

selection_invert ()

selection_invert ()

Invert the selection in the current layer.

selection_group ()

selection_group ()

Group the selection.

See also: Groups

selection_ungroup ()

selection_ungroup ()

Ungroup the selection.

See also: Groups

selection_cut ()

selection_cut ()

Cut the current selection.

selection_copy ()

selection_copy ()

Copy the current selection.

selection_paste ()

selection_paste ()

Paste the current selection at the same location it was cut from.

To paste to a particular location, simply use selection_paste() followed by selection_move_to().

selection_scale ()

selection_scale (in  'd' grow)

Scale the selection relative to it's current size.

grow:
The amount to scale the selection, 1 has no effect. Between 0 and 1 will shrink it proportionally. Greater than one will grow it proportionally.

selection_move ()

selection_move (in  'd' x,
                in  'd' y)

This will move the selection relative to it's current location.

This may be accomplished with transformation attributes or by changing x and y attributes depending on the state of the objects in the selection.

x:
Amount to move in the x direction.
y:
Amount to move in the y direction.

See also: Coordinate System

selection_move_to ()

selection_move_to (in  'd' x,
                   in  'd' y)

This will move the center of the selection to a specific location.

This may be accomplished with transformation attributes or by changing x and y attributes depending on the state of the objects in the selection.

x:
X coordinate to move to.
y:
Y coordinate to move to.

See also: Coordinate System

selection_move_to_layer ()

selection_move_to_layer (in  's' layer)

Move every item in the selection to a different layer.

Will error if layer does not exist.

layer:
layer to move the selection to.

See also: Layers and Levels

selection_get_center ()

selection_get_center (out 'ad' centerpoint)

Gets the center of the selections bounding box in X,Y coordinates.

centerpoint:
Center of the selection.

See also: Coordinate System

selection_to_path ()

selection_to_path ()

Turns all the objects in the selection into paths.

See also: object_to_path()

selection_combine ()

selection_combine (in  's'  type,
                   out 'as' newpaths)

Will erase all objects in the selection and replace with a single aggregate path.

There are 5 types that can be passed in:

'union': The new shape is all of the other shapes put together, even if they don't overlap (paths can have multiple non-contiguous areas.)

'intersection': The new shape is composed of the area where ALL the objects in the selection overlap. If there is no area where all shapes overlap the new shape will be empty.

'difference': The area of the second shape is subtracted from the first, only works with two objects.

'exclusion': The new shape is the area(s) where none of the objects in the selection overlaped. Only works with two objects.

'division': the first object is split into multiple segments by the second object. Only works with two objects.

type:
Type of combination.
newpaths:
List of the ids of resulting paths after applying the operation.

selection_change_level ()

selection_change_level (in  's' command,
                        out 'b' objectsmoved)

Will change the level of a selection, respective of other objects in the same layer. Will not affect the overlap of objects in different layers. Will do nothing if the selection contains objects in multiple layers.

There are 4 commands that can be passed in:

"raise" or "lower": Move the selection one level up, or one level down.

"to_top" of "to_bottom": Move the selection above all other objects or below all other objects.

command:
How to change the level
objectsmoved:
True if the objects changed levels. False if they don't(if they were already on top when being raised for example.)

layer_new ()

layer_new (out 's' layername)

Turns all the objects in the selection into paths.

layername:
The name of the new layer.

See also: Layers and Levels

layer_set ()

layer_set (in  's' layer)

Sets the layer given as the current layer

layer:
The name of any layer.

See also: Layers and Levels

layer_get_all ()

layer_get_all (out 'as' layers)

Get a list of all the layers in this document.

layers:
list of layers.

See also: Layers and Levels

layer_change_level ()

layer_change_level (in  's' command,
                    out 'b' layermoved)

Will change the level of a layer, respective of other layers. Will not affect the relative level of objects within the layer.

There are 4 commands that can be passed in:

"raise" or "lower": Move the layer one level up, or one level down.

"to_top" of "to_bottom": Move the layer above all other layers or below all other layers.

command:
How to change the level
layermoved:
True if the layer was moved. False if it was not (if it was already on top when being raised for example.)

layer_next ()

layer_next ()

Sets the next (or higher) layer as active.

See also: Layers and Levels

layer_previous ()

layer_previous ()

Sets the previous (or lower) layer as active.

See also: Layers and Levels

get_children ()

get_children (in  's'  type,
              out 'as' parentid)

Returns the children of any node. This function along with get_parent() can be used to navigate the XML tree.

type:
Any node with an "id" attribute.
parentid:
The ids of this nodes children, NULL if bottom level.

get_parent ()

get_parent (in  's' type,
            out 's' parentid)

Returns the parent of any node. This function along with get_children() can be used to navigate the XML tree.

type:
Any node with an "id" attribute.
parentid:
The id of this nodes parent, NULL if toplevel.

Signal Details

The ObjectMoved signal

ObjectMoved ('s' object_name)

Emitted when an object has been moved.

object_name:
The id of the object.

Name

org.inkscape.proposed — proposed interface

Methods

path_new         (in  'd'  x,
                  in  'd'  y)
path_append      (in  's'  path,
                  in  's'  type,
                  in  'ad' arguments)
selection_remove (in  's'  name)

Signals

Signals_Proposal       ()
ObjectResized          ('s' object_name)
ObjectStyleModified    ('s' object_name)
ObjectCreated          ('s' object_name)
ObjectAddedToSelection ('s' object_name)

Implemented Interfaces

Objects implementing org.inkscape.proposed also implements org.freedesktop.DBus.Introspectable, org.freedesktop.DBus.Properties

Description

Details

path_new ()

path_new (in  'd' x,
          in  'd' y)

Begins a new path, extra nodes can be added with path_append().

x:
The x value to begin the path.
y:
The y value to begin the path.

path_append ()

path_append (in  's'  path,
             in  's'  type,
             in  'ad' arguments)

Adds to an existing path. Close the path by sending "z" and no arguments.

You can no longer append to a path if it is closed.

path:
The name of the path to append to.
type:
A single letter denoting what type of node is beeing appended.
arguments:
An array of numbers that describe the position and attributes of the path node.

selection_remove ()

selection_remove (in  's' name)

Removes a single object from the selection. In proposed because I already have a ton of selection functions and am not sure people would need this.

name:
A object to remove from the selection.

Signal Details

The Signals_Proposal signal

Signals_Proposal ()

Signals would undoubtedly be a useful thing to have in many circumstances. They are in proposed for two reasons: One, they complicate things for script writers and may conflict with the proposed C wrapper library. Two, I'm not sure how much coding it would take to implement them because I am familiar with neither Dbus signals or Inkscape events. Until I have done more experimenting I don't want to promise anything I'm not sure can be implemented in a timely fashion.

The ObjectResized signal

ObjectResized ('s' object_name)

Emitted when an object has been resized.

object_name:
The id of the object.

The ObjectStyleModified signal

ObjectStyleModified ('s' object_name)

Emitted when the style of an object has been changed.

object_name:
The id of the object.

The ObjectCreated signal

ObjectCreated ('s' object_name)

Emitted when an object has been created. Possibly useful for working in conjunction with a live user.

object_name:
The id of the object.

The ObjectAddedToSelection signal

ObjectAddedToSelection ('s' object_name)

Emitted when an object has been added to the selection. Possibly useful for working in conjunction with a live user.

object_name:
The id of the object.

Index

C

call_verb
document, call_verb ()
close
document, close ()

D

delete_all
document, delete_all ()
desktop_close_all
application, desktop_close_all ()
desktop_new
application, desktop_new ()
document_get_css
document, document_get_css ()
document_get_display_area
document, document_get_display_area ()
document_get_height
document, document_get_height ()
document_get_width
document, document_get_width ()
document_merge_css
document, document_merge_css ()
document_new
application, document_new ()
document_resize_to_fit_selection
document, document_resize_to_fit_selection ()
document_set_css
document, document_set_css ()
document_set_display_area
document, document_set_display_area ()

E

ellipse
document, ellipse ()
exit
application, exit ()
document, exit ()

G

get_active_document
application, get_active_document ()
get_attribute
document, get_attribute ()
get_children
document, get_children ()
get_css
document, get_css ()
get_desktop_list
application, get_desktop_list ()
get_node_coordinates
document, get_node_coordinates ()
get_parent
document, get_parent ()
get_path
document, get_path ()

I

image
document, image ()
import
document, import ()

L

layer_change_level
document, layer_change_level ()
layer_get_all
document, layer_get_all ()
layer_new
document, layer_new ()
layer_next
document, layer_next ()
layer_previous
document, layer_previous ()
layer_set
document, layer_set ()
line
document, line ()
load
document, load ()

M

mark_as_unmodified
document, mark_as_unmodified ()
merge_css
document, merge_css ()
modify_css
document, modify_css ()
move
document, move ()
move_to
document, move_to ()
move_to_layer
document, move_to_layer ()

N

node
document, node ()

O

ObjectAddedToSelection
proposed, The ObjectAddedToSelection signal
ObjectCreated
proposed, The ObjectCreated signal
ObjectMoved
document, The ObjectMoved signal
ObjectResized
proposed, The ObjectResized signal
ObjectStyleModified
proposed, The ObjectStyleModified signal
object_to_path
document, object_to_path ()

P

path_append
proposed, path_append ()
path_new
proposed, path_new ()
pause_updates
document, pause_updates ()
polygon
document, polygon ()

R

rectangle
document, rectangle ()
redo
document, redo ()
resume_updates
document, resume_updates ()

S

save
document, save ()
save_as
document, save_as ()
selection_add
document, selection_add ()
selection_add_list
document, selection_add_list ()
selection_box
document, selection_box ()
selection_change_level
document, selection_change_level ()
selection_clear
document, selection_clear ()
selection_combine
document, selection_combine ()
selection_copy
document, selection_copy ()
selection_cut
document, selection_cut ()
selection_delete
document, selection_delete ()
selection_get
document, selection_get ()
selection_get_center
document, selection_get_center ()
selection_group
document, selection_group ()
selection_invert
document, selection_invert ()
selection_move
document, selection_move ()
selection_move_to
document, selection_move_to ()
selection_move_to_layer
document, selection_move_to_layer ()
selection_paste
document, selection_paste ()
selection_remove
proposed, selection_remove ()
selection_rotate
document, selection_rotate ()
selection_scale
document, selection_scale ()
selection_set
document, selection_set ()
selection_set_list
document, selection_set_list ()
selection_to_path
document, selection_to_path ()
selection_ungroup
document, selection_ungroup ()
select_all
document, select_all ()
select_all_in_all_layers
document, select_all_in_all_layers ()
set_attribute
document, set_attribute ()
set_color
document, set_color ()
set_double_attribute
document, set_double_attribute ()
set_int_attribute
document, set_int_attribute ()
set_text
document, set_text ()
Signals_Proposal
proposed, The Signals_Proposal signal
spiral
document, spiral ()
star
document, star ()

T

text
document, text ()
text_apply_style
document, text_apply_style ()
transform
document, transform ()

U

undo
document, undo ()
update
document, update ()