:consts

:param

net_init=options

Possible options include "spawn/gui" or "unix/path/to/socket". See "ENVIRONMENT" in Gimp::Net for other possibilities. If this is not specified, "Gimp" will try various options, falling back to "spawn" which starts a new GIMP instance.

It is important that "Gimp" be able to connect to an instance of GIMP one way or another: otherwise, it will not be able to load the various constants on which modules rely. The connection is made when "Gimp::import" is called, after "Gimp" has been compiled - so don't put "use Gimp ();"

spawn_options=options

:DEFAULT

''

:auto (DEPRECATED)

 use Gimp qw(:auto);
 Gimp->displays_flush; # fine
 my $name = $layer->get_name; # also fine
 gimp_quit(0); # will lose its parameter, due to Perl's OO implementation!
 Gimp->quit(0); # works correctly
 gimp_image_undo_disable($image); # as does this, by a coincidence

This tag is deprecated, and you will be far better off using Gimp-Perl solely in OO mode.

:pollute (DEPRECATED)

Plugin

The perl script is written as a plug-in, probably using "Gimp::Fu". GIMP, on start-up, runs all the plug-ins in its plugins directory at startup (including all the perl scripts) in "query" mode.

Any plugin will register itself as a GIMP "procedure" in the PDB, during its run in "query" mode.

When such a procedure is called, either from the menu system or a scripting interface, the plugin will be run in "run" mode, and GIMP will supply it with the appropriate arguments.

From outside GIMP

The architecture may be visualised like this:

 perlscript <-> Gimp::Net <-> Perl-Server <-> Gimp::Lib <-> GIMP

This has certain consequences; native GIMP objects like images and layers obviously persist between Perl method calls, but "libgimp" entities such as "GimpDrawable", with the perl interface Gimp::PixelRgn, require special handling. Currently they do not work when used over "Gimp::Net".

CALLBACKS

The additional "on_proc" is how to supply code that will be run every time a GIMP PDB call is made. This is mainly useful for updating the progress bar on a plugin.

Gimp::on_query

Do any activities that must be performed at GIMP startup, when the plugin is queried. Should typically have at least one call to "Gimp->install_procedure".

Gimp::on_net

Run when the plugin is executed from the command line, either in "net mode" via the Perl-Server, or "batch mode".

Gimp::on_lib

Run only when called from within GIMP, i.e. in "plugin mode".

Gimp::on_run

Run when anything calls it (network or lib).

Gimp::on_quit

Run when plugin terminates - allows a plugin (or extension, see below) to clean up after itself before it actually exits.

Gimp::on_proc

Run each time a PDB call is made. Currently only operates in "lib mode".

AVAILABLE CLASSES

  Gimp::Base # purely virtual
    +-Gimp::Color
    +-Gimp::Image
    +-Gimp::Selection
    +-Gimp::Display
    +-Gimp::Parasite
    +-Gimp::Item
        +-Gimp::Vectors
        +-Gimp::Drawable
          +-Gimp::Layer
          +-Gimp::Channel

Classes for which non-PDB objects are created (see Gimp::PixelRgn):

  Gimp::GimpDrawable
  Gimp::PixelRgn
  Gimp::Tile

Classes for which objects are not created:

  Gimp
  Gimp::Brush
  Gimp::Brushes
  Gimp::Context
  Gimp::Edit
  Gimp::Gradient
  Gimp::Gradients
  Gimp::Palette
  Gimp::Pattern
  Gimp::Patterns
  Gimp::Plugin
  Gimp::Progress

Gimp::Base

Methods:

$object->become($class)

Allows an object of one class to change its class to another, but with the same ID. If a method call of "is_valid" returns false, an exception will be thrown. It is intended for use in plugins, e.g. where GIMP passes a "Gimp::Drawable", but you need a "Gimp::Layer":

  my ($image, $drawable, $color) = @_;
  $drawable->become('Gimp::Layer'); # now can call layer methods on it

Returns $object.

$class->existing($id)

Allows you to instantiate a Gimp-Perl object with the given $class and $id. The same check as above is done, throwing an exception if failed.

$object->id

Returns the underlying GIMP identifier, an integer.

$object->is_valid

Returns true if the object is a valid object of the relevant class. Subclasses use appropriate GIMP functions: e.g. Gimp::Layer uses "gimp_item_is_layer".

stringify

It also provides a "stringify" overload method, so debugging output can be more readable.

Gimp::Parasite

Self-explanatory methods:

$parasite = Gimp::Parasite->new($name, $flags, $data)

$name and $data are perl strings, "flags" is the numerical flag value.

$parasite->name

$parasite->flags

$parasite->data

$parasite->has_flag($flag)

$parasite->is_type($type)

$parasite->is_persistent

$parasite->is_error

$different_parasite = $parasite->copy

$parasite->compare($other_parasite)

SPECIAL METHODS

Gimp->install_procedure

Takes as parameters "(name, blurb, help, author, copyright, date, menu_path, image_types, type, params[, return_vals])".

Mostly the same as gimp_install_procedure from the C library. The parameters and return values for the functions are each specified as an array ref containing array-refs with three elements, "[PARAM_TYPE, "NAME", "DESCRIPTION"]", e.g.:

  Gimp::on_query {
     Gimp->install_procedure(
        $Gimp::Net::PERLSERVERPROC, "Gimp-Perl scripts net server",
        "Allow scripting GIMP with Perl providing Gimp::Net server",
        "Marc Lehmann <pcg\@goof.com>", "Marc Lehmann", "1999-12-02",
        N_"<Image>/Filters/Languages/_Perl/_Server", undef,
        $Gimp::Net::PERLSERVERTYPE,
        [
         [&Gimp::PDB_INT32, "run_mode", "Interactive, [non-interactive]"],
         [&Gimp::PDB_INT32, "flags", "internal flags (must be 0)"],
         [&Gimp::PDB_INT32, "extra", "multi-purpose"],
         [&Gimp::PDB_INT32, "verbose", "Gimp verbose var"],
        ],
        [],
     );
  };

Gimp::Progress->init(message,[display])

Gimp::Progress->update(percentage)

Initializes or updates a progress bar. In networked modules these are a no-op.

Gimp::Image->list

$image->get_layers

$image->get_channels

These functions return what you would expect: an array of images, layers or channels. The reason why this is documented is that the usual way to return "PDB_INT32ARRAY"s would be to return a reference to an array of integers, rather than blessed objects:

  perl -MGimp -e '@x = Gimp::Image->list; print "@x\n"'
  # returns: Gimp::Image->existing(7) Gimp::Image->existing(6)

$drawable->bounds, $gdrawable->bounds

Returns an array (x,y,w,h) containing the upper left corner and the size of currently selected parts of the drawable, just as needed by "Gimp::PixelRgn->new" and similar functions. Exist for objects of both "Gimp::Drawable" and "Gimp::GimpDrawable".

NORMAL METHODS

 $image = Gimp->image_new(...); # calls gimp_image_new(...)
 $image = Gimp::Image->new(...); # calls gimp_image_new as well
 $image = new Gimp::Image(...); # the same in green
 Gimp::Palette->set_foreground(...); # calls gimp_palette_set_foreground(..)
 $image->histogram(...); # calls gimp_histogram($image,...), since
                         # gimp_image_histogram does not exist

Return values from functions are automatically blessed to their corresponding classes, e.g.:

 $image = new Gimp::Image(...); # $image is now blessed to Gimp::Image
 $image->height;                # calls gimp_image_height($image)
 $image->flatten;               # likewise gimp_flatten($image)

The object argument ($image in the above examples) is prepended to the argument list - this is how Perl does OO.

Another shortcut: many functions want a (redundant) image argument, like

 $image->shear ($layer, ...)

Since all you want is to shear the $layer, not the $image, this is confusing as well. In cases like this, Gimp-Perl allows you to write:

 $layer->shear (...)

And automatically infers the additional IMAGE-type argument.

Because method call lookup also search the "plug_in_", "perl_fu_" and "script_fu_" namespaces, any plugin can automatically become a method for an image or drawable (see below).

As the (currently) last goodie, if the first argument is of type INT32, its name is "run_mode" and there are no other ambiguities, you can omit it, i.e. these five calls are equivalent:

 plug_in_gauss_rle(RUN_NONINTERACTIVE, $image, $layer, 8, 1, 1);
 plug_in_gauss_rle($image, $layer, 8, 1, 1);
 plug_in_gauss_rle($layer, 8, 1, 1);
 $layer->plug_in_gauss_rle(8, 1, 1);
 $layer->gauss_rle(8, 1, 1);

You can call all sorts of sensible and not-so-sensible functions, so this feature can be abused:

 patterns_list Gimp::Image;     # will call gimp_patterns_list
 quit Gimp::Plugin;             # will quit the Gimp, not an Plugin.

there is no image involved here whatsoever...

The 'gimpdoc' script will also return OO variants when functions are described. For example:

  gimpdoc image_new

has a section:

  SOME SYNTAX ALTERNATIVES
       $image = Gimp->image_new (width,height,type)
       $image = new Gimp::Image (width,height,type)
       $image = image_new Gimp::Display (width,height,type)

Gimp::main()

Gimp::gtk_init()

Gimp::set_rgb_db(filespec)

Gimp::initialized()

Gimp::register_callback(gimp_function_name, perl_function)

The first argument is the name of a registered gimp function that you want to overwrite ('perl_fu_make_something'), and the second argument can be either a name of the corresponding perl sub ('Elsewhere::make_something') or a code reference ("\&my_make").

Gimp::canonicalize_colour

For example:

 $color = canonicalize_colour ("#ff00bb"); # html format
 $color = canonicalize_colour ([255,255,34]); # RGB
 $color = canonicalize_colour ([255,255,34,255]); # RGBA
 $color = canonicalize_colour ([1.0,1.0,0.32]); # actual GimpRGB
 $color = canonicalize_colour ('red'); # uses the color database

Note that bounds checking is somewhat lax; this assumes relatively good input.

gimp_tile_*, gimp_pixel_rgn_*, gimp_drawable_get

server_eval(string)