Inkscape Wiki - User contributions [en]

PowerStroke

2008-09-03T17:26:47Z

Rubikcube: added comment -> synfig

= Power stroke =

The proposed power stroke LPE is as follow:

[[Image:Power-stroke-1.png]]

== Functionality ==

This LPE allows a modulated stroke from manually entered values.

Further development could allow direct width reading from a pressure-enabled device.

== Workflow ==

The user simply creates the line, it might for example be based on an outline.

Then the user applies the LPE to his shape, it overrides the normal stroke rendering and allows custom line width at different nodes of the path.

Only the stroke-width property of the path is overridden, the rest of the stroke properties keep working as usual, when relevant.

== GUI ==

Se image above. User selects a nodes or a set of nodes and affects values to those. When a node is selected, you can see what its value is by the change in values in the number entry or by the state of the push button.

Additionally, hovering over a node could show the value of a node. Graphical feedback could even possibly set different icons for nodes that are set and others that are interpolated.

Perhaps Alt+drag a node to change the thickness?

A combination of a metakey and the scroll wheel would be intuitive as well (with status bar message stating you can do that, of course). -- [[jegHegy]]

= Comments =

== By JohanE ==
This is very well doable, but would require a new "Nodepath" implementation that enables writing special values (preferably a struct) per node. There is already something like this, the "nodetypes" attribute, but it is too restrictive. Expanding this would enable this effect, and opens up many other possibilities. Nice idea !

== By Pajarico ==
I'm thinking this tool could allow the user to copy a path or an object or group of objects to any node in a path. Which is similar to what you're proposing, only this doesn't use interpolation between adjacent nodes, it just places an element on a specific node (or nodes if you have several selected).

I'm not sure if it is better to open a separate blueprint or not. --Pajarico, [[User:Pajarico|Pajarico]] 22:36, 21 June 2008 (UTC)

== By rubikcube ==
You might want to have a look at how [http://www.synfig.org synfig] handles varying width for paths. Paths are called "Blines" there, the relevant feature is explained shortly at the bottom of [http://synfig.org/Creating_Shapes one of its manual pages]. --[[User:Rubikcube|Rubikcube]] 17:26, 3 September 2008 (UTC)

PythonEffectTutorial

2008-08-07T21:51:45Z

Rubikcube: Link to python documentation

Effect extensions in Inkscape means a simple programs or scripts that reads an SVG file from standard input, transforms it somehow and prints it to the standart output. Usually Inkscape sits on both ends, providing the file with some parameters as input first and finally reading the output, which is then used for further work.
[[Image:Effect_flow.svg|thumb|right|400px]]

We will write a simple effect extension script in [http://docs.python.org Python] that will put "Hello World!" or "Hello <value of --what option>!" string in the center of document and inside a new layer.

<blockquote>
''This script won't work with the current version of inkscape, it might still help as a useful guide how to create your own scripts though. Especially the methods to access the xml structure have changed, please refer to the [http://codespeak.net/lxml/ lxml] documentation.''
</blockquote>

== Effect Extension Script ==

First of all create a file ''hello_world.py'' and make it executable with the Python interpreter with the well-known directive:
<pre>
#!/usr/bin/env python
</pre>

If you're going to put the file somewhere else than into inkscape's installation directory, we need to add a path so that python can find the necessary modules:
<pre>
import sys
sys.path.append('/usr/share/inkscape/extensions') # or another path, as necessary
</pre>

Import the ''inkex.py'' file with the ''Effect'' base class that will do most of the work for us and the ''simplestyle.py'' module with support functions for working with CSS styles. We will use just the ''formatStyle'' function from this module:
<pre>
import inkex
from simplestyle import *
</pre>

Declare a ''HelloWordEffect'' class that inherits from ''Effect'' and write a constructor where the base class is initialized and script options for the option parser are defined:
<pre>
class HelloWorldEffect(inkex.Effect):
def __init__(self):
inkex.Effect.__init__(self)
self.OptionParser.add_option('-w', '--what', action = 'store',
type = 'string', dest = 'what', default = 'World',
help = 'What would you like to greet?')
</pre>

The complete documentation for the ''OptionParser'' class can be found at http://docs.python.org/lib/module-optparse.html. Here we just use the ''add_option'' method which has as first argument a short option name, as second argument a long option name and then a few other arguments with this meaning:

* ''action'' - An action which should be done with option value. In this case we use action ''store'' which will store option value in ''self.options.<destination>'' attribute.
* ''type'' - Type of option value. We use string here.
* ''dest'' - Destination of option action specified by ''action'' argument. Using ''what'' value we say that we want to store option value to self.options.what attribute.
* ''default'' - Defalut value for this option if it is not specified.
* ''help'' - A help string that will be displayed if script will be given no arguments or some option or argument will have wrong syntax.

Inkscape will create a GUI form with widgets for all specified options and prefill them with the default values specified using the ''.inx'' file for this extension which we will write later.

We need to override only one ''Effect'' class method to provide the desired effect functionality:
<pre>
def effect(self):
what = self.options.what
</pre>
As you can imagine we just stored the ''--what'' option value to the ''what'' variable.

Now we will finally start to do something. We will have to work with the XML representation of the SVG document that we can access via ''Effect'''s ''self.document'' attribute.
It is of lxml's '' _ElementTree'' class type. Complete documentation for the lxml package lxml can be found at http://codespeak.net/lxml/.

First we get SVG document's ''svg'' element and its dimensions:
<pre>
svg = self.document.getroot()
# or alternatively
# svg = self.document.xpath('//svg:svg',namespaces=inkex.NSS)[0]

# Again, there are two ways to get the attibutes:
width = inkex.unittouu(svg.get('width'))
height = inkex.unittouu(svg.attrib['height'])
</pre>
The ''xpath'' function returns a list of all matching elements so we just use the first one of them.

We now create an SVG group element ('' 'g' '') and "mark" it as a layer using Inkscape' SVG extensions:
<pre>
layer = inkex.etree.SubElement(svg, 'g')
layer.set(inkex.addNS('label', 'inkscape'), 'Hello %s Layer' % (what))
layer.set(inkex.addNS('groupmode', 'inkscape'), 'layer')
</pre>
This creates ''inkscape:label'' and ''inkscape:groupmode'' attributes, which will only be read by Inkscape or compatible applications. To all other viewers, this new element looks just like a plain SVG group.

Now we create an SVG text element with a text value containing the "Hello World" string:
<pre>
text = inkex.etree.Element(inkex.addNS('text','svg'))
text.text = 'Hello %s!' % (what)
</pre>

Set the position of the text to the center of SVG document:
<pre>
text.set('x', str(width / 2))
text.set('y', str(height / 2))
</pre>

If we want to center the text on its position we need to define the CSS style of the SVG ''text'' element. Actually we use the ''text-anchor'' SVG extension to CSS styles to do that work:
<pre>
style = {'text-align' : 'center', 'text-anchor' : 'middle'}
text.set('style', formatStyle(style))
</pre>

Finally we connect all created elements together and put them into the SVG document:
<pre>
layer.append(text)
</pre>

We just defined a class that inherited from the original effect extension so we have to create an instance of it and execute it in the main control flow:
<pre>
effect = HelloWorldEffect()
effect.affect()
</pre>

== Extension Description File ==

To include script in Inkscape's main menu create ''hello_world.inx'' file describing script evokation.

<pre>
<inkscape-extension>
<_name>Hello World!</_name>
<id>org.ekips.filter.hello_world</id>
<dependency type="executable" location="extensions">hello_world.py</dependency>
<dependency type="executable" location="extensions">inkex.py</dependency>
<param name="what" type="string" _gui-text="What would you like to greet?">World</param>
<effect>
<object-type>all</object-type>
<effects-menu>
<submenu _name="Examples"/>
</effects-menu>
</effect>
<script>
<command reldir="extensions" interpreter="python">hello_world.py</command>
</script>
</inkscape-extension>
</pre>

Create ''<param>'' element for every option of a script and ''<dependency>'' for every included module which is not from Python standard library. Inkscape will search for this modules in directory with script. ''<effect>'' element and its descendants defines name of menu item evoking our new "Hello World!" extension.

If the inx file isn't well formed or if any of the dependencies wasn't met, the extension won't show up in the menu. If your extension doesn't show up, take a look at extension-errors.log, which may give you a hint why it wasn't loaded.

== Installation ==

To install a new extenstion just put ''hello_world.py'' and ''hello_world.inx'' files with all dependency modules to the ''<path_to_inkscape>/extensions'' or ''~/.inkscape/extensions'' directory. On Linux you will probably have to make the python script executable first if you haven't done this yet. This is usually done by the usual command (or in your preferred file manager):
<pre>
$ chmod a+x hello_world.py
</pre>

Now start Inkscape. A new menu item ''Hello World!'' in ''Effects->Examples'' menu should appear.

== Complete Source Code ==

Here is a complete commented source pre of ''hello_world.py'' script file:

<pre>
#!/usr/bin/env python

# These two lines are only needed if you don't put the script directly into
# the installation directory
import sys
sys.path.append('/usr/share/inkscape/extensions')

# We will use the inkex module with the predefined Effect base class.
import inkex
# The simplestyle module provides functions for style parsing.
from simplestyle import *

class HelloWorldEffect(inkex.Effect):
"""
Example Inkscape effect extension.
Creates a new layer with a "Hello World!" text centered in the middle of the document.
"""
def __init__(self):
"""
Constructor.
Defines the "--what" option of a script.
"""
# Call the base class constructor.
inkex.Effect.__init__(self)

# Define string option "--what" with "-w" shortcut and default value "World".
self.OptionParser.add_option('-w', '--what', action = 'store',
type = 'string', dest = 'what', default = 'World',
help = 'What would you like to greet?')

def effect(self):
"""
Effect behaviour.
Overrides base class' method and inserts "Hello World" text into SVG document.
"""
# Get script's "--what" option value.
what = self.options.what

# Get access to main SVG document element and get its dimensions.
svg = self.document.getroot()
# or alternatively
# svg = self.document.xpath('//svg:svg',namespaces=inkex.NSS)[0]

# Again, there are two ways to get the attibutes:
width = inkex.unittouu(svg.get('width'))
height = inkex.unittouu(svg.attrib['height'])

# Create a new layer.
layer = inkex.etree.SubElement(svg, 'g')
layer.set(inkex.addNS('label', 'inkscape'), 'Hello %s Layer' % (what))
layer.set(inkex.addNS('groupmode', 'inkscape'), 'layer')

# Create text element
text = inkex.etree.Element(inkex.addNS('text','svg'))
text.text = 'Hello %s!' % (what)

# Set text position to center of document.
text.set('x', str(width / 2))
text.set('y', str(height / 2))

# Center text horizontally with CSS style.
style = {'text-align' : 'center', 'text-anchor': 'middle'}
text.set('style', formatStyle(style))

# Connect elements together.
layer.append(text)

# Create effect instance and apply it.
effect = HelloWorldEffect()
effect.affect()
</pre>

Last edited by --[[User:Rubikcube|Rubikcube]] 21:18, 7 August 2008 (UTC), based on a version by
[[User:Blackhex|Blackhex]] 11:59, 26 April 2007 (UTC)

Talk:PythonEffectTutorial

2008-08-07T21:21:16Z

Rubikcube: should work now

==Current issues==
* None left that I know of, it should work now with a current installation. --[[User:Rubikcube|Rubikcube]] 21:21, 7 August 2008 (UTC)

PythonEffectTutorial

2008-08-07T21:19:53Z

Rubikcube: /* Complete Source Code */ adaped docstrings

Effect extensions in Inkscape means a simple programs or scripts that reads an SVG file from standard input, transforms it somehow and prints it to the standart output. Usually Inkscape sits on both ends, providing the file with some parameters as input first and finally reading the output, which is then used for further work.
[[Image:Effect_flow.svg|thumb|right|400px]]

We will write a simple effect extension script in Python that will put "Hello World!" or "Hello <value of --what option>!" string in the center of document and inside a new layer.

<blockquote>
''This script won't work with the current version of inkscape, it might still help as a useful guide how to create your own scripts though. Especially the methods to access the xml structure have changed, please refer to the [http://codespeak.net/lxml/ lxml] documentation.''
</blockquote>

== Effect Extension Script ==

First of all create a file ''hello_world.py'' and make it executable with the Python interpreter with the well-known directive:
<pre>
#!/usr/bin/env python
</pre>

If you're going to put the file somewhere else than into inkscape's installation directory, we need to add a path so that python can find the necessary modules:
<pre>
import sys
sys.path.append('/usr/share/inkscape/extensions') # or another path, as necessary
</pre>

Import the ''inkex.py'' file with the ''Effect'' base class that will do most of the work for us and the ''simplestyle.py'' module with support functions for working with CSS styles. We will use just the ''formatStyle'' function from this module:
<pre>
import inkex
from simplestyle import *
</pre>

Declare a ''HelloWordEffect'' class that inherits from ''Effect'' and write a constructor where the base class is initialized and script options for the option parser are defined:
<pre>
class HelloWorldEffect(inkex.Effect):
def __init__(self):
inkex.Effect.__init__(self)
self.OptionParser.add_option('-w', '--what', action = 'store',
type = 'string', dest = 'what', default = 'World',
help = 'What would you like to greet?')
</pre>

The complete documentation for the ''OptionParser'' class can be found at http://docs.python.org/lib/module-optparse.html. Here we just use the ''add_option'' method which has as first argument a short option name, as second argument a long option name and then a few other arguments with this meaning:

* ''action'' - An action which should be done with option value. In this case we use action ''store'' which will store option value in ''self.options.<destination>'' attribute.
* ''type'' - Type of option value. We use string here.
* ''dest'' - Destination of option action specified by ''action'' argument. Using ''what'' value we say that we want to store option value to self.options.what attribute.
* ''default'' - Defalut value for this option if it is not specified.
* ''help'' - A help string that will be displayed if script will be given no arguments or some option or argument will have wrong syntax.

Inkscape will create a GUI form with widgets for all specified options and prefill them with the default values specified using the ''.inx'' file for this extension which we will write later.

We need to override only one ''Effect'' class method to provide the desired effect functionality:
<pre>
def effect(self):
what = self.options.what
</pre>
As you can imagine we just stored the ''--what'' option value to the ''what'' variable.

Now we will finally start to do something. We will have to work with the XML representation of the SVG document that we can access via ''Effect'''s ''self.document'' attribute.
It is of lxml's '' _ElementTree'' class type. Complete documentation for the lxml package lxml can be found at http://codespeak.net/lxml/.

First we get SVG document's ''svg'' element and its dimensions:
<pre>
svg = self.document.getroot()
# or alternatively
# svg = self.document.xpath('//svg:svg',namespaces=inkex.NSS)[0]

# Again, there are two ways to get the attibutes:
width = inkex.unittouu(svg.get('width'))
height = inkex.unittouu(svg.attrib['height'])
</pre>
The ''xpath'' function returns a list of all matching elements so we just use the first one of them.

We now create an SVG group element ('' 'g' '') and "mark" it as a layer using Inkscape' SVG extensions:
<pre>
layer = inkex.etree.SubElement(svg, 'g')
layer.set(inkex.addNS('label', 'inkscape'), 'Hello %s Layer' % (what))
layer.set(inkex.addNS('groupmode', 'inkscape'), 'layer')
</pre>
This creates ''inkscape:label'' and ''inkscape:groupmode'' attributes, which will only be read by Inkscape or compatible applications. To all other viewers, this new element looks just like a plain SVG group.

Now we create an SVG text element with a text value containing the "Hello World" string:
<pre>
text = inkex.etree.Element(inkex.addNS('text','svg'))
text.text = 'Hello %s!' % (what)
</pre>

Set the position of the text to the center of SVG document:
<pre>
text.set('x', str(width / 2))
text.set('y', str(height / 2))
</pre>

If we want to center the text on its position we need to define the CSS style of the SVG ''text'' element. Actually we use the ''text-anchor'' SVG extension to CSS styles to do that work:
<pre>
style = {'text-align' : 'center', 'text-anchor' : 'middle'}
text.set('style', formatStyle(style))
</pre>

Finally we connect all created elements together and put them into the SVG document:
<pre>
layer.append(text)
</pre>

We just defined a class that inherited from the original effect extension so we have to create an instance of it and execute it in the main control flow:
<pre>
effect = HelloWorldEffect()
effect.affect()
</pre>

== Extension Description File ==

To include script in Inkscape's main menu create ''hello_world.inx'' file describing script evokation.

<pre>
<inkscape-extension>
<_name>Hello World!</_name>
<id>org.ekips.filter.hello_world</id>
<dependency type="executable" location="extensions">hello_world.py</dependency>
<dependency type="executable" location="extensions">inkex.py</dependency>
<param name="what" type="string" _gui-text="What would you like to greet?">World</param>
<effect>
<object-type>all</object-type>
<effects-menu>
<submenu _name="Examples"/>
</effects-menu>
</effect>
<script>
<command reldir="extensions" interpreter="python">hello_world.py</command>
</script>
</inkscape-extension>
</pre>

Create ''<param>'' element for every option of a script and ''<dependency>'' for every included module which is not from Python standard library. Inkscape will search for this modules in directory with script. ''<effect>'' element and its descendants defines name of menu item evoking our new "Hello World!" extension.

If the inx file isn't well formed or if any of the dependencies wasn't met, the extension won't show up in the menu. If your extension doesn't show up, take a look at extension-errors.log, which may give you a hint why it wasn't loaded.

== Installation ==

To install a new extenstion just put ''hello_world.py'' and ''hello_world.inx'' files with all dependency modules to the ''<path_to_inkscape>/extensions'' or ''~/.inkscape/extensions'' directory. On Linux you will probably have to make the python script executable first if you haven't done this yet. This is usually done by the usual command (or in your preferred file manager):
<pre>
$ chmod a+x hello_world.py
</pre>

Now start Inkscape. A new menu item ''Hello World!'' in ''Effects->Examples'' menu should appear.

== Complete Source Code ==

Here is a complete commented source pre of ''hello_world.py'' script file:

<pre>
#!/usr/bin/env python

# These two lines are only needed if you don't put the script directly into
# the installation directory
import sys
sys.path.append('/usr/share/inkscape/extensions')

# We will use the inkex module with the predefined Effect base class.
import inkex
# The simplestyle module provides functions for style parsing.
from simplestyle import *

class HelloWorldEffect(inkex.Effect):
"""
Example Inkscape effect extension.
Creates a new layer with a "Hello World!" text centered in the middle of the document.
"""
def __init__(self):
"""
Constructor.
Defines the "--what" option of a script.
"""
# Call the base class constructor.
inkex.Effect.__init__(self)

# Define string option "--what" with "-w" shortcut and default value "World".
self.OptionParser.add_option('-w', '--what', action = 'store',
type = 'string', dest = 'what', default = 'World',
help = 'What would you like to greet?')

def effect(self):
"""
Effect behaviour.
Overrides base class' method and inserts "Hello World" text into SVG document.
"""
# Get script's "--what" option value.
what = self.options.what

# Get access to main SVG document element and get its dimensions.
svg = self.document.getroot()
# or alternatively
# svg = self.document.xpath('//svg:svg',namespaces=inkex.NSS)[0]

# Again, there are two ways to get the attibutes:
width = inkex.unittouu(svg.get('width'))
height = inkex.unittouu(svg.attrib['height'])

# Create a new layer.
layer = inkex.etree.SubElement(svg, 'g')
layer.set(inkex.addNS('label', 'inkscape'), 'Hello %s Layer' % (what))
layer.set(inkex.addNS('groupmode', 'inkscape'), 'layer')

# Create text element
text = inkex.etree.Element(inkex.addNS('text','svg'))
text.text = 'Hello %s!' % (what)

# Set text position to center of document.
text.set('x', str(width / 2))
text.set('y', str(height / 2))

# Center text horizontally with CSS style.
style = {'text-align' : 'center', 'text-anchor': 'middle'}
text.set('style', formatStyle(style))

# Connect elements together.
layer.append(text)

# Create effect instance and apply it.
effect = HelloWorldEffect()
effect.affect()
</pre>

Last edited by --[[User:Rubikcube|Rubikcube]] 21:18, 7 August 2008 (UTC), based on a version by
[[User:Blackhex|Blackhex]] 11:59, 26 April 2007 (UTC)

PythonEffectTutorial

2008-08-07T21:18:06Z

Rubikcube: /* Complete Source Code */ changed complete source code

Effect extensions in Inkscape means a simple programs or scripts that reads an SVG file from standard input, transforms it somehow and prints it to the standart output. Usually Inkscape sits on both ends, providing the file with some parameters as input first and finally reading the output, which is then used for further work.
[[Image:Effect_flow.svg|thumb|right|400px]]

We will write a simple effect extension script in Python that will put "Hello World!" or "Hello <value of --what option>!" string in the center of document and inside a new layer.

<blockquote>
''This script won't work with the current version of inkscape, it might still help as a useful guide how to create your own scripts though. Especially the methods to access the xml structure have changed, please refer to the [http://codespeak.net/lxml/ lxml] documentation.''
</blockquote>

== Effect Extension Script ==

First of all create a file ''hello_world.py'' and make it executable with the Python interpreter with the well-known directive:
<pre>
#!/usr/bin/env python
</pre>

If you're going to put the file somewhere else than into inkscape's installation directory, we need to add a path so that python can find the necessary modules:
<pre>
import sys
sys.path.append('/usr/share/inkscape/extensions') # or another path, as necessary
</pre>

Import the ''inkex.py'' file with the ''Effect'' base class that will do most of the work for us and the ''simplestyle.py'' module with support functions for working with CSS styles. We will use just the ''formatStyle'' function from this module:
<pre>
import inkex
from simplestyle import *
</pre>

Declare a ''HelloWordEffect'' class that inherits from ''Effect'' and write a constructor where the base class is initialized and script options for the option parser are defined:
<pre>
class HelloWorldEffect(inkex.Effect):
def __init__(self):
inkex.Effect.__init__(self)
self.OptionParser.add_option('-w', '--what', action = 'store',
type = 'string', dest = 'what', default = 'World',
help = 'What would you like to greet?')
</pre>

The complete documentation for the ''OptionParser'' class can be found at http://docs.python.org/lib/module-optparse.html. Here we just use the ''add_option'' method which has as first argument a short option name, as second argument a long option name and then a few other arguments with this meaning:

* ''action'' - An action which should be done with option value. In this case we use action ''store'' which will store option value in ''self.options.<destination>'' attribute.
* ''type'' - Type of option value. We use string here.
* ''dest'' - Destination of option action specified by ''action'' argument. Using ''what'' value we say that we want to store option value to self.options.what attribute.
* ''default'' - Defalut value for this option if it is not specified.
* ''help'' - A help string that will be displayed if script will be given no arguments or some option or argument will have wrong syntax.

Inkscape will create a GUI form with widgets for all specified options and prefill them with the default values specified using the ''.inx'' file for this extension which we will write later.

We need to override only one ''Effect'' class method to provide the desired effect functionality:
<pre>
def effect(self):
what = self.options.what
</pre>
As you can imagine we just stored the ''--what'' option value to the ''what'' variable.

Now we will finally start to do something. We will have to work with the XML representation of the SVG document that we can access via ''Effect'''s ''self.document'' attribute.
It is of lxml's '' _ElementTree'' class type. Complete documentation for the lxml package lxml can be found at http://codespeak.net/lxml/.

First we get SVG document's ''svg'' element and its dimensions:
<pre>
svg = self.document.getroot()
# or alternatively
# svg = self.document.xpath('//svg:svg',namespaces=inkex.NSS)[0]

# Again, there are two ways to get the attibutes:
width = inkex.unittouu(svg.get('width'))
height = inkex.unittouu(svg.attrib['height'])
</pre>
The ''xpath'' function returns a list of all matching elements so we just use the first one of them.

We now create an SVG group element ('' 'g' '') and "mark" it as a layer using Inkscape' SVG extensions:
<pre>
layer = inkex.etree.SubElement(svg, 'g')
layer.set(inkex.addNS('label', 'inkscape'), 'Hello %s Layer' % (what))
layer.set(inkex.addNS('groupmode', 'inkscape'), 'layer')
</pre>
This creates ''inkscape:label'' and ''inkscape:groupmode'' attributes, which will only be read by Inkscape or compatible applications. To all other viewers, this new element looks just like a plain SVG group.

Now we create an SVG text element with a text value containing the "Hello World" string:
<pre>
text = inkex.etree.Element(inkex.addNS('text','svg'))
text.text = 'Hello %s!' % (what)
</pre>

Set the position of the text to the center of SVG document:
<pre>
text.set('x', str(width / 2))
text.set('y', str(height / 2))
</pre>

If we want to center the text on its position we need to define the CSS style of the SVG ''text'' element. Actually we use the ''text-anchor'' SVG extension to CSS styles to do that work:
<pre>
style = {'text-align' : 'center', 'text-anchor' : 'middle'}
text.set('style', formatStyle(style))
</pre>

Finally we connect all created elements together and put them into the SVG document:
<pre>
layer.append(text)
</pre>

We just defined a class that inherited from the original effect extension so we have to create an instance of it and execute it in the main control flow:
<pre>
effect = HelloWorldEffect()
effect.affect()
</pre>

== Extension Description File ==

To include script in Inkscape's main menu create ''hello_world.inx'' file describing script evokation.

<pre>
<inkscape-extension>
<_name>Hello World!</_name>
<id>org.ekips.filter.hello_world</id>
<dependency type="executable" location="extensions">hello_world.py</dependency>
<dependency type="executable" location="extensions">inkex.py</dependency>
<param name="what" type="string" _gui-text="What would you like to greet?">World</param>
<effect>
<object-type>all</object-type>
<effects-menu>
<submenu _name="Examples"/>
</effects-menu>
</effect>
<script>
<command reldir="extensions" interpreter="python">hello_world.py</command>
</script>
</inkscape-extension>
</pre>

Create ''<param>'' element for every option of a script and ''<dependency>'' for every included module which is not from Python standard library. Inkscape will search for this modules in directory with script. ''<effect>'' element and its descendants defines name of menu item evoking our new "Hello World!" extension.

If the inx file isn't well formed or if any of the dependencies wasn't met, the extension won't show up in the menu. If your extension doesn't show up, take a look at extension-errors.log, which may give you a hint why it wasn't loaded.

== Installation ==

To install a new extenstion just put ''hello_world.py'' and ''hello_world.inx'' files with all dependency modules to the ''<path_to_inkscape>/extensions'' or ''~/.inkscape/extensions'' directory. On Linux you will probably have to make the python script executable first if you haven't done this yet. This is usually done by the usual command (or in your preferred file manager):
<pre>
$ chmod a+x hello_world.py
</pre>

Now start Inkscape. A new menu item ''Hello World!'' in ''Effects->Examples'' menu should appear.

== Complete Source Code ==

Here is a complete commented source pre of ''hello_world.py'' script file:

<pre>
#!/usr/bin/env python

# These two lines are only needed if you don't put the script directly into
# the installation directory
import sys
sys.path.append('/usr/share/inkscape/extensions')

# We will use the inkex module with the predefined Effect base class.
import inkex
# The simplestyle module provides functions for style parsing.
from simplestyle import *

"""
Example Inkscape effect extension.
Creates a new layer with a "Hello World!" text centered in the middle of the document.
"""
class HelloWorldEffect(inkex.Effect):
"""
Constructor.
Defines the "--what" option of a script.
"""
def __init__(self):
# Call the base class constructor.
inkex.Effect.__init__(self)

# Define string option "--what" with "-w" shortcut and default value "World".
self.OptionParser.add_option('-w', '--what', action = 'store',
type = 'string', dest = 'what', default = 'World',
help = 'What would you like to greet?')

def effect(self):
"""
Effect behaviour.
Overrides base class' method and inserts "Hello World" text into SVG document.
"""
# Get script's "--what" option value.
what = self.options.what

# Get access to main SVG document element and get its dimensions.
svg = self.document.getroot()
# or alternatively
# svg = self.document.xpath('//svg:svg',namespaces=inkex.NSS)[0]

# Again, there are two ways to get the attibutes:
width = inkex.unittouu(svg.get('width'))
height = inkex.unittouu(svg.attrib['height'])

# Create a new layer.
layer = inkex.etree.SubElement(svg, 'g')
layer.set(inkex.addNS('label', 'inkscape'), 'Hello %s Layer' % (what))
layer.set(inkex.addNS('groupmode', 'inkscape'), 'layer')

# Create text element
text = inkex.etree.Element(inkex.addNS('text','svg'))
text.text = 'Hello %s!' % (what)

# Set text position to center of document.
text.set('x', str(width / 2))
text.set('y', str(height / 2))

# Center text horizontally with CSS style.
style = {'text-align' : 'center', 'text-anchor': 'middle'}
text.set('style', formatStyle(style))

# Connect elements together.
layer.append(text)

# Create effect instance and apply it.
effect = HelloWorldEffect()
effect.affect()
</pre>

Last edited by --[[User:Rubikcube|Rubikcube]] 21:18, 7 August 2008 (UTC), based on a version by
[[User:Blackhex|Blackhex]] 11:59, 26 April 2007 (UTC)

PythonEffectTutorial

2008-08-07T21:08:26Z

Rubikcube: /* Installation */ added chmod notice

Effect extensions in Inkscape means a simple programs or scripts that reads an SVG file from standard input, transforms it somehow and prints it to the standart output. Usually Inkscape sits on both ends, providing the file with some parameters as input first and finally reading the output, which is then used for further work.
[[Image:Effect_flow.svg|thumb|right|400px]]

We will write a simple effect extension script in Python that will put "Hello World!" or "Hello <value of --what option>!" string in the center of document and inside a new layer.

<blockquote>
''This script won't work with the current version of inkscape, it might still help as a useful guide how to create your own scripts though. Especially the methods to access the xml structure have changed, please refer to the [http://codespeak.net/lxml/ lxml] documentation.''
</blockquote>

== Effect Extension Script ==

First of all create a file ''hello_world.py'' and make it executable with the Python interpreter with the well-known directive:
<pre>
#!/usr/bin/env python
</pre>

If you're going to put the file somewhere else than into inkscape's installation directory, we need to add a path so that python can find the necessary modules:
<pre>
import sys
sys.path.append('/usr/share/inkscape/extensions') # or another path, as necessary
</pre>

Import the ''inkex.py'' file with the ''Effect'' base class that will do most of the work for us and the ''simplestyle.py'' module with support functions for working with CSS styles. We will use just the ''formatStyle'' function from this module:
<pre>
import inkex
from simplestyle import *
</pre>

Declare a ''HelloWordEffect'' class that inherits from ''Effect'' and write a constructor where the base class is initialized and script options for the option parser are defined:
<pre>
class HelloWorldEffect(inkex.Effect):
def __init__(self):
inkex.Effect.__init__(self)
self.OptionParser.add_option('-w', '--what', action = 'store',
type = 'string', dest = 'what', default = 'World',
help = 'What would you like to greet?')
</pre>

The complete documentation for the ''OptionParser'' class can be found at http://docs.python.org/lib/module-optparse.html. Here we just use the ''add_option'' method which has as first argument a short option name, as second argument a long option name and then a few other arguments with this meaning:

* ''action'' - An action which should be done with option value. In this case we use action ''store'' which will store option value in ''self.options.<destination>'' attribute.
* ''type'' - Type of option value. We use string here.
* ''dest'' - Destination of option action specified by ''action'' argument. Using ''what'' value we say that we want to store option value to self.options.what attribute.
* ''default'' - Defalut value for this option if it is not specified.
* ''help'' - A help string that will be displayed if script will be given no arguments or some option or argument will have wrong syntax.

Inkscape will create a GUI form with widgets for all specified options and prefill them with the default values specified using the ''.inx'' file for this extension which we will write later.

We need to override only one ''Effect'' class method to provide the desired effect functionality:
<pre>
def effect(self):
what = self.options.what
</pre>
As you can imagine we just stored the ''--what'' option value to the ''what'' variable.

Now we will finally start to do something. We will have to work with the XML representation of the SVG document that we can access via ''Effect'''s ''self.document'' attribute.
It is of lxml's '' _ElementTree'' class type. Complete documentation for the lxml package lxml can be found at http://codespeak.net/lxml/.

First we get SVG document's ''svg'' element and its dimensions:
<pre>
svg = self.document.getroot()
# or alternatively
# svg = self.document.xpath('//svg:svg',namespaces=inkex.NSS)[0]

# Again, there are two ways to get the attibutes:
width = inkex.unittouu(svg.get('width'))
height = inkex.unittouu(svg.attrib['height'])
</pre>
The ''xpath'' function returns a list of all matching elements so we just use the first one of them.

We now create an SVG group element ('' 'g' '') and "mark" it as a layer using Inkscape' SVG extensions:
<pre>
layer = inkex.etree.SubElement(svg, 'g')
layer.set(inkex.addNS('label', 'inkscape'), 'Hello %s Layer' % (what))
layer.set(inkex.addNS('groupmode', 'inkscape'), 'layer')
</pre>
This creates ''inkscape:label'' and ''inkscape:groupmode'' attributes, which will only be read by Inkscape or compatible applications. To all other viewers, this new element looks just like a plain SVG group.

Now we create an SVG text element with a text value containing the "Hello World" string:
<pre>
text = inkex.etree.Element(inkex.addNS('text','svg'))
text.text = 'Hello %s!' % (what)
</pre>

Set the position of the text to the center of SVG document:
<pre>
text.set('x', str(width / 2))
text.set('y', str(height / 2))
</pre>

If we want to center the text on its position we need to define the CSS style of the SVG ''text'' element. Actually we use the ''text-anchor'' SVG extension to CSS styles to do that work:
<pre>
style = {'text-align' : 'center', 'text-anchor' : 'middle'}
text.set('style', formatStyle(style))
</pre>

Finally we connect all created elements together and put them into the SVG document:
<pre>
layer.append(text)
</pre>

We just defined a class that inherited from the original effect extension so we have to create an instance of it and execute it in the main control flow:
<pre>
effect = HelloWorldEffect()
effect.affect()
</pre>

== Extension Description File ==

To include script in Inkscape's main menu create ''hello_world.inx'' file describing script evokation.

<pre>
<inkscape-extension>
<_name>Hello World!</_name>
<id>org.ekips.filter.hello_world</id>
<dependency type="executable" location="extensions">hello_world.py</dependency>
<dependency type="executable" location="extensions">inkex.py</dependency>
<param name="what" type="string" _gui-text="What would you like to greet?">World</param>
<effect>
<object-type>all</object-type>
<effects-menu>
<submenu _name="Examples"/>
</effects-menu>
</effect>
<script>
<command reldir="extensions" interpreter="python">hello_world.py</command>
</script>
</inkscape-extension>
</pre>

Create ''<param>'' element for every option of a script and ''<dependency>'' for every included module which is not from Python standard library. Inkscape will search for this modules in directory with script. ''<effect>'' element and its descendants defines name of menu item evoking our new "Hello World!" extension.

If the inx file isn't well formed or if any of the dependencies wasn't met, the extension won't show up in the menu. If your extension doesn't show up, take a look at extension-errors.log, which may give you a hint why it wasn't loaded.

== Installation ==

To install a new extenstion just put ''hello_world.py'' and ''hello_world.inx'' files with all dependency modules to the ''<path_to_inkscape>/extensions'' or ''~/.inkscape/extensions'' directory. On Linux you will probably have to make the python script executable first if you haven't done this yet. This is usually done by the usual command (or in your preferred file manager):
<pre>
$ chmod a+x hello_world.py
</pre>

Now start Inkscape. A new menu item ''Hello World!'' in ''Effects->Examples'' menu should appear.

== Complete Source Code ==

Here is a complete commented source pre of ''hello_world.py'' script file:

<pre>
#!/usr/bin/env python

# These two lines are only needed if you don't put the script directly into
# the installation directory
import sys
sys.path.append('/usr/share/inkscape/extensions') # or another path, as necessary

# We will use inex module with predefined effect base class.
import inkex
# simplestyle module provides functions for style parsing.
from simplestyle import *

""" Example Inkscape effect extension.
Creates a new layer with "Hello World!" text centered in middle of document."""
class HelloWorldEffect(inkex.Effect):
""" Constructor.
Defines "--what" option of a script."""
def __init__(self):
# Call base class construtor.
inkex.Effect.__init__(self)

# Define string option "--what" with "-w" shortcut and default value "World".
self.OptionParser.add_option('-w', '--what', action = 'store',
type = 'string', dest = 'what', default = 'World',
help = 'What would you like to greet?')

""" Effect behaviour.
Overrides base class' method and insert "Hello World" text in SVG document. """
def effect(self):
# Get script "--what" option value.
what = self.options.what

# Get access to main SVG document element and get its dimensions.
svg = self.document.getElementsByTagName('svg')[0]
width = inkex.unittouu(svg.getAttribute('width'))
height = inkex.unittouu(svg.getAttribute('height'))

# Create a new layer.
layer = self.document.createElement('g')
layer.setAttribute('inkscape:label', 'Hello %s Layer' % (what))
layer.setAttribute('inkscape:groupmode', 'layer')

# Create text element
text = self.document.createElement('text')
value = self.document.createTextNode('Hello %s!' % (what))

# Set text position to center of document.
text.setAttribute('x', str(width / 2))
text.setAttribute('y', str(height / 2))

# Center text horizontally with CSS style.
style = {'text-align' : 'center', 'text-anchor': 'middle'}
text.setAttribute('style', formatStyle(style))

# Connect elements together.
text.appendChild(value)
layer.appendChild(text)
svg.appendChild(layer)

# Create effect instance and apply it.
effect = HelloWorldEffect()
effect.affect()
</pre>

[[User:Blackhex|Blackhex]] 11:59, 26 April 2007 (UTC)

PythonEffectTutorial

2008-08-07T21:03:31Z

Rubikcube: /* Effect Extension Script */ adapted everything to the lxml package

Effect extensions in Inkscape means a simple programs or scripts that reads an SVG file from standard input, transforms it somehow and prints it to the standart output. Usually Inkscape sits on both ends, providing the file with some parameters as input first and finally reading the output, which is then used for further work.
[[Image:Effect_flow.svg|thumb|right|400px]]

We will write a simple effect extension script in Python that will put "Hello World!" or "Hello <value of --what option>!" string in the center of document and inside a new layer.

<blockquote>
''This script won't work with the current version of inkscape, it might still help as a useful guide how to create your own scripts though. Especially the methods to access the xml structure have changed, please refer to the [http://codespeak.net/lxml/ lxml] documentation.''
</blockquote>

== Effect Extension Script ==

First of all create a file ''hello_world.py'' and make it executable with the Python interpreter with the well-known directive:
<pre>
#!/usr/bin/env python
</pre>

If you're going to put the file somewhere else than into inkscape's installation directory, we need to add a path so that python can find the necessary modules:
<pre>
import sys
sys.path.append('/usr/share/inkscape/extensions') # or another path, as necessary
</pre>

Import the ''inkex.py'' file with the ''Effect'' base class that will do most of the work for us and the ''simplestyle.py'' module with support functions for working with CSS styles. We will use just the ''formatStyle'' function from this module:
<pre>
import inkex
from simplestyle import *
</pre>

Declare a ''HelloWordEffect'' class that inherits from ''Effect'' and write a constructor where the base class is initialized and script options for the option parser are defined:
<pre>
class HelloWorldEffect(inkex.Effect):
def __init__(self):
inkex.Effect.__init__(self)
self.OptionParser.add_option('-w', '--what', action = 'store',
type = 'string', dest = 'what', default = 'World',
help = 'What would you like to greet?')
</pre>

The complete documentation for the ''OptionParser'' class can be found at http://docs.python.org/lib/module-optparse.html. Here we just use the ''add_option'' method which has as first argument a short option name, as second argument a long option name and then a few other arguments with this meaning:

* ''action'' - An action which should be done with option value. In this case we use action ''store'' which will store option value in ''self.options.<destination>'' attribute.
* ''type'' - Type of option value. We use string here.
* ''dest'' - Destination of option action specified by ''action'' argument. Using ''what'' value we say that we want to store option value to self.options.what attribute.
* ''default'' - Defalut value for this option if it is not specified.
* ''help'' - A help string that will be displayed if script will be given no arguments or some option or argument will have wrong syntax.

Inkscape will create a GUI form with widgets for all specified options and prefill them with the default values specified using the ''.inx'' file for this extension which we will write later.

We need to override only one ''Effect'' class method to provide the desired effect functionality:
<pre>
def effect(self):
what = self.options.what
</pre>
As you can imagine we just stored the ''--what'' option value to the ''what'' variable.

Now we will finally start to do something. We will have to work with the XML representation of the SVG document that we can access via ''Effect'''s ''self.document'' attribute.
It is of lxml's '' _ElementTree'' class type. Complete documentation for the lxml package lxml can be found at http://codespeak.net/lxml/.

First we get SVG document's ''svg'' element and its dimensions:
<pre>
svg = self.document.getroot()
# or alternatively
# svg = self.document.xpath('//svg:svg',namespaces=inkex.NSS)[0]

# Again, there are two ways to get the attibutes:
width = inkex.unittouu(svg.get('width'))
height = inkex.unittouu(svg.attrib['height'])
</pre>
The ''xpath'' function returns a list of all matching elements so we just use the first one of them.

We now create an SVG group element ('' 'g' '') and "mark" it as a layer using Inkscape' SVG extensions:
<pre>
layer = inkex.etree.SubElement(svg, 'g')
layer.set(inkex.addNS('label', 'inkscape'), 'Hello %s Layer' % (what))
layer.set(inkex.addNS('groupmode', 'inkscape'), 'layer')
</pre>
This creates ''inkscape:label'' and ''inkscape:groupmode'' attributes, which will only be read by Inkscape or compatible applications. To all other viewers, this new element looks just like a plain SVG group.

Now we create an SVG text element with a text value containing the "Hello World" string:
<pre>
text = inkex.etree.Element(inkex.addNS('text','svg'))
text.text = 'Hello %s!' % (what)
</pre>

Set the position of the text to the center of SVG document:
<pre>
text.set('x', str(width / 2))
text.set('y', str(height / 2))
</pre>

If we want to center the text on its position we need to define the CSS style of the SVG ''text'' element. Actually we use the ''text-anchor'' SVG extension to CSS styles to do that work:
<pre>
style = {'text-align' : 'center', 'text-anchor' : 'middle'}
text.set('style', formatStyle(style))
</pre>

Finally we connect all created elements together and put them into the SVG document:
<pre>
layer.append(text)
</pre>

We just defined a class that inherited from the original effect extension so we have to create an instance of it and execute it in the main control flow:
<pre>
effect = HelloWorldEffect()
effect.affect()
</pre>

== Extension Description File ==

To include script in Inkscape's main menu create ''hello_world.inx'' file describing script evokation.

<pre>
<inkscape-extension>
<_name>Hello World!</_name>
<id>org.ekips.filter.hello_world</id>
<dependency type="executable" location="extensions">hello_world.py</dependency>
<dependency type="executable" location="extensions">inkex.py</dependency>
<param name="what" type="string" _gui-text="What would you like to greet?">World</param>
<effect>
<object-type>all</object-type>
<effects-menu>
<submenu _name="Examples"/>
</effects-menu>
</effect>
<script>
<command reldir="extensions" interpreter="python">hello_world.py</command>
</script>
</inkscape-extension>
</pre>

Create ''<param>'' element for every option of a script and ''<dependency>'' for every included module which is not from Python standard library. Inkscape will search for this modules in directory with script. ''<effect>'' element and its descendants defines name of menu item evoking our new "Hello World!" extension.

If the inx file isn't well formed or if any of the dependencies wasn't met, the extension won't show up in the menu. If your extension doesn't show up, take a look at extension-errors.log, which may give you a hint why it wasn't loaded.

== Installation ==

To install a new extenstion just put ''hello_world.py'' and ''hello_world.inx'' files with all dependency modules to ''<path_to_inkscape>/extensions'' or ''~/.inkscape/extensions'' directory and start Inkscape. A new menu item ''Hello World!'' in ''Effects->Examples'' menu should appear.

== Complete Source Code ==

Here is a complete commented source pre of ''hello_world.py'' script file:

<pre>
#!/usr/bin/env python

# These two lines are only needed if you don't put the script directly into
# the installation directory
import sys
sys.path.append('/usr/share/inkscape/extensions') # or another path, as necessary

# We will use inex module with predefined effect base class.
import inkex
# simplestyle module provides functions for style parsing.
from simplestyle import *

""" Example Inkscape effect extension.
Creates a new layer with "Hello World!" text centered in middle of document."""
class HelloWorldEffect(inkex.Effect):
""" Constructor.
Defines "--what" option of a script."""
def __init__(self):
# Call base class construtor.
inkex.Effect.__init__(self)

# Define string option "--what" with "-w" shortcut and default value "World".
self.OptionParser.add_option('-w', '--what', action = 'store',
type = 'string', dest = 'what', default = 'World',
help = 'What would you like to greet?')

""" Effect behaviour.
Overrides base class' method and insert "Hello World" text in SVG document. """
def effect(self):
# Get script "--what" option value.
what = self.options.what

# Get access to main SVG document element and get its dimensions.
svg = self.document.getElementsByTagName('svg')[0]
width = inkex.unittouu(svg.getAttribute('width'))
height = inkex.unittouu(svg.getAttribute('height'))

# Create a new layer.
layer = self.document.createElement('g')
layer.setAttribute('inkscape:label', 'Hello %s Layer' % (what))
layer.setAttribute('inkscape:groupmode', 'layer')

# Create text element
text = self.document.createElement('text')
value = self.document.createTextNode('Hello %s!' % (what))

# Set text position to center of document.
text.setAttribute('x', str(width / 2))
text.setAttribute('y', str(height / 2))

# Center text horizontally with CSS style.
style = {'text-align' : 'center', 'text-anchor': 'middle'}
text.setAttribute('style', formatStyle(style))

# Connect elements together.
text.appendChild(value)
layer.appendChild(text)
svg.appendChild(layer)

# Create effect instance and apply it.
effect = HelloWorldEffect()
effect.affect()
</pre>

[[User:Blackhex|Blackhex]] 11:59, 26 April 2007 (UTC)

PythonEffectTutorial

2008-08-07T20:44:48Z

Rubikcube: /* Effect Extension Script */ corrected some spelling / grammar mistakes

Effect extensions in Inkscape means a simple programs or scripts that reads an SVG file from standard input, transforms it somehow and prints it to the standart output. Usually Inkscape sits on both ends, providing the file with some parameters as input first and finally reading the output, which is then used for further work.
[[Image:Effect_flow.svg|thumb|right|400px]]

We will write a simple effect extension script in Python that will put "Hello World!" or "Hello <value of --what option>!" string in the center of document and inside a new layer.

<blockquote>
''This script won't work with the current version of inkscape, it might still help as a useful guide how to create your own scripts though. Especially the methods to access the xml structure have changed, please refer to the [http://codespeak.net/lxml/ lxml] documentation.''
</blockquote>

== Effect Extension Script ==

First of all create a file ''hello_world.py'' and make it executable with the Python interpreter with the well-known directive:

<pre>
#!/usr/bin/env python
</pre>

If you're going to put the file somewhere else than into inkscape's installation directory, we need to add a path so that python can find the necessary modules:

<pre>
import sys
sys.path.append('/usr/share/inkscape/extensions') # or another path, as necessary
</pre>

Import the ''inkex.py'' file with the ''Effect'' base class that will do most of the work for us and the ''simplestyle.py'' module with support functions for working with CSS styles. We will use just the ''formatStyle'' function from this module:

<pre>
import inkex
from simplestyle import *
</pre>

Declare a ''HelloWordEffect'' class that inherits from ''Effect'' and write a constructor where the base class is initialized and script options for the option parser are defined:

<pre>
class HelloWorldEffect(inkex.Effect):
def __init__(self):
inkex.Effect.__init__(self)
self.OptionParser.add_option('-w', '--what', action = 'store',
type = 'string', dest = 'what', default = 'World',
help = 'What would you like to greet?')
</pre>

The complete documentation for the ''OptionParser'' class can be found at http://docs.python.org/lib/module-optparse.html. Here we just use the ''add_option'' method which has as first argument a short option name, as second argument a long option name and then a few other arguments with this meaning:

* ''action'' - An action which should be done with option value. In this case we use action ''store'' which will store option value in ''self.options.<destination>'' attribute.
* ''type'' - Type of option value. We use string here.
* ''dest'' - Destination of option action specified by ''action'' argument. Using ''what'' value we say that we want to store option value to self.options.what attribute.
* ''default'' - Defalut value for this option if it is not specified.
* ''help'' - A help string that will be displayed if script will be given no arguments or some option or argument will have wrong syntax.

Inkscape will create a GUI form with widgets for all specified options and prefill them with the default values specified using the ''.inx'' file for this extension which we will write later.

We need to override only one ''Effect'' class method to provide the desired effect functionality:
<pre>
def effect(self):
what = self.options.what
</pre>

As you can imagine we just stored the ''--what'' option value to the ''what'' variable.

Now we will finally start to do something. We will have to work with the XML representation of the SVG document that we can access via ''Effect'''s ''self.document'' attribute. It is of ''Document'' class type from ''xml.dom'' module. Complete documentation for this module can be found at http://docs.python.org/lib/module-xml.dom.html.

First get SVG document ''svg'' element and its dimensions:

<pre>
svg = self.document.getElementsByTagName('svg')[0]
width = inkex.unittouu(svg.getAttribute('width'))
height = inkex.unittouu(svg.getAttribute('height'))
</pre>

Function ''getElementsByTagName'' returns list of all found elements of this name so we just use first of them.

Create SVG group element and "convert" it to layer using Inkscape SVG extenstions:

<pre>
layer = self.document.createElement('g')
layer.setAttribute('inkscape:label', 'Hello %s Layer' % (what))
layer.setAttribute('inkscape:groupmode', 'layer')
</pre>

Create SVG text element and its value containing "Hello World"" string:

<pre>
text = self.document.createElement('text')
value = self.document.createTextNode('Hello %s!' % (what))
</pre>

Set position of text to center of SVG document:

<pre>
text.setAttribute('x', str(width / 2))
text.setAttribute('y', str(height / 2))
</pre>

If we want center text on its position we will define CSS style of SVG ''text'' element. Actually use ''text-anchor'' SVG extension to CSS styles to do that work:

<pre>
style = {'text-align' : 'center', 'text-anchor' : 'middle'}
text.setAttribute('style', formatStyle(style))
</pre>

Finally connect all created elements together and put them in SVG document:

<pre>
text.appendChild(value)
layer.appendChild(text)
svg.appendChild(layer)
</pre>

We just defined a class of our effect extension so we have to create an instance of it and execute it in main control flow:

<pre>
effect = HelloWorldEffect()
effect.affect()
</pre>

== Extension Description File ==

To include script in Inkscape's main menu create ''hello_world.inx'' file describing script evokation.

<pre>
<inkscape-extension>
<_name>Hello World!</_name>
<id>org.ekips.filter.hello_world</id>
<dependency type="executable" location="extensions">hello_world.py</dependency>
<dependency type="executable" location="extensions">inkex.py</dependency>
<param name="what" type="string" _gui-text="What would you like to greet?">World</param>
<effect>
<object-type>all</object-type>
<effects-menu>
<submenu _name="Examples"/>
</effects-menu>
</effect>
<script>
<command reldir="extensions" interpreter="python">hello_world.py</command>
</script>
</inkscape-extension>
</pre>

Create ''<param>'' element for every option of a script and ''<dependency>'' for every included module which is not from Python standard library. Inkscape will search for this modules in directory with script. ''<effect>'' element and its descendants defines name of menu item evoking our new "Hello World!" extension.

If the inx file isn't well formed or if any of the dependencies wasn't met, the extension won't show up in the menu. If your extension doesn't show up, take a look at extension-errors.log, which may give you a hint why it wasn't loaded.

== Installation ==

To install a new extenstion just put ''hello_world.py'' and ''hello_world.inx'' files with all dependency modules to ''<path_to_inkscape>/extensions'' or ''~/.inkscape/extensions'' directory and start Inkscape. A new menu item ''Hello World!'' in ''Effects->Examples'' menu should appear.

== Complete Source Code ==

Here is a complete commented source pre of ''hello_world.py'' script file:

<pre>
#!/usr/bin/env python

# These two lines are only needed if you don't put the script directly into
# the installation directory
import sys
sys.path.append('/usr/share/inkscape/extensions') # or another path, as necessary

# We will use inex module with predefined effect base class.
import inkex
# simplestyle module provides functions for style parsing.
from simplestyle import *

""" Example Inkscape effect extension.
Creates a new layer with "Hello World!" text centered in middle of document."""
class HelloWorldEffect(inkex.Effect):
""" Constructor.
Defines "--what" option of a script."""
def __init__(self):
# Call base class construtor.
inkex.Effect.__init__(self)

# Define string option "--what" with "-w" shortcut and default value "World".
self.OptionParser.add_option('-w', '--what', action = 'store',
type = 'string', dest = 'what', default = 'World',
help = 'What would you like to greet?')

""" Effect behaviour.
Overrides base class' method and insert "Hello World" text in SVG document. """
def effect(self):
# Get script "--what" option value.
what = self.options.what

# Get access to main SVG document element and get its dimensions.
svg = self.document.getElementsByTagName('svg')[0]
width = inkex.unittouu(svg.getAttribute('width'))
height = inkex.unittouu(svg.getAttribute('height'))

# Create a new layer.
layer = self.document.createElement('g')
layer.setAttribute('inkscape:label', 'Hello %s Layer' % (what))
layer.setAttribute('inkscape:groupmode', 'layer')

# Create text element
text = self.document.createElement('text')
value = self.document.createTextNode('Hello %s!' % (what))

# Set text position to center of document.
text.setAttribute('x', str(width / 2))
text.setAttribute('y', str(height / 2))

# Center text horizontally with CSS style.
style = {'text-align' : 'center', 'text-anchor': 'middle'}
text.setAttribute('style', formatStyle(style))

# Connect elements together.
text.appendChild(value)
layer.appendChild(text)
svg.appendChild(layer)

# Create effect instance and apply it.
effect = HelloWorldEffect()
effect.affect()
</pre>

[[User:Blackhex|Blackhex]] 11:59, 26 April 2007 (UTC)

PythonEffectTutorial

2008-07-30T17:41:29Z

Rubikcube: Added note about the current state of this example

Effect extensions in Inkscape means a simple programs or scripts that reads an SVG file from standard input, transforms it somehow and prints it to the standart output. Usually Inkscape sits on both ends, providing the file with some parameters as input first and finally reading the output, which is then used for further work.
[[Image:Effect_flow.svg|thumb|right|400px]]

We will write a simple effect extension script in Python that will put "Hello World!" or "Hello <value of --what option>!" string in the center of document and inside a new layer.

<blockquote>
''This script won't work with the current version of inkscape, it might still help as a useful guide how to create your own scripts though. Especially the methods to access the xml structure have changed, please refer to the [http://codespeak.net/lxml/ lxml] documentation.''
</blockquote>

== Effect Extension Script ==

First of all create a file ''hello_world.py'' and make it executable with the Python interpreter with the well-known directive:

<pre>
#!/usr/bin/env python
</pre>

If you're going to put the file somewhere else than into inkscape's installation directory, we need to add a path so that python can find the necessary modules:

<pre>
import sys
sys.path.append('/usr/share/inkscape/extensions') # or another path, as necessary
</pre>

Import ''inkex.py'' file with ''Effect'' base class that will do most of work for us and ''simplestyle.py'' module with support functions for working with CSS styles. We will use just the ''formatStyle'' function from this module.:

<pre>
import inkex
from simplestyle import *
</pre>

Declare ''HelloWordEffect'' class and write a constructor where the base class is initialized and script options for the option parser are defined:

<pre>
class HelloWorldEffect(inkex.Effect):
def __init__(self):
inkex.Effect.__init__(self)
self.OptionParser.add_option('-w', '--what', action = 'store',
type = 'string', dest = 'what', default = 'World',
help = 'What would you like to greet?')
</pre>

The complete documentation for the ''OptionParser'' class can be found at http://docs.python.org/lib/module-optparse.html. Here we just use the ''add_option'' method which has as first argument a short option name, as second argument a long option name and then a few other arguments with this meaning:

* ''action'' - An action which should be done with option value. In this case we use action ''store'' which will store option value in ''self.options.<destination>'' attribute.
* ''type'' - Type of option value. We use string here.
* ''dest'' - Destination of option action specified by ''action'' argument. Using ''what'' value we say that we want to store option value to self.options.what attribute.
* ''default'' - Defalut value for this option if it is not specified.
* ''help'' - A help string that will be displayed if script will be given no arguments or some option or argument will have wrong syntax.

Inkscape will create a GUI form with widgets for all specified options and prefill them with specified default values using ''.inx''. file for this extenstion which we will write later.

We need to override only one ''Effect'' class method to provide effect functionality:
<pre>
def effect(self):
what = self.options.what
</pre>

As you can mention we just stored ''--what'' option value to ''what'' variable.

Now we will finally start to do something. We will work with XML representation of SVG document via ''self.document'' attribute. It is of ''Document'' class type from ''xml.dom'' module. Complete documentation for this module can be found at http://docs.python.org/lib/module-xml.dom.html.

First get SVG document ''svg'' element and its dimensions:

<pre>
svg = self.document.getElementsByTagName('svg')[0]
width = inkex.unittouu(svg.getAttribute('width'))
height = inkex.unittouu(svg.getAttribute('height'))
</pre>

Function ''getElementsByTagName'' returns list of all found elements of this name so we just use first of them.

Create SVG group element and "convert" it to layer using Inkscape SVG extenstions:

<pre>
layer = self.document.createElement('g')
layer.setAttribute('inkscape:label', 'Hello %s Layer' % (what))
layer.setAttribute('inkscape:groupmode', 'layer')
</pre>

Create SVG text element and its value containing "Hello World"" string:

<pre>
text = self.document.createElement('text')
value = self.document.createTextNode('Hello %s!' % (what))
</pre>

Set position of text to center of SVG document:

<pre>
text.setAttribute('x', str(width / 2))
text.setAttribute('y', str(height / 2))
</pre>

If we want center text on its position we will define CSS style of SVG ''text'' element. Actually use ''text-anchor'' SVG extension to CSS styles to do that work:

<pre>
style = {'text-align' : 'center', 'text-anchor' : 'middle'}
text.setAttribute('style', formatStyle(style))
</pre>

Finally connect all created elements together and put them in SVG document:

<pre>
text.appendChild(value)
layer.appendChild(text)
svg.appendChild(layer)
</pre>

We just defined a class of our effect extension so we have to create an instance of it and execute it in main control flow:

<pre>
effect = HelloWorldEffect()
effect.affect()
</pre>

== Extension Description File ==

To include script in Inkscape's main menu create ''hello_world.inx'' file describing script evokation.

<pre>
<inkscape-extension>
<_name>Hello World!</_name>
<id>org.ekips.filter.hello_world</id>
<dependency type="executable" location="extensions">hello_world.py</dependency>
<dependency type="executable" location="extensions">inkex.py</dependency>
<param name="what" type="string" _gui-text="What would you like to greet?">World</param>
<effect>
<object-type>all</object-type>
<effects-menu>
<submenu _name="Examples"/>
</effects-menu>
</effect>
<script>
<command reldir="extensions" interpreter="python">hello_world.py</command>
</script>
</inkscape-extension>
</pre>

Create ''<param>'' element for every option of a script and ''<dependency>'' for every included module which is not from Python standard library. Inkscape will search for this modules in directory with script. ''<effect>'' element and its descendants defines name of menu item evoking our new "Hello World!" extension.

If the inx file isn't well formed or if any of the dependencies wasn't met, the extension won't show up in the menu. If your extension doesn't show up, take a look at extension-errors.log, which may give you a hint why it wasn't loaded.

== Installation ==

To install a new extenstion just put ''hello_world.py'' and ''hello_world.inx'' files with all dependency modules to ''<path_to_inkscape>/extensions'' or ''~/.inkscape/extensions'' directory and start Inkscape. A new menu item ''Hello World!'' in ''Effects->Examples'' menu should appear.

== Complete Source Code ==

Here is a complete commented source pre of ''hello_world.py'' script file:

<pre>
#!/usr/bin/env python

# These two lines are only needed if you don't put the script directly into
# the installation directory
import sys
sys.path.append('/usr/share/inkscape/extensions') # or another path, as necessary

# We will use inex module with predefined effect base class.
import inkex
# simplestyle module provides functions for style parsing.
from simplestyle import *

""" Example Inkscape effect extension.
Creates a new layer with "Hello World!" text centered in middle of document."""
class HelloWorldEffect(inkex.Effect):
""" Constructor.
Defines "--what" option of a script."""
def __init__(self):
# Call base class construtor.
inkex.Effect.__init__(self)

# Define string option "--what" with "-w" shortcut and default value "World".
self.OptionParser.add_option('-w', '--what', action = 'store',
type = 'string', dest = 'what', default = 'World',
help = 'What would you like to greet?')

""" Effect behaviour.
Overrides base class' method and insert "Hello World" text in SVG document. """
def effect(self):
# Get script "--what" option value.
what = self.options.what

# Get access to main SVG document element and get its dimensions.
svg = self.document.getElementsByTagName('svg')[0]
width = inkex.unittouu(svg.getAttribute('width'))
height = inkex.unittouu(svg.getAttribute('height'))

# Create a new layer.
layer = self.document.createElement('g')
layer.setAttribute('inkscape:label', 'Hello %s Layer' % (what))
layer.setAttribute('inkscape:groupmode', 'layer')

# Create text element
text = self.document.createElement('text')
value = self.document.createTextNode('Hello %s!' % (what))

# Set text position to center of document.
text.setAttribute('x', str(width / 2))
text.setAttribute('y', str(height / 2))

# Center text horizontally with CSS style.
style = {'text-align' : 'center', 'text-anchor': 'middle'}
text.setAttribute('style', formatStyle(style))

# Connect elements together.
text.appendChild(value)
layer.appendChild(text)
svg.appendChild(layer)

# Create effect instance and apply it.
effect = HelloWorldEffect()
effect.affect()
</pre>

[[User:Blackhex|Blackhex]] 11:59, 26 April 2007 (UTC)

PythonEffectTutorial

2008-07-30T08:22:35Z

Rubikcube:

Effect extensions in Inkscape means a simple programs or scripts that reads an SVG file from standard input, transforms it somehow and prints it to the standart output. Usually Inkscape sits on both ends, providing the file with some parameters as input first and finally reading the output, which is then used for further work.
[[Image:Effect_flow.svg|thumb|right|400px]]

We will write a simple effect extension script in Python that will put "Hello World!" or "Hello <value of --what option>!" string in the center of document and inside a new layer.

== Effect Extension Script ==

First of all create a file ''hello_world.py'' and make it executable with the Python interpreter with the well-known directive:

<pre>
#!/usr/bin/env python
</pre>

If you're going to put the file somewhere else than into inkscape's installation directory, we need to add a path so that python can find the necessary modules:

<pre>
import sys
sys.path.append('/usr/share/inkscape/extensions') # or another path, as necessary
</pre>

Import ''inkex.py'' file with ''Effect'' base class that will do most of work for us and ''simplestyle.py'' module with support functions for working with CSS styles. We will use just the ''formatStyle'' function from this module.:

<pre>
import inkex
from simplestyle import *
</pre>

Declare ''HelloWordEffect'' class and write a constructor where the base class is initialized and script options for the option parser are defined:

<pre>
class HelloWorldEffect(inkex.Effect):
def __init__(self):
inkex.Effect.__init__(self)
self.OptionParser.add_option('-w', '--what', action = 'store',
type = 'string', dest = 'what', default = 'World',
help = 'What would you like to greet?')
</pre>

The complete documentation for the ''OptionParser'' class can be found at http://docs.python.org/lib/module-optparse.html. Here we just use the ''add_option'' method which has as first argument a short option name, as second argument a long option name and then a few other arguments with this meaning:

* ''action'' - An action which should be done with option value. In this case we use action ''store'' which will store option value in ''self.options.<destination>'' attribute.
* ''type'' - Type of option value. We use string here.
* ''dest'' - Destination of option action specified by ''action'' argument. Using ''what'' value we say that we want to store option value to self.options.what attribute.
* ''default'' - Defalut value for this option if it is not specified.
* ''help'' - A help string that will be displayed if script will be given no arguments or some option or argument will have wrong syntax.

Inkscape will create a GUI form with widgets for all specified options and prefill them with specified default values using ''.inx''. file for this extenstion which we will write later.

We need to override only one ''Effect'' class method to provide effect functionality:
<pre>
def effect(self):
what = self.options.what
</pre>

As you can mention we just stored ''--what'' option value to ''what'' variable.

Now we will finally start to do something. We will work with XML representation of SVG document via ''self.document'' attribute. It is of ''Document'' class type from ''xml.dom'' module. Complete documentation for this module can be found at http://docs.python.org/lib/module-xml.dom.html.

First get SVG document ''svg'' element and its dimensions:

<pre>
svg = self.document.getElementsByTagName('svg')[0]
width = inkex.unittouu(svg.getAttribute('width'))
height = inkex.unittouu(svg.getAttribute('height'))
</pre>

Function ''getElementsByTagName'' returns list of all found elements of this name so we just use first of them.

Create SVG group element and "convert" it to layer using Inkscape SVG extenstions:

<pre>
layer = self.document.createElement('g')
layer.setAttribute('inkscape:label', 'Hello %s Layer' % (what))
layer.setAttribute('inkscape:groupmode', 'layer')
</pre>

Create SVG text element and its value containing "Hello World"" string:

<pre>
text = self.document.createElement('text')
value = self.document.createTextNode('Hello %s!' % (what))
</pre>

Set position of text to center of SVG document:

<pre>
text.setAttribute('x', str(width / 2))
text.setAttribute('y', str(height / 2))
</pre>

If we want center text on its position we will define CSS style of SVG ''text'' element. Actually use ''text-anchor'' SVG extension to CSS styles to do that work:

<pre>
style = {'text-align' : 'center', 'text-anchor' : 'middle'}
text.setAttribute('style', formatStyle(style))
</pre>

Finally connect all created elements together and put them in SVG document:

<pre>
text.appendChild(value)
layer.appendChild(text)
svg.appendChild(layer)
</pre>

We just defined a class of our effect extension so we have to create an instance of it and execute it in main control flow:

<pre>
effect = HelloWorldEffect()
effect.affect()
</pre>

== Extension Description File ==

To include script in Inkscape's main menu create ''hello_world.inx'' file describing script evokation.

<pre>
<inkscape-extension>
<_name>Hello World!</_name>
<id>org.ekips.filter.hello_world</id>
<dependency type="executable" location="extensions">hello_world.py</dependency>
<dependency type="executable" location="extensions">inkex.py</dependency>
<param name="what" type="string" _gui-text="What would you like to greet?">World</param>
<effect>
<object-type>all</object-type>
<effects-menu>
<submenu _name="Examples"/>
</effects-menu>
</effect>
<script>
<command reldir="extensions" interpreter="python">hello_world.py</command>
</script>
</inkscape-extension>
</pre>

Create ''<param>'' element for every option of a script and ''<dependency>'' for every included module which is not from Python standard library. Inkscape will search for this modules in directory with script. ''<effect>'' element and its descendants defines name of menu item evoking our new "Hello World!" extension.

If the inx file isn't well formed or if any of the dependencies wasn't met, the extension won't show up in the menu. If your extension doesn't show up, take a look at extension-errors.log, which may give you a hint why it wasn't loaded.

== Installation ==

To install a new extenstion just put ''hello_world.py'' and ''hello_world.inx'' files with all dependency modules to ''<path_to_inkscape>/extensions'' or ''~/.inkscape/extensions'' directory and start Inkscape. A new menu item ''Hello World!'' in ''Effects->Examples'' menu should appear.

== Complete Source Code ==

Here is a complete commented source pre of ''hello_world.py'' script file:

<pre>
#!/usr/bin/env python

# These two lines are only needed if you don't put the script directly into
# the installation directory
import sys
sys.path.append('/usr/share/inkscape/extensions') # or another path, as necessary

# We will use inex module with predefined effect base class.
import inkex
# simplestyle module provides functions for style parsing.
from simplestyle import *

""" Example Inkscape effect extension.
Creates a new layer with "Hello World!" text centered in middle of document."""
class HelloWorldEffect(inkex.Effect):
""" Constructor.
Defines "--what" option of a script."""
def __init__(self):
# Call base class construtor.
inkex.Effect.__init__(self)

# Define string option "--what" with "-w" shortcut and default value "World".
self.OptionParser.add_option('-w', '--what', action = 'store',
type = 'string', dest = 'what', default = 'World',
help = 'What would you like to greet?')

""" Effect behaviour.
Overrides base class' method and insert "Hello World" text in SVG document. """
def effect(self):
# Get script "--what" option value.
what = self.options.what

# Get access to main SVG document element and get its dimensions.
svg = self.document.getElementsByTagName('svg')[0]
width = inkex.unittouu(svg.getAttribute('width'))
height = inkex.unittouu(svg.getAttribute('height'))

# Create a new layer.
layer = self.document.createElement('g')
layer.setAttribute('inkscape:label', 'Hello %s Layer' % (what))
layer.setAttribute('inkscape:groupmode', 'layer')

# Create text element
text = self.document.createElement('text')
value = self.document.createTextNode('Hello %s!' % (what))

# Set text position to center of document.
text.setAttribute('x', str(width / 2))
text.setAttribute('y', str(height / 2))

# Center text horizontally with CSS style.
style = {'text-align' : 'center', 'text-anchor': 'middle'}
text.setAttribute('style', formatStyle(style))

# Connect elements together.
text.appendChild(value)
layer.appendChild(text)
svg.appendChild(layer)

# Create effect instance and apply it.
effect = HelloWorldEffect()
effect.affect()
</pre>

[[User:Blackhex|Blackhex]] 11:59, 26 April 2007 (UTC)

PythonEffectTutorial

2008-07-30T08:15:22Z

Rubikcube: Added sketch

Effect extensions in Inkscape means a simple programs or scripts that reads an SVG file from standard input, transforms it somehow and prints it to the standart output. Usually Inkscape sits on both ends, providing the file with some parameters as input first and finally reading the output, which is then used for further work.
[[Image:Effect_flow.svg]]

We will write a simple effect extension script in Python that will put "Hello World!" or "Hello <value of --what option>!" string in the center of document and inside a new layer.

== Effect Extension Script ==

First of all create a file ''hello_world.py'' and make it executable with the Python interpreter with the well-known directive:

<pre>
#!/usr/bin/env python
</pre>

If you're going to put the file somewhere else than into inkscape's installation directory, we need to add a path so that python can find the necessary modules:

<pre>
import sys
sys.path.append('/usr/share/inkscape/extensions') # or another path, as necessary
</pre>

Import ''inkex.py'' file with ''Effect'' base class that will do most of work for us and ''simplestyle.py'' module with support functions for working with CSS styles. We will use just the ''formatStyle'' function from this module.:

<pre>
import inkex
from simplestyle import *
</pre>

Declare ''HelloWordEffect'' class and write a constructor where the base class is initialized and script options for the option parser are defined:

<pre>
class HelloWorldEffect(inkex.Effect):
def __init__(self):
inkex.Effect.__init__(self)
self.OptionParser.add_option('-w', '--what', action = 'store',
type = 'string', dest = 'what', default = 'World',
help = 'What would you like to greet?')
</pre>

The complete documentation for the ''OptionParser'' class can be found at http://docs.python.org/lib/module-optparse.html. Here we just use the ''add_option'' method which has as first argument a short option name, as second argument a long option name and then a few other arguments with this meaning:

* ''action'' - An action which should be done with option value. In this case we use action ''store'' which will store option value in ''self.options.<destination>'' attribute.
* ''type'' - Type of option value. We use string here.
* ''dest'' - Destination of option action specified by ''action'' argument. Using ''what'' value we say that we want to store option value to self.options.what attribute.
* ''default'' - Defalut value for this option if it is not specified.
* ''help'' - A help string that will be displayed if script will be given no arguments or some option or argument will have wrong syntax.

Inkscape will create a GUI form with widgets for all specified options and prefill them with specified default values using ''.inx''. file for this extenstion which we will write later.

We need to override only one ''Effect'' class method to provide effect functionality:
<pre>
def effect(self):
what = self.options.what
</pre>

As you can mention we just stored ''--what'' option value to ''what'' variable.

Now we will finally start to do something. We will work with XML representation of SVG document via ''self.document'' attribute. It is of ''Document'' class type from ''xml.dom'' module. Complete documentation for this module can be found at http://docs.python.org/lib/module-xml.dom.html.

First get SVG document ''svg'' element and its dimensions:

<pre>
svg = self.document.getElementsByTagName('svg')[0]
width = inkex.unittouu(svg.getAttribute('width'))
height = inkex.unittouu(svg.getAttribute('height'))
</pre>

Function ''getElementsByTagName'' returns list of all found elements of this name so we just use first of them.

Create SVG group element and "convert" it to layer using Inkscape SVG extenstions:

<pre>
layer = self.document.createElement('g')
layer.setAttribute('inkscape:label', 'Hello %s Layer' % (what))
layer.setAttribute('inkscape:groupmode', 'layer')
</pre>

Create SVG text element and its value containing "Hello World"" string:

<pre>
text = self.document.createElement('text')
value = self.document.createTextNode('Hello %s!' % (what))
</pre>

Set position of text to center of SVG document:

<pre>
text.setAttribute('x', str(width / 2))
text.setAttribute('y', str(height / 2))
</pre>

If we want center text on its position we will define CSS style of SVG ''text'' element. Actually use ''text-anchor'' SVG extension to CSS styles to do that work:

<pre>
style = {'text-align' : 'center', 'text-anchor' : 'middle'}
text.setAttribute('style', formatStyle(style))
</pre>

Finally connect all created elements together and put them in SVG document:

<pre>
text.appendChild(value)
layer.appendChild(text)
svg.appendChild(layer)
</pre>

We just defined a class of our effect extension so we have to create an instance of it and execute it in main control flow:

<pre>
effect = HelloWorldEffect()
effect.affect()
</pre>

== Extension Description File ==

To include script in Inkscape's main menu create ''hello_world.inx'' file describing script evokation.

<pre>
<inkscape-extension>
<_name>Hello World!</_name>
<id>org.ekips.filter.hello_world</id>
<dependency type="executable" location="extensions">hello_world.py</dependency>
<dependency type="executable" location="extensions">inkex.py</dependency>
<param name="what" type="string" _gui-text="What would you like to greet?">World</param>
<effect>
<object-type>all</object-type>
<effects-menu>
<submenu _name="Examples"/>
</effects-menu>
</effect>
<script>
<command reldir="extensions" interpreter="python">hello_world.py</command>
</script>
</inkscape-extension>
</pre>

Create ''<param>'' element for every option of a script and ''<dependency>'' for every included module which is not from Python standard library. Inkscape will search for this modules in directory with script. ''<effect>'' element and its descendants defines name of menu item evoking our new "Hello World!" extension.

If the inx file isn't well formed or if any of the dependencies wasn't met, the extension won't show up in the menu. If your extension doesn't show up, take a look at extension-errors.log, which may give you a hint why it wasn't loaded.

== Installation ==

To install a new extenstion just put ''hello_world.py'' and ''hello_world.inx'' files with all dependency modules to ''<path_to_inkscape>/extensions'' or ''~/.inkscape/extensions'' directory and start Inkscape. A new menu item ''Hello World!'' in ''Effects->Examples'' menu should appear.

== Complete Source Code ==

Here is a complete commented source pre of ''hello_world.py'' script file:

<pre>
#!/usr/bin/env python

# These two lines are only needed if you don't put the script directly into
# the installation directory
import sys
sys.path.append('/usr/share/inkscape/extensions') # or another path, as necessary

# We will use inex module with predefined effect base class.
import inkex
# simplestyle module provides functions for style parsing.
from simplestyle import *

""" Example Inkscape effect extension.
Creates a new layer with "Hello World!" text centered in middle of document."""
class HelloWorldEffect(inkex.Effect):
""" Constructor.
Defines "--what" option of a script."""
def __init__(self):
# Call base class construtor.
inkex.Effect.__init__(self)

# Define string option "--what" with "-w" shortcut and default value "World".
self.OptionParser.add_option('-w', '--what', action = 'store',
type = 'string', dest = 'what', default = 'World',
help = 'What would you like to greet?')

""" Effect behaviour.
Overrides base class' method and insert "Hello World" text in SVG document. """
def effect(self):
# Get script "--what" option value.
what = self.options.what

# Get access to main SVG document element and get its dimensions.
svg = self.document.getElementsByTagName('svg')[0]
width = inkex.unittouu(svg.getAttribute('width'))
height = inkex.unittouu(svg.getAttribute('height'))

# Create a new layer.
layer = self.document.createElement('g')
layer.setAttribute('inkscape:label', 'Hello %s Layer' % (what))
layer.setAttribute('inkscape:groupmode', 'layer')

# Create text element
text = self.document.createElement('text')
value = self.document.createTextNode('Hello %s!' % (what))

# Set text position to center of document.
text.setAttribute('x', str(width / 2))
text.setAttribute('y', str(height / 2))

# Center text horizontally with CSS style.
style = {'text-align' : 'center', 'text-anchor': 'middle'}
text.setAttribute('style', formatStyle(style))

# Connect elements together.
text.appendChild(value)
layer.appendChild(text)
svg.appendChild(layer)

# Create effect instance and apply it.
effect = HelloWorldEffect()
effect.affect()
</pre>

[[User:Blackhex|Blackhex]] 11:59, 26 April 2007 (UTC)

File:Effect flow.svg

2008-07-30T08:07:36Z

Rubikcube: Sketch of data flow through inkscape effect scripts

Sketch of data flow through inkscape effect scripts

PythonEffectTutorial

2008-07-30T07:59:23Z

Rubikcube: Added more info to the first paragraph, some minor corrections

Effect extensions in Inkscape means a simple programs or scripts that reads an SVG file from standard input, transforms it somehow and prints it to the standart output. Usually Inkscape sits on both ends, providing the file with some parameters as input first and finally reading the output, which is then used for further work.

We will write a simple effect extension script in Python that will put "Hello World!" or "Hello <value of --what option>!" string in the center of document and inside a new layer.

== Effect Extension Script ==

First of all create a file ''hello_world.py'' and make it executable with the Python interpreter with the well-known directive:

<pre>
#!/usr/bin/env python
</pre>

If you're going to put the file somewhere else than into inkscape's installation directory, we need to add a path so that python can find the necessary modules:

<pre>
import sys
sys.path.append('/usr/share/inkscape/extensions') # or another path, as necessary
</pre>

Import ''inkex.py'' file with ''Effect'' base class that will do most of work for us and ''simplestyle.py'' module with support functions for working with CSS styles. We will use just the ''formatStyle'' function from this module.:

<pre>
import inkex
from simplestyle import *
</pre>

Declare ''HelloWordEffect'' class and write a constructor where the base class is initialized and script options for the option parser are defined:

<pre>
class HelloWorldEffect(inkex.Effect):
def __init__(self):
inkex.Effect.__init__(self)
self.OptionParser.add_option('-w', '--what', action = 'store',
type = 'string', dest = 'what', default = 'World',
help = 'What would you like to greet?')
</pre>

The complete documentation for the ''OptionParser'' class can be found at http://docs.python.org/lib/module-optparse.html. Here we just use the ''add_option'' method which has as first argument a short option name, as second argument a long option name and then a few other arguments with this meaning:

* ''action'' - An action which should be done with option value. In this case we use action ''store'' which will store option value in ''self.options.<destination>'' attribute.
* ''type'' - Type of option value. We use string here.
* ''dest'' - Destination of option action specified by ''action'' argument. Using ''what'' value we say that we want to store option value to self.options.what attribute.
* ''default'' - Defalut value for this option if it is not specified.
* ''help'' - A help string that will be displayed if script will be given no arguments or some option or argument will have wrong syntax.

Inkscape will create a GUI form with widgets for all specified options and prefill them with specified default values using ''.inx''. file for this extenstion which we will write later.

We need to override only one ''Effect'' class method to provide effect functionality:
<pre>
def effect(self):
what = self.options.what
</pre>

As you can mention we just stored ''--what'' option value to ''what'' variable.

Now we will finally start to do something. We will work with XML representation of SVG document via ''self.document'' attribute. It is of ''Document'' class type from ''xml.dom'' module. Complete documentation for this module can be found at http://docs.python.org/lib/module-xml.dom.html.

First get SVG document ''svg'' element and its dimensions:

<pre>
svg = self.document.getElementsByTagName('svg')[0]
width = inkex.unittouu(svg.getAttribute('width'))
height = inkex.unittouu(svg.getAttribute('height'))
</pre>

Function ''getElementsByTagName'' returns list of all found elements of this name so we just use first of them.

Create SVG group element and "convert" it to layer using Inkscape SVG extenstions:

<pre>
layer = self.document.createElement('g')
layer.setAttribute('inkscape:label', 'Hello %s Layer' % (what))
layer.setAttribute('inkscape:groupmode', 'layer')
</pre>

Create SVG text element and its value containing "Hello World"" string:

<pre>
text = self.document.createElement('text')
value = self.document.createTextNode('Hello %s!' % (what))
</pre>

Set position of text to center of SVG document:

<pre>
text.setAttribute('x', str(width / 2))
text.setAttribute('y', str(height / 2))
</pre>

If we want center text on its position we will define CSS style of SVG ''text'' element. Actually use ''text-anchor'' SVG extension to CSS styles to do that work:

<pre>
style = {'text-align' : 'center', 'text-anchor' : 'middle'}
text.setAttribute('style', formatStyle(style))
</pre>

Finally connect all created elements together and put them in SVG document:

<pre>
text.appendChild(value)
layer.appendChild(text)
svg.appendChild(layer)
</pre>

We just defined a class of our effect extension so we have to create an instance of it and execute it in main control flow:

<pre>
effect = HelloWorldEffect()
effect.affect()
</pre>

== Extension Description File ==

To include script in Inkscape's main menu create ''hello_world.inx'' file describing script evokation.

<pre>
<inkscape-extension>
<_name>Hello World!</_name>
<id>org.ekips.filter.hello_world</id>
<dependency type="executable" location="extensions">hello_world.py</dependency>
<dependency type="executable" location="extensions">inkex.py</dependency>
<param name="what" type="string" _gui-text="What would you like to greet?">World</param>
<effect>
<object-type>all</object-type>
<effects-menu>
<submenu _name="Examples"/>
</effects-menu>
</effect>
<script>
<command reldir="extensions" interpreter="python">hello_world.py</command>
</script>
</inkscape-extension>
</pre>

Create ''<param>'' element for every option of a script and ''<dependency>'' for every included module which is not from Python standard library. Inkscape will search for this modules in directory with script. ''<effect>'' element and its descendants defines name of menu item evoking our new "Hello World!" extension.

If the inx file isn't well formed or if any of the dependencies wasn't met, the extension won't show up in the menu. If your extension doesn't show up, take a look at extension-errors.log, which may give you a hint why it wasn't loaded.

== Installation ==

To install a new extenstion just put ''hello_world.py'' and ''hello_world.inx'' files with all dependency modules to ''<path_to_inkscape>/extensions'' or ''~/.inkscape/extensions'' directory and start Inkscape. A new menu item ''Hello World!'' in ''Effects->Examples'' menu should appear.

== Complete Source Code ==

Here is a complete commented source pre of ''hello_world.py'' script file:

<pre>
#!/usr/bin/env python

# These two lines are only needed if you don't put the script directly into
# the installation directory
import sys
sys.path.append('/usr/share/inkscape/extensions') # or another path, as necessary

# We will use inex module with predefined effect base class.
import inkex
# simplestyle module provides functions for style parsing.
from simplestyle import *

""" Example Inkscape effect extension.
Creates a new layer with "Hello World!" text centered in middle of document."""
class HelloWorldEffect(inkex.Effect):
""" Constructor.
Defines "--what" option of a script."""
def __init__(self):
# Call base class construtor.
inkex.Effect.__init__(self)

# Define string option "--what" with "-w" shortcut and default value "World".
self.OptionParser.add_option('-w', '--what', action = 'store',
type = 'string', dest = 'what', default = 'World',
help = 'What would you like to greet?')

""" Effect behaviour.
Overrides base class' method and insert "Hello World" text in SVG document. """
def effect(self):
# Get script "--what" option value.
what = self.options.what

# Get access to main SVG document element and get its dimensions.
svg = self.document.getElementsByTagName('svg')[0]
width = inkex.unittouu(svg.getAttribute('width'))
height = inkex.unittouu(svg.getAttribute('height'))

# Create a new layer.
layer = self.document.createElement('g')
layer.setAttribute('inkscape:label', 'Hello %s Layer' % (what))
layer.setAttribute('inkscape:groupmode', 'layer')

# Create text element
text = self.document.createElement('text')
value = self.document.createTextNode('Hello %s!' % (what))

# Set text position to center of document.
text.setAttribute('x', str(width / 2))
text.setAttribute('y', str(height / 2))

# Center text horizontally with CSS style.
style = {'text-align' : 'center', 'text-anchor': 'middle'}
text.setAttribute('style', formatStyle(style))

# Connect elements together.
text.appendChild(value)
layer.appendChild(text)
svg.appendChild(layer)

# Create effect instance and apply it.
effect = HelloWorldEffect()
effect.affect()
</pre>

[[User:Blackhex|Blackhex]] 11:59, 26 April 2007 (UTC)

Talk:PythonEffectTutorial

2008-07-30T07:32:06Z

Rubikcube: Tutorial still valid for current lxml?

==Current issues==
Excerpt from an email I sent to the inkscape-devel list:
<blockquote>Hello,
I hope this list is the correct one for this kind of question:
Has anyone managed to get http://wiki.inkscape.org/wiki/index.php/PythonEffectTutorial to work without major changes? It failed for me both on a gentoo system and on a pretty vanilla Ubuntu 8.04 box. I don't know if I will find the time to edit the wiki page according to the current lxml behaviour, but I might give it a try. Additionally Ishmal(I think) said on irc/jabber that lxml might not be used in the future anymore anyway.

Now for the list of problems I encountered:
* Simply making the file executable and putting it into ~/.inkscape/extensions/ is not sufficient, it won't find inkex there, but no problem, simply add
import sys
sys.path.append('/usr/share/inkscape/extensions') # or another path, as appropriate for your installation
to the top of it. A minor problem.
* All the getElementsByTagName, getAttribute, createElement,... methods are unknown to lxml, at least in the versions here (1.3.6). Inkscape returns the python error message ending with:
File "/home/dhornun/.inkscape/extensions/helloworld.py", line 32, in effect
svg = self.document.getElementsByTagName('svg')[0]
AttributeError: 'etree._ElementTree' object has no attribute 'getElementsByTagName'
If this is not a problem on the distributions' side, those can probably be fixed by adapting the code to reflect lxml's current API.
</blockquote>
Hopefully I'll find the time to fix this either on my machine or here in the wiki. The first point was fixed already. --[[User:Rubikcube|Rubikcube]] 07:32, 30 July 2008 (UTC)

PythonEffectTutorial

2008-07-30T07:21:03Z

Rubikcube: /* Complete Source Code */ Added to path

Effect extensions in Inkscape means a simple programs or scripts that reads input SVG file transforms it somehow and prints it to the standart output.

We will write simple effect extension script in Python that will put "Hello World!" or "Hello <value of --what option>!" string in the center of document and inside a new layer.

== Effect Extension Script ==

First of all create file ''hello_world.py'' and make them executable with Python interpreter with well-known directive:

<pre>
#!/usr/bin/env python
</pre>

If you're going to put the file somewhere else than into inkscape's installation directory, we need to add a path so that python can find the necessary modules:

<pre>
import sys
sys.path.append('/usr/share/inkscape/extensions') # or another path, as necessary
</pre>

Import ''inkex.py'' file with ''Effect'' base class that will do most of work for us and ''simplestyle.py'' module with support functions for working with CSS styles. We will use just the ''formatStyle'' function from this module.:

<pre>
import inkex
from simplestyle import *
</pre>

Declare ''HelloWordEffect'' class and write a constructor where base class is initialized and script option for opition parser is defined:

<pre>
class HelloWorldEffect(inkex.Effect):
def __init__(self):
inkex.Effect.__init__(self)
self.OptionParser.add_option('-w', '--what', action = 'store',
type = 'string', dest = 'what', default = 'World',
help = 'What would you like to greet?')
</pre>

Complete documentation for ''OptionParser'' class can be found at http://docs.python.org/lib/module-optparse.html. Here we just use ''add_option'' method which has as first argument short option name, as second argument long option name and then a few other arguments with this meaning:

* ''action'' - An action which should be done with option value. In this case we use action ''store'' which will store option value in ''self.options.<destination>'' attribute.
* ''type'' - Type of option value. We use string here.
* ''dest'' - Destination of option action specified by ''action'' argument. Using ''what'' value we say that we want to store option value to self.options.what attribute.
* ''default'' - Defalut value for this option if it is not specified.
* ''help'' - A help string that will be displayed if script will be given no arguments or some option or argument will have wrong syntax.

Inkscape will create a GUI form with widgets for all specified options and prefill them with specified default values using ''.inx''. file for this extenstion which we will write later.

We need to override only one ''Effect'' class method to provide effect functionality:
<pre>
def effect(self):
what = self.options.what
</pre>

As you can mention we just stored ''--what'' option value to ''what'' variable.

Now we will finally start to do something. We will work with XML representation of SVG document via ''self.document'' attribute. It is of ''Document'' class type from ''xml.dom'' module. Complete documentation for this module can be found at http://docs.python.org/lib/module-xml.dom.html.

First get SVG document ''svg'' element and its dimensions:

<pre>
svg = self.document.getElementsByTagName('svg')[0]
width = inkex.unittouu(svg.getAttribute('width'))
height = inkex.unittouu(svg.getAttribute('height'))
</pre>

Function ''getElementsByTagName'' returns list of all found elements of this name so we just use first of them.

Create SVG group element and "convert" it to layer using Inkscape SVG extenstions:

<pre>
layer = self.document.createElement('g')
layer.setAttribute('inkscape:label', 'Hello %s Layer' % (what))
layer.setAttribute('inkscape:groupmode', 'layer')
</pre>

Create SVG text element and its value containing "Hello World"" string:

<pre>
text = self.document.createElement('text')
value = self.document.createTextNode('Hello %s!' % (what))
</pre>

Set position of text to center of SVG document:

<pre>
text.setAttribute('x', str(width / 2))
text.setAttribute('y', str(height / 2))
</pre>

If we want center text on its position we will define CSS style of SVG ''text'' element. Actually use ''text-anchor'' SVG extension to CSS styles to do that work:

<pre>
style = {'text-align' : 'center', 'text-anchor' : 'middle'}
text.setAttribute('style', formatStyle(style))
</pre>

Finally connect all created elements together and put them in SVG document:

<pre>
text.appendChild(value)
layer.appendChild(text)
svg.appendChild(layer)
</pre>

We just defined a class of our effect extension so we have to create an instance of it and execute it in main control flow:

<pre>
effect = HelloWorldEffect()
effect.affect()
</pre>

== Extension Description File ==

To include script in Inkscape's main menu create ''hello_world.inx'' file describing script evokation.

<pre>
<inkscape-extension>
<_name>Hello World!</_name>
<id>org.ekips.filter.hello_world</id>
<dependency type="executable" location="extensions">hello_world.py</dependency>
<dependency type="executable" location="extensions">inkex.py</dependency>
<param name="what" type="string" _gui-text="What would you like to greet?">World</param>
<effect>
<object-type>all</object-type>
<effects-menu>
<submenu _name="Examples"/>
</effects-menu>
</effect>
<script>
<command reldir="extensions" interpreter="python">hello_world.py</command>
</script>
</inkscape-extension>
</pre>

Create ''<param>'' element for every option of a script and ''<dependency>'' for every included module which is not from Python standard library. Inkscape will search for this modules in directory with script. ''<effect>'' element and its descendants defines name of menu item evoking our new "Hello World!" extension.

If the inx file isn't well formed or if any of the dependencies wasn't met, the extension won't show up in the menu. If your extension doesn't show up, take a look at extension-errors.log, which may give you a hint why it wasn't loaded.

== Installation ==

To install a new extenstion just put ''hello_world.py'' and ''hello_world.inx'' files with all dependency modules to ''<path_to_inkscape>/extensions'' or ''~/.inkscape/extensions'' directory and start Inkscape. A new menu item ''Hello World!'' in ''Effects->Examples'' menu should appear.

== Complete Source Code ==

Here is a complete commented source pre of ''hello_world.py'' script file:

<pre>
#!/usr/bin/env python

# These two lines are only needed if you don't put the script directly into
# the installation directory
import sys
sys.path.append('/usr/share/inkscape/extensions') # or another path, as necessary

# We will use inex module with predefined effect base class.
import inkex
# simplestyle module provides functions for style parsing.
from simplestyle import *

""" Example Inkscape effect extension.
Creates a new layer with "Hello World!" text centered in middle of document."""
class HelloWorldEffect(inkex.Effect):
""" Constructor.
Defines "--what" option of a script."""
def __init__(self):
# Call base class construtor.
inkex.Effect.__init__(self)

# Define string option "--what" with "-w" shortcut and default value "World".
self.OptionParser.add_option('-w', '--what', action = 'store',
type = 'string', dest = 'what', default = 'World',
help = 'What would you like to greet?')

""" Effect behaviour.
Overrides base class' method and insert "Hello World" text in SVG document. """
def effect(self):
# Get script "--what" option value.
what = self.options.what

# Get access to main SVG document element and get its dimensions.
svg = self.document.getElementsByTagName('svg')[0]
width = inkex.unittouu(svg.getAttribute('width'))
height = inkex.unittouu(svg.getAttribute('height'))

# Create a new layer.
layer = self.document.createElement('g')
layer.setAttribute('inkscape:label', 'Hello %s Layer' % (what))
layer.setAttribute('inkscape:groupmode', 'layer')

# Create text element
text = self.document.createElement('text')
value = self.document.createTextNode('Hello %s!' % (what))

# Set text position to center of document.
text.setAttribute('x', str(width / 2))
text.setAttribute('y', str(height / 2))

# Center text horizontally with CSS style.
style = {'text-align' : 'center', 'text-anchor': 'middle'}
text.setAttribute('style', formatStyle(style))

# Connect elements together.
text.appendChild(value)
layer.appendChild(text)
svg.appendChild(layer)

# Create effect instance and apply it.
effect = HelloWorldEffect()
effect.affect()
</pre>

[[User:Blackhex|Blackhex]] 11:59, 26 April 2007 (UTC)

PythonEffectTutorial

2008-07-30T07:19:39Z

Rubikcube: /* Effect Extension Script */ path added

Effect extensions in Inkscape means a simple programs or scripts that reads input SVG file transforms it somehow and prints it to the standart output.

We will write simple effect extension script in Python that will put "Hello World!" or "Hello <value of --what option>!" string in the center of document and inside a new layer.

== Effect Extension Script ==

First of all create file ''hello_world.py'' and make them executable with Python interpreter with well-known directive:

<pre>
#!/usr/bin/env python
</pre>

If you're going to put the file somewhere else than into inkscape's installation directory, we need to add a path so that python can find the necessary modules:

<pre>
import sys
sys.path.append('/usr/share/inkscape/extensions') # or another path, as necessary
</pre>

Import ''inkex.py'' file with ''Effect'' base class that will do most of work for us and ''simplestyle.py'' module with support functions for working with CSS styles. We will use just the ''formatStyle'' function from this module.:

<pre>
import inkex
from simplestyle import *
</pre>

Declare ''HelloWordEffect'' class and write a constructor where base class is initialized and script option for opition parser is defined:

<pre>
class HelloWorldEffect(inkex.Effect):
def __init__(self):
inkex.Effect.__init__(self)
self.OptionParser.add_option('-w', '--what', action = 'store',
type = 'string', dest = 'what', default = 'World',
help = 'What would you like to greet?')
</pre>

Complete documentation for ''OptionParser'' class can be found at http://docs.python.org/lib/module-optparse.html. Here we just use ''add_option'' method which has as first argument short option name, as second argument long option name and then a few other arguments with this meaning:

* ''action'' - An action which should be done with option value. In this case we use action ''store'' which will store option value in ''self.options.<destination>'' attribute.
* ''type'' - Type of option value. We use string here.
* ''dest'' - Destination of option action specified by ''action'' argument. Using ''what'' value we say that we want to store option value to self.options.what attribute.
* ''default'' - Defalut value for this option if it is not specified.
* ''help'' - A help string that will be displayed if script will be given no arguments or some option or argument will have wrong syntax.

Inkscape will create a GUI form with widgets for all specified options and prefill them with specified default values using ''.inx''. file for this extenstion which we will write later.

We need to override only one ''Effect'' class method to provide effect functionality:
<pre>
def effect(self):
what = self.options.what
</pre>

As you can mention we just stored ''--what'' option value to ''what'' variable.

Now we will finally start to do something. We will work with XML representation of SVG document via ''self.document'' attribute. It is of ''Document'' class type from ''xml.dom'' module. Complete documentation for this module can be found at http://docs.python.org/lib/module-xml.dom.html.

First get SVG document ''svg'' element and its dimensions:

<pre>
svg = self.document.getElementsByTagName('svg')[0]
width = inkex.unittouu(svg.getAttribute('width'))
height = inkex.unittouu(svg.getAttribute('height'))
</pre>

Function ''getElementsByTagName'' returns list of all found elements of this name so we just use first of them.

Create SVG group element and "convert" it to layer using Inkscape SVG extenstions:

<pre>
layer = self.document.createElement('g')
layer.setAttribute('inkscape:label', 'Hello %s Layer' % (what))
layer.setAttribute('inkscape:groupmode', 'layer')
</pre>

Create SVG text element and its value containing "Hello World"" string:

<pre>
text = self.document.createElement('text')
value = self.document.createTextNode('Hello %s!' % (what))
</pre>

Set position of text to center of SVG document:

<pre>
text.setAttribute('x', str(width / 2))
text.setAttribute('y', str(height / 2))
</pre>

If we want center text on its position we will define CSS style of SVG ''text'' element. Actually use ''text-anchor'' SVG extension to CSS styles to do that work:

<pre>
style = {'text-align' : 'center', 'text-anchor' : 'middle'}
text.setAttribute('style', formatStyle(style))
</pre>

Finally connect all created elements together and put them in SVG document:

<pre>
text.appendChild(value)
layer.appendChild(text)
svg.appendChild(layer)
</pre>

We just defined a class of our effect extension so we have to create an instance of it and execute it in main control flow:

<pre>
effect = HelloWorldEffect()
effect.affect()
</pre>

== Extension Description File ==

To include script in Inkscape's main menu create ''hello_world.inx'' file describing script evokation.

<pre>
<inkscape-extension>
<_name>Hello World!</_name>
<id>org.ekips.filter.hello_world</id>
<dependency type="executable" location="extensions">hello_world.py</dependency>
<dependency type="executable" location="extensions">inkex.py</dependency>
<param name="what" type="string" _gui-text="What would you like to greet?">World</param>
<effect>
<object-type>all</object-type>
<effects-menu>
<submenu _name="Examples"/>
</effects-menu>
</effect>
<script>
<command reldir="extensions" interpreter="python">hello_world.py</command>
</script>
</inkscape-extension>
</pre>

Create ''<param>'' element for every option of a script and ''<dependency>'' for every included module which is not from Python standard library. Inkscape will search for this modules in directory with script. ''<effect>'' element and its descendants defines name of menu item evoking our new "Hello World!" extension.

If the inx file isn't well formed or if any of the dependencies wasn't met, the extension won't show up in the menu. If your extension doesn't show up, take a look at extension-errors.log, which may give you a hint why it wasn't loaded.

== Installation ==

To install a new extenstion just put ''hello_world.py'' and ''hello_world.inx'' files with all dependency modules to ''<path_to_inkscape>/extensions'' or ''~/.inkscape/extensions'' directory and start Inkscape. A new menu item ''Hello World!'' in ''Effects->Examples'' menu should appear.

== Complete Source Code ==

Here is a complete commented source pre of ''hello_world.py'' script file:

<pre>
#!/usr/bin/env python

# We will use inex module with predefined effect base class.
import inkex
# simplestyle module provides functions for style parsing.
from simplestyle import *

""" Example Inkscape effect extension.
Creates a new layer with "Hello World!" text centered in middle of document."""
class HelloWorldEffect(inkex.Effect):
""" Constructor.
Defines "--what" option of a script."""
def __init__(self):
# Call base class construtor.
inkex.Effect.__init__(self)

# Define string option "--what" with "-w" shortcut and default value "World".
self.OptionParser.add_option('-w', '--what', action = 'store',
type = 'string', dest = 'what', default = 'World',
help = 'What would you like to greet?')

""" Effect behaviour.
Overrides base class' method and insert "Hello World" text in SVG document. """
def effect(self):
# Get script "--what" option value.
what = self.options.what

# Get access to main SVG document element and get its dimensions.
svg = self.document.getElementsByTagName('svg')[0]
width = inkex.unittouu(svg.getAttribute('width'))
height = inkex.unittouu(svg.getAttribute('height'))

# Create a new layer.
layer = self.document.createElement('g')
layer.setAttribute('inkscape:label', 'Hello %s Layer' % (what))
layer.setAttribute('inkscape:groupmode', 'layer')

# Create text element
text = self.document.createElement('text')
value = self.document.createTextNode('Hello %s!' % (what))

# Set text position to center of document.
text.setAttribute('x', str(width / 2))
text.setAttribute('y', str(height / 2))

# Center text horizontally with CSS style.
style = {'text-align' : 'center', 'text-anchor': 'middle'}
text.setAttribute('style', formatStyle(style))

# Connect elements together.
text.appendChild(value)
layer.appendChild(text)
svg.appendChild(layer)

# Create effect instance and apply it.
effect = HelloWorldEffect()
effect.affect()
</pre>

[[User:Blackhex|Blackhex]] 11:59, 26 April 2007 (UTC)

TutorialIdeas

2006-07-17T11:43:10Z

Rubikcube: /* Tutorials in development */ link updated for isometric transformations

This page will consist of brainstorming and basic development of new tutorials that will be useful for new/old users.

Also see [[TutorialsAndHelp]]

=== Completed Tutorials ===

* [[DefaultTutorial]]
* [http://home.programmer-art.org/?page=inkscape Daniel Taylor's Web-Based Inkscape Tutorials] - Hopefully he will make SVG tutorials that we can inlude with Inkscape, like our current [[DefaultTutorial]].
* making shiny marbles... http://inkscape.org/wiki_uploads/marbles_tut.svg
* also see [http://inkscape.org/cgi-bin/wiki.pl?OtherProjects#outsidetut Outside Tutorials and Tips]
* [[ElementsPrinciplesOfDesign]] (rejon)
* [http://kargs.net/docs/easter_egg_tutorial.svg Easter Egg Tutorial]

=== Tutorials in development ===

* [http://homepage.univie.ac.at/reinhard.stepanek/fxos80/metchart.html How to create meteorological charts with Inkscape], Tutorial by Reinhard Stepanek
* Daniel Pope's Clownfish Tutorial - [http://www.mauveweb.co.uk/misc/tutorials/clownfish.svg Part 1] [http://www.mauveweb.co.uk/misc/tutorials/clownfish2.svg Part 2] - drop me an email at mauve@mauveweb.co.uk to suggest changes.
* A very small sheet with instructions for doing [http://www.gimpforum.de/album/file.php?n=4323&w=o isometric transformations] - if anyone has comments or wants to have a look at the original svg, contact me at daniel dot hornung <at> gmx dot de

=== Planned Tutorials ===

* [[UsingTheCloneTiler]] - Clones

* Text and Typography

* Clippath/Mask/Pattern

* Effects

* SVG Filters

* XML Editor

=== Tutorial Scratchpad ===

* How to create an icon
* How to build a presentation using Inkview.
* How to build complex shapes using boolean operations.
* How to use Inkscape to create graphics for LaTeX / ConTeXt documents.
* etc

A tutorial in progress of writing by John Griessen

This writing is a journal of how a project to recreate a business card originally
made with Illutrator 7, after losing the original file, so the comparison to Illustrator is
much from memory and not to be taken as the last word, but a guide as to how the programs compare.

Attached is a png of the printed business card:

It originally was a collection of paths filled with colors and text objects with grouping to
make replicating some objects easy.

The shell command '$inkscape --version' tells us this is Inkscape 0.39cvs (Jul 2 2004) .

The logo main element is a pseudo sine wave, and I made it before with grid snap and stretching and replicating, so now I set my units to mm and grid spacing and snap to 1 and remember how it would be nice to have major and minor grids instead of just one, so I want to create some vertical guides evenly spaced and cannot remember and start looking in docs. In Illustrator 7, clicking on the ruler bar created a guide if I recall... Once created, it could be moved with grid snap like any object, so getting it on grid or off was easy. As I read around, I find the usage of guides in "Keys and Mouse" "drag off a ruler" is the way... and a guide is on the page, and I can't snap it to easily make the accurate secondary grid I had wanted....Is there a way to? I try duplicate on the guide, but alas, it is not a regular object... it cannot be selected as they are...so I cannot replicate guides to make other grids after all... note for the beginner, to get bezier curves out of the line/bezier tool, you must click-drag. A click-only will give you only connected straight line segments. I'll have to use lines as guides,
http://home.austin.rr.com/jgriessen/ill2ink-tut1.png

[[Category:Help Wanted]]

=== Other SVG Tutorials ===

* http://www.codeproject.com/books/learnsvgchapter07.asp

TutorialIdeas

2006-07-17T00:07:31Z

Rubikcube: /* Tutorials in development */ added tutorial for isometric transforms

This page will consist of brainstorming and basic development of new tutorials that will be useful for new/old users.

Also see [[TutorialsAndHelp]]

=== Completed Tutorials ===

* [[DefaultTutorial]]
* [http://home.programmer-art.org/?page=inkscape Daniel Taylor's Web-Based Inkscape Tutorials] - Hopefully he will make SVG tutorials that we can inlude with Inkscape, like our current [[DefaultTutorial]].
* making shiny marbles... http://inkscape.org/wiki_uploads/marbles_tut.svg
* also see [http://inkscape.org/cgi-bin/wiki.pl?OtherProjects#outsidetut Outside Tutorials and Tips]
* [[ElementsPrinciplesOfDesign]] (rejon)
* [http://kargs.net/docs/easter_egg_tutorial.svg Easter Egg Tutorial]

=== Tutorials in development ===

* [http://homepage.univie.ac.at/reinhard.stepanek/fxos80/metchart.html How to create meteorological charts with Inkscape], Tutorial by Reinhard Stepanek
* Daniel Pope's Clownfish Tutorial - [http://www.mauveweb.co.uk/misc/tutorials/clownfish.svg Part 1] [http://www.mauveweb.co.uk/misc/tutorials/clownfish2.svg Part 2] - drop me an email at mauve@mauveweb.co.uk to suggest changes.
* A very small sheet with instructions for doing [http://www.gimpforum.de/album/images/791/1_isometric.png isometric transforms] - if anyone has comments or wants to have the original svg, contact me at daniel dot hornung <at> gmx dot de

=== Planned Tutorials ===

* [[UsingTheCloneTiler]] - Clones

* Text and Typography

* Clippath/Mask/Pattern

* Effects

* SVG Filters

* XML Editor

=== Tutorial Scratchpad ===

* How to create an icon
* How to build a presentation using Inkview.
* How to build complex shapes using boolean operations.
* How to use Inkscape to create graphics for LaTeX / ConTeXt documents.
* etc

A tutorial in progress of writing by John Griessen

This writing is a journal of how a project to recreate a business card originally
made with Illutrator 7, after losing the original file, so the comparison to Illustrator is
much from memory and not to be taken as the last word, but a guide as to how the programs compare.

Attached is a png of the printed business card:

It originally was a collection of paths filled with colors and text objects with grouping to
make replicating some objects easy.

The shell command '$inkscape --version' tells us this is Inkscape 0.39cvs (Jul 2 2004) .

The logo main element is a pseudo sine wave, and I made it before with grid snap and stretching and replicating, so now I set my units to mm and grid spacing and snap to 1 and remember how it would be nice to have major and minor grids instead of just one, so I want to create some vertical guides evenly spaced and cannot remember and start looking in docs. In Illustrator 7, clicking on the ruler bar created a guide if I recall... Once created, it could be moved with grid snap like any object, so getting it on grid or off was easy. As I read around, I find the usage of guides in "Keys and Mouse" "drag off a ruler" is the way... and a guide is on the page, and I can't snap it to easily make the accurate secondary grid I had wanted....Is there a way to? I try duplicate on the guide, but alas, it is not a regular object... it cannot be selected as they are...so I cannot replicate guides to make other grids after all... note for the beginner, to get bezier curves out of the line/bezier tool, you must click-drag. A click-only will give you only connected straight line segments. I'll have to use lines as guides,
http://home.austin.rr.com/jgriessen/ill2ink-tut1.png

[[Category:Help Wanted]]

=== Other SVG Tutorials ===

* http://www.codeproject.com/books/learnsvgchapter07.asp