GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  GIMP::FU (3)

.ds Aq ’

NAME

Gimp::Fu - Easy framework for Gimp-Perl scripts

CONTENTS

SYNOPSIS



  use Gimp;
  use Gimp::Fu;
  podregister {
    # your code
  };
  exit main;
  __END__
  =head1 NAME

  function_name - Short description of the function

  =head1 SYNOPSIS

  <Image>/Filters/Menu/Location...

  =head1 DESCRIPTION

  Longer description of the function...



DESCRIPTION

This module provides all the infrastructure you need to write Gimp-Perl plugins. Dov Grobgeld has written an excellent tutorial for Gimp-Perl. You can find it at http://www.gimp.org/tutorials/Basic_Perl/.

This distribution comes with many example scripts. One is examples/example-fu.pl, which is a small Gimp::Fu-script you can take as a starting point for your experiments. You should be able to run it from GIMP already by looking at Filters/Languages/_Perl/Test/Dialog.

Your main interface for using Gimp::Fu is the podregister function.

PODREGISTER

This:



  podregister {
    # your code
  };



does the same as this:



  register , , , , , , , , , sub {
    # your code
  };



It extracts all the relevant values from your script’s POD documentation - see the section on EMBEDDED POD DOCUMENTATION for an explanation. You will also notice you don’t need to provide the sub keyword, thanks to Perl’s prototyping.

    AUTOMATIC PERL PARAMETER INSERTION

Thanks to Filter::Simple source filtering, this podregister-ed function:



  # the POD "PARAMETERS" section defines vars called "x" and "y"
  # the POD "SYNOPSIS" i.e. menupath starts with "<Image>"
  # the POD "IMAGE TYPES" says "*" - this means image and drawable params too
  podregister {
     # code...
  };



will also have the exact equivalent (because it’s literally this) of:



  podregister {
     my ($image, $drawable, $x, $y) = @_;
     # code...
  };



This means if you add or remove parameters in the POD, or change their order, your code will just continue to work - no more maintaining two copies of the parameter list. The above is the most common scenario, but see the menupath for the other possibilities for the variable names you will be supplied with.

THE REGISTER FUNCTION



  register
    "function_name",
    "blurb", "help",
    "author", "copyright",
    "date",
    "menupath",
    "imagetypes",
    [
      [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)
    ],
    sub { code };



All these parameters except the code-ref can be replaced with , in which case they will be substituted with appropriate values from various sections (see below) of the POD documentation in your script.

It is <B>highlyB> recommended you use the PODREGISTER interface, unless you wish to have more than one interface (i.e. menu entry) to your plugin, with different parameters.
function_name Defaults to the NAME section of the POD, the part <B>beforeB> the first -. Falls back to the script’s filename.

The PDB name of the function, i.e. the name under which it 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 Defaults to the NAME section of the POD, the part <B>afterB> the first -.

A one-sentence description of this script/plug-in.

help Defaults to the DESCRIPTION section of the POD.

A help text describing this script. Should give more information than blurb.

author Defaults to the AUTHOR section of the POD.

The name (and also the e-mail address if possible!) of the script-author.

copyright Defaults to the LICENSE section of the POD.

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

date Defaults to the DATE section of the POD.

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

menupath Defaults to the SYNOPSIS section of the POD.

The menu entry GIMP should create. <B>NoteB> this is different from Script-Fu, which asks only for which <B>menuB> in which to place the entry, using the second argument to (its equivalent of) register as the actual label; here, you spell out the <B>fullB> menu entry including label name.

