Gimp Python Documentation
Prev |  | Next

# 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_handle`r(`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

Prev | Home | Next
The Procedural Database |  | Gimp Objects