Script extensions - Revision history

Moini at 19:57, 3 February 2023

2023-02-03T19:57:33Z

← Older revision		Revision as of 19:57, 3 February 2023
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.]		[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.]

Frigory: Orthotypographic review

2017-11-14T17:31:28Z

Orthotypographic review

← Older revision		Revision as of 17:31, 14 November 2017
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 [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.]

	== Introduction ==		== 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.		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 ==		== Script functions ==
Line 9:		Line 9:
	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:

	* 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 outputting 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.
Line 23:		Line 23:
	</pre>		</pre>

	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.		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~~ ==		== Important tips ==

	* Receive 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.
Line 38:		Line 38:

	The INX file allows you to:		The INX file allows you to:
	* ~~Define~~ the script file and other dependencies.		* define the script file and other dependencies;
	* ~~List~~ all parameters and their types (to generate an input dialog window).		* list all parameters and their types (to generate an input dialog window);
	* ~~Mark~~ dialog window text for translation.		* mark dialog window text for translation;
	* ~~Define~~ an Inkscape menu entry.		* define an Inkscape menu entry;
	* ~~Chain~~ extensions.		* chain extensions.

	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 65:		Line 66:

	== Verbs interface and the id 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:~~

	* as an identifier in the config file so the most recently used parameter values are stored and recalled each time the extension is run.		When you define your extension you will have <code><name></code> and <code><id></code> 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.		* 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.		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 <code><id>foo.github.my_extension</id></code>:
			* <code>inkscape --verb foo.github.my_extension</code> will open Inkscape and open the dialog to your extension;
	E.g. ~~Assuming~~ the id in your extension was <code><id>foo.github.my_extension</id></code>		* <code>inkscape --verb foo.github.my_extension.noprefs</code> will open Inkscape and run the dialog with the last set values;
			* <code>inkscape --verb ZoomPage --verb foo.github.my_extension</code> will open Inkscape, zoom full page, and open the dialog to your extension;
	<code>inkscape --verb foo.github.my_extension</code> will open Inkscape and open the dialog to your extension..		* <code>inkscape --verb-list</code> will show you the available verbs.

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

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

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

	== Installing ==		== Installing ==
Line 89:		Line 84:
	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.

	*[[PythonEffectTutorial]]

	*[[Python modules for extensions]]

	*[[Tips For Python Script Extensions]]		* [[Generating objects from extensions]]. How to use a script to generate actual objects inside SVG documents.
			* [[PythonEffectTutorial]]
			* [[Python modules for extensions]]
			* [[Tips For Python Script Extensions]]

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

Matyilona: /* See Also */ Adding link to Python modules for extensions

2017-11-06T20:59:35Z

See Also: Adding link to Python modules for extensions

← Older revision		Revision as of 20:59, 6 November 2017
Line 94:		Line 94:

	*[[PythonEffectTutorial]]		*[[PythonEffectTutorial]]

			*[[Python modules for extensions]]

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

Moini: /* Interaction */

2017-03-19T16:35:17Z

Interaction

← Older revision		Revision as of 16:35, 19 March 2017
Line 23:		Line 23:
	</pre>		</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 ==

Moini: /* Interaction */

2017-03-19T16:33:44Z

Interaction

← Older revision		Revision as of 16:33, 19 March 2017
Line 19:		Line 19:
	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.

	~~<code>~~<pre>		<pre>
	(interpreter)? your_script (--param=value)* /path/to/input[[/SVGfile]] \| inkscape		(interpreter)? your_script (--param=value)* /path/to/input[[/SVGfile]] \| inkscape
	</pre~~></code~~>		</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) 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.

Moini at 23:03, 26 February 2017

2017-02-26T23:03:57Z

← Older revision		Revision as of 23:03, 26 February 2017
Line 81:		Line 81:
	<code>inkscape --verb ZoomPage --verb foo.github.my_extension</code> will open inkscape, Zoom full page, and open the dialog to your extension.		<code>inkscape --verb ZoomPage --verb foo.github.my_extension</code> will open inkscape, Zoom full page, and open the dialog to your extension.

	<code>inkscape ~~--verb ZoomPage~~ --verb-list</code> will show you the available verbs.		<code>inkscape --verb-list</code> will show you the available verbs.

	== Installing ==		== Installing ==

Neon22: added verb discovery line

2017-02-26T22:19:07Z

added verb discovery line

← Older revision		Revision as of 22:19, 26 February 2017
Line 81:		Line 81:
	<code>inkscape --verb ZoomPage --verb foo.github.my_extension</code> will open inkscape, Zoom full page, and open the dialog to your extension.		<code>inkscape --verb ZoomPage --verb foo.github.my_extension</code> will open inkscape, Zoom full page, and open the dialog to your extension.

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

	== Installing ==		== Installing ==

Neon22: Added Verbs and id tag section

2017-02-26T22:11:54Z

Added Verbs and id tag section

← Older revision		Revision as of 22:11, 26 February 2017
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]].

			== 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 <code><id>foo.github.my_extension</id></code>

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

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

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



	== Installing ==		== Installing ==

Raphael: /* See Also */ Removing dead link

2016-03-13T10:38:42Z

User8192: spelling

2015-01-23T22:52:22Z

spelling

← Older revision		Revision as of 22:52, 23 January 2015
Line 11:		Line 11:
	* 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.

← Older revision		Revision as of 10:38, 13 March 2016
Line 73:		Line 73:

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

	*[http://www.ekips.org/comp/inkscape/extending.php#ignorance\| Aarons website] describing his path to learning how scripting extensions work. '''VERY OUT-OF-DATE'''

	*[[PythonEffectTutorial]]		*[[PythonEffectTutorial]]