Difference between revisions of "Script extensions"

From Inkscape Wiki
Jump to navigation Jump to search
m
m
Line 1: Line 1:
[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.]
[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 ===
== Introduction ==


Traditional unix scripts can be used to extend Inkscape's functionality.  
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 HOWTO describes the "ins and outs" of writing one of these scripts and making it work with Inkscape's core 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 HOWTO describes the "ins and outs" of writing one of these scripts and making it work with Inkscape's core functionality.


=== Script functions ===
== Script functions ==


There are three kinds of functions that can be added with a script:
There are three kinds of functions that can be added with a script:
Line 16: Line 16:
While all of these are very similar in the scripting interface, there are slight differences between them.
While all of these are very similar in the scripting interface, there are slight differences between them.


=== Interaction ===
== Interaction ==


It is important for a script author to understand how Inkscape and scripts communicate.
It is important for a script author to understand how Inkscape and scripts communicate.
Line 24: Line 24:
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 ===
== Important Tips ==


* Receive the inkscape arguments.
* Receive the inkscape arguments.
Line 32: Line 32:
* Send error text to the error output and help the user.
* Send error text to the error output and help the user.


=== Extension description file ===
== 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.
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.
Line 45: Line 45:
See [[INX extension descriptor format]] for help creating an INX file.
See [[INX extension descriptor format]] for help creating an INX file.


==== Parameters ====
=== 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 <code>--paramname=paramvalue</code>. Specify the script file to be run with the <code><command></code> tag.
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 <code>--paramname=paramvalue</code>. Specify the script file to be run with the <code><command></code> tag.


Line 63: Line 63:
For a detailed description of all parameters and input controls, see [[INX Parameters]].
For a detailed description of all parameters and input controls, see [[INX Parameters]].


=== Installing ===
== 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.)
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.)
Line 69: Line 69:
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.
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.


=== See Also ===
== See Also ==


*[[Generating_objects_from_extensions]]. How to use a script to generate actual objects inside SVG documents.
*[[Generating_objects_from_extensions]]. How to use a script to generate actual objects inside SVG documents.

Revision as of 12:24, 2 November 2010

[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 HOWTO 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 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

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

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.

See Also

  • Aarons website describing his path to learning how scripting extensions work. VERY OUT-OF-DATE