Code

Patch by Adib for 248721. Thanks Adib!
[inkscape.git] / doc / extension_system.txt
1 == Inkscape Extensions ==
3 === Introduction ===
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
12 so forth.
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
17 overall system.
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.
26 === Terminology ===
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
62  in the codebase.
65 === Requirements ===
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
70      changing.
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
74      subsystem.
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
78      extensions.
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
88      inconsistent state.
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.
94 === Overview ===
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:
121 Extension
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
129                  structure  
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
140                  functions directly. 
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
162 extension.
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
205 Inkscape.
207 === INX Files ===
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
222 if they are met.
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.
231 === Input ===
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...'
248 dialog.
250 === Output ===
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.
263 === Effect ===
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.
269 === Print ===
271 The Print Extension Type is for extensions that interface with printing
272 subsystems.  Examples would be Win32, postscript, and GNOME Print.
274 === Collection ===
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
300 it however you wish.
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
315 do properly.
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
382 in the core.
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.
388 === Conclusion ===
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
398 it is not needed.
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