Gimp::Fu

Fu(u) User Contributed Perl Documentation Fu(u)

NAME
Gimp::Fu - "easy to use" framework for Gimp scripts

SYNOPSIS
use Gimp;
use Gimp::Fu;

(this module uses Gtk, so make sure it's correctly installed)

DESCRIPTION
Currently, there are only three functions in this module.
This fully suffices to provide a professional interface
and the ability to run this script from within the Gimp
and standalone from the commandline.

Dov Grobgeld has written an excellent tutorial for
Gimp-Perl. While not finished, it's definitely worth a
look! You can find it at "http://imagic.weiz-
mann.ac.il/~dov/gimp/perl-tut.html".

INTRODUCTION
In general, a Gimp::Fu script looks like this:

#!/path/to/your/perl

use Gimp;
use Gimp::Fu;

exit main;

(This distribution comes with example scripts. One is
"examples/example-fu.pl", which is small Gimp::Fu-script
you can take as starting point for your experiments)

THE REGISTER FUNCTION

register
"function_name",
"blurb", "help",
"author", "copyright",
"date",
"menu path",
"image types",
[
[PF_TYPE,name,desc,optional-default,optional-extra-args],
[PF_TYPE,name,desc,optional-default,optional-extra-args],
# etc...
],
[
# like above, but for return values (optional)
],
['feature1', 'feature2'...], # optionally check for features
sub { code };

function name
The pdb name of the function, i.e. the name under which
is will be registered in the Gimp database. If it
doesn't start with "perl_fu_", "file_", "plug_in_" or
"extension_", it will be prepended. If you don't want
this, prefix your function name with a single "+". The
idea here is that every Gimp::Fu plug-in will be found
under the common "perl_fu_"-prefix.

blurb
A small description of this script/plug-in. Defaults to
"=pod(d)" (see the section on EMBEDDED POD DOCUMENTA-
TION for an explanation of this string).

help
A help text describing this script. Should be longer and
more verbose than "blurb". Default is "=pod(d)".

author
The name (and also the e-mail address if possible!) of
the script-author. Default is "=pod(d)".

date
The "last modified" time of this script. There is no
strict syntax here, but I recommend ISO format (yyyymmdd
or yyyy-mm-dd). Default value is "=pod(d)".

menu path
The menu entry Gimp should create. It should start
either with <Image>, if you want an entry in the image
menu (the one that opens when clicking into an image),
<Xtns>, for the Xtns menu or <None> for none.

image types
The types of images your script will accept. Examples
are "RGB", "RGB*", "GRAY, RGB" etc... Most scripts will
want to use "*", meaning "any type".

the parameter array
An array ref containing parameter definitions. These are
similar to the parameter definitions used for
"gimp_install_procedure", but include an additional
default value used when the caller doesn't supply one,
and optional extra arguments describing some types like
"PF_SLIDER".

Each array element has the form "[type, name, descrip-
tion, default_value, extra_args]".

<Image>-type plugins get two additional parameters,
image ("PF_IMAGE") and drawable ("PF_DRAWABLE"). Do not
specify these yourself. Also, the "run_mode" argument is
never given to the script, but its value canm be
accessed in the package-global $run_mode. The name is
used in the dialog box as a hint, the description will
be used as a tooltip.

See the section PARAMETER TYPES for the supported types.

the return values
This is just like the parameter array, just that it
describes the return values. Of course, default values
and the enhanced Gimp::Fu parameter types don't make
much sense here. (Even if they did, it's not implemented
anyway..). This argument is optional.

If you supply a parameter type (e.g. "PF_IMAGE") instead
of a full specification ("[PF_IMAGE, ...]"), Gimp::Fu
might supply some default values. This is only imple-
mented for "PF_IMAGE" at the moment.

the features requirements
See Gimp::Features for a description of which features
can be checked for. This argument is optional (but
remember to specify an empty return value array, "[]",
if you want to specify it).

the code
This is either a anonymous sub declaration ("sub { your
code here; }", or a coderef, which is called when the
script is run. Arguments (including the image and draw-
able for <Image> plug-ins) are supplied automatically.

It is good practise to return an image, if the script
creates one, or "undef", since the return value is
interpreted by Gimp::Fu (like displaying the image or
writing it to disk). If your script creates multiple
pictures, return an array.

PARAMETER TYPES

PF_INT8, PF_INT16, PF_INT32, PF_INT, PF_FLOAT, PF_STRING,
PF_VALUE
Are all mapped to a string entry, since perl doesn't
really distinguish between all these datatypes. The rea-
son they exist is to help other scripts (possibly writ-
ten in other languages! really!). It's nice to be able
to specify a float as 13.45 instead of "13.45" in C!
"PF_VALUE" is synonymous to "PF_STRING", and <PF_INT> is
synonymous to <PF_INT32>.

PF_COLOR, PF_COLOUR
Will accept a colour argument. In dialogs, a colour pre-
view will be created which will open a colour selection
box when clicked.

PF_IMAGE
A gimp image.

