1
== Inkscape Extensions ==
5
The extensions system in Inkscape is a way for adding functionality to
6
Inkscape, without affecting the core of the program itself. We want
7
Inkscape to follow a core-plus-modules approach similar to that adopted
8
by many successful open source projects such as the Linux kernel, Perl,
9
Apache, Gimp, and so on. There are many different types of extension
10
mechanisms, including file format conversion tools, filter scripts that
11
process SVG, user interface elements that can be added at runtime, and
14
This proposal defines a design for handling this wide variety of
15
extensions in a flexible manner. This document provides a way to
16
understand the extensions system, and how extensions fit into this
19
Much of the documentation that will be useful for users of the extension
20
system is not included in this document, it is autogenerated from the
21
source code and placed on the Inkscape webpage. While this is less
22
convienient, it is more correct, and maintained as the source code is
23
modified. Please look aton the Inkscape webpage also.
28
*Extension* - An extension is something that extends the functionality
29
of Inkscape without being directly part of the core. This implies
30
that it should be easy to remove or add, and nothing in the core should
31
depend on it directly.
33
*Extension Type* - Establishes the functional interface that the
34
Extension provides, including the types of messages it handles and what
35
is contained in its data structures.
37
*Extension Implementation* - Defines how the extension is accessed;
38
i.e. through message passing, pipe/exec calls with commandline
39
arguments, direct function calls, etc.
41
*Plug-in* - An extension that is implemented through a loadable library.
42
This is a .so file on Unix-like systems or a .dll on Win32. The
43
libraries should not be loaded until they are used.
45
*Script* - A script is a type of extension that is implemented through
46
an external program that recieves and sets SVG data through files and
47
pipes. This allows Inkscape to use programs that handle SVG but are
48
targeted differently, seemlessly inside of Inkscape.
50
*Language Binding* - A special type of plug-in that wraps a scripting
51
language interpreter such as Perl, Python, Lisp, etc. A user
52
interested in programmatic access to Inkscape's internals via one of
53
these languages can install (or create) the relevant Language Binding
54
Plug-in to achieve this.
56
*INX* - *'INkscape eXtension'* - The filename extension used for XML
57
metadata files that describe each Inkscape Extension.
59
*Internal Extension* - A part of the Inkscape codebase which uses the
60
extension system in order to make it more modular. This code is
61
compiled into Inkscape, but appears as an extension to all other code
67
* Uses a general language binding system so it's easy to add new
68
language binding support.
69
* Allows direct interaction with the document object model including
71
* Allows some limited interaction with the Inkscape UI such as
72
manipulating grids, overlays, etc.
73
* Allows direct interaction with file load/save/export/print
75
* Guaranteed to work properly with the undo system, even if the
76
extension is not written carefully.
77
* Well documented so is easy for people to learn how to make new
79
* Each extension can be implemented, distributed, and managed
80
independently of the core project.
81
* Icons, buttons, and other UI elements for extensions fit seamlessly
82
into main application GUI.
83
* User can easily select which extensions to automatically load into
84
application at startup.
85
* Loading of extensions shall not seriously slow startup time or make
86
a major impact on memory footprint.
87
* Failure of a extension shall not leave the drawing in an
89
* Main application must gracefully recover from extension crashes or
90
other serious problems with extension execution.
91
* Dependencies for particular extensions must be clearly identified for user if missing.
96
Different kinds of extensions can be categorized in two ways. First,
97
but what the extension does: File format converters, printing, SVG
98
manipulation, symbol libraries, etc. Second, by how the extension is
99
implemented: command-line scripts, dynamically loaded libraries,
100
internal compiled-in code, etc.
102
The first kind of categorization is called the *Extension Type*. This
103
essentially establishes a calling interface and the set of messages the
104
extension must be able to receive and handle. For example, extensions
105
of type Print must have a way to handle 'print' message.
107
The second is the *Extension Implementation*. This defines the
108
mechanism Inkscape must use for passing messages to the extension. For
109
example, commandline scripts would have messages passed as commandline
110
arguments, whereas loadable plug-ins would have the messages passed to
111
the plug-in's message handler routine.
113
The categories of both Extension Types and Extension Implementations are
114
left open ended. This way, if someone comes up with new ideas for ways
115
to extend Inkscape that doesn't fit within the existing models, they can
116
add these mechanisms in a straightforward fashion.
118
For the purposes of this document, however, we focus on just the
119
following Types and Implementations:
122
"Input" - loading various file formats
123
"Output" - saving as various file formats
124
"Effect" - apply some sort of change to SVG elements in the doc
125
"Print" - prints using different drivers or modes
126
"Collection" - a group of objects that have thumbnails and images that
127
can be used inside a document. Libraries can be
128
searchable and may be presented in a hierarchical
131
"Extension Implementations"
132
"Internal" - code that is internal to Inkscape which uses the
133
extension system for some functionality
134
"Script" - a cmdline program that takes an SVG document to its
135
STDIN and emits a modified SVG document to its STDOUT,
136
with control messages given as commandline parameters.
138
"Plug-in" - a loadable module with a message handler routine that
139
receives messages and that operates on the Inkscape API
142
=== Extension System Basics ===
144
Leaving the topic of Types and Implementations aside, we can make some
145
generalizations about how all Extensions work, and behaviors or
146
attributes that all Extensions share. This includes how they are
147
registered, how they handle preferences, how dependency resolution is
148
achieved, and versioning. These common behaviors are all established
149
via a base class that all Extension Types derive from.
151
=== Extension Base Class ===
153
The Extension base class holds the attribute data that all extensions
154
must have and establishes the base functionality that all extensions
155
share. All extensions have the following properties:
157
"ID" - A unique identifier for this extension that is used for refering
158
to the extension and naming its parameters in the configuration files.
160
"Name" - The textual name of the extension, it is used for user
161
interaction with the extension. It is used for users to identify the
164
"Parameters" - Each extension keeps a record of all of the parameters
165
that it has. The can be changed internally, through a GUI, or by other
166
extensions. Parameters can be found and adjusted using functions that
167
are within the base class.
169
=== Extension Registry ===
171
Inkscape maintains a data structure of all the registered extensions.
172
This registry can be queried against to retrieve lists of extensions
173
meeting various conditions (such as all Input extensions).
175
The Extension Registry contains all extensions whether or not they
176
failed their dependency checking on startup. This allows for additional
177
information to be displayed on the reasoning behind marking the
178
extension as disabled.
180
The registry can be reloaded from the Inkscape GUI while Inkscape is
181
running. This can be used to add new extensions into the system, or
182
help debug new extensions. When the registry is reloaded all extensions
183
are first unloaded, then they're specification files are re-read.
185
=== Handling Preferences ===
187
Individual extensions can have their own preferences which are used by
188
the extension. These are typically attributes of the operation that can
189
be modified by the user through a dialog. It is also possible to have
190
other extensions modify these values when they are using an extension.
191
For most extensions, these will be edited by a dialog that relates to
192
the preferences of the user.
194
The preferences themselves are defined in the inx file that describes
195
the extension. In this definition there is the name, the type, and the
196
default value. The types are: boolean, integer, float and string.
197
Other types can be developed using these as a basis. If there is no
198
custom value set the default value is used.
200
When a value is written to a preference for an extension, that value is
201
saved in the global preferences for Inkscape using the ID of the module
202
as the basis for the naming. At next use (including after restarting
203
the application) this value is used instead of the default. This allows
204
user preferences on a extension to remain persistent throughout uses of
209
The INX file is the description of the Inkscape Extension. It provides
210
all of the information that is used to identify the extension, and
211
determine what type of extension it is. This file is loaded on startup
212
of Inkscape, and the objects relating to the extension are created. All
213
extensions have an inx file, but many internal extensions compile this
214
file into the codebase (to reduce dependencies).
216
The INX file also contains information on the dependencies that are
217
required for the extension to operate. These dependencies can be
218
everything from required files, required libraries or other extensions
219
that help this one. The dependencies are checked as the file is loaded,
220
and an extension is marked as dead if they are not met. Also
221
dependencies can check different versions of particular objects to see
225
=== Extension Types ===
227
Each Extension is identified by it's 'Type'. This determines the type
228
of programmatic interface that it adheres to, enabling Inkscape to know
229
what functionality it can expect from the extension.
233
An input extension provides a way to get data into Inkscape. This type
234
of extension creates a document given a filename. This is done by using
235
the 'open' method within the class. Also, there is a 'prefs' function
236
which will generate a GtkDialog. This dialog is then used to get any
237
settings that the incomming file and extension my use. This function is
238
executed, and the dialog returns, before the open method is called.
240
There are also several other settings stored in an Input extension.
241
This includes information on the type of file the input module can take
242
in including its filename extension and mime type. Also, there is a
243
space to store a tooltip for additional information on the file type in
244
the file dialog. Lastly, there is the key of which Output extension is
245
recommended for saving this filetype. This is useful, as there is no
246
other direct links between the Input and Ouput functions, and a user
247
expects to be able to open and save without using the 'Save As...'
252
An output extension controls how SVG documents are exported from
253
Inkscape. This type of extension creates a file given a document
254
object. This is done using the 'save' method within the class.
256
The method for how files are exported depends on what type of
257
Implementation is used. For Scripts, the file is first saved as a
258
temporary SVG file, and then processed by calling the commandline
259
programs to convert it. For Plug-ins, the document object is passed to
260
the extension with a 'save' message and a filename, and the extension
261
program performs the file save operation itself.
265
Effect extensions cause a modification of a loaded document. For
266
example, it might add a new shape to the drawing, or change all selected
267
objects to be purple with green dotted borders.
271
The Print Extension Type is for extensions that interface with printing
272
subsystems. Examples would be Win32, postscript, and GNOME Print.
277
=== Creating Extensions ===
279
In this chapter, we discuss how to create an extension from scratch,
280
incorporate into Inkscape, and release it for the general Inkscape
281
community to use. This chapter can be read independently of the rest of
282
the document, using the rest as reference material.
284
=== Selecting an Extension Strategy ===
286
First of all, you will need to select the method you'll use for creating your extension.
288
Scripts are the simplest extensions to create, because they work through
289
STDIN/STDOUT, so you need to know very little about Inkscape internals
290
to make them work. However, their ability to interact with the Inkscape
291
internals is limited compared with other approaches. For file format
292
converters, this is usually fine. You can also create filters programs
293
that take the entire document to its STDIN, process it, and return a
294
modified copy to STDOUT. Some control of the extension is possible via
295
its commandline arguments.
297
One of the nice things about Scripts is that they can be written in any
298
language. It need not even be a scripting language - as long as it
299
handles STDIN and STDOUT and uses commandline arguments, you can write
302
Plug-ins are more powerful than Scripts, but require more knowledge of
303
Inkscape internals, and must be written according to specific criteria.
304
Generally, since these are loaded as dynamic objects, they'll need to be
305
written in a language that can generate them, such as C or C++.
307
The best of both worlds can be available through Language Bindings,
308
which are Plug-ins that wrapper a script interpreter. This enables you
309
to call various Inkscape internal routines through your scripting
310
language's functions. If someone has created a Language Binding for
311
your language of choice, you're all set, otherwise you'll have to create
312
a Plug-in for it. Language Binding Plug-ins have a few more
313
requirements than ordinary Plug-ins, and require a greater amount of
314
knowledge of the Inkscape internals, so it can take quite some time to
317
Internal Extensions are in a way the reverse of a normal Extension, in
318
that instead of providing a way to hook into Inkscape from the outside,
319
they provide hooks from inside Inkscape. These are used directly by
320
Inkscape, such as in the case of compiled-in printing modules. Most
321
users will never need to write this type of extension, they are pretty
322
much for Inkscape core developers only.
324
=== Writeing Your Extension ===
326
This section provides some guidance and examples for implementing
327
different kinds of Extensions.
329
=== Writing Script Extensions ===
331
=== Writing Plug-in Extensions ===
333
=== Writing Language Binding Plug-in Extensions ===
335
=== Creating an INX File ===
337
Every extension must have a corrosponding *.inx file. This is an XML
338
file that provides Inkscape with information about the module and allows
339
it to load the info without needing to access the module itself. The
340
*.inx file contains enough info for Inkscape to set up menu items and
341
know what kinds of functionality to expect from the extension.
343
=== Packaging Your Extension ===
345
=== Contributing Your Extensino to the Inkscape Community ===
347
Once your extension is complete, you may wish to share it with the
348
community. There are of course no hard and fast rules for how to share
349
your work, but this section illustrates some approaches.
351
=== Listing Your Extension ===
353
First, you will need to put your extension someplace that others can
354
find and download it. If you have adequate webspace, you could simply
355
upload it to your web server. More typically, you will want to upload
356
it to a mirroring system like SourceForge (http://www.sourceforge.net),
357
CPAN (http://www.cpan.org), and the like. The Inkscape project may also
358
be willing to host your extension; contact the admins for more info.
360
It can also be helpful to list your extension with one of the various
361
software registries, such as Freshmeat (http://www.freshmeat.net). You
362
should also list it on the Inkscape Wiki site.
364
=== Announcing Your Extension ===
366
After posting your extension someplace from which it can be downloaded,
367
you should also announce its availability, by sending an email to
368
inkscape-announce@lists.sourceforge.net. You may also want to announce
369
it on other related sites; for instance, if you've written a plug-in to
370
allow operation of Imagemagick from within Inkscape, it could be a good
371
idea to announce it to the Imagemagick list.
374
=== Incorporating Your Extension in to Inkscape ===
376
Because the intent with the extension system is to break things *out*
377
from the core, most extensions should be packaged and distributed
378
independently of the main Inkscape distribution. However, for ease of
379
user installation, an extension-pack can be shipped along with the core
380
Inkscape package. Also, certain extensions may be so critical to
381
Inkscape operation (such as for printing) that they should be included
384
If your extension seems like it should be incorporated into the Inkscape
385
core, contact the Inkscape developers about this, and discuss how best
386
to include it in the distribution with them.
390
It is anticipated that the incorporation of this extensions capability
391
will bring Inkscape added power and flexibility while avoiding bloating
392
the core with cool-but-rarely-used functionality. Further, it empowers
393
users and non-core Inkscape developers to extend the application with
394
their own new capabilities, without needing to gain special access and
395
acceptance by the project. Dynamic loading of functionality will also
396
allow Inkscape to remain 'lean and mean', loading up functionality on an
397
as-needed basis, and conserving memory by unloading functionality when
400
The key point of this design specification is the architectural concept
401
of separately identifying an extension's interface type, or 'Extension
402
Type', from its implementation method, or 'Extension Implementation'.
403
This feature enables Inkscape to be extended in a variety of mechanisms,
404
including ways not yet foreseen.
407
=== History and references ===
409
Base design taken from Ted Gould's Extension System work.
411
This document originally authored by Bryce Harrington, July 2004
added
removed
doc/extension_system.txt
