Inkscape Wiki - User contributions [en]

Script extensions

2016-03-13T10:38:42Z

Raphael: /* See Also */ Removing dead link

[Note: This page concerns using scripting languages to create new Inkscape functionality. To access Inkscape functionality from scripting languages (i.e. to script Inkscape), see the Inkscape man page (especially in the development version or v0.46 or later, which provide --select and --verb options), or see the work in the src/extension/script directory of Inkscape source.]

== Introduction ==

Traditional Unix scripts can be used to extend Inkscape's functionality. Such programs read a stream of data on standard input, transform the data in some way, and then write the modified data to standard output. This is an easy way to expand Inkscape and provide custom functionality without learning the internals of Inkscape. Libraries for reading and writing SVG data exist for many programming languages, and most provide support for XML. This tutorial describes the "ins and outs" of writing one of these scripts and making it work with Inkscape's core functionality.

== Script functions ==

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

* Input, providing translation from a file format to SVG
* Output, providing translation from SVG to a format
* Effect, taking in SVG, changing it, and then outputting SVG

While all of these are very similar in the scripting interface, there are slight differences between them.

== Interaction ==

It is important for a script author to understand how Inkscape and scripts communicate.

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

Inkscape runs your script (optionally with an interpreter) passing it any number of parameters in long gnu style. The final argument is the name of the temporary svg file your script should read. After processing, the script should return the modified svg file to inkscape on STDOUT.

== Important Tips ==

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

== Extension description file ==

In order for Inkscape to make use of an external script or program, you must describe that script to Inkscape using an INX file. See the inkscape share directory for examples.

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

See [[INX extension descriptor format]] for help creating an INX file.

=== Parameters ===
The INX file describes which parameters the extension needs. Inkscape will prompt the user with a UI to fill out these parameters before the extension is called. Each parameter will be passed to the script as <code>--paramname=paramvalue</code>. Specify the script file to be run with the <code><command></code> tag.

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

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

* String (textbox)
* Boolean (checkbox)
* Int (numeric textbox)
* Float (numeric textbox)
* Enum (drop down selection list)
* Option group (radio buttons)
* Notebook (pages/tabs)
* Description (not a parameter, provides static text)

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

== Installing ==

Installing is as simple as copying the script (unless it resides in your path) and its INX file to the inkscape/share/extensions ($HOME/.config/inkscape/extensions) directory. (If you install a script in your home directory be sure to copy the dependencies.)

If you are looking to use scripts that have already been written, the most difficult part will likely be the installation. Since scripts are separate programs they may have any number of dependencies that are not included with inkscape. Currently, the best way to find missing dependencies is by reading the error messages produced by running the script from the command line.

== See Also ==

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

*[[PythonEffectTutorial]]

*[[Tips For Python Script Extensions]]

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

Inkscape

2016-03-13T10:37:37Z

Raphael: /* Miscellaneous */ Add Script Extension link

{{Main_Page/Localized_versions}}

This is a freeform area for Inkscape development and discussion.
Curious about [[WikiSyntax]]?