PF_DRAWABLE
A gimp drawable (image, channel or layer).

PF_TOGGLE, PF_BOOL
A boolean value (anything perl would accept as true or
false). The description will be used for the toggle-but-
ton label!

PF_SLIDER
Uses a horizontal scale. To set the range and stepsize,
append an array ref (see Gtk::Adjustment for an explana-
tion) "[range_min, range_max, step_size, page_increment,
page_size]" as "extra argument" to the description
array. Default values will be substitued for missing
entries, like in:

[PF_SLIDER, "alpha value", "the alpha value", 100, [0, 255, 1] ]

PF_SPINNER
The same as PF_SLIDER, except that this one uses a spin-
button instead of a scale.

PF_RADIO
In addition to a default value, an extra argument
describing the various options must be provided. That
extra argument must be a reference to an array filled
with "Option-Name =" Option-Value> pairs. Gimp::Fu will
then generate a horizontal frame with radio buttons, one
for each alternative. For example:

[PF_RADIO, "direction", "the direction to move to", 5, [Left => 5, Right => 7]]]

draws two buttons, when the first (the default, "Left")
is activated, 5 will be returned. If the second is acti-
vated, 7 is returned.

PF_FONT
Lets the user select a font and returns a X Logical Font
Descriptor (XLFD). The default argument, if specified,
must be a full XLFD specification, or a warning will be
printed. Please note that the gimp text functions using
these fontnames (gimp_text_..._fontname) ignore the
size. You can extract the size and dimension by using
the "xlfd_size" function.

In older Gimp-Versions a user-supplied string is
returned.

PF_BRUSH, PF_PATTERN, PF_GRADIENT
Lets the user select a brush/pattern/gradient whose name
is returned as a string. The default brush/pattern/gra-
dient-name can be preset.

PF_CUSTOM
PF_CUSTOM is for those of you requiring some non-stan-
dard-widget. You have to supply a code reference return-
ing three values as the extra argument:

(widget, settor, gettor)

"widget" is Gtk widget that should be used.

"settor" is a function that takes a single argument, the
new value for the widget (the widget should be updated
accordingly).

"gettor" is a function that should return the current
value of the widget.

While the values can be of any type (as long as it fits
into a scalar), you should be prepared to get a string
when the script is started from the commandline or via
the PDB.

PF_FILE
This represents a file system object. It usually is a
file, but can be anything (directory, link). It might
not even exist at all.

PF_TEXT
Similar to PF_STRING, but the entry widget is much
larger and has Load and Save buttons.

EMBEDDED POD DOCUMENTATION

The register functions expects strings (actually scalars)
for documentation, and nobody wants to embed long parts of
documentation into a string, cluttering the whole script.

Therefore, Gimp::Fu utilizes the Gimp::Pod module to dis-
play the full text of the pod sections that are embedded
in your scripts (see perlpod for an explanation of the POD
documentation format) when the user hits the "Help" button
in the dialog box.

Since version 1.094, you can embed specific sections or
the full pod text into any of the blurb, help, author,
copyright and date arguments to the register functions.
Gimp::Fu will look into all these strings for sequences of
the form "=pod(section-name)". If found, they will be
replaced by the text of the corresponding section from the
pod documentation. If the named section is not found (or
is empty, as in "=pod()"), the full pod documentation is
embedded.

Most of the mentioned arguments have default values (see
THE REGISTER FUNCTION) that are used when the arguments
are either undefined or empty strings, making the register
call itself much shorter and, IMHO, more readable.

MISC. FUNCTIONS

"save_image(img,options_and_path)"
This is the internal function used to save images. As
it does more than just gimp_file_save, I thought it
would be handy in other circumstances as well.

The "img" is the image you want to save (which might
get changed during the operation!), "options_and_path"
denotes the filename and optinal options. If there are
no options, "save_image" tries to deduce the filetype
from the extension. The syntax for options is

[IMAGETYPE[OPTIONS...]:]filespec

IMAGETYPE is one of GIF, JPG, JPEG, PNM or PNG,
options include

options valid for all images
+F flatten the image (default depends on the image)
-F do not flatten the image

options for GIF and PNG images
+I do save as interlaced (GIF only)
-I do not save as interlaced (default)

options for GIF animations (use with -F)
+L save as looping animation
-L save as non-looping animation (default)
-Dn default frame delay (default is 0)
-Pn frame disposal method: 0=don't care, 1 = combine, 2 = replace

options for PNG images
-Cn use compression level n
-E Do not skip ancillary chunks (default)
+E Skip ancillary chunks

options for JPEG images
-Qn use quality "n" to save file (JPEG only)
-S do not smooth (default)
+S smooth before saving

some examples:

test.jpg save the image as a simple jpeg
JPG:test.jpg same
JPG-Q70:test.jpg the same but force a quality of 70
GIF-I-F:test.jpg save a gif image(!) named test.jpg
non-inerlaced and without flattening

AUTHOR
Marc Lehmann <pcg@goof.com>