How to Write Extensions

This guide video series will focus on writing python extensions from beginners through to advanced subjects, you should know the basics of python and some understanding of how SVG works to get the best use out of this guide. For information about the C++ or XSLT extensions see the main Inkscape development information.

Writing Extensions (Text Guide)

Extension types

The following extension types exist for Inkscape:

• input (read a file / data, e.g. "DHW file input" extension which is used to import *.dhw file into Inkscape)
• output (write a file / data, e.g. "GIMP XCF" extension which is used to export from Inkscape to GIMP XCF file format)
• effect (change contents in the document, most extensions in "Extensions" menu belong to that category)
• print (output to an external device, e.g.

Extension implementation

Overview

• Internal
  • C++ implementation (directly in Inkscape's codebase)
• External
  • scripts - e.g. python, perl or as system (console) scripts
  • XSL transformations

User Interface and parameter types: Extension Definition File (INX)

All extensions are defined through Inkscape Extension Definition Files (.inx) which are XML files in the

http://www.inkscape.org/namespace/inkscape/extension

namespace and described by the Relax NG available [here].

Parameters

Extensions can be supplied with values obtained through easily definable parameters. Inkscape provides the basic GUI for user input. The following parameters are supported:

• int (for an integer number input field)
• string (for a text input field)
• float (for a float number input field)
• boolean (for a checkbox)
• enum (for a dropdown list)
• optiongroup (for a dropdown list or radio buttons)
• color (for a color selector, like the one in the Fill & Stroke dialog)

For the sake of the UI there are also the following two parameters that do not provide data to the extension but alter the user input GUI.

• description (for descriptions below parameters)
• notebook (for tabs)

See also: INX Parameters

Structure

RadioButton example

The following mark-up:

<?xml version="1.0" encoding="UTF-8"?>
<inkscape-extension xmlns="http://www.inkscape.org/namespace/inkscape/extension">
  <_name>RadioButton example</_name>
  <id>org.inkscape.effect.radiobuttontest</id>
  <param name="radio1" type="optiongroup" _gui-text="Select option: ">
    <option value="string1">translatable string 1</option>
    <option value="string2">string 2</option>
    <option value="string3">test 3!</option>
  </param>
  <param name="radio2" type="optiongroup" _gui-text="Select second option: ">
    <option value="string11">string1</option>
    <option value="string22">string2</option>
    <option>test3!</option>
  </param>
  <effect>
    <object-type>all</object-type>
    <effects-menu>
      <submenu _name="Developer Examples"/>
    </effects-menu>
  </effect>
  ...
</inkscape-extension>

Will result in the following GUI being created:

Translations

To allow the .inx files to fit snugly into Inkscape's i18n infrastructure some XML elements and attributes are prefixed with an underscore (_) character to indicate that the containing text should be marked for translation.

The extension script: a script written in the programming language of your choice

Inkscape comes with some .py files (foremost inkex.py) which supply you with some basic functionality (like error messages, getting ids of selected elements, etc.) you can build on with your extension, if you write it in Python.

Find the inkex.py API reference (for Inkscape >= 1.0) on GitLab.

Draft extension tutorials for 1.0

For examples, please take a look into the "extensions" folder of your Inkscape installation. It is recommended to take a look at an extension that does something similar to what your new extension will do (e.g. modify path data, write a file, import a specific file format, send data to plotter or printer), to see how it could be done. On a typical UNIX distribution, the folder may be in /usr/share/inkscape/extensions/.

Alternatively, it can also be viewed online at https://gitlab.com/inkscape/extensions/-/tree/master .

Some more information is also available in the following locations:

• INX extension descriptor format
• Extension documentation (auto-generated)
• Documentation of extension utility functions (auto-generated)

Sharing your extension

So you've written a new Inkscape extension for yourself now, to suit your own needs. Wouldn't it be great if others, who need the same, but don't know how to program, could also use your extension, and maybe give feedback to you, and suggest enhancements, or if other programmers could join you to help improve your extension?

To achieve this, you'll need to do the following:

• License your extension with an open source software license, e.g. GPL, like Inkscape.
• Keep your extension in a place where others can help with development, i.e. a website that allows developers to collaborate like GitLab, for example.
• Share your extension with other users by uploading it to this website, into your InkSpace gallery.
  It must follow all website code of conduct rules AND the extensions guidelines.
  Extensions which break any of the rules may be removed or edited to comply with the rules.
  • Open the upload form.
  • Upload your extension files, archived to a single zip file.
  • Select the "Extensions" category.
  • Add a helpful description that allows users without programming knowledge to understand what your extension does, with info about dependencies and the Inkscape versions and operating systems that you know your extension will work with.
  • Also add a small thumbnail preview image (190x190px), which will help people understand what the extension is for.
  • If applicable, add a link to the place where development of the extension happens
  • To make sorting easier, it's helpful for users if you add a couple of tags (find a list of official tags that can be used at the right of this page, below the headings 'Version', 'Extension Type' and 'Platform'). If your extension does something that cannot be represented by any of the 'Extension Type' tags, please let us know, so we can add one that fits.
  • Also fill in all the other fields in the upload form, then click on 'Publish'.
  • Your upload will now be available for download on the extensions page.
• Vetting If you want your extension installable from the Extensions Manager, then it must be vetted by one of the extensions contributors. You should join the Inkscape extension team's chat room and ask for a reviewer. Be sure to paste the link to the uploaded extension here on inkscape.org for review.
• Watch how others enjoy using your extension, and, if you like to, engage with them to keep your extension updated and free of bugs.
• Try to remember to update your uploaded extension files in your inkscape.org uploads when you update the extension in your repository and tell a reviewer when you do.