view release on metacpan or  search on metacpan

lib/Gimp/Fu.pm  view on Meta::CPAN

   }
   0;
}

1;
__END__

=head1 NAME

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

=head1 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...

=head1 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 C<http://www.gimp.org/tutorials/Basic_Perl/>.

This distribution comes with many example scripts. One is
C<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 C<Gimp::Fu> is the C<podregister> function.

=head1 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 L</"EMBEDDED POD DOCUMENTATION"> for an
explanation. You will also notice you don't need to provide the C<sub>
keyword, thanks to Perl's prototyping.

=head2 AUTOMATIC PERL PARAMETER INSERTION

Thanks to L<Filter::Simple> source filtering, this C<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 L</menupath> for the other possibilities for the variable
names you will be supplied with.

=head1 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 C<''>, 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<highly> recommended you use the L</PODREGISTER> interface,
unless you wish to have more than one interface (i.e. menu entry) to
your plugin, with different parameters.

=over 2

=item function_name

Defaults to the NAME section of the POD, the part B<before> the first

lib/Gimp/Fu.pm  view on Meta::CPAN

    $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 });
  },],

C<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:

=over 2

=item C<widget>

Gtk2 widget that should be used.

=item C<settor>

Function that takes a single argument, the new value for the widget
(the widget should be updated accordingly).

=item C<gettor>

Function returning the current value of the widget.

=back

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

=item 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.

=item PF_TEXT

Similar to PF_STRING, but the entry widget is much larger and has Load,
Save, and Edit (in external editor) buttons.

=back

=head1 EMBEDDED POD DOCUMENTATION

Gimp::Fu uses the Gimp::Pod module to access POD sections that are
embedded in your scripts (see L<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 C<register>.

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

=head1 MISCELLANEOUS FUNCTIONS

=over 2

=item C<save_image(img,options_and_path)>

This is the internal function used to save images, which does more than
C<gimp_file_save>.

The C<img> is the GIMP image you want to save (which might get changed
during the operation!), C<options_and_path> denotes the filename and
possibly options. If there are no options, C<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=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
 -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 C<.xcf>, which will save in XCF format.

=back