mirror of
https://gitlab.gnome.org/GNOME/gimp.git
synced 2025-07-03 09:23:24 +00:00
573 lines
10 KiB
HTML
573 lines
10 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//Norman Walsh//DTD DocBook HTML 1.0//EN">
|
|
<HTML
|
|
><HEAD
|
|
><TITLE
|
|
>The Structure Of A Plugin</TITLE
|
|
><META
|
|
NAME="GENERATOR"
|
|
CONTENT="Modular DocBook HTML Stylesheet"><LINK
|
|
REL="HOME"
|
|
TITLE="Gimp Python Documentation"
|
|
HREF="pygimp.html"><LINK
|
|
REL="PREVIOUS"
|
|
TITLE="Gimp Python Documentation"
|
|
HREF="pygimp.html"><LINK
|
|
REL="NEXT"
|
|
TITLE="The Procedural Database"
|
|
HREF="procedural-database.html"></HEAD
|
|
><BODY
|
|
><DIV
|
|
CLASS="NAVHEADER"
|
|
><TABLE
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
CELLPADDING="0"
|
|
CELLSPACING="0"
|
|
><TR
|
|
><TH
|
|
COLSPAN="3"
|
|
ALIGN="center"
|
|
>Gimp Python Documentation</TH
|
|
></TR
|
|
><TR
|
|
><TD
|
|
WIDTH="10%"
|
|
ALIGN="left"
|
|
VALIGN="bottom"
|
|
><A
|
|
HREF="pygimp.html"
|
|
>Prev</A
|
|
></TD
|
|
><TD
|
|
WIDTH="80%"
|
|
ALIGN="center"
|
|
VALIGN="bottom"
|
|
></TD
|
|
><TD
|
|
WIDTH="10%"
|
|
ALIGN="right"
|
|
VALIGN="bottom"
|
|
><A
|
|
HREF="procedural-database.html"
|
|
>Next</A
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"></DIV
|
|
><DIV
|
|
CLASS="SECT1"
|
|
><H1
|
|
CLASS="SECT1"
|
|
><A
|
|
NAME="STRUCTURE-OF-PLUGIN"
|
|
>The Structure Of A Plugin</A
|
|
></H1
|
|
><P
|
|
>The majority of code in this package resides in
|
|
<TT
|
|
CLASS="FILENAME"
|
|
>gimpmodule.c</TT
|
|
>, but this provides a poor
|
|
interface for implementing some portions of a plugin. For this
|
|
reason, there is a python module called
|
|
<TT
|
|
CLASS="FILENAME"
|
|
>plugin.py</TT
|
|
> that sets out a structure for
|
|
plugins and implements some things that were either too difficult
|
|
or impossible to do in C.</P
|
|
><P
|
|
>The main purpose of <TT
|
|
CLASS="FILENAME"
|
|
>plugin.py</TT
|
|
> was to
|
|
implement an object oriented structure for plug-ins. As well as
|
|
this, it handles tracebacks, which are otherwise ignored by
|
|
<TT
|
|
CLASS="FILENAME"
|
|
>libgimp</TT
|
|
>, and gives a method to call
|
|
other Gimp-Python plug-ins without going through the procedural
|
|
database.</P
|
|
><DIV
|
|
CLASS="SECT2"
|
|
><H2
|
|
CLASS="SECT2"
|
|
><A
|
|
NAME="EXAMPLE-PLUGIN"
|
|
>An Example Plugin</A
|
|
></H2
|
|
><P
|
|
>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:</P
|
|
><DIV
|
|
CLASS="EXAMPLE"
|
|
><P
|
|
><B
|
|
>Example 1. A sample python plugin</B
|
|
></P
|
|
><TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><PRE
|
|
CLASS="PROGRAMLISTING"
|
|
>#!/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()</PRE
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="SECT2"
|
|
><H2
|
|
CLASS="SECT2"
|
|
><A
|
|
NAME="IMPORTANT-MODULES"
|
|
>Import Modules</A
|
|
></H2
|
|
><P
|
|
>In this plugin, a number of modules are imported. The
|
|
important ones are:</P
|
|
><P
|
|
></P
|
|
><UL
|
|
><LI
|
|
><P
|
|
><TT
|
|
CLASS="FILENAME"
|
|
>gimpfu</TT
|
|
>: 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.</P
|
|
><P
|
|
>By using "from gimpfu import *", this module also
|
|
provides an easy way to get all the commonly used symbols
|
|
into the plugin's namespace.</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
><TT
|
|
CLASS="FILENAME"
|
|
>gimp</TT
|
|
>: the main part of the gimp
|
|
extension. This is imported with gimpfu.</P
|
|
></LI
|
|
><LI
|
|
><P
|
|
><TT
|
|
CLASS="FILENAME"
|
|
>gimpenums</TT
|
|
>: a number of useful
|
|
constants. This is also automatically imported with
|
|
gimpfu.</P
|
|
></LI
|
|
></UL
|
|
><P
|
|
>The pdb variable is a variable for accessing the
|
|
procedural database. It is imported into the plugin's namespace
|
|
with gimpfu for convenience.</P
|
|
></DIV
|
|
><DIV
|
|
CLASS="SECT2"
|
|
><H2
|
|
CLASS="SECT2"
|
|
><A
|
|
NAME="PLUGIN-FRAMEWORK"
|
|
>Plugin Framework</A
|
|
></H2
|
|
><P
|
|
>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.</P
|
|
><P
|
|
>Using the gimpfu plugin, all you need to do is write the
|
|
function that should be run, make a call to
|
|
<TT
|
|
CLASS="FUNCTION"
|
|
><B
|
|
>register</B
|
|
></TT
|
|
>, and finally a call to
|
|
<TT
|
|
CLASS="FUNCTION"
|
|
><B
|
|
>main</B
|
|
></TT
|
|
> to get the plugin started.</P
|
|
><P
|
|
>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.</P
|
|
><P
|
|
>After defining the plugin function, you need to call
|
|
<TT
|
|
CLASS="FUNCTION"
|
|
><B
|
|
>register</B
|
|
></TT
|
|
> 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
|
|
<TT
|
|
CLASS="FUNCTION"
|
|
><B
|
|
>register</B
|
|
></TT
|
|
> are:</P
|
|
><P
|
|
></P
|
|
><TABLE
|
|
BORDER="0"
|
|
><TR
|
|
><TD
|
|
>name</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>blurb</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>help</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>author</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>copyright</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>date</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>menupath</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>imagetypes</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>params</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>results</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>function</TD
|
|
></TR
|
|
></TABLE
|
|
><P
|
|
></P
|
|
><P
|
|
>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.</P
|
|
><P
|
|
>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:</P
|
|
><P
|
|
></P
|
|
><TABLE
|
|
BORDER="0"
|
|
><TR
|
|
><TD
|
|
>PF_INT8</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>PF_INT16</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>PF_INT32</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>PF_INT</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>PF_FLOAT</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>PF_STRING</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>PF_VALUE</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>PF_INT8ARRAY</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>PF_INT16ARRAY</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>PF_INT32ARRAY</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>PF_INTARRAY</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>PF_FLOATARRAY</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>PF_STRINGARRAY</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>PF_COLOR</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>PF_COLOUR</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>PF_REGION</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>PF_IMAGE</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>PF_LAYER</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>PF_CHANNEL</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>PF_DRAWABLE</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>PF_TOGGLE</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>PF_BOOL</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>PF_SLIDER</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>PF_SPINNER</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>PF_ADJUSTMENT</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>PF_FONT</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>PF_FILE</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>PF_BRUSH</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>PF_PATTERN</TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
>PF_GRADIENT</TD
|
|
></TR
|
|
></TABLE
|
|
><P
|
|
></P
|
|
><P
|
|
>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).</P
|
|
><P
|
|
>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.</P
|
|
><P
|
|
>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.</P
|
|
><P
|
|
>The final parameter to <TT
|
|
CLASS="FUNCTION"
|
|
><B
|
|
>register</B
|
|
></TT
|
|
> is
|
|
the plugin function itself.</P
|
|
><P
|
|
>After registering one or more plugin functions, you must
|
|
call the <TT
|
|
CLASS="FUNCTION"
|
|
><B
|
|
>main</B
|
|
></TT
|
|
> 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.</P
|
|
></DIV
|
|
></DIV
|
|
><DIV
|
|
CLASS="NAVFOOTER"
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"><TABLE
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
CELLPADDING="0"
|
|
CELLSPACING="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="left"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="pygimp.html"
|
|
>Prev</A
|
|
></TD
|
|
><TD
|
|
WIDTH="34%"
|
|
ALIGN="center"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="pygimp.html"
|
|
>Home</A
|
|
></TD
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="right"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="procedural-database.html"
|
|
>Next</A
|
|
></TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="left"
|
|
VALIGN="top"
|
|
>Gimp Python Documentation</TD
|
|
><TD
|
|
WIDTH="34%"
|
|
ALIGN="center"
|
|
VALIGN="top"
|
|
> </TD
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="right"
|
|
VALIGN="top"
|
|
>The Procedural Database</TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
></BODY
|
|
></HTML
|
|
>
|