Difference between revisions of "Script extensions"

From Inkscape Wiki
Jump to navigation Jump to search
Line 20: Line 20:


Inkscape runs your script (optionally with an interpreter) 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.
Inkscape runs your script (optionally with an interpreter) 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 ===
* Recive 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.


=== Localisation of extensions ===
=== Localisation of extensions ===

Revision as of 16:31, 16 November 2006

Introduction

Inkscape provides the ability for its functionality to be extended using traditional unix scripts. By this, we mean a program that takes in a stream of data through standard in, and then outputs that data on standard out. This is a very easy way to expand Inkscape, and provide custom functionality, without learning the internals of Inkscape. Plus, there are SVG read and writing libraries out there for almost any language, and the rest of them all have XML support (which is really what you probably want to use anyway). This HOWTO discusses the ends and outs of writing one of these scripts and getting it to work with the Inkscape core functionality.

Types of scripts

There are three functions that 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 outputing 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) 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

  • Recive 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.

Localisation of extensions

To allow localisation of strings in extension for Inkscape, some xml tags have to be adapted to variant readable by intltool. It means that tags or parametres has to have "_" prepended to their name, e.g. <_name>name of extension</_name>

Also the path to the extension has to be included in POTFILES.in file to tell intltool where to look for translatable content.

Usefull information, before this section gets fully updated, can be found at Ted's blog.

Description

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.

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 through the commandline as "--paramname=paramvalue". Eg. 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 OK, it

will pass '--string1="text"' to the program specified by the <command> tag.

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

Boolean
Int
Float
String
Description
Enum
Notebook

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/.inkscape/extensions) directory.

If you are looking to use scripts that have already been written, the most difficult part will likely be the installation. Since scripts are seperate 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.

See Also