It should start with one of the following:
<Image>/*/Plugin-menu-label If the plugin works on or produces an image.

If the imagetypes argument (see below) is defined and non-zero-length, Gimp::Fu will <B>supply parametersB>:
o PF_IMAGE called <B>imageB>
o PF_DRAWABLE called <B>drawableB>

as the first parameters to the plugin.

If the plugin is intending to create an image rather than to work on an existing one, make sure you supply undef or "" as the imagetypes. In that case, Gimp::Fu will supply a PF_IMAGE return value if the first return value is not a PF_IMAGE.

In any case, the plugin will be installed in the specified menu location; almost always under File/Create or Filters.

<Load>/Text describing input/file-extensions[/prefixes] The file-extensions are comma-separated. The prefixes are optional.

Gimp::Fu will automatically register the plugin as a load-handler using Gimp->register_load_handler.

Gimp::Fu will <B>supply parametersB>:
o PF_STRING called <B>filenameB>
o PF_STRING called <B>raw_filenameB>

as the first parameters to the plugin. It will also automatically add a return-value which is a PF_IMAGE, unless there is already such a value as first return value.

<Save>/Text describing output/file-extensions[/prefixes] The file-extensions are comma-separated. The prefixes are optional.

Gimp::Fu will automatically register the plugin as a save-handler using Gimp->register_save_handler. This is not (in GIMP 2.8 terms) a save-handler anymore, but an export-handler.

Gimp::Fu will <B>supply parametersB>:
o PF_IMAGE called <B>imageB>
o PF_DRAWABLE called <B>drawableB>
o PF_STRING called <B>filenameB>
o PF_STRING called <B>raw_filenameB>

as the first parameters to the plugin.

Outline:



  podregister {
    my $export = Gimp::UI::export_image(
      my $new_image=$image,
      my $new_drawable=$drawable,
      "COLORHTML",
      EXPORT_CAN_HANDLE_RGB
    );
    return if $export == EXPORT_CANCEL;
    # ...
    $new_image->delete if $export == EXPORT_EXPORT;
  };



<Toolbox>/Label This type of plugin will not have the image and drawable passed, nor will it require (or return) it. It will still have a run_mode added.
<None> If the script does not need to have a menu entry.

imagetypes Defaults to the IMAGE TYPES section of the POD.

The types of images your script will accept. Examples are RGB, RGB*, GRAY, RGB etc... Most scripts will want to use *, meaning any type. Either undef or " will mean none". Not providing the relevant POD section is perfectly valid, so long as you intend to create and return an image.

the parameter array Defaults to the PARAMETERS section of the POD, passed to eval, e.g.:



  =head PARAMETERS

    [ PF_COLOR, color, Colour, black ],
    [ PF_FONT, font, Font, Arial ],



You don’t <B>haveB> to indent it so that POD treats it as verbatim, but it will be more readable in the Help viewer if you do.

An array reference containing parameter definitions. These are similar to the parameter definitions used for gimp_install_procedure but include an additional <B>defaultB> 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) <B>if and only ifB> the image types are defined and non-zero-length. Do not specify these yourself - see the menupath entry above. Also, the run_mode argument is never given to the script but its value can be accessed in the package-global $Gimp::Fu::run_mode. The <B>descriptionB> will be used in the dialog box as a label.

See the section PARAMETER TYPES for the supported types.

The default values have an effect when called from a menu in GIMP, and when the script is called from the command line. However, they have a limited effect when called from Gimp::Net; data types that do not have an invalid value, like text does, may not be passed as an undefined value; this is because while Perl can use undef instead of anything, GIMP cannot. For instance, it is possible to pass a PF_STRING as undef, which will then be set to the supplied default value, but not a PF_COLOR.

the return values Defaults to the RETURN VALUES section of the POD, passed to eval. Not providing the relevant POD section is perfectly valid, so long as you intend to return no values.

This is just like the parameter array except that it describes the return values. Specify the type, variable name and description only. This argument is optional. If you wish your plugin to return an image, you must specify that (unless your image types is false, see below), e.g.:



  use Gimp;
  use Gimp::Fu;
  register
     function_name, "help", "blurb", "author", "copyright", "2014-04-11",
     "<Image>/Filters/Render/Do Something...",
     "*",
     [ [PF_INT32, "imagesize", "Image size", 1] ],
     [ [PF_IMAGE, "output image", "Output image"] ],
     sub { Gimp::Image->new($_[0], $_[0], RGB) };



If your image types is false, then Gimp::Fu will ensure your first return parameter is a PF_IMAGE. If for some reason you need to return an image value that will satisfy the requirement to return the right number of values but is invalid, you can return either -1 or undef.

You <B>mustB> return the correct number (and types) of values from your function.

the code This is either an 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.

You <B>mustB> make sure your plugin returns the correct types of value, or none:



 sub {
   # no return parameters were specified
   ();
 };



If you want to display images, you must have your script do that. Gimp::Fu will no longer automatically do that for you, so your plugins will thereby be good GIMP citizens, able to fit in with plugins/filters written in other languages.

PARAMETER TYPES

PF_INT8, PF_INT16, PF_INT32 All mapped to sliders or spinners with suitable min/max.
PF_FLOAT, PF_VALUE For PF_FLOAT (or PF_VALUE, a synonym), you should probably use a PF_SPINNER or PF_SLIDER with suitable values.
PF_STRING A string.
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. The default value needs to be a suitable Gimp-Perl colour; see Gimp::canonicalize_colour in Gimp.



 [ PF_COLOR, colour, Input colour, white ],
 [ PF_COLOR, colour2, Input colour 2, [ 255, 128, 0 ] ],



PF_IMAGE A GIMP image.
PF_DRAWABLE A GIMP drawable (channel or layer).
PF_TOGGLE, PF_BOOL A boolean value (anything Perl would accept as true or false).
PF_SLIDER Uses a horizontal scale. To set the range and stepsize, append an array ref (see Gtk2::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 substituted 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", "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 whose name is returned as a string.
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 Example:



  [PF_CUSTOM, "direction", "Direction to fade(0-8)", 4, sub {
    my $btnTable = new Gtk2::Table(3,3,1);
    $btnTable->set_border_width(6);
    my $btn = new Gtk2::RadioButton;
    my ($u_direction, @buttons);
    for (my $x=0;$x<3;$x++) {
      for (my $y=0;$y<3;$y++) {
        my $dir = $x*3 + $y;
        $buttons[$dir] = $btn = Gtk2::RadioButton->new_from_widget($btn);
        $btn->set_mode(0);
        $btn->signal_connect("clicked", sub { $u_direction = $_[1]; }, $dir);
        $btn->show;
        $btnTable->attach_defaults($btn, $x, $x+1, $y, $y+1);
        my $pixmap = Gtk2::Image->new_from_pixmap(
          Gtk2::Gdk::Pixmap->colormap_create_from_xpm_d(
            undef, $btn->get_colormap,
            $btn->style->bg(normal), @{$arr[$dir]}
          )
        );
        $pixmap->show;
        $btn->add($pixmap);
      }
    }
    $btnTable->show;
    ($btnTable, sub { $buttons[$_[0]]->clicked }, sub { $u_direction });
  },],



PF_CUSTOM is for those of you requiring some non-standard-widget. You supply a reference to code returning three values as the extra argument:
widget Gtk2 widget that should be used.
settor Function that takes a single argument, the new value for the widget (the widget should be updated accordingly).
gettor Function returning the current value of the widget.

The value set and returned must be a string. For an example of this, see examples/example-no-fu.

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

Gimp::Fu uses the Gimp::Pod module to access 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. More importantly, various sections of the POD can be used instead of hardcoding strings in the call to register.

Most of the mentioned arguments have default values (see THE REGISTER FUNCTION) that are used when the arguments are undefined or false, making the register call itself much shorter.

MISCELLANEOUS FUNCTIONS

save_image(img,options_and_path) This is the internal function used to save images, which does more than gimp_file_save.

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



 [OPTIONS...:]filespec

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

 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=dont 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
 -Q70:test.jpg  the same but force a quality of 70
 -I-F:test.gif  save a GIF image, non-interlaced and without flattening



You can specify a file with extension .xcf, which will save in XCF format.

COMMAND LINE USAGE

Your scripts can immediately be used from the command line. E.g.



  /usr/local/lib/gimp/2.0/plug-ins/example-fu -i



Use the --help flag to see the available options:



  Usage: .../example-fu [gimp-args..] [interface-args..] [script-args..]
         gimp-arguments are
             -h | -help | --help | -?   print some help
             -v | --verbose             be more verbose in what you do
             --host|--tcp HOST[:PORT]   connect to HOST (optionally using PORT)
                                        (for more info, see Gimp::Net(3))
         interface-arguments are
             -o | --output <filespec>   write image to disk
             -i | --interact            let the user edit the values first
         script-arguments are
             --width number             Image width [360]
             --height integer           Image height [100]
             --text string              Message [example text]
             --longtext string          Longer text [more example text]
             --bordersize integer (32-bit) Border size [10]
             --borderwidth number       Border width [0.2]
             --font font                Font
             --text_colour colour       Text colour [[10 10 10]]
             --bg_colour colour         Background colour [[255 128 0]]
             --ignore_cols boolean      Ignore colours [0]
             --extra_image image        Additional picture to ignore
             --extra_draw drawable (%[filename:]number or %a = active) Something to ignore as well
             --type data                Effect type [0]
             --a_brush brush            An unused brush
             --a_pattern pattern        An unused pattern
             --a_gradients gradient     An unused gradients



You may notice that the drawable above offers the option of %[filename:]number (or %a) - this means you can specify which drawable by numeric ID, or if specified as %filename:number, Gimp::Fu will open that file and set the parameter to the numberth layer (starting from zero). From the command line, image may be specified either as %number or as a filename.

If interactive mode is chosen (either by specifying the command-line flag, or not giving all the arguments), and no output file is given, Gimp::Fu will add a parameter to get an output file.

If the --output option is given, the argument will be passed to save_image. This means you can specify various options on how you want the image to be saved/converted, as part of the filename.

AUTHOR

Marc Lehmann <pcg@goof.com>

SEE ALSO

perl(1), Gimp.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 FU (3) 2014-06-30

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.