Gimp Python Documentation
Prev |  | Next

# The Structure Of A Plugin

The majority of code in this package resides in `gimpmodule.c`, but this provides a poor interface for implementing some portions of a plugin. For this reason, there is a python module called `plugin.py` that sets out a structure for plugins and implements some things that were either too difficult or impossible to do in C.

The main purpose of `plugin.py` was to implement an object oriented structure for plug-ins. As well as this, it handles tracebacks, which are otherwise ignored by `libgimp`, and gives a method to call other Gimp-Python plug-ins without going through the procedural database.

## An Example Plugin

As in a lot of manuals, the first thing you examine is an example, so here is an example. I have included it before explaining what it does to allow more advanced programmers to see the structure up front. It is a translation of the clothify Script-Fu extension:

Example 1. A sample python plugin

    #!/usr/bin/python
    import math
    from gimpfu import *

    have_gimp11 = gimp.major_version > 1 or \
    	      gimp.major_version == 1 and gimp.minor_version >= 1

    def python_clothify(timg, tdrawable, bx=9, by=9,
    		    azimuth=135, elevation=45, depth=3):
    	bx = 9 ; by = 9 ; azimuth = 135 ; elevation = 45 ; depth = 3
    	width = tdrawable.width
    	height = tdrawable.height
    	img = gimp.image(width, height, RGB)
    	layer_one = gimp.layer(img, "X Dots", width, height, RGB_IMAGE,
    			       100, NORMAL_MODE)
    	img.disable_undo()
    	if have_gimp11:
    		pdb.gimp_edit_fill(layer_one)
    	else:
    		pdb.gimp_edit_fill(img, layer_one)
    	img.add_layer(layer_one, 0)
    	pdb.plug_in_noisify(img, layer_one, 0, 0.7, 0.7, 0.7, 0.7)
    	layer_two = layer_one.copy()
    	layer_two.mode = MULTIPLY_MODE
    	layer_two.name = "Y Dots"
    	img.add_layer(layer_two, 0)
    	pdb.plug_in_gauss_rle(img, layer_one, bx, 1, 0)
    	pdb.plug_in_gauss_rle(img, layer_two, by, 0, 1)
    	img.flatten()
    	bump_layer = img.active_layer
    	pdb.plug_in_c_astretch(img, bump_layer)
    	pdb.plug_in_noisify(img, bump_layer, 0, 0.2, 0.2, 0.2, 0.2)
    	pdb.plug_in_bump_map(img, tdrawable, bump_layer, azimuth,
    			     elevation, depth, 0, 0, 0, 0, TRUE, FALSE, 0)
    	gimp.delete(img)

    register(
    	"python_fu_clothify",
    	"Make the specified layer look like it is printed on cloth",
    	"Make the specified layer look like it is printed on cloth",
    	"James Henstridge",
    	"James Henstridge",
    	"1997-1999",
    	"<Image>/Filters/Artistic/Clothify",
    	"RGB*, GRAY*",
    	[
    		(PF_INT, "x_blur", "X Blur", 9),
    		(PF_INT, "y_blur", "Y Blur", 9),
    		(PF_INT, "azimuth", "Azimuth", 135),
    		(PF_INT, "elevation", "elevation", 45),
    		(PF_INT, "depth", "Depth", 3)
    	],
    	[],
    	python_clothify)

    main()

## Import Modules

In this plugin, a number of modules are imported. The important ones are:

- `gimpfu`: this module provides a simple interface for writing plugins, similar to what script-fu provides. It provides the GUI for entering in parameters in interactive mode and performs some sanity checks when registering the plugin.

  By using "from gimpfu import *", this module also provides an easy way to get all the commonly used symbols into the plugin's namespace.

- `gimp`: the main part of the gimp extension. This is imported with gimpfu.

- `gimpenums`: a number of useful constants. This is also automatically imported with gimpfu.

The pdb variable is a variable for accessing the procedural database. It is imported into the plugin's namespace with gimpfu for convenience.

## Plugin Framework

With pygimp-0.4, the gimpfu module was introduced. It simplifies writing plugins a lot. It handles the run mode (interactive, non interactive or run with last values), providing a GUI for interactive mode and saving the last used settings.

Using the gimpfu plugin, all you need to do is write the function that should be run, make a call to `register`, and finally a call to `main` to get the plugin started.

If the plugin is to be run on an image, the first parameter to the plugin function should be the image, and the second should be the current drawable (do not worry about the run_mode parameter). Plugins that do not act on an existing image (and hence go in the toolbox's menus) do not need these parameters. Any other parameters are specific to the plugin.

After defining the plugin function, you need to call `register` to register the plugin with gimp (When the plugin is run to query it, this information is passed to gimp. When it is run interactively, this information is used to construct the GUI). The parameters to `register` are:

name
blurb
help
author
copyright
date
menupath
imagetypes
params
results
function

Most of these parameters are quite self explanatory. The menupath option should start with <Image%gt;/ for image plugins and <Toolbox>/ for toolbox plugins. The remainder of the menupath is a slash separated path to its menu item.

The params parameter holds a list parameters for the function. It is a list of tuples. Note that you do not have to specify the run_type, image or drawable parameters, as gimpfu will add these automatically for you. The tuple format is (type, name, description, default [, extra]). The allowed type codes are:

PF_INT8
PF_INT16
PF_INT32
PF_INT
PF_FLOAT
PF_STRING
PF_VALUE
PF_INT8ARRAY
PF_INT16ARRAY
PF_INT32ARRAY
PF_INTARRAY
PF_FLOATARRAY
PF_STRINGARRAY
PF_COLOR
PF_COLOUR
PF_REGION
PF_IMAGE
PF_LAYER
PF_CHANNEL
PF_DRAWABLE
PF_TOGGLE
PF_BOOL
PF_SLIDER
PF_SPINNER
PF_ADJUSTMENT
PF_FONT
PF_FILE
PF_BRUSH
PF_PATTERN
PF_GRADIENT

These values map onto the standard PARAM_* constants. The reason to use the extra constants is that they give gimpfu more information, so it can produce a better interface (for instance, the PF_FONT type is equivalent to PARAM_STRING, but in the GUI you get a small button that will bring up a font selection dialog).

The PF_SLIDER, PF_SPINNER and PF_ADJUSTMENT types require the extra parameter. It is of the form (min, max, step), and gives the limits for the spin button or slider.

The results parameter is a list of 3-tuples of the form (type, name, description). It defines the return values for the function. If there is only a single return value, the plugin function should return just that value. If there is more than one, the plugin function should return a tuple of results.

The final parameter to `register` is the plugin function itself.

After registering one or more plugin functions, you must call the `main` function. This will cause the plugin to start running. A GUI will be displayed when needed, and your plugin function will be called at the appropriate times.

Prev | Home | Next
Gimp Python Documentation |  | The Procedural Database