Difference between revisions of "Script extensions"

From Inkscape Wiki
Jump to navigation Jump to search
(40 intermediate revisions by 17 users not shown)
Line 1: Line 1:
=== Introduction ===
[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.]


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.
== Introduction ==


=== Types of scripts ===
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.


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


* Input, providing translation from a file format to SVG
* Input, providing translation from a file format to SVG
* Output, providing translation from SVG to a format
* Output, providing translation from SVG to a format
* Effect, taking in SVG, changing it, and then outputing SVG
* 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.
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.


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


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, more info here: [[Extension_Interpreters | 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 ===
== Important Tips ==


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


=== Localisation of extensions ===
== Extension description file ==


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


Also the path to the extension has to be included in POTFILES.in file to tell intltool where to look for translatable content.
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.


Usefull information, before this section gets fully updated, can be found at [http://gould.cx/ted/blog/Translating_Custom_XML Ted's blog].
See [[INX extension descriptor format]] for help creating an INX file.


=== Description ===
=== 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.


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


==== Parameters ====
There are several types of parameters that can be requested by the INX description:
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
* 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)


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
For a detailed description of all parameters and input controls, see [[INX Parameters]].


will pass '--string1="text"' to the program specified by the <command> tag.
== 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:


There are several types of parameters that can be requested by the INX description:
* 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.


===== Boolean =====
Inkscape can be called from the command line and the extension can be run using this interface.


===== Int =====
E.g. Assuming the id in your extension was <code><id>foo.github.my_extension</id></code>


===== Float =====
<code>inkscape --verb foo.github.my_extension</code> will open Inkscape and open the dialog to your extension..


===== String =====
<code>inkscape --verb foo.github.my_extension.noprefs</code> will open inkscape and run the dialog with the last set values.


===== Description =====
<code>inkscape --verb ZoomPage --verb foo.github.my_extension</code> will open inkscape, Zoom full page, and open the dialog to your extension.


===== Enum =====
<code>inkscape --verb-list</code>  will show you the available verbs.


===== Notebook =====
== 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/.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  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  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 ==


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


*http://www.ekips.org/comp/inkscape/extending.php#ignorance
*[[PythonEffectTutorial]]


*[[MakingAnExtension]]
*[[Tips For Python Script Extensions]]


[[Category:Developer Documentation]]
[[Category:Extensions]]
[[Category:Extensions]]

Revision as of 16:35, 19 March 2017

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

See Also