The Structure Of A Plugin

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:

#!/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:

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:

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.