Gimp::Fu - ``easy to use'' framework for Gimp scripts
use Gimp; use Gimp::Fu;
(this module uses Gtk, so make sure it's correctly installed)
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.weizmann.ac.il/~dov/gimp/perl-tut.html.
In general, a Gimp::Fu script looks like this:
#!/path/to/your/perl
use Gimp; use Gimp::Fu;
register <many arguments>, sub {
your code;
}
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)
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 };
perl_fu_-prefix.
blurb. Default is ``=pod(HELP)''.
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, description, 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.
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 implemented for PF_IMAGE at the moment.
[], if you want to specify it).
sub { your code here; }, or a
coderef, which is called when the script is run. Arguments (including the
image and drawable 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.
PF_VALUE is synonymous
to PF_STRING, and <PF_INT> is synonymous to <PF_INT32>.
[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] ]
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 activated, 7 is returned.
xlfd_size function.
In older Gimp-Versions a user-supplied string is returned.
(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.
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 display 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.
save_image(img,options_and_path)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
Marc Lehmann <pcg@goof.com>
perl(1), the Gimp manpage.