Fu(3) User Contributed Perl Documentation Fu(3)NAMEGimp::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. You can
find it at "http://imagic.weizmann.ac.il/~dov/gimp/perl-tut-2.0/".
INTRODUCTION
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)
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(NAME)"
(see the section on EMBEDDED POD DOCUMENTATION for an explanation of
this string).
help
A help text describing this script. Should be longer and more verbose
than "blurb". Default is "=pod(HELP)".
author
The name (and also the e-mail address if possible!) of the script-
author. Default is "=pod(AUTHOR)".
copyright
The copyright designation for this script. Important! Safe your
intellectual rights! The default is "=pod(AUTHOR)".
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(DATE)".
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), <Toolbox>/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, 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 can 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 implemented 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 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.
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 reason they exist is to
help other scripts (possibly written 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 preview 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-button label!
PF_SLIDER
Uses a horizontal scale. To set the range and stepsize, append an
array ref (see Gtk::Adjustment for an explanation) "[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 spinbutton 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 activated, 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/gradient-name can be preset.
PF_CUSTOM
PF_CUSTOM is for those of you requiring some non-standard-widget. You
have to supply a code reference returning 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, Save, and Edit (in external editor) 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 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.
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
-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 the 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-interlaced and without flattening
AUTHOR
Marc Lehmann <pcg@goof.com>
SEE ALSOperl(1), Gimp.
POD ERRORS
Hey! The above document had some coding errors, which are explained
below:
Around line 375:
=cut found outside a pod block. Skipping to next block.
Around line 780:
=cut found outside a pod block. Skipping to next block.
perl v5.18.1 2004-07-22 Fu(3)
