Gimp Module Procedures

The gimp module contains a number of procedures and functions, as well as the definitions of many gimp types such as images, and the procedural database. This section explains the base level procedures.

Constructors and Object Deletion

There are a number of functions in the gimp module that are used to create the objects used to make up an image in Gimp. Here is a set of descriptions of these constructors:

gimp.image(width, height, type)

This procedure creates an image with the given dimensions and type (type is one of RGB, GRAY or INDEXED).

gimp.layer(img, name, width, height, type, opacity, mode)

Create a new layer called name, with the given dimensions and type (one of the *_IMAGE constants), opacity (float between 0 and 100) and a mode (one of the *_MODE constants). The layer can then be added to the image with the img.add_layer method.

gimp.channel(img, name, width, height, opacity, colour)

Create a new channel object with the given dimensions, opacity and colour (one of the *_CHANNEL constants). This channel can then be added to an image.

gimp.display(img)

Create a new display window for the given image. The window will not be displayed until a call to gimp.displays_flush is made.

gimp.parasite(name, flags, data)

Create a new parasite. The parasite can then be attached to gimp, an image or a drawable. This is only available in gimp >= 1.1

When any of these objects get removed from memory (such as when their name goes out of range), the gimp thing it represents does not get deleted with it (otherwise when your plugin finished running, it would delete all its work). In order to delete the thing the Python object represents, you should use the gimp.delete procedure. It deletes the gimp thing associated with the Python object given as a parameter. If the object is not an image, layer, channel, drawable or display gimp.delete does nothing.

Configuration Information

There are a number of functions that can be used to gather information about the environment the plugin is running in:

gimp.color_cube() or gimp.colour_cube()

Returns the current colour cube.

gimp.gamma()

Returns the current gamma correction.

gimp.install_cmap()

Returns non-zero if a colour map has been installed.

gimp.use_xshm()

Returns non-zero if Gimp is using X shared memory.

gimp.gtkrc()

Returns the file name of the GTK configuration file.

Palette Operations

These functions alter the currently selected foreground and background.

gimp.get_background()

Returns a 3-tuple containing the current background colour in RGB form.

gimp.get_foreground()

Returns a 3-tuple containing the current foreground colour in RGB form.

gimp.set_background(r, g, b)

Sets the current background colour. The three arguments can be replaced by a single 3-tuple like that returned by gimp.get_background.

gimp.set_foreground(r, g, b)

Sets the current foreground colour. Like gimp.set_background, the arguments may be replaced by a 3-tuple.

Gradient Operations

These functions perform operations on gradients:

gimp.gradients_get_active()

Returns the name of the active gradient.

gimp.gradients_set_active(name)

Sets the active gradient.

gimp.gradients_get_list()

Returns a list of the names of the available gradients.

gimp.gradients_sample_uniform(num)

Returns a list of num samples, where samples consist of 4-tuples of floats representing the red, green, blue and alpha values for the sample.

gimp.gradients_sample_custom(pos)

Similar to gimp.gradients_sample_uniform, except the samples are taken at the positions given in the list of floats pos instead of uniformly through the gradient.

PDB Registration Functions

These functions either install procedures into the PDB or alert gimp to their special use (eg as file handlers).

For simple plugins, you will usually only need to use register from gimpfu.

gimp.install_procedure(name, blurb, help, author, copyright, date, menu_path, image_types, type, params, ret_vals)

This procedure is used to install a procedure into the PDB. The first eight parameters are strings, type is a one of the PROC_* constants, and the last two parameters are sequences describing the parameters and return values. Their format is the same as the param and ret_vals methods or PDB procedures.

gimp.install_temp_proc(name, blurb, help, author, copyright, date, menu_path, image_types, type, params, ret_vals)

This procedure is used to install a procedure into the PDB temporarily. That is, it must be added again every time gimp is run. This procedure will be called the same way as all other procedures for a plugin.

gimp.uninstall_temp_proc(name)

This removes a temporary procedure from the PDB.

gimp.register_magic_load_handler(name, extensions, prefixes, magics)

This procedure tells Gimp that the PDB procedure name can load files with extensions and prefixes (eg http:) with magic information magics.

gimp.register_load_handler(name, extensions, prefixes)

This procedure tells Gimp that the PDB procedure name can load files with extensions and prefixes (eg http:).

gimp.register_save_handler(name, extensions, prefixes)

This procedure tells Gimp that the PDB procedure name can save files with extensions and prefixes (eg http:).

Other Functions

These are the other functions in the gimp module.

gimp.main(init_func, quit_func, query_func, run_func)

This function is the one that controls the execution of a Gimp-Python plugin. It is better to not use this directly but rather subclass the plugin class, defined in the the section called The gimpplugin Module.

gimp.pdb

The procedural database object.

gimp.progress_init([label])

(Re)Initialise the progress meter with label (or the plugin name) as a label in the window.

gimp.progress_update(percnt)

Set the progress meter to percnt done.

gimp.query_images()

Returns a list of all the image objects.

gimp.quit()

Stops execution immediately and exits.

gimp.displays_flush()

Update all the display windows.

gimp.tile_width()

The maximum width of a tile.

gimp.tile_height()

The maximum height of a tile.

gimp.tile_cache_size(kb)

Set the size of the tile cache in kilobytes.

gimp.tile_cache_ntiles(n)

Set the size of the tile cache in tiles.

gimp.get_data(key)

Get the information associated with key. The data will be a string. This function should probably be used through the the section called The gimpshelf Module.

gimp.set_data(key, data)

Set the information in the string data with key. The data will persist for the whole gimp session. Rather than directly accessing this function, it is better to go through the the section called The gimpshelf Module.

gimp.extension_ack()

Tells gimp that the plugin has finished its work, while keeping the plugin connection open. This is used by an extension plugin to tell gimp it can continue, while leaving the plugin connection open. This is what the script-fu plugin does so that only one scheme interpreter is needed.

gimp.extension_process(timeout)

Makes the plugin check for messages from gimp. generally this is not needed, as messages are checked during most calls in the gimp module.

Parasites

In gimp >= 1.1, it is possible to attach arbitrary data to an image through the use of parasites. Parasites are simply wrappers for the data, containing its name and some flags. Parasites have the following parameters:

data

The data for the parasite -- a string

flags

The flags for the parasite

is_persistent

True if this parasite is persistent

is_undoable

True if this parasite is undoable

name

The name of the parasite

Parasites also have the methods copy, is_type and has_flag.

There is a set of four functions that are used to manipulate parasites. They exist as functions in the gimp module, and methods for image and drawable objects. They are:

parasite_find(name)

find a parasite by its name.

parasite_attach(parasite)

Attach a parasite to this object.

attach_new_parasite(name, flags, data)

Create a new parasite and attach it.

parasite_detach(name)

Detach the named parasite