Advanced usage

Most users will not need the features described here, but they provide additional power to scripts.

Direct SVG access

Because the Python code is invoked from within an inkex.EffectExtension object's effect method, it is possible to invoke functions from Inkscape's core API. For example, the document as a whole can be read and modified via svg_root, which corresponds to self.svg in a conventionally developed extension.

Variable: svg_root (type inkex.SvgDocumentElement)

From this, it is possible to perform a variety of queries of or transformations on the document as a whole. The following is a simple example:

Example:

svg_root.title = 'My beautiful drawing'

That sets the document title in both a top-level <title> element and as a tag within the document's <metadata> block.

Simple Inkscape Scripting additionally makes available to scripts its own extension object:

Variable: extension (type inkex.EffectExtension)

That is, extension corresponds to what would be self in a conventionally developed extension.

Example:

dir = extension.svg_path()
if dir == "":
    print('The current image is not backed by a file.')
else:
    print(f'The current image can be found in {dir}.')

Arbitrary SVG objects

Objects created directly using Inkscape's inkex API can be made available to Simple Inkscape Scripting by passing them to the inkex_object function:

Function: inkex_object(iobj)

Example:

c = inkex.Circle(cx="200", cy="200", r="50")
inkex_object(c)

Simple Inkscape Scripting supports the complementary operation as well: retrieving the inkex object that underlies any of the objects created using Simple Inkscape Scripting's shape API:

Method: get_inkex_object()

Example:

p1 = path('M 61 196 C 125 132 128 263 192 196 253 132 263 263 320 200 384 128 384 256 448 195 515 131 512 256 576 192',
          stroke='purple', stroke_width=4)
p2 = duplicate(p1, stroke='magenta')
obj = p2.get_inkex_object()
obj.set('d', obj.path.rotate(15, inkex.Vector2d(61, 196)))

The preceding example draws two identical wavy paths, one purple and one magenta. It extracts the inkex.PathElement from the latter and invokes rotate on its path member. Doing so modifies all of the path commands—in contrast to attaching a rotation transform to an unmodified path.

Foreign XML

SVG supports the ability to embed "foreign" (non-SVG) XML within a rectangular region of the image. While Inkscape currently does not display foreign XML—or even acknowledge its existence in the GUI—other SVG renders may.

Function: foreign((x1, y1), (x2, y2), xml)

Place foreign XML string xml within the rectangle extending from (x1, y1) to (x2, y2). xml must represent a single, well-formed, XML element and normally will need to specify its XML namespace. foreign is a shape constructor so it accepts the same common arguments as all other shapes. (Only a few have any impact, however.)

foreign is most commonly used to embed HTML within an image, Although Inkscape does not render HTML foreign objects, all modern web browsers do. Hence, the output of the following example is best viewed in a web browser.

Example:

rect((10, 10), (390, 210), round=25, fill='#e7e8e3', stroke_width='2px')
foreign((20, 20), (380, 200), '''\
<div xmlns="http://www.w3.org/1999/xhtml">
  <h1>Test of foreign XML</h1>

  <table border="1px">
    <tbody>
      <tr><td>Did</td> <td>this</td> <td>work?</td></tr>
      <tr><td>Yes,</td> <td>it</td> <td>did!</td></tr>
      <tr><td>Hurrah!</td> <td>Hurrah!</td> <td>Hooray!</td></tr>
    </tbody>
  </table>
</div>
''')

Note that

1. The code overlays a foreign object atop an ordinary SVG rounded rectangle.
2. The top-level XML element, <div>, specifies that it and its children represent XML elements taken from the HTML namespace (http://www.w3.org/1999/xhtml).
3. Arbitrary HTML fragments are allowed. This example uses an <h1> and a <table> element.