{| cellspacing="11" style="width:100%;"
|-style="vertical-align:top;"
| style="width:33%;background-color: #E6E6E6; padding:.5em;"|
=== Project Info ===
* [http://www.inkscape.org/ Inkscape Homepage]
* [[About Inkscape]]
* [[Features of Inkscape|Features]]
* [[FAQ]] - Frequently Asked Questions
* [[Supported operating systems]]
* [[Tools]] - Supporting Tools and Applications
* [[Galleries]]
* [[Inkscape coverage|Coverage]] - Awards, articles, presentations, books about Inkscape
* [[Inkscape popularity|Popularity]]
* [[InkscapeInvariants|Inkscape's Mission]]
* [[CommunicationChannels|Communication Channels]]: how to reach us
* [[AnnouncementToSodipodi|Announcement To Sodipodi]]: this started it all
* [[Branding]]
* [[Travel Reimbursement Policy]]
* [[FundedProjectSystemDevelopment|Funded Project System Development]]

|style="width:33%;;background-color: white; padding:.5em;"|

=== User Documentation ===
* [[Installing Inkscape|Installation]]
* [[International and Local Communities]]
* [[Inkscape glossary]]
* [[User manual information]] - where to find the free Inkscape manual and how to contribute to it
* [http://inkscape.org/en/learn/tutorials/ Tutorials]
* [[Inkscape SVG vs. plain SVG]]
* [[Output format requirements]] - what's needed to save in some formats
* [[Effect requirements]] - what's needed to use some effects
* [[Effect reference]] - what each effect does
* [[Connector tool tutorial]]
* [[Installing fonts]]
* [[Emergency save]] - recovery in case Inkscape crashed
* [[Release notes]]
** '''for version [[Release notes/0.92|0.92]] (active development)'''
** '''for version [[Release notes/0.91|0.91]] (current release)'''
** older versions: [[Release notes/0.48.5|0.48.5]] [[Release notes/0.48.4|0.48.4]] [[Release notes/0.48.3|0.48.3]], [[Release notes/0.48.2|0.48.2]], [[Release notes/0.48.1|0.48.1]], [[Release notes/0.48|0.48]], [[Release notes/0.47|0.47]]
* [[Announcing Releases]]
* [[Tricks and tips]] - miscellaneous advice, may be slightly outdated

|style="width:33%;background-color: #E6E6E6; padding:.5em;"|

=== Help Inkscape Without Coding ===
* [[Bug management]]
* [[Testing]]
* [[Translation information]]
* [[WebSite]]
* [[Inkscape Classes]]
* [[Conferences]]
* [[Fundraising Ideas]]

* [[HelpWanted]]
* [[BugTriageProjects]]
* [[CreatingDists]]: how to build packages
* [[StableBranchUpdates]]
* [[UpdatingTrackerItems]]
* [[TutorialsAndHelp]]
* [[How_To_Start_A_Page]] how to use the wiki
* [[CreatingScreencasts]]
* [[AboutScreenContest]]
|}

{| cellspacing="0" style="width: 100%; background-color: white; border-width:1px; border-style:solid; border-color:#62C012; align:left; padding:11px 0em 0em 11px;"
|- style="vertical-align:top;"
| colspan="2"|

=== Developer Documentation ===
|- style="vertical-align:top;"
| style="width:50%;|
==== First Steps ====
* [[Working with Bazaar]] - How to obtain the source code. A quick start on how to use our version control system
* [[Working with Git]]
* [[Compiling Inkscape|Compilation]]
* [[Compiling Inkscape on Windows]]
* [[Using Eclipse]] - Debug Inkscape on Windows using Eclipse (outdated)
* [[Using Visual Studio]] - Debug Inkscape on Windows using Microsoft Visual Studio
* [[Developer manual]] - various important information, be sure to read this before coding
* [[Debugging Inkscape|Debugging]] - random tips to help debug problems
* [[Project organization]] - procedures, hierarchy, developer roles and the likes
* [[Janitorial tasks]] - small tasks that need doing
* [[Doxygen documentation]]
* [[Working with SVN]] - besides the code in Bazaar, we still have some things in SVN.
* [[Working with CMake]] - Getting started with cmake coding for configuring and building Inkscape

==== Developer tutorials ====
* [[Architectural overview]] - a high-level look at Inkscape
* [[Preferences subsystem]] - creating and using preference values
* XML subsystem (WIP) - how to manipulate the XML representation of a document
* Display subsystem (WIP) - how to make things appear on the canvas
* Tools subsystem (WIP) - how to create a new tool
* [[Creating a new SPObject]]
* Extensions
** [[Extension subsystem]] - an overview of the functionality provided by extensions and the possible implementations
** [[Script extensions]]
** [[Python modules for extensions]] - some helpful routines for use in Python script extensions
* [[Creating Live Path Effects]]
* [[Boost shared pointers]]
* [[Using libsigc++ signals]]
* [[Windows development on Linux]]

==== Miscellaneous ====
* [[Script extensions]]: extends Inkscape easily using scripting languages (Python, Perl,...)
* [[INX extension descriptor format]]
* [[Inkscape-specific XML attributes]] - documentation of attributes from Inkscape's XML namespace

* [[Extension repository]]: an Internet central for Inkscape Extensions
* [[Related programs]]

| style="width:50%;|

==== Continuous Integration (Automated testing) ====
* [http://jenkins.inkscape.org Our main testing website (Jenkins)]
* [[How to contribute to automated tests]]
* [[Jenkins server setup]]

==== Development Discussion ====
* [[Roadmap]]: the main todo list
* [[Dependencies]] - what libs are needed to build Inkscape
* [[C++11]] - What C++11 features can be used
* [[NewFeatureProposals]]
* [[ExtensionArchitectureProposals]]
* [[Coding Style|Coding Style Discussion]]
* [[FileTypes]]
* [[ApplicationIcons]] (Application + Interface)
* [[Icons]]
* [[InkscapeColor]]
* [[PrintingSubsystem]]
* [[SVG Tiny Compliance]]
* [[SVG Test Suite Compliance]] - [[W3C]] full test suite
* [[CSS Support]]
* [[Google Summer Of Code]]
* [[Improved Media Management]]
* [[UI MockupScreenshots]]
* [[Swatch Book]]
* [[Tablet Dialog]]
* [[ViewBoxToDo]] View box support info
* [[Caching]]
* [[UI and Document coordinates‎]]
* [[Mipmapping]]
* [[GtkMMification]]: replace C boilerplate with gtkmm objects
* [[CMake Tasks]]: Converting the Inkscape build system to CMake

===Lib2Geom===
*[[lib2geom]]
*[[lib2geom Goals]]
*[[lib2geom FAQ]]
*[[lib2geom SVN Repository Guide]]
*[[WorkingWith2GeomFAQ]]: real-life questions answered about using 2Geom in real code
*[[lib2geom py2geom]]: python bindings to 2geom. With this you can use the power of 2geom in python scripts.

|- style="vertical-align:top;"
| style="width:50%;|
==== User Interface Discussion ====
* [[Translation_information]]
* [[AddingInterfaceVerbs]]
* [[AccessibleGraphics]]
* [[ObjectManager]]
* [[DialogsReorganization]]
* [[ModalInterfaces]]
* [[TextUsability]]: text tool /dialog dialog
* [[KeyboardShortcutsToDo]]
** [[KeyboardProfiles]]: how you can help
* [[StatusbarAPI]]
* [[Animation-(Timeline)]]
* [[Free Desktop Graphic Suite]]

| style="width:50%; |
|}

* [[WikiAttic]]: pages that are no longer relevant but kept for historical value

__NOTOC__

[[Category:About Inkscape]]
[[Category:User Documentation]]

PythonEffectTutorial

2016-03-13T10:33:46Z

Raphael: Small style improvements + typo 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 standard 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 create a new "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 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 [https://docs.python.org/2/library/optparse.html docs.python.org]. 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 can be found at [http://lxml.de/ lxml.de].

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 = self.unittouu(svg.get('width'))
height = self.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>
<?xml version="1.0" encoding="UTF-8"?>
<inkscape-extension xmlns="http://www.inkscape.org/namespace/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 ''~/.config/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 ''Extensions->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 = self.unittouu(svg.get('width'))
height = self.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)
[[Category:Developer Documentation]]
[[Category:Extensions]]

Tips For Python Script Extensions

2016-03-13T09:58:09Z

Raphael: Change default advices after v0.91

==Adding Translation Capability==

One can add the ability to have Python text messages included for translation. To provide an error message, rather than using the Python <tt>sys.stderr</tt>, use the provided <tt>errormsg()</tt> function from inkex.py in conjunction with <tt>gettext</tt>.

You must include the following at the beginning of your Python script:
import inkex
inkex.localize()

Note: In prior versions (0.49), you will have to include the following lines instead:
import inkex
import gettext
_ = gettext.gettext

Where you wish to have an error message, write the following:
inkex.errormsg(_("This will be written to Python stderr"))

Of course, you may also change "_" to something else if you wish.

[[Category:Extensions]]

Developer manual

2016-03-05T20:12:37Z

Raphael: /* Please use const */ typo correction

= Inkscape Developer’s Manual =

== Introduction ==

For those of you just joining us, or who have been with us but are just
now getting the itch to work on Inkscape, I thought I’d give some tips
for how to get started working in the codebase based on our own
experiences.

One of the first things most people wonder is “What should I work on?”.
As you may have already noticed, we generally don’t “assign” projects.
We figure there’s plenty more work to do than people to do it, so you
may as well work on something that you’re either interested in or that
adds something of benefit to you; that’s extra motivation to get your
own itches scratched.

If you’re really stumped though, we keep a detailed [[Roadmap]] in wiki that
you’re welcome to browse through to look for ideas of things to work
on. Tasks that do not have names beside them are open for anyone to
take; if you want to take ownership of a task, just put your name beside
it. Feel free to add or reword tasks as needed, although try not to
load up the current milestone with tasks that aren’t critical for the
release. Feel free to work on stuff that is several milestones down the
road; there’s rarely any problem with getting stuff done sooner than
planned. ;-)

We have a process for gaining SVN commit access. The reason is that
while it is important that we keep access to the codebase open, we don’t
want to be crazy and leave it wide open to any random passer-by. The
process is that we require that the person make two contributions
(patches, documentation, web collateral, etc.) and then make a request
to get account access.

In general you won’t need SVN commit access in order to start doing
development, because you can work from an anonymous checkout and create
patches. If you’ve not done this before, you’ll need to learn this
skill first (basically see docs for `svn diff`).

When you first start hacking on Inkscape code, I wouldn’t recommend
taking an objective of implementing a specific feature, because you will
need some time to familiarize yourself with the codebase, and because
you won’t really know what features are going to be straightforward to
implement and which will be highly challenging. Of course, if you have
the time and love adventures, this might be a fun way to go.

There are four approaches that I’ve seen people effectively use in
getting into the codebase:

<ul>
<li>Write code documentation. Some people who don’t mind adding
comments to code or writing docs find it useful to just go through
code they’re interested in working on and writing up what it does.
The codebase is in dire need of better docs, so this approach pays
dividends well into the future.
</li>

<li>Fix bugs. Tracing down the cause of reported bugs is an effective
way to gain understanding of the codebase in small chunks. Many
common bugs can be traced down and fixed in a matter of hours, and
often will identify some bit of code in need of refactoring or
extension. Note that some of our older bugs are in the system
because they’re hard to fix, so you’ll want to work on the more
recent ones.
</li>

<li>Chip in on a group effort. Occasionally we identify a major
refactoring effort (such as when we converted from C to C++), that
we encourage lots of people to help on, in the philosophy that many
hands makes short work. This work tends to be pretty rote so is
not hard for new folks to get involved with; it just takes time. We
generally have one of these kinds of efforts per release. It
usually isn’t glamorous work, but in aggregate moves the codebase
forward in a major way.
</li>

<li>Subsystem/module work. Some people want to get their hands in the
details quick, so take the approach of developing new code separate
from the codebase, to be integrated in later. This generally tends
to take a larger time commitment than the other approaches, but can be
an effective approach in some circumstances. We have a SVN module
called <code>experimental</code> that you’re welcome to house your work until
it’s ready for prime time.
</li>
</ul>

Beyond that, you’re going to find the documentation for the Inkscape
code is pretty scarce. We’ve worked on bits and pieces but
unfortunately the vast majority of the code is undocumented. On the
plus side, often you can implement the stuff you care about after
learning only a limited portion of the codebase.

I think you’d find Inkscape an enjoyable Open Source project to work on.
There’s a huge range of interesting and useful skills that can be
learned from it, plus the developers are great guys to participate with.
The project itself runs smoothly and puts a premium on keeping things
friendly and low-stress, so heated arguments are rare. The users have
been great to work with and very appreciative of even small new features
and fixes. Plus, since Inkscape is so visual in nature, it’s very cool
to see how your little changes make noticeable improvements to the app
overall.

== C++ Reference ==
* FAQ (with answers) sheet. We strongly recommend that everyone read this site comprehensively. You should not need to bookmark it, it should be the first of the sites on your autocomplete list for <code>par</code>!

http://www.parashift.com/c++-faq-lite/

It is actually more in-depth than the name FAQ suggests. Many experienced C++ programmers would benefit from it.

* List of <s>[http://www.cs.helsinki.fi/u/vkarvone/2004s/cplusplus/errors.html schoolboy errors] (Broken Link)</s>. None of these should appear in [http://en.wikipedia.org/wiki/Free/Libre/Open-Source_Software FLOSS] code.

== Please use const ==

Please be very aggressive in adding ''const'' to any code you write. It will help us understand code better and will prevent bugs from creeping in. It is very easy to remove ''const'' later on, but very hard to add it.

''const'' can go on either side of a type. However once you get into references and pointers and such with C++, you generally read those from right-to-left. So it makes the code a little more legible if the ''const'' comes between the variable type and name.

int const foo;
// RTL reading gives "foo is a constant int".

And then:

int const & foo;
// RTL reading gives "foo is a reference to a constant int"

int const * foo;
// RTL reading gives "foo is a pointer to a constant int"

whereas:

int * const foo;
// RTL reading gives "foo is a constant pointer to an int"

Read also:
* [http://www.cprogramming.com/tutorial/const_correctness.html Const Correctness]
* [http://yosefk.com/c++fqa/const.html Const Correctness]

== Strings ==
Please make sure any user-visible strings are localizable. This requires wrapping them with "_(" and ")", like so:

<code>"Select object"</code>
becomes
<code>_("Select object")</code>

In case the interpretation of the string may be ambiguous or may differ according to context, you can add a context prefix (that won't be displayed) in order to eliminate the ambiguity.
<code>"Ambiguous string"</code>
can then become
<code>C_("Context", "Ambiguous string")</code>

For more complex things, please check the gettext/localization documentation.
See also http://library.gnome.org/devel/glib/unstable/glib-I18N.html

== Implementing User Interface Changes ==

[[UI improvements]] are enjoyable to work on because they produce visible changes in how Inkscape works. These improvements are one of the most tangible ways to help improve how Inkscape works; thus, we strongly support new developers wishing to work in these areas.

It is also very important to us that Inkscape presents an organized, productive, and easily discoverable interface to users. Because of this it is important that new Inkscape UI developers work to ensure changes make Inkscape’s UI *more* consistent, *more* flexible, *more* cohesive, and so on. We don’t have firm rules about what can and cannot done, in order to ensure plenty of freedom for innovation. However, we can outline some general principles and guidelines that are important to keep in mind:

Don’t please the artist—BE the artist. Many times UI is designed and created by programmers who “understand what the user wants”. But in Inkscape we believe that the best requirements list is the list inside the user’s head. Requirements docs, usability studies, and so on are very indirect ways of transferring this gut-level understanding from user to programmer. We believe the best way to ensure this information is communicated clearly is for the user to BE the programmer. Or, alternatively, for the programmer to BECOME a user.

This is why we so strongly encourage users to get involved in coding, and why we so strongly encourage programmers to focus on the features that are most important to them personally. This is also why it is absolutely critical to pay close attention to what users report when using a new feature—often they can tip you off to alternate designs that achieve the same result in a better way.

Eliminate limitations. Commercial software is often developed to fulfill feature requirement lists from a marketing department. As such, it’s common to see the feature implemented to meet the requirement exactly, and no more. However, especially with artistic software, art is often found outside what seems reasonable. So when putting in a new feature, avoid the temptation to limit it to what you expect people to use it for—instead generalize it and open as many parameters as possible for tweaking, and let the artist decide what is reasonable. That’s their job.

As an example, a drawing program might want to support the features “feather” and “drop shadow”. Obviously, users need these important features. Commercial software may well implement these as distinct features, each with their own UI controls. However, these features are just special cases of the more general gaussian blur, and in Inkscape we implemented *that*. With that in place, artists can do feathering and blur, and a variety of other effects.

It is interesting to note that, as an open collaborative standard, SVG
necessarily has the same goals as Inkscape: a minimum set of
universal, well thought-out building blocks that can accommodate the
widest possible range of graphics and applications. Thus, simply by
following the SVG philosophy, Inkscape scores quite a few important
points over commercial software. Live clones, patterns that can be contain any
objects, layers that are essentially groups and can be easily
converted to/from groups. These are all examples where the underlying
universality of SVG directly translates into extremely valuable user
features.

== Implementing New SVG Features ==

The most important way to help Inkscape is to implement a new SVG feature in it. Our hope is to eventually support ALL SVG features, so if you can help check one off the list, it brings us close to the nirvana of 100% SVG compliance. :-)

Generally we find that implementation of an SVG feature goes through three discrete stages:

<ol>
<li>Find the appropriate tags and attributes in the SVG spec</li>
<li>Implement support for rendering files with these tags</li>
<li>Implement support for UI controls to edit the tags</li>
</ol>

Step 1 is mostly a research project. Start by reading the SVG spec so you
can learn about the tag, the attributes that go with it, and so forth.
It is good practice to set up a page in the Wiki for storing your notes
as you do this process, so that in case you don’t make it to steps 2 and
3, then maybe someone else can benefit from your research.

Step 2 is the fun part. It helps to be comfortable with Inkscape internals
for this part. Depending on the feature, it may require advanced
knowledge of transformation, rendering, document management, and so on.
For this part, just hand-edit an SVG file to put the tags in that you
found in step #1, and keep plugging away at the code until Inkscape
displays things as the specification dictates. It can help to compare
your work with Batik, as we use that program as our reference
implementation.

Step 3 is the most important stage. It is the point at which the
feature becomes available for users. This step often requires knowledge
of Gtk+, for creating dialogs, widgets, menus, etc. for allowing the
user to edit the characteristics of the feature. Be sure to listen to
feedback from other developers and users—especially if there are
different opinions. It is hard to come up with UI that everyone can
agree on, but it is worth the work to achieve this—the more critique
your UI survives, the better loved the feature will be for future users.

Looking through Inkscape’s history, these stages are often done by different people. If you’re new to Inkscape, you may find working on stages 1 and 3 easiest, but there are many developers who can answer questions when you’re ready to dig into the internals, so don’t be afraid to ask questions!

== Standards Compliance - Extension Namespaces ==

* Only elements and attributes from our extension namespaces that ''do not affect rendering'' may be saved in SVG documents.
* Generally, this means that extension elements and attributes should only be used to provide UI hints.
* Extension elements and attributes should ''only'' be used where an existing facility provided by XML or SVG is not sufficient.

== Global Verbs ==

Here’s a readers’ digest summary of how Inkscape accelerators work:

A global mapping between key combinations and integer [[verb]] IDs
(<code>sp_verb_t</code>) is maintained in <code>shortcuts.cpp</code>; these are registered using
<code>sp_shortcut_set()</code>.

Given an <code>sp_verb_t</code> and an <code>SPView</code>, you can get an SPAction which
represents that action in that view. These mappings are currently
hard-coded in <code>verbs.cpp</code>.

<code>SPActions</code> derive from <code>NRActiveObject</code>, which putatively provides a
“lightweight” method of doing callbacks (vs <code>GObject</code> signals). I
don’t completely understand how it works.

<code>SPActions</code> also contain the label, image, etc, used for buttons and
menuitems.

<code>sp_shortcut_invoke()</code> looks up the <code>SPAction</code> for a keypress and <code>SPView</code> and
invokes it automatically. <code>SPEventContexts</code> call it for keypresses that they do not handle themselves.

== Garbage collection ==

As you know, many automatic garbage collectors (like <code>libgc</code>) only
free and recycle memory periodically. This means you may have some
extra slush that could be freed, but hasn’t yet.

There are other forces at work, though...

Pretty much all allocators, whether automatic or not, whether the
system <code>malloc()</code> or some custom allocator like <code>libgc</code>’s, work the
same way: they request large blocks of memory from the operating
system, then divvy those blocks into smaller ones internally to
satisfy application allocation requests.

When an application frees memory, that memory is usually recycled
internally rather than returned to the OS immediately. The reason
for this is that the large memory blocks acquired from the OS must
be completely unused before they can actually be freed.

For example, let’s say an allocator acquires 16 8MB blocks from
the OS in response to 32768 4k application allocations...

In a worst-case scenario, it’s possible that the application could
free 32752 of those 4k blocks but the remaining 16 4k just happen
to be distributed across the 16 8MB blocks requested from the OS.

If that happens, from the application’s point of view it may only
have 64k allocated, but as far as the OS is concerned, it’s still
using 128MB!

Note that this applies to nearly all allocators in common use.

While it’s unusual for things to get quite that bad, memory
fragmentation is common enough that many popular allocators (for
example Perl’s) simply don’t bother trying to return memory to the
OS at all (the memory will still get forcibly reclaimed by the OS
when the process exits).

[ FWIW, <code>libgc</code>’s allocator is one of the ones that _does_ make an
effort to release memory to the OS, but it is limited by
fragmentation like any other ]

Also note that for various reasons, the statistics you get from the
OS aren’t going to directly reflect the amount of heap-allocated
memory. Be careful drawing conclusions from only looking at e.g.
the output of <code>top(1)</code>...

(The worst thing is, due to the modern practice of
overcommitting memory, the OS may literally lie to an application
about the amount of memory it is being given, hoping the
application won’t really try to use it all.)

The best approach to evaluating memory usage is if you can ask the
allocator for information on memory usage directly, as that matches
the world from the point of view of the application.

leftover gradients/markers/patterns will get automatically cleaned up when the objects that use them are deleted.

Caveats:

* this only applies to such objects created with a build of Inkscape which post-dates this commit (June 7 2004) 

* not all automatically-created objects will necessarily be collected; the code that creates them needs to be updated to set the correct collection policy

* paint objects won’t get collected until another editing operation takes place, since <code>NRArenaShape</code> currently holds onto an <code>SPStyle</code> for too long

Technical details:

Assuming its collection policy permits it, an object will be collected
if neither it nor its descendants have any outstanding inter-document
URI references (nonzero <code>SPObject::hrefcount</code>).

There are two “policies” for collecting orphans:

* “with-parent” - the object will only be collected if one of its ancestors is collected

* “always” - the object is always collected if unused

(a third policy might be “never”, which would necessarily also prevent
that object’s ancestors from ever being collected; I do not plan on
implementing it)

The policy in effect is determined by the inkscape:collect attribute.

Be careful with the “always” policy; it really only makes sense for
“private” objects that are indirectly created behind the scenes (e.g. by
selecting a fill or marker option in the GUI).

<code>SPDocument</code> manages a queue of objects to collect; <code>SPObject</code> handles the machinery for actually queueing them when their <code>hrefcount</code> falls (based on policy), and performing the actual collection (<code>delete</code>).
<code>SPDocument::collectObjects()</code> performs a collection pass. It’s currently only called from <code>sp_document_maybe_done()</code>.

== Inkscape Experimental SVN ==

The <code>experimental</code> module in Inkscape SVN is provided as a kind of “scratchpad” for
working up new ideas that aren’t quite ready for folding into the main codebase.
This includes architectural sketches, examples, experimental patchsets, tools & utilities, or
whatever else strikes the developer’s fancy.

Please create a subdirectory within <code>experimental/</code> for your work. You’re welcome to either post
the stuff at the top level or create a subdirectory for yourself. Things linked in at the top level
should be considered fair game for other developers to collaborate on; items posted under
a developer’s username should be considered ask-first. Same sort of idea as wiki.

One of the principles behind this module is the idea of a shared working space. Other developers
working in experimental can fairly easily see what others are working on in the tree, and perhaps
borrow or contribute ideas back and forth. Since it is by definition not ‘production’ code, the
work may be incomplete or in a non-compileable state...and that’s okay.

When an experiment has matured to the point of being actually useful, please move it out of
the experimental module to someplace more appropriate. Alternatively, if the experimental work has become obsolete or irrelevant, please remove it so we can avoid having the experimental tree get too bulky.

== Directory Organization ==

=== Distribution / Packaging Files ===

Files related to generation of distribution packages should go under inkscape/packaging, as follows:

inkscape/packaging/
common/
debian/
fedora/
fink/
mandrake/
suse/

=== "Share" Collateral ===

A variety of items are installed in addition to the program itself, and placed into a <code>share</code> directory structured as follows:

AUTHORS
NEWS
clipart/
examples/
extensions/
fonts/
gradients/
icons/
keyboards/
markers/
palettes/
patterns/
screens/
about.svg
templates/
tutorials/

In the SVN codebase, all of these are placed in <code>inkscape/share/</code> (except <code>AUTHORS</code> and <code>NEWS</code> which will be copied to share during installation. The idea is that in theory, this entire tree structure can be copied into place on the user’s machine.

However, we need to provide the user some level of control over the installation. They may wish to exclude some items, or may wish to augment the default install with some items external to the Inkscape package. For example, they may wish to incorporate external clipart collections. One approach would be to install symlinks in the given component directory to the external collection. For example, if the flags package were to install into <code>/usr/share/flags-svg/</code>, we’d just symlink there.

=== Code modules ===
Several parts of the code were written in a modular way, and they have been
accordingly placed in subdirectories of <code>src/</code>, while the main src directory
still contains the biggest part. To get a first overview of the modules, you
might want to have a look at these dependency graphs before you read deeper
into the source code (outside at the moment):
<s>
[http://www.ark.in-berlin.de/gri-debug.svgz]
[http://www.ark.in-berlin.de/gri-dialogs.svgz]
[http://www.ark.in-berlin.de/gri-display.svgz]
[http://www.ark.in-berlin.de/gri-io.svgz]
[http://www.ark.in-berlin.de/gri-libcroco.svgz]
[http://www.ark.in-berlin.de/gri-libnr.svgz]
[http://www.ark.in-berlin.de/gri-libnrtype.svgz]
[http://www.ark.in-berlin.de/gri-livarot.svgz]
[http://www.ark.in-berlin.de/gri-widgets.svgz]
[http://www.ark.in-berlin.de/gri-xml.svgz]</s> (links broken)


These are not all modules! For questions about how to generate these graphs
with graph-includes, please [mailto:rwst@users.sf.net].

Question on <code>.svgz</code> files: Is the server sending the right <code>Content-Encoding:</code> header?
This matters to Mozilla browsers in standards compliance mode! http://jwatt.org/svg/authoring/#server-configuration

= See Also =
* [[DirectoryReorgProposal]]
* [[InkscapeJanitors]]
* [[CompilingInkscape]]

= Links =
[http://advogato.org/article/51.html Software Quality]

[[Category:Developer Documentation]]