NAME

       gimp-perl is a plug-in used for writing GIMP extensions/plug-ins/load &
       save handlers in Perl.

WARNING

       This version of the module is for use with GIMP 2.8.0 or later.

       Current limitations:

       Please report all problems

SYNOPSIS

       my $img = new Image (600, 300, RGB);
       my $bg = $img->layer_new(600,300,RGB_IMAGE,"Background",100,NORMAL_MODE);
       $img->add_layer($bg, 1);
       $img->edit_fill($bg);
       $img->display_new;

       A complete & documented example script can be found at the end of
       this document (search for EXAMPLE).

DOCUMENTATION

       Online documentation is largely outdated.  Much of the documentation at
       http://www.goof.com/pcg/marc/gimp.html still applies.  The POD
       information embedded in the modules is the latest available, though
       it isn't very updated either.

PREREQUISITES

       To install/use this perl extension, you need to have the following
       software packages installed (the given order is best):

       Perl 5.6 (or higher):

          While this extension might run with perl 5.6, it is being developed
          using Perl 5.14, and later. If you encounter problems when trying to
          use a version of Perl older than 5.14, update to a newer version of
          Perl and try again. The developers of this module can neither support
          nor encourage the use of older versions of Perl.

       The GNU Image Manipulation Program, aka. GIMP
       http://www.gimp.org/
       ftp://ftp.gimp.org/pub/gimp/

          gimp-2.8 (or newer, e.g. git master) is required.  For
          older versions of GIMP, use version 1.2* of the gimp-perl
          module.

       Gtk, the perl extension for gtk+2
       http://gtk2-perl.sourceforge.net

          The "gtk2-perl-xs" variant is required, the "inline"
          version is *NOT* supported. Releases (as on CPAN) may work.

       PDL, the Perl Data Language
       http://www.cpan.org/

          Optionally, you can install the PDL module to be able to
          manipulate pixel data (or to be able to run the example plug-ins
          that do pixel manipulation). PDL is available at any CPAN
          mirror, version 2.4 or higher is recommended. Without PDL,
          some plug-ins do not work (they will not be installed),
	  and accessing raw image data is impossible.

INSTALLATION

       On Unix/Linux, you should be able to run "perl Makefile.PL", make, make
       test && make install. To get a listing of configuration options, enter:

       perl ./Makefile.PL --help

       Simply using "perl Makefile.PL" should do the job on most systems,
       but watch out for warnings. If everything went fine, enter "make",
       "make test, (su to appropriate level if you are installing system-wide),
       "make install".

       After installation, these perl plug-ins should be visible from
       within the Gimp (and many, many more):

       <Toolbox>/Xtns/Perl-Server
       <Image>/Filters/Artistic/Windify
       <Image>/Filters/Misc/Prepare for GIF
       <Image>/Filters/Misc/Webify

OVERWRITING INSTALL LOCATIONS (PREFIX)

       In the rare case that you want to install the gimp-perl modules
       somewhere else than in the standard location then there is a
       standard way to accomplish this.

       Usually, you can just use the PREFIX=/path option to the
       Makefile.PL, or the other common solution of adding the INST* path
       definitions onto the "make install" commandline.

       These options are described in the "perldoc ExtUtils::MakeMaker"
       manpage.

       If you are building a slp/deb/rpm/whatever package you usually want
       to use the normal prefix, while overwriting the prefix at "make
       install" time. In that case, just build gimp-perl (or the whole
       GIMP) as usual, but instead of just calling "make install", use
       something like the following command (this example is for debian):

          make prefix=`pwd`/debian/tmp/usr PREFIX=`pwd`/debian/tmp/usr \
               install

       The lowercase prefix is used by the Gimp, the uppercase PREFIX is
       used by perl.  Rarely you also want to specifiy manpage directories
       etc.. you can also overwrite these (see "man ExtUtils::MakeMaker")
       as well, e.g. for debian:

          make prefix=`pwd`/debian/tmp/usr PREFIX=`pwd`/debian/tmp/usr \
               INSTALLMAN1DIR=`pwd`/debian/tmp/usr/man/man1 \
               INSTALLMAN3DIR=`pwd`/debian/tmp/usr/man/man3 \
               install

SUPPORT/MAILING LISTS/MORE INFO

       The gimp-user and gimp-developer lists (see
       http://www.gimp.org/mail_lists.html) are currently the suggested
       mailing lists.

       New releases will be announced to gimp-announce.

       You can also upload your scripts to the gimp registry at
       http://registry.gimp.org/.

       If you think your script is of general intrest, please let
       <sjburges@gimp.org> know and it will be considered for
       inclusion in future Gimp module releases.  If you just want
       a link to your gimp-perl project, please mail <sjburges@gimp.org>
       also.

BLURB

       gimp-perl is an effort to make a usable, debuggable, and flexible
       interface to GIMP through use of Perl.

LICENSE

       The gimp-perl module is available under the GNU Public License
       (see COPYING.GPL for details) and the Artistic License (see
       COPYING.Artistic for details). Many of the scripts in the example
       section follow these rules, but some of them have a different
       licensing approach.  Each should have a licensing statement; please
       consult individual plugin sources/POD for more info.

       (c)1998,1999 Marc Lehmann <pcg@goof.com>
       (c)2003,2004 Seth Burgess <sjburges@gimp.org>

EXAMPLE PERL PLUG-IN

        To get even more look & feel, here is a complete plug-in source,
        it's the examples/example-fu script from the distribution.

#!/opt/bin/perl

use Gimp;
use Gimp::Fu;

register
  "gimp_fu_example_script",                      # fill in a function name
  "A non-working example of Gimp::Fu usage",     # and a short description,
  "Just a starting point to derive new ".        # a (possibly multiline) help text
  "scripts. Always remember to put a long".
  "help message here!",
  "Marc Lehmann <pcg\@goof.com>",                # don't forget your name (author)
  "(c)1998,1999,2000 Marc Lehmann",              # and your copyright!
  "20000321",                                    # the date this script was written (YYYYMMDD)
  N_"<Image>/File/Create/Gimp::Fu Example...",        # the menu path - the 'N_' is for internationalization
  "RGB*, GRAYA",                                 # image types to accept (RGB, RGAB amnd GRAYA)
  [ # one of each type of parameter here
    # argument type, switch name   , a short description           , default value, extra arguments
    [PF_SLIDER    , "width"       , "The image width"             , 360, [300, 500]],
    [PF_SPINNER   , "height"      , "The image height"            , 100, [100, 200]],
    [PF_STRING    , "text"        , "The message"                 , "example text"],
    [PF_INT32     , "bordersize"  , "The bordersize"              , 10],
    [PF_FLOAT     , "borderwidth" , "The borderwidth"             , 1/5],
    [PF_FONT      , "font"        , "The font family"             ],
    [PF_COLOUR    , "text_colour" , "The (foreground) text colour", [10,10,10]],
    [PF_COLOUR    , "bg_colour"   , "The background colour"       , [0xff,0x80,0]],
    [PF_TOGGLE    , "ignore_cols" , "Ignore colours"              , 0],
    [PF_IMAGE     , "extra_image" , "An additional picture to ignore"],
    [PF_DRAWABLE  , "extra_draw"  , "Something to ignore as well" ],
    [PF_RADIO     , "type"        , "The effect type"             , 0, [small => 0, large => 1]],
    [PF_BRUSH     , "a_brush"     , "An unused brush"             ],
    [PF_PATTERN   , "a_pattern"   , "An unused pattern"           ],
    [PF_GRADIENT  , "a_gradients" , "An unused gradients"         ],
  ],
  sub {
    # now do something useful with our parameters
    my($width,$height,$text,$brd1,$brd2,$font,$fg,$bg,$ignore,$xtraimg,
    $xtradrw,$effecttype,$brush,$pattern,$gradient)=@_;

    # set tracing, disable this to get rid of the debugging output
    Gimp::set_trace(TRACE_CALL);

    my $img = new Gimp::Image ($width, $height, RGB);

    # put an undo group around any modifications, so that
    # they can be undone in one step.
    $img->undo_group_start;

    # the __ before the string in the next line indicates text that must be translated
    my $l = new Gimp::Layer ($img, $width, $height, RGB, __"Background", 100, NORMAL_MODE);
    $l->add_layer(0);

    # now a few syntax examples

    Gimp::Context->set_foreground($fg) unless $ignore;
    Gimp::Context->set_background($bg) unless $ignore;

    fill $l BACKGROUND_FILL;
    $text_layer = $img->text_fontname(-1, 10, 10, $text, 5, 1, 10, PIXELS, $font);

    Gimp::Palette->set_foreground("green");

    # close the undo push group
    $img->undo_group_end;

    $img;        # return the image, or an empty list, i.e. ()
  };

exit main;  # call the "main" funciton to start the script working
