Difference between revisions of "Script extensions"

Latest revision as of 19:57, 3 February 2023

The Inkscape Wiki is no longer used to host information about Extension development.

You can now find related information at GitLab.

This page is kept for historical reasons, e.g. to document specific decisions in Inkscape development.

[Note: This page concerns using scripting languages to create new Inkscape functionality. To access Inkscape functionality from scripting languages (i.e. to script Inkscape), see the Inkscape man page (especially in the development version or v0.46 or later, which provide --select and --verb options), or see the work in the src/extension/script directory of Inkscape source.]

Introduction

Traditional Unix scripts can be used to extend Inkscape's functionality. Such programs read a stream of data on standard input, transform the data in some way, and then write the modified data to standard output. This is an easy way to expand Inkscape and provide custom functionality without learning the internals of Inkscape. Libraries for reading and writing SVG data exist for many programming languages, and most provide support for XML. This tutorial describes the "ins and outs" of writing one of these scripts and making it work with Inkscape's core functionality.

Script functions

There are three kinds of functions that can be added with a script:

Input, providing translation from a file format to SVG
Output, providing translation from SVG to a format
Effect, taking in SVG, changing it, and then outputting SVG

While all of these are very similar in the scripting interface, there are slight differences between them.

Interaction

It is important for a script author to understand how Inkscape and scripts communicate.

(interpreter)? your_script (--param=value)* /path/to/input[[/SVGfile]] | inkscape

Inkscape runs your script (optionally with an interpreter, more info here: Extension Interpreters), passing it any number of parameters in long GNU style. The final argument is the name of the temporary SVG file your script should read. After processing, the script should return the modified SVG file to Inkscape on STDOUT.

Important tips

Receive the Inkscape arguments.
Clear temp files if it creates one.
Write full changed SVG to the default output.
Don't break an xml:space="preserve" area.
Send error text to the error output and help the user.

Extension description file

In order for Inkscape to make use of an external script or program, you must describe that script to Inkscape using an INX file. See the inkscape share directory for examples.

The INX file allows you to:

define the script file and other dependencies;
list all parameters and their types (to generate an input dialog window);
mark dialog window text for translation;
define an Inkscape menu entry;
chain extensions.

See INX extension descriptor format for help creating an INX file.

Parameters

The INX file describes which parameters the extension needs. Inkscape will prompt the user with a UI to fill out these parameters before the extension is called. Each parameter will be passed to the script as --paramname=paramvalue. Specify the script file to be run with the <command> tag.

For example, if you have described a string parameter with name string1 in the INX file, Inkscape will present a textbox to the user. When the user fills in text and presses Apply, it will pass --string1="text" to the script.

There are several types of parameters that can be requested by the INX description:

String (textbox)
Boolean (checkbox)
Int (numeric textbox)
Float (numeric textbox)
Enum (drop down selection list)
Option group (radio buttons)
Notebook (pages/tabs)
Description (not a parameter, provides static text)

For a detailed description of all parameters and input controls, see INX Parameters.

Verbs interface and the id tag

When you define your extension you will have <name> and <id> tags at the top of the INX file. The id tag is used for two purposes:

as an identifier in the config file so the most recently used parameter values are stored and recalled each time the extension is run;
as the identifier for the verbs interface so your extension can be run from the command line.

Inkscape can be called from the command line and the extension can be run using this interface. E.g. assuming the id in your extension was <id>foo.github.my_extension</id>:

inkscape --verb foo.github.my_extension will open Inkscape and open the dialog to your extension;
inkscape --verb foo.github.my_extension.noprefs will open Inkscape and run the dialog with the last set values;
inkscape --verb ZoomPage --verb foo.github.my_extension will open Inkscape, zoom full page, and open the dialog to your extension;
inkscape --verb-list will show you the available verbs.

Installing

Installing is as simple as copying the script (unless it resides in your path) and its INX file to the inkscape/share/extensions ($HOME/.config/inkscape/extensions) directory. (If you install a script in your home directory be sure to copy the dependencies.)

If you are looking to use scripts that have already been written, the most difficult part will likely be the installation. Since scripts are separate programs they may have any number of dependencies that are not included with inkscape. Currently, the best way to find missing dependencies is by reading the error messages produced by running the script from the command line.

@@ Line 1: / Line 1: @@
+{{Template:MovedToOtherSite|topic=Extension development|new_url=https://inkscape.gitlab.io/extensions/documentation/|new_site=GitLab}}
+----
 [Note: This page concerns using scripting languages to create new Inkscape functionality.  To access Inkscape functionality from scripting languages (i.e. to script Inkscape), see the [https://inkscape.org/en/doc/inkscape-man.html Inkscape man page] (especially in the development version or v0.46 or later, which provide <code>--select</code> and <code>--verb</code> options), or see the work in the src/extension/script directory of Inkscape source.]