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:

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.