Gimp Python Documentation
Prev |  | Next

# The Procedural Database

The procedural database is a registry of things gimp and its plugins can do. When you install a procedure for your plugin, you are extending the procedural database.

The procedural database is self documenting, in that when you install a procedure in it, you also add documentation for it, its parameters and return values.

## The Gimp-Python Model

In Gimp-Python, the procedural database is represented by the object `gimp.pdb`. In most of my plugins, I make an assignment from `gimp.pdb` to `pdb` for convenience.

You can query the procedural database with `pdb`'s method `query`. Its specification is:

    pdb.query(name, [blurb, [help, [author, [copyright, [date, [type]]]]]])

Each parameter is a regular expression that is checked against the corresponding field in the procedural database. The method returns a list of the names of matching procedures. If `query` is called without any arguments, it will return every procedure in the database.

## Procedural Database Procedures

Procedures can be accessed as procedures, or by treating `pdb` as a mapping objest. As an example, the probedure `gimp_edit_fill` can be accessed as either `pdb.gimp_edit_fill` or `pdb['gimp_edit_fill']`. The second form is mainly for procedures whose names are not valid Python names (eg in script-fu-..., the dashes are interpreted as minuses).

These procedure objects have a number of attribute:

proc_name

  The name of the procedure.

proc_blurb

  A short piece of information about the procedure.

proc_help

  More detailed information about the procedure.

proc_author

  The author of the procedure.

proc_copyright

  The copyright holder for the procedure (usually the same as the author).

proc_date

  The date when the procedure was written.

proc_type

  The type of procedure. This will be one of PROC_PLUG_IN, PROC_EXTENSION or PROC_TEMPORARY.

nparams

  The number of parameters the procedure takes.

nreturn_vals

  The number of return values the procedure gives.

params

  A description of parameters of the procedure. It takes the form of a tuple of 3-tuples, where each 3-tuple describes a parameter. The items in the 3-tuple are a parameter type (one of the PARAM_* constants), a name for the parameter, and a description of the parameter.

return_vals

  A description of the return values. It takes the same form as the `params` attribute.

A procedure object may also be called. At this point, Gimp-Python doesn't support keyword arguments for PDB procedures. Arguments are passed to the procedure in the normal method. The return depends on the number of return values:

- If there are zero return values, `None` is returned.

- If there is only a single return value, it is returned.

- If there are more return values, then they are returned as a tuple.

## More Information

For more information on invoking PDB procedures, please see the example plugins. For information on individual procedures, please see the PDB Browser plugin (in the Xtns menu). It allows you to peruse the database interactively.

Prev | Home | Next
The Structure Of A Plugin |  | Gimp Module Procedures