++ed by:
ILUX DELON ZMUGHAL EMAZEP

4 PAUSE users
2 non-PAUSE users.

Marc A. Lehmann

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.weizmann.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;
   
   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)

Attention: at the moment it's neccessary to always import the Gimp::Fu module after the Gimp module.

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_", "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.

help

A help text describing this script. Should be longer and more verbose than blurb.

The copyright designation for this script. Important! Safe your intellectual rights!

date

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

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, 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.

the return values

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

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.

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 PNG images
 -Cn    use compression level n

 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>

SEE ALSO

perl(1), Gimp.

3 POD Errors

The following errors were encountered while parsing the POD:

Around line 10:

=cut found outside a pod block. Skipping to next block.

Around line 687:

=cut found outside a pod block. Skipping to next block.

Around line 1008:

=cut found outside a pod block. Skipping to next block.