[gimp-web/testing] Updated to GP 2.3.
- From: Ed J <edj src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gimp-web/testing] Updated to GP 2.3.
- Date: Fri, 2 May 2014 07:35:02 +0000 (UTC)
commit fe41b25714564ecafdeaef190bbc8cc506acb041
Author: Ed J <edj src gnome org>
Date: Fri May 2 08:34:29 2014 +0100
Updated to GP 2.3.
tutorials/Basic_Perl/basic | 33 +
tutorials/Basic_Perl/basic-logo | 63 +
tutorials/Basic_Perl/basic-logo-dialog.png | Bin 7933 -> 17386 bytes
tutorials/Basic_Perl/basic-logo.png | Bin 9375 -> 6880 bytes
tutorials/Basic_Perl/circles | 60 +
tutorials/Basic_Perl/circles.png | Bin 10062 -> 12168 bytes
tutorials/Basic_Perl/hello-world1 | 52 +
tutorials/Basic_Perl/hello-world1.png | Bin 7830 -> 12702 bytes
tutorials/Basic_Perl/horiz-cat | 61 +
tutorials/Basic_Perl/index.htrw | 1834 +++++++++++++++------------
tutorials/Basic_Perl/interact | 7 +
tutorials/Basic_Perl/paint-select | 55 +
tutorials/Basic_Perl/paint-select.png | Bin 4587 -> 7542 bytes
tutorials/Basic_Perl/perl-gimp-from-shell | 2 +
tutorials/Basic_Perl/pg-shell | 17 +
tutorials/Basic_Perl/tpix.gif | Bin 0 -> 825 bytes
tutorials/Basic_Perl/uni | 49 +
tutorials/Basic_Perl/uni-entry.png | Bin 7290 -> 9748 bytes
tutorials/Basic_Perl/uni-menu.png | Bin 13380 -> 55891 bytes
tutorials/Basic_Perl/uni-result.png | Bin 2991 -> 9001 bytes
20 files changed, 1418 insertions(+), 815 deletions(-)
---
diff --git a/tutorials/Basic_Perl/basic b/tutorials/Basic_Perl/basic
new file mode 100755
index 0000000..bf70bbe
--- /dev/null
+++ b/tutorials/Basic_Perl/basic
@@ -0,0 +1,33 @@
+#!/usr/bin/perl -w
+
+use Gimp;
+use Gimp::Fu;
+
+podregister { die "I DIED\n" };
+
+exit main;
+__END__
+
+=head1 NAME
+
+test_exception - exercise gimp-perl filter testing exceptions
+
+=head1 SYNOPSIS
+
+<Image>/Filters/Languages/_Perl/_Test/Exception
+
+=head1 DESCRIPTION
+
+Exercise Gimp-Perl exceptions.
+
+=head1 AUTHOR
+
+The Author.
+
+=head1 DATE
+
+20140310
+
+=head1 LICENSE
+
+The licensing terms.
diff --git a/tutorials/Basic_Perl/basic-logo b/tutorials/Basic_Perl/basic-logo
new file mode 100755
index 0000000..ed025c8
--- /dev/null
+++ b/tutorials/Basic_Perl/basic-logo
@@ -0,0 +1,63 @@
+#!/usr/bin/perl
+
+use Gimp;
+use Gimp::Fu;
+
+podregister {
+ my $img = Gimp::Image->new(100, 100, RGB); # any old size
+ my $background = $img->layer_new(
+ 100, 100, RGB, "Background", 100, NORMAL_MODE
+ );
+ $img->insert_layer($background, 0, 0);
+ Gimp::Context->set_foreground($fgcolor); # Choose color of text
+ # Create the text layer. Using -1 as the drawable creates a new layer.
+ my $text_layer = $img->text_fontname(
+ -1, 0, 0, $text, $border, 1, $size, POINTS, $font
+ );
+ # Get size of the text drawable and resize the image and the
+ # background layer to this size.
+ my ($width, $height) = ($text_layer->width, $text_layer->height);
+ $img->resize($width, $height, 0, 0);
+ $background->resize($width, $height, 0, 0);
+ # Fill the background layer now when it has the right size.
+ Gimp::Context->set_background($bgcolor);
+ $background->edit_fill(BACKGROUND_FILL);
+ Gimp::Display->new($img);
+ return $img;
+};
+
+exit main;
+__END__
+
+=head1 NAME
+
+basic_logo - Basic logo
+
+=head1 SYNOPSIS
+
+<Image>/File/Create/Tutorial/Basic Logo
+
+=head1 DESCRIPTION
+
+Make a basic logo.
+
+=head1 PARAMETERS
+
+ [PF_FONT, "font", "Font", "Utopia Bold"],
+ [PF_INT32, "size", "Font size", 10],
+ [PF_INT32, "border", "Border", 10],
+ [PF_STRING, "text", "Text", "Hello world!"],
+ [PF_COLOR, "bgcolor", "Background color", [40,180,160]],
+ [PF_COLOR, "fgcolor", "Foreground color", [255,255,0]],
+
+=head1 AUTHOR
+
+Dov Grobgeld
+
+=head1 DATE
+
+2004-03-27
+
+=head1 LICENSE
+
+Dov Grobgeld
diff --git a/tutorials/Basic_Perl/basic-logo-dialog.png b/tutorials/Basic_Perl/basic-logo-dialog.png
index cfa9b5c..ff344be 100644
Binary files a/tutorials/Basic_Perl/basic-logo-dialog.png and b/tutorials/Basic_Perl/basic-logo-dialog.png
differ
diff --git a/tutorials/Basic_Perl/basic-logo.png b/tutorials/Basic_Perl/basic-logo.png
index 46db90f..4069117 100644
Binary files a/tutorials/Basic_Perl/basic-logo.png and b/tutorials/Basic_Perl/basic-logo.png differ
diff --git a/tutorials/Basic_Perl/circles b/tutorials/Basic_Perl/circles
new file mode 100755
index 0000000..032721b
--- /dev/null
+++ b/tutorials/Basic_Perl/circles
@@ -0,0 +1,60 @@
+#!/usr/bin/perl
+
+use Gimp;
+use Gimp::Fu;
+
+podregister {
+ # Create the background
+ my $img = Gimp::Image->new($size, $size, RGB);
+ $layer = $img->layer_new($size, $size, RGB, "Layer 1", 100, NORMAL_MODE);
+ $img->insert_layer($layer, -1, 0);
+ Gimp::Context->set_background($bgcolor);
+ $layer->edit_fill(BACKGROUND_FILL);
+ my $ncircles = int($size/$radius/2);
+ for ($i=0; $i<$ncircles; $i++) {
+ for ($j=0; $j<$ncircles; $j++) {
+ # Select a circle
+ $img->select_ellipse(
+ CHANNEL_OP_REPLACE, $i*$radius*2, $j*$radius*2, $radius*2, $radius*2
+ );
+ my $color = [$i*30, ($ncircles-$j)*25, ($i+$j)*15]; # mix colors
+ Gimp::Context->set_background($color);
+ $layer->edit_fill(BACKGROUND_FILL);
+ }
+ }
+ Gimp::Display->new($img);
+ return $img;
+};
+
+exit main;
+__END__
+
+=head1 NAME
+
+circles - a loop
+
+=head1 SYNOPSIS
+
+<Image>/File/Create/Tutorial/Circles
+
+=head1 DESCRIPTION
+
+a loop
+
+=head1 PARAMETERS
+
+ [PF_INT32, "size", "Image size", 100],
+ [PF_COLOR, "bgcolor", "Background color", [40,180,60]],
+ [PF_INT32, "radius", "Circle radius", 10]
+
+=head1 AUTHOR
+
+Dov
+
+=head1 DATE
+
+1999-05-14
+
+=head1 LICENSE
+
+Dov
diff --git a/tutorials/Basic_Perl/circles.png b/tutorials/Basic_Perl/circles.png
index 4b0d656..bc087fb 100644
Binary files a/tutorials/Basic_Perl/circles.png and b/tutorials/Basic_Perl/circles.png differ
diff --git a/tutorials/Basic_Perl/hello-world1 b/tutorials/Basic_Perl/hello-world1
new file mode 100755
index 0000000..51f0662
--- /dev/null
+++ b/tutorials/Basic_Perl/hello-world1
@@ -0,0 +1,52 @@
+#!/usr/bin/perl
+
+use Gimp;
+use Gimp::Fu;
+
+podregister {
+ my $img = Gimp::Image->new(350, 100, RGB);
+ my $drw = $img->layer_new($img->width, $img->height,
+ RGB, "BG", 100, NORMAL_MODE);
+ $img->insert_layer($drw, -1, 0);
+ Gimp::Context->set_background("black");
+ $drw->edit_fill(BACKGROUND_FILL);
+ Gimp::Context->set_foreground([255,255,0]); # Choose color of text
+ # Create the text
+ my $textlayer = $drw->text_fontname(0, 0, $text, 10, 1, $size, POINTS, $font);
+ $textlayer->floating_sel_anchor;
+ Gimp::Display->new($img);
+ return $img;
+};
+
+exit main;
+__END__
+
+=head1 NAME
+
+hello_world1 - basic text
+
+=head1 SYNOPSIS
+
+<Image>/File/Create/Tutorial/Basic text 1
+
+=head1 DESCRIPTION
+
+basic text
+
+=head1 PARAMETERS
+
+ [PF_FONT, "font", "Font", "Sans"],
+ [PF_INT32, "size", "Font size", 70],
+ [PF_STRING, "text", "Text", "Hello world!"]
+
+=head1 AUTHOR
+
+Dov
+
+=head1 DATE
+
+2004-03-27
+
+=head1 LICENSE
+
+Dov
diff --git a/tutorials/Basic_Perl/hello-world1.png b/tutorials/Basic_Perl/hello-world1.png
index ef3563c..5aa37d8 100644
Binary files a/tutorials/Basic_Perl/hello-world1.png and b/tutorials/Basic_Perl/hello-world1.png differ
diff --git a/tutorials/Basic_Perl/horiz-cat b/tutorials/Basic_Perl/horiz-cat
new file mode 100755
index 0000000..5645dc9
--- /dev/null
+++ b/tutorials/Basic_Perl/horiz-cat
@@ -0,0 +1,61 @@
+#!/usr/bin/perl
+
+use Gimp;
+use Gimp::Fu;
+
+podregister {
+ die "Must select layer.\n" unless $drawable->is_layer;
+ $drawable->become('Gimp::Layer');
+ my $image2 = $drawable2->get_image;
+ my ($w1, $h1) = ($drawable->width, $drawable->height);
+ my ($w2, $h2) = ($drawable2->width, $drawable2->height);
+ my $hmax = $h1 > $h2 ? $h1 : $h2; # new height is maximum height of the images
+ $image->undo_group_start; # Create an undo group
+ # Resize the drawable layer to make room for the image
+ $image->resize($w1+$w2, $hmax, 0, ($hmax-$h1)/2);
+ $drawable->resize($w1+$w2, $hmax, 0, ($hmax-$h1)/2);
+ # Copy $drawable2 and paste it into the new space of $drawable1
+ $image2->selection_all; # select all of image2
+ $drawable2->edit_copy;
+ $image2->selection_none;
+ # make a selection in image 1 where $drawable2 is to be pasted
+ $image->select_rectangle(CHANNEL_OP_ADD, $w1, ($hmax-$h2)/2, $w2, $h2);
+ $drawable->edit_paste(0)->floating_sel_anchor; # paste and then anchor it
+ $image->undo_group_end; # Close the undo group
+ return;
+};
+
+exit main;
+__END__
+
+=head1 NAME
+
+horiz_cat - Horizontal concat
+
+=head1 SYNOPSIS
+
+<Image>/Filters/Tutorial/Horizontal Concat
+
+=head1 DESCRIPTION
+
+Horizontal concatenation of images.
+
+=head1 PARAMETERS
+
+ [PF_DRAWABLE, "drawable2", "Drawable to concatenate", undef],
+
+=head1 IMAGE TYPES
+
+*
+
+=head1 AUTHOR
+
+Dov Grobgeld
+
+=head1 DATE
+
+2004-03-27
+
+=head1 LICENSE
+
+Dov Grobgeld
diff --git a/tutorials/Basic_Perl/index.htrw b/tutorials/Basic_Perl/index.htrw
index 2e589c3..4ee7ad9 100644
--- a/tutorials/Basic_Perl/index.htrw
+++ b/tutorials/Basic_Perl/index.htrw
@@ -2,858 +2,1062 @@
<title>GIMP - Basic Perl</title>
<!--#include virtual="/includes/wgo-look-feel.xhtml" -->
<!--#include virtual="/includes/wgo-page-init.xhtml" -->
-<h1>Basic Perl</h1>
-<p>
- Text and images Copyright (C) 1999-2002 <a href="mail:People-Grobgeld_Dov">Dov Grobgeld</a> and may not be
used without permission of the author.
-</p>
+<div class="box">
+<h1 align=center>A Tutorial for Gimp-Perl Users<br>
+ Updated for Gimp 2.8 / Gimp-Perl 2.3<br>
+ <font size=-1>© Ed J</font><br>
+ <font size=-1>Last modified: 2014-05-02</font><br>
+</h1>
-<p><em>Editor's note: this tutorial was originally written for GIMP
-1.2. Parts of it will not work with GIMP 2.x and later versions due
-to changes in font handling and PDB API.</em></p>
+<h2>Table of contents</h2>
+<ul>
+<li> <a href="#SEC1">1. Version notes</a></li>
+<li> <a href="#SEC2">2. Background</a></li>
+<li> <a href="#SEC3">3. What you need</a></li>
+<li> <a href="#SEC4">4. The Gimp module</a></li>
+<li> <a href="#SEC5">5. The GIMP PDB</a></li>
+<li> <a href="#SEC5.1">5.1. Gimp::Fu and the podregister function</a></li>
+<li> <a href="#SEC5.2">5.2. A commented script</a></li>
+<li> <a href="#SEC6">6. Object oriented syntax</a></li>
+<li> <a href="#SEC7">7. Painting areas with selections</a></li>
+<li> <a href="#SEC7.1">7.1. Complex selections</a></li>
+<li> <a href="#SEC7.2">7.2. Loops</a></li>
+<li> <a href="#SEC8">8. Creating text</a></li>
+<li> <a href="#SEC8.1">8.1. Hello World - writing text in an image</a></li>
+<li> <a href="#SEC9">9. Floating selections</a></li>
+<li> <a href="#SEC10">10. The Perl Server and stand-alone scripts</a></li>
+<li> <a href="#SEC10.1">10.1. A shell for Gimp-Perl</a></li>
+<li> <a href="#SEC11">11. End notes</a></li>
+<li> <a href="#SEC12">12. Links and references</a></li>
+</ul>
-<h2>Intention</h2>
-<p>
- So far most of the script programming for GIMP has been done using Scheme through Script-Fu.
- Unfortunately the Scheme environment GIMP provides is very primitive, e.g. without any reasonable error
handling.
- Furthermore, must users are not familiar with Scheme as a language. Some users may therefore prefer to
write scripts for the GIMP in Perl.
-</p>
-<p>
- Perl as a language is probably more familiar to web-literate users as it is the major language for writing
CGI scripts.
- Now, GIMP scripts may also be written with Perl. This tutorial will describe how to write such plug-ins
and scripts for GIMP.
-</p>
-<p>
- As there are several excellent tutorial texts describing the Perl language, this tutorial will assume a
working knowledge of Perl,
- and will instead concentrate on the use of GIMP together with the use of the Perl modules Gimp and
Gimp::Fu,
- written by Marc Lehmann <a href="mail:People-Lehmann_Marc">pcg goof com</a>.
-</p>
+<h2><a name="SEC1">1. Version notes</a></h2>
+This work is a slightly modified version of Dov Grobgeld's excellent
+tutorial. It has been updated to Gimp-Perl 2.3.
<p>
- <b>NOTE:</b> This tutorial was originally written for a 1.2 version of GIMP. It was proofread and some
updates were applied as of March 22, 2007.
- However, the sample scripts which are shown on this page have not been re-tested to verify that they will
work with the current 2.2 version of GIMP.
-</p>
-<h2>1. What You Need</h2>
-<p>
- The Perl::Gimp tutorial scripts have been tested with the following versions:
-</p>
-<ol>
- <li>GIMP version 1.2 or later, with all its prerequisites.</li>
- <li>Perl version 5.005 or later.</li>
- <li>The Perl module Gtk, version 0.7003</li>
- <li>The Gimp module, version 1.201 or later</li>
-</ol>
-<p>
- Perl and all its associated modules are available in source form from the Perl Comprehensive Archive
Network, CPAN.
-</p>
+<h2><a name="SEC2">2. Background</a></h2>
-<h2>2. The Gimp module</h2>
+One of the wonderful features of GIMP is that it all its functionality may
+be accessed through scripting. Available scripting environments include
+Scheme through Script-Fu, and Python. Scheme can be a little difficult
+to use if one does not already know the language.
<p>
- Most scripts make use of the simplified interface Gimp::Fu provides with the GIMP module.
- Gimp::Fu provides a framework for entering parameters to the script in a frame like interface,
- just like Script-Fu, but also allows running of the script in batch mode from the command line.
- This tutorial will go into a detailed description of the construction of a Gimp::Fu script but,
- before we do this, here is the general framework of a Perl-Fu script.
-</p>
-<pre class="code">
- #!/usr/local/bin/perl
- use Gimp ":auto";
- use Gimp::Fu;
- # Register extension to GIMP
- register ... ;
- exit main(); # Handle over control to GIMP
-</pre>
-<p>
- The interesting items to note in the script are the use of the two modules Gimp and Gimp::Fu,
- the register function (which will be described in detail below), and the way control is handed over to the
Gimp module on line 6.
- The use of the ":auto" statement makes Perl automatically include all of the GIMP PDB functions and
constants into the Perl name space.
-</p>
+Perl as a language is far more capable than Scheme, and also has CPAN,
+giving access to vast numbers of modules to get things done. Now, GIMP
+may also be scripted in Perl. This tutorial will describe how to write
+such plug-ins and scripts for Gimp.<p>
-<h2>3. The GIMP PDB</h2>
-<p>
- Before going into the details of the Perl-Fu script, we will describe how to access the various functions
of GIMP.
- All functions known to GIMP are available through the procedural database (PDB). All the PDB functions may
be called from Perl, as will be seen below.
- These PDB functions are either internal to GIMP, or have been made available through a plug-in or a script
extension. As far as the caller is concerned
- there is no difference. As we will see below, when a Perl function is registered through the register
function it will appear in the PDB as well.
-</p>
-<p>
- GIMP/Perl comes with a PDB browser available in <span class="filter">Xtns -> PDB Explorer</span>.
- (There is another PDB browser available in <span class="filter">Xtns -> DB Browser</span> but the PDB
Explorer is more suited for Perl users.)
- This browser provides a way of seeing all the functions in the PDB, as well as their input and output
parameters.
- E.g. the PDB Explorer entry for gimp_image_new, which will be used in the example below looks like this:
-</p>
-
- <table><tbody>
- <tr><th valign=top align=right>Name:</th><td colspan=3>gimp_image_new</td></tr>
- <tr><th valign=top align=right>Blurb:</th><td valign=top colspan=3>Creates a new image with the
specified width, height, and type.</td></tr>
- <tr><th valign=top align=right valign=top>In:</th><td valign=top>INT32</td><td
valign=top>width</td><td valign=top>The width of the image</td></tr>
- <tr><th valign=top></th><td valign=top>INT32</td><td valign=top>height</td><td valign=top>The
height of the image</td></tr>
- <tr><th valign=top></th><td valign=top>INT32</td><td valign=top>type</td><td valign=top>The type
of image { RGB (0), GRAY (1), INDEXED (2) }</td></tr>
- <tr><th valign=top align=right>Out:</th><td valign=top>IMAGE</td><td valign=top>image</td><td
valign=top>The ID of the newly created image</td></tr>
- <tr><th valign=top valign=top>Help:</th><td colspan=3>Creates a new image, undisplayed with the
specified extents and type. A layer should be created and added before this image is displayed,
-or subsequent calls to 'gimp_display_new' with this image as an argument will fail. Layers can be created
using the 'gimp_layer_new' command.
-They can be added to an image using the 'gimp_image_add_layer' command
- </td></tr>
- </tbody></table>
+As there are several excellent tutorial texts describing the perl
+language, this tutorial will assume a working knowledge of Perl,
+and will instead concentrate on the use of GIMP together with the
+perl modules Gimp and Gimp::Fu.
+<h2><a name="SEC3">3. What you need</a></h2>
-<p>
- All the the constants mentioned in the PDB Explorer have been defined within Gimp::Fu and may be used
within Perl.
- E.g. a call to create a new image of size 100x150 of type RGB looks as follows:
-</p>
+ The tutorial scripts have been tested on Linux (a Windows version is
+ in the works) with the following versions:
+ <OL>
+ <LI> Gimp version 2.8.10. </LI>
+
+ <LI> Perl version 5.14 or later. </LI>
+
+ <LI> The perl module Gtk2, version 1.249, available from <a
href="http://gtk2-perl.sourceforge.net/";>http://gtk2-perl.sourceforge.net</a> </LI>
+
+ <LI> The Gimp-Perl module, version 2.3 or later, available from
+ <a href="http://search.cpan.org/dist/Gimp/";>http://search.cpan.org/dist/Gimp/</a></LI>
+ </OL>
+ Perl and all its associated modules are available in source form from
+ the Comprehensive Perl Archive network, CPAN.
-<pre class="code">$img = gimp_image_new(100, 150, RGB)</pre>
+<h2><a name="SEC4">4. The Gimp module</a></h2>
-<p>
- The PDB entry above shows that gimp_image_new is called with three parameters (width, height, type).
- These are all of type INT32. This type, and other types, will be explained below.
-</p>
-<p>
- Script-Fu scripts are called just like any other script according to the PDB signature in the PDB browser.
E.g. to run the Script-Fu Basic One logo just do:
-</p>
+Most scripts make use of the simplified interface Gimp::Fu provided
+with the Gimp module. Gimp::Fu provides a framework for entering
+parameters to the script in a dialog-box interface, just like Script-Fu,
+but also allows running of the script in batch mode from the command line.
+This tutorial will go into detailed descriptions of the construction of
+a Gimp::Fu script, but before we do this, here is the general framework
+of such a script.<p>
-<pre>script_fu_basic1_logo("Hello", 72,
- "-*-utopia-*-r-*-*-72-*-*-*-*-*-*-*",
- [0,0,0],[1,1,1]);</pre>
-<p>
- Unfortunately, as of this writing, calling Script-Fu from Perl has proved to make both Script-Fu and GIMP
very unstable and caused both of them to crash.
- If any of the readers is able to describe what is needed to get it to run successfully, I will happily
include this in a future version of this tutorial.
-</p>
-<p>
- <b>NOTE:</b> When calling a PDB function from Perl::Gimp that has an image and a drawable as the two first
arguments,
- only the drawable should be given as argument in the calling sequence.
-</p>
+<table border><tr><th bgcolor=#E0E0FF><a href="basic">basic</a><tr><td bgcolor=#FFE0E0><pre><font size=-1
color=red> 1: </font>#!/usr/bin/perl -w
+<font size=-1 color=red> 2: </font>
+<font size=-1 color=red> 3: </font>use Gimp;
+<font size=-1 color=red> 4: </font>use Gimp::Fu;
+<font size=-1 color=red> 5: </font>
+<font size=-1 color=red> 6: </font>podregister { die "I DIED\n" };
+<font size=-1 color=red> 7: </font>
+<font size=-1 color=red> 8: </font>exit main;
+<font size=-1 color=red> 9: </font>__END__
+<font size=-1 color=red> 10: </font>
+<font size=-1 color=red> 11: </font>=head1 NAME
+<font size=-1 color=red> 12: </font>
+<font size=-1 color=red> 13: </font>test_exception - exercise gimp-perl filter testing exceptions
+<font size=-1 color=red> 14: </font>
+<font size=-1 color=red> 15: </font>=head1 SYNOPSIS
+<font size=-1 color=red> 16: </font>
+<font size=-1 color=red> 17: </font><Image>/Filters/Languages/_Perl/_Test/Exception
+<font size=-1 color=red> 18: </font>
+<font size=-1 color=red> 19: </font>=head1 DESCRIPTION
+<font size=-1 color=red> 20: </font>
+<font size=-1 color=red> 21: </font>Exercise Gimp-Perl exceptions.
+<font size=-1 color=red> 22: </font>
+<font size=-1 color=red> 23: </font>=head1 AUTHOR
+<font size=-1 color=red> 24: </font>
+<font size=-1 color=red> 25: </font>The Author.
+<font size=-1 color=red> 26: </font>
+<font size=-1 color=red> 27: </font>=head1 DATE
+<font size=-1 color=red> 28: </font>
+<font size=-1 color=red> 29: </font>20140310
+<font size=-1 color=red> 30: </font>
+<font size=-1 color=red> 31: </font>=head1 LICENSE
+<font size=-1 color=red> 32: </font>
+<font size=-1 color=red> 33: </font>The licensing terms. </pre></table><br>
-<h2>4. Gimp::Fu and the register function</h2>
-<p>
- Gimp::Fu is Perl's answer to Script-Fu. It provides a simplified method for accepting parameters for a
script through a Gtk interface,
- just like Script-Fu, but as we shall see below, it has some additional bells and whistles.
- <br /><br />
- The main function for a Gimp::Fu script is the register function. This function declares the interface of
the script to GIMP.
- The register function takes the following 10 parameters, that must all be provided:
-</p>
-<ol>
- <li>The name of the function - a string. This is the name of the function as it will be known in the
PDB.</li>
- <li>A small description - a string</li>
- <li>A help text - a string</li>
- <li>The authors name - a string</li>
- <li>The copyright of the script - a string</li>
- <li>Creation date - a string</li>
- <li>Menu path - a string. The path has one of the two forms:
- <ol>
- <li>"<Toolbox>/Xtns/Perl-Fu/Script Name"</li>
- <li>"<Image>/Perl-Fu/Script Name"</li>
- </ol>
- If form 1. is given, then the script is a standalone script that appears in the menu hierarchy under
Xtns/Perl-Fu and takes
- all of its inputs through the Gimp::Fu interface frame. If form 2. is given, on the other hand, the
script is tied to the
- image menu popped up through use of the right-hand mouse button over any image. In this case Gimp::Fu
will add, as the first
- two parameters to the script, the ID of the image and the drawable which was active when the script was
invoked.
- </li>
- <li>
- The acceptable image types - a string. This list contains a list
- of image types acceptable. This field is only used for scripts
- that are in the "<Image>" hierarchy. For images in the
- <Toolbox> hierarchy, this should be an empty string.
- Possible values are listed in the table below:
- <table><tbody>
- <tr><th>value</th><th>meaning</th></tr>
- <tr><td valign="top">* </td><td valign=top>Any images are accepted</td></tr>
- <tr><td valign=top>RGB </td><td valign=top>RGB images</td></tr>
- <tr><td valign=top>RGBA</td><td valign=top>RGB images with alpha channels</td></tr>
- <tr><td valign=top>GREY</td><td valign=top>Grey level images</td></tr>
- </tbody></table>
- <br />
- </li>
-
- <li>
- Parameters - A reference to an array of parameters. (A reference
- to an array in Perl is simply an array written within square
- brackets). Each parameter in turn is a reference to an array
- containing the following four or five values:
- <ol>
- <li>
- The type of the parameter. The types recognized by Gimp::Fu
- and Perl are given in the following table:
- <table><tbody>
- <tr>
- <th>Type</th>
- <th>Possible forms</th>
- <th>Comment</th>
- </tr>
- <tr>
- <td valign=top>
- PF_INT<br />
- PF_INT32<br />
- PF_INT16<br />
- PF_INT8<br />
- </td>
- <td valign=top>42</td>
- <td valign=top>A number. PF_INT is a synonym to PF_INT32.</td>
- </tr>
- <tr>
- <td valign=top>
- PF_VALUE<br />
- PF_FLOAT<br />
- </td>
- <td valign=top>3.141</td>
- <td valign=top>A floating point number.</td>
- </tr>
- <tr>
- <td valign=top>
- PF_TOGGLE<br />
- PF_BOOLEAN
- </td>
- <td valign=top>
- 0<br />
- 1
- </td>
- <td valign=top>
- A boolean value.
- </td>
- </tr>
- <tr>
- <td valign=top>
- PF_SLIDER<br />
- PF_SPINNER
- </td>
- <td valign=top>
- An integer value through a slider and a spinner
- interface. The range parameter should be specified and
- is interpreted as minimum, maximum, and step,
- e.g. [0,100,1].
- </td>
- <td valign=top></td>
- </tr>
- <tr>
- <td valign=top>PF_FONT</td>
- <td valign=top>-*-blippo-*-*-*-*-24-*-*-*-*-*-*-*</td>
- <td valign=top>A font in X11 font format. This interface launches a font browser.</td>
- </tr>
- <tr>
- <td valign=top>PF_STRING</td>
- <td valign=top>"A string"</td>
- <td valign=top>A string</td>
- </tr>
- <tr>
- <td valign=top>
- PF_COLOR<br />
- PF_COLOUR
- </td>
- <td valign=top>
- [255,127,0]<br />
- <tt>#ff7f00</tt>
- </td>
- <td valign=top>
- A color may either be expressed as a reference to an
- array of three components, or as a hexadecimal
- triple, proceeded by the hash sign.
- </td>
- </tr>
- <tr>
- <td valign=top>PF_TOGGLE</td>
- <td valign=top>0<br />1</td>
- <td valign=top>A boolean toggle</td>
- </tr>
- <tr>
- <td valign=top>PF_IMAGE</td>
- <td valign=top>-</td>
- <td valign=top>An image</td>
- </tr>
- <tr>
- <td valign=top>PF_DRAWABLE</td>
- <td valign=top>-</td>
- <td valign=top>A drawable.</td>
- </tr>
- <tr>
- <td valign=top>PF_BRUSH</td>
- <td valign=top></td>
- <td valign=top>A brush</td>
- </tr>
- <tr>
- <td valign=top>PF_GRADIENT</td>
- <td valign=top></td>
- <td valign=top>A gradient</td>
- </tr>
- <tr>
- <td valign=top>PF_PATTERN</td>
- <td valign=top></td>
- <td valign=top>A pattern</td>
- </tr>
- </tbody>
- </table>
-<br />
-
- </li>
- <li>The name of the parameter - a string</li>
- <li>A help text for the parameter</li>
- <li>Default value for the parameter. This should be given in the form listed in the table above.</li>
- <li>An array defining allowed range for the value. This is only possible for PF_SLIDER and
PF_SPINNER.</li>
- </ol>
- </li>
- <li>A reference to an array of return types of the sub in the 11th parameter.</li>
- <li>
- The sub to be called - a reference to a sub . This subroutine will be called with the associated menu
entry declared through the Menu path described above.
- When the sub is called it is passed as arguments the list of parameters declared in field 9, described
above, and in the case of a "<Image>..." script,
- the active image and layer as first and second parameters.
- <br />
- A reference to a sub in Perl may be declared in two ways. You can declare a subroutine at a different
place in the source file
- (e.g. sub run) and reference it by writing \&run. An alternative way is to write it inline by simply
writing:
- <br />
- <pre>sub { ($text, $color) = @_ ; ... }</pre>
- <br />
- The sub is expected not need to display a new image after it has created it.
- Instead it is expected to return the new image or images that were created in accordance with the return
types declared in parameter 10 of the register call described above.
- This behaviour has been added in order to be able to call the sub non-interactively. More about that
behaviour below.
- </li>
-</ol>
-
-<h2>4.2 A commented script</h2>
-<p>
- The following Gimp::Fu script example shows the steps described in the previous section.
- It registers a script that takes two values, the size of the image and a color, and then produces an image
of the requested size with the requested color.
- Quite useless but it shows the important steps of how to register a script, how to create a new image, and
how to access some PDB functions.
-</p>
-<pre class="code">
- #!/usr/local/bin/perl -w
- use Gimp ":auto";
- use Gimp::Fu;
- sub img_uni {
- my ($size, $color) = @_;
- # Create a new image
- $img = gimp_image_new($size, $size, RGB);
- # Create a new layer
- $layer = gimp_layer_new($img, $size, $size, RGB,
- "Layer 1", 100, NORMAL_MODE);
- # add the layer to the image
- gimp_image_add_layer($img, $layer, -1);
- # Set the background to the required color
- gimp_palette_set_background($color);
- # Paint the layer
- gimp_edit_fill($layer, BG_IMAGE_FILL);
- # Return the image
- return $img;
- }
- register
- "img_uni", # fill in name
- "Create a uniform image", # a small description
- "A tutorial script", # a help text
- "Dov Grobgeld", # Your name
- "Dov Grobgeld (c)", # Your copyright
- "1999-05-14", # Date
- "<Toolbox>/Xtns/Perl-Fu/Tutorial/Img Uni", # menu path
- "",
- [
- [PF_INT, "size", "Img size", 100],
- [PF_COLOR, "color", "Img color", [255,127,0]]
- ],
- \&img_uni;
- exit main();
-</pre>
-<p>
- Most of these commands are directly copied out the PDB.
- <br />
- <br />
- This script shows the essential steps of producing a stand-alone script:
-</p>
-<table><tbody>
- <tr><th>line(s)</th><th>Description</th></tr>
- <tr><td>10 </td><td>Creating a new image.</td></tr>
- <tr><td>13-14 </td><td>Creating one or more layers.</td></tr>
- <tr><td>17 </td><td>Attaching the layer to the image. </td></tr>
- <tr><td>19-23 </td><td>Do some painting operations in the layers. </td></tr>
- <tr><td>26 </td><td>Return the image to the caller</td></tr>
- <tr><td> 29-42 </td><td>Registration of the extension</td></tr>
-</tbody></table>
-<p>
- To test the script, save it in the directory <b>$HOME/.gimp-2.2/plug-ins</b>. It must then be made
executable through the command:
- <br />
- <br />
- <b>chmod +x $HOME/.gimp-2.2/plug-ins/uni</b>
- <br />
- <br />
- Then start GIMP. It is generally a good idea to test the syntax of the script with perl -c before starting
GIMP.
- (A more official way to add scripts is to use the gimptool --install-bin command).
-</p>
-<p>
- <b>Note:</b> It is not possible to add scripts once GIMP is running.
- On the other hand, it is possible to change a script which has already been registered, as long as the
parameters don't change.
-</p>
-<p class="images">
- <img src="uni-menu.png" alt=""/>
-</p>
-<p>
- The script is now accessible through the menu system through the <b>Xtns</b> top menu.
-</p>
-<p class="images">
- <img src="uni-entry.png" alt=""/>
-</p>
-<p>
- When choosing this menu entry the following screen is popped up.
-</p>
-<p class="images">
- <img src="uni-result.png" alt=""/>
-</p>
-<p>
- Choosing the default values creates a result like the image above.
-</p>
+The key points to note in the script are:
+<ul>
+<li>the use of the two
+modules <tt>Gimp</tt> and <tt>Gimp::Fu</tt>,
+<li>the podregister function, which will be described in detail below,
+<li>the way the control is
+handed over to <tt>Gimp</tt> module on line 8, and
+<li>the POD documentation below the <tt>__END__</tt> line.
+</ul>
-<h2>5. Object oriented syntax</h2>
-<p>
- Gimp::Fu provides an alternative object-oriented syntax for the image and the drawable commands.
- Here is a table showing the procedural vs the object oriented syntax for a few commands:
-</p>
-<table><tbody>
- <tr><th>procedural syntax</th>
- <th>object oriented syntax</th>
- </tr>
- <tr>
- <td>gimp_image_add_layer($drw,-1);</td>
- <td>$img->add_layer($drw, -1);</td>
- </tr>
- <tr>
- <td>gimp_drawable_width($drw);</td>
- <td>$drw->width();</td>
- </tr>
- </tbody></table>
-<p>
- The substitution rule for converting a PDB function call into a method is as simple as erasing
``gimp_image_'' from the beginning of the function call
- and calling this method through the image object. Similarly for the gimp_drawable_... functions.
-</p>
-<p>
- Note that the object oriented syntax is only syntactic sugar that makes the calling syntax cleaner in some
cases.
- The error messages are still given in the procedural format.
-</p>
+<h2><a name="SEC5">5. The GIMP PDB</a></h2>
-<h2>6. Painting areas with selections</h2>
-<p>
- In the uni script the function gimp_edit_fill was called to fill the whole image. Looking at the info for
gimp_edit_fill in the PDB browser we find the following:
-</p>
-
- <table><tbody>
- <tr><th valign=top align=right>Name:</th><td colspan=3>gimp_edit_fill</td></tr>
- <tr><th valign=top align=right>Blurb:</th><td valign=top colspan=3>Fill selected area of
drawable</td></tr>
- <tr>
- <th valign=top align=right valign=top>In:</th>
- <td valign=top>DRAWABLE</td>
- <td valign=top>drawable</td>
- <td valign=top>The drawable to fill from</td>
- </tr>
- <tr>
- <th valign=top></th><td valign=top>INT32</td><td valign=top>fill_type</td>
- <td valign=top>The type of fill: FG_IMAGE_FILL (0), BG_IMAGE_FILL (1), WHITE_IMAGE_FILL (2),
TRANS_IMAGE_FILL (3), NO_IMAGE_FILL (4)</td>
- </tr>
- <tr><th valign=top valign=top>Help:</th><td colspan=3>
- This procedure fills the specified drawable with the fill mode. If the
- fill mode is foreground, the current foreground color is used. If the
- fill mode is background, the current background color is used. Other
- fill modes should not be used. This procedure only affects regions
- within a selection if there is a selection active.
- </td>
- </tr>
- </tbody></table>
+Before going into the details of the Gimp::Fu script, we will
+describe how to access the functionality of GIMP. All
+functions known to GIMP are available through the procedural database
+(PDB). All the PDB functions may be called from perl, as will be seen
+below. These PDB functions are either internal to GIMP, or have been
+made available through a plug-in or a script extension, but as far as
+the caller is concerned there is no difference. As we will see below,
+when a perl function is registered through the <tt>podregister</tt>
+function, it will appear in the PDB as well.
+<p>Gimp comes with a PDB browser available
+in <b>Help/Procedure Browser</b>. This browser provides a way of seeing
+all the functions in the PDB, as well as their input and output
+parameters. E.g. the DB Browser entry for
+<tt>gimp-image-new</tt>, which will be used in the example below
+looks like this:
<p>
- Thus, if a selection is active when gimp_edit_fill is called only the selection is painted.
- There are lots of ways of choosing a selection as can be seen when searching for a ``select'' in the PDB.
- The example below uses gimp_rect_select, whose entry in the PDB looks as follows:
-</p>
-
- <table><tbody>
- <tr><th valign=top align=right>Name:</th><td colspan=3>gimp_rect_select</td></tr>
- <tr><th valign=top align=right>Blurb:</th><td valign=top colspan=3>Create a rectangular
selection over the specified image</td></tr>
- <tr><th valign=top align=right valign=top>In:</th><td valign=top>IMAGE</td><td
valign=top>image</td><td valign=top>The image</td></tr>
- <tr><th valign=top></th><td valign=top>FLOAT</td><td valign=top>x</td><td valign=top>x
coordinate of upper-left corner of rectangle</td></tr>
- <tr><th valign=top></th><td valign=top>FLOAT</td><td valign=top>y</td><td valign=top>y
coordinate of upper-left corner of rectangle</td></tr>
- <tr><th valign=top></th><td valign=top>FLOAT</td><td valign=top>width</td><td valign=top>the
width of the rectangle: width > 0</td></tr>
- <tr><th valign=top></th><td valign=top>FLOAT</td><td valign=top>height</td><td valign=top>the
height of the rectangle: width > 0</td></tr>
- <tr><th valign=top></th><td valign=top>INT32</td><td valign=top>operation</td><td valign=top>the
selection operation: {ADD (0), SUB(1), REPLACE (2), INTERSECT (3) }</td></tr>
- <tr><th valign=top></th><td valign=top>INT32</td><td valign=top>feather</td><td
valign=top>feather option for selections</td></tr>
- <tr><th valign=top></th><td valign=top>FLOAT</td><td valign=top>feather_radius</td><td
valign=top>radius for feather operation</td></tr>
- <tr><th valign=top valign=top>Help:</th>
- <td colspan=3>
- This tool creates a rectangular selection over the
- specified image. The rectangular region can be either
- added to, subtracted from, or replace the contents of
- the previous selection mask. If the feather option is
- enabled, the resulting selection is blurred before
- combining. The blur is a gaussian blur with the
- specified feather radius.
- </td>
- </tr>
- </tbody></table>
+<p><table><tr><td bgcolor=#e0e0e0>
+<table>
+<tr><th valign=top align=right>Name:</th><td bgcolor=#e0e0ff colspan=3>plug-in-gauss-iir</td></tr>
+<tr><th valign=top align=right>Blurb:</th><td valign=top colspan=3>Apply a gaussian blur</td></tr>
+<tr>
+<th valign=top align=right valign=top>In:</th><td valign=top>INT32</td><td valign=top>run-mode</td><td
valign=top>The run mode { RUN-INTERACTIVE (0), RUN-NONINTERACTIVE (1) }</td>
+</tr>
+<tr>
+<th valign=top></th><td valign=top>IMAGE</td><td valign=top>image</td><td valign=top>Input image
(unused)</td>
+</tr>
+<tr>
+<th valign=top></th><td valign=top>DRAWABLE</td><td valign=top>drawable</td><td valign=top>Input
drawable</td>
+</tr>
+<tr>
+<th valign=top></th><td valign=top>FLOAT</td><td valign=top>radius</td><td valign=top>Radius of gaussian
blur (in pixels, > 0.0)</td>
+</tr>
+<tr>
+<th valign=top></th><td valign=top>INT32</td><td valign=top>horizontal</td><td valign=top>Blur in horizontal
direction</td>
+</tr>
+<tr>
+<th valign=top></th><td valign=top>INT32</td><td valign=top>vertical</td><td valign=top>Blur in vertical
direction</td>
+</tr>
+<tr><th valign=top valign=top>Help:</th><td colspan=3>Applies a gaussian blur to the drawable, with
specified radius of affect. The standard deviation of the normal distribution used to modify pixel values is
calculated based on the supplied radius. Horizontal and vertical blurring can be independently invoked by
specifying only one to run. The IIR gaussian blurring works best for large radius values and for images
which are not computer-generated.</td></tr></table>
+</table></p>
-<p>
- A simple use of this function which selects a rectangle in the middle of an image and paints that
rectangle with a user defined color.
- This example also introduces a couple of new features we haven't seen before:
-</p>
-<ul>
- <li>The script is associated with an image since its menu path starts with "<Image>/...".
- Note that as a result of this the callback sub in line 13 receives two additional parameters, the active
image and the seleced drawable.</li>
- <li>The use of a subroutine without a name as a parameter to register</li>
- <li>The use of the PDB functions gimp_undo_push_group_start and gimp_undo_push_group_end. These functions
declare an undo group.
- When an undo is done on the image, instead of having the individual operators undo, all the actions
between the undo start and the
- undo group calls will be undone at once.</li>
- <li>The return type of the register function defines what new images should be displayed by GIMP.
- In this case we don't want to display any new images and therefore return an empty array.</li>
-</ul>
-<pre class="code">
-#!/usr/local/bin/perl -w
-use Gimp ":auto";
-use Gimp::Fu;
-register
- "img_paint_select",
- "Paints the selection", "Paints the selection",
- "Dov Grobgeld", "Dov Grobgeld", "1999-05-14",
- "<Image>/Perl-Fu/Tutorial/Paint Select",
- "*",
- [
- [PF_COLOR, "color", "Rectangle color", [0,0,255]] ],
- sub {
- my($img, $layer, $color) = @_;
- my($width, $height) = (gimp_image_width($img),
- gimp_image_height($img));
- # Select a rectangle inside the image and paint it with color
- gimp_undo_push_group_start($img);
- gimp_rect_select($img,
- $width/4, $height/4, $width/2, $height/2,
- REPLACE, 0,0);
- gimp_palette_set_background($color);
- gimp_edit_fill($layer, BG_IMAGE_FILL);
- gimp_selection_none($img);
- gimp_displays_flush();
- gimp_undo_push_group_end($img);
- # Tell GIMP not to display a new image
- return ();
- };
-exit main();
-</pre>
-<p class="images">
- <img src="paint-select.png" alt=""/>
-</p>
-<p>
- The result when run on our previous image.
-</p>
+All the the constants mentioned in the PDB Explorer have been defined
+within Gimp::Fu and may be used within perl. E.g. a call to
+blur an image looks as follows:
-<h2>6.1 Complex selections</h2>
-<p>
- Besides rectangular selections elliptical selections may also be created through the PDB functions
- gimp_ellipse_select() and gimp_free_select() which allows the selection of ellipses and polygons.
-</p>
-<p>
- More complex selections may be created through the channel mechanism. The PDB gimp_channel_new() creates a
new channel.
- The channel is a drawable that may be painted into, just like any other drawable, but with the difference
that it is always a grey level image.
- Once the channel is finished, the channel may be loaded into the selection through the PDB function
gimp_selection_load().
-</p>
-<p>
- Search for ``select'' in the DB Browser to see a list of all the selection related functions.
-</p>
+<pre>
+ Gimp::Plugin->gauss_iir($image, $drawable, 50, 6, 6);</pre>
-<h2>6.2 Loops</h2>
-<p>
- In Perl it is trivial to write loops that, together with the various selecton tools, give powerful
creative possibilities.
- Here is an example that mixes colors in circles. There is nothing really new here, but it shows the power
of what we have described above.
-</p>
-<pre class="code">
-#!/usr/local/bin/perl
-use Gimp ":auto";
-use Gimp::Fu;
-sub circles {
- my ($size, $bgcolor, $radius) = @_;
- # Create the background
- $img = gimp_image_new($size, $size, RGB);
- $layer = gimp_layer_new($img, $size, $size, RGB,
- "Layer 1", 100, NORMAL_MODE);
- gimp_image_add_layer($layer, -1);
- gimp_palette_set_background($bgcolor);
- gimp_edit_fill($layer, BG_IMAGE_FILL);
- my $ncircles = int($size/$radius/2);
- for ($i=0; $i<$ncircles; $i++) {
- for ($j=0; $j<$ncircles; $j++) {
- # Be creative and mix colors
- $color = [$i*30, ($ncircles-$j)*25, ($i+$j)*15];
- # Select a circle
- gimp_ellipse_select($img,
- $i*$radius*2, $j*$radius*2,
- $radius*2, $radius*2,
- REPLACE, 1, 0, 0);
- # Paint the color in the circle
- gimp_palette_set_background($color);
- gimp_edit_fill($layer, BG_IMAGE_FILL);
- gimp_selection_none($img);
- }
- }
- return $img;
-}
-# register the script
-register "circles", "a loop", "a loop", "Dov", "Dov", "1999-05-14",
- "<Toolbox>/Xtns/Perl-Fu/Tutorial/Circles",
- "",
- [
- [PF_INT32, "size", "Img size", 100],
- [PF_COLOR, "bg", "Background color", [40,180,60]],
- [PF_INT32, "radius", "Circle radius", 10]
- ],
- \&circles;
-exit main();
-</pre>
-<p class="images">
- <img src="circles.png" alt=""/>
-</p>
-<p>
- The result.
-</p>
+Note that Perl is using underline characters where the DB browser
+uses hyphens! The PDB entry above shows that <tt>plug-in-gauss-iir</tt>
+is called with various parameters, of various types. These will be
+explained below.
+
+<p> You will also see that the first parameter, <tt>run-mode</tt>,
+was omitted. This is a feature of Gimp-Perl, which will automatically
+supply that parameter if you leave it off. This will make your code a
+lot tidier-looking.
-<h2>7. Creating text, Hello World - writing text in an image</h2>
<p>
- To create text the PDB function gimp_text_fontname() may be used. In this function the font is specified
in the X11 font conventions.
- (There are also some older functions, gimp_text and gimp_text_ext in which the different X11 fields are
specified explicitly.)
- Here is an example of a script that creates an image containing "Hello world".
-</p>
-<pre class="code">
-#!/usr/local/bin/perl
-use Gimp ":auto";
-use Gimp::Fu;
-sub text1 {
- my($font, $text) = @_;
- # Create a new image
- $img = gimp_image_new(350, 100, RGB);
- # Create a new layer and draw it to the image at the top
- $drw = gimp_layer_new($img, $img->width, $img->height,
- RGB, "BG", 100, NORMAL_MODE);
- $drw->add_layer(-1);
- gimp_palette_set_background("black");
- gimp_edit_fill($drw, BG_IMAGE_FILL);
- # Choose color of text
- gimp_palette_set_foreground([255,255,0]);
- # Create the text
- my $border = 10;
- my $text_layer = gimp_text_fontname($drw, 0, 0, $text,
- $border, 1,
- xlfd_size($font), $font);
- gimp_floating_sel_anchor($text_layer);
- return $img;
-}
-# register the script
-register "hello_world1", "basic text", "basic text", "Dov", "Dov",
- "1999-05-14",
- "<Toolbox>/Xtns/Perl-Fu/Tutorial/Basic text 1",
- "",
- [
- [PF_FONT, "font", "font", "-*-utopia-bold-r-*-*-70-*-*-*-*-*-*-*"],
- [PF_STRING, "text", "text", "Hello world!"]
- ],
- \&text1;
-# Handle over control to GIMP
-exit main();
+Script-Fu scripts are called just like any other script according
+to the PDB signature in the PDB browser. E.g. to run the
+script-fu-basic1-logo just do:
+<pre>
+script_fu_basic1_logo("Hello", 72,
+ "Utopia 72",
+ [0,0,0],[255,255,255]);</pre>
+
+<h3><a name="SEC5.1">5.1. Gimp::Fu and the podregister function</a></h3>
+
+ Gimp::Fu is Perl's answer to Script-Fu. It provides a simplified method
+ for accepting parameters for a script through a Gtk2 interface,
+ just like script-fu, but as we shall see below, it has some additional
+ bells and whistles.<p>
+
+ The main function for a Gimp-Fu script is the <tt>podregister</tt> function.
+ This function declares the interface of the script to GIMP. The
+ <tt>podregister</tt> function provides GIMP with the following information,
+ from various sections of its
+ <a href="http://perldoc.perl.org/perlpod.html";>POD (plain old
+ documentation)</a>:
+ <OL>
+ <LI> The name of the function. It comes from the first part of the
+ <tt>NAME</tt> section, before the dash. Tells GIMP the name by which
+ the function will be known in the PDB. </LI><P>
+ <LI> A small description, from the <tt>NAME</tt> section, after the
+ dash. </LI><p>
+ <LI> A help text, from the <tt>DESCRIPTION</tt> section. </LI><p>
+ <LI> The author's name, from the <tt>AUTHOR</tt> section. </LI><p>
+ <LI> The copyright of the script, from the <tt>LICENSE</tt> section. </LI><p>
+ <LI> Creation date - any text, from the <tt>DATE</tt> section. </LI><p>
+ <LI> Menu path - a string, from the <tt>SYNOPSIS</tt> section.
+ The path can take these forms, though there are other options:
+ <OL>
+ <LI> "<Toolbox>/Xtns/Perl/Script Name" </LI>
+ <LI> "<Image>/Perl-Fu/Script Name" </LI>
+ </OL>
+ If form 1. is given, then the script is a standalone script
+ that appears in the menu hierarchy under Xtns/Perl-Fu and
+ takes all its inputs through the Gimp::Fu interface dialog.
+ If form 2. is given on the other hand, then the script
+ is tied to the image menu popped up through the right hand
+ button over any image. In this case Gimp::Fu will add as
+ the first two parameters to the script the image and the
+ drawable active when the script was invoked.
+ </LI><p>
+ <LI> The acceptable image types, from the <tt>IMAGE TYPES</tt>
+ section - a string. This list contains
+ a list of image types acceptable. This field is only used
+ for scripts that are in the "<Image>" hieararchy.
+ Possible values are listed in the table below:
+
+ <table>
+ <tr><th bgcolor=#dfdfdf>value</th><th bgcolor=#dfdfdf>meaning</th></tr>
+ <tr><td bgcolor=#dfdfee valign=top>*<td bgcolor=#dfdfee valign=top>Any images are accepted</tr>
+ <tr><td bgcolor=#dfdfee valign=top>RGB <td bgcolor=#dfdfee valign=top>RGB images</tr>
+ <tr><td bgcolor=#dfdfee valign=top>RGBA <td bgcolor=#dfdfee valign=top>RGB images with alpha
channels</tr>
+ <tr><td bgcolor=#dfdfee valign=top>GREY <td bgcolor=#dfdfee valign=top>Grey level images</tr>
+ </table>
+ </LI><p>
+ <LI> Parameters, from the <tt>PARAMETERS</tt> section. This will be
+ Perl code, which Gimp::Fu evaluates as a list of parameters.
+ Each parameter in turn is a reference to an array containing the
+ following four or five values (A reference to an array in Perl is
+ simply an array written within square brackets):
+ <OL>
+ <LI> The type of the parameter. The types recognized by
+ Gimp::Fu and their Perl counterparts are given in the
+ following table:
+
+ <table>
+ <tr><th bgcolor=#dfdfdf>Type</th><th bgcolor=#dfdfdf width=30%>Possible forms</th>
+ <th bgcolor=#dfdfdf width=50%>Comment</tr>
+ <tr><td bgcolor=#dfdfee valign=top>PF_INT32<br>
+ PF_INT16<br>
+ PF_INT8<br><td bgcolor=#dfdfee valign=top>42<td bgcolor=#dfdfee valign=top>An
integer.</tr>
+ <tr><td bgcolor=#dfdfee valign=top>PF_FLOAT<br><td bgcolor=#dfdfee valign=top>3.141<td
bgcolor=#dfdfee valign=top>A floating point number.
+ <tr><td bgcolor=#dfdfee valign=top>PF_TOGGLE
+ <td bgcolor=#dfdfee valign=top>0<br>1<td bgcolor=#dfdfee valign=top>A boolean
value.
+ <tr><td bgcolor=#dfdfee valign=top>PF_SLIDER<br>
+ PF_SPINNER
+ <td bgcolor=#dfdfee valign=top>An integer value through a slider and a spinner interface.
The range parameter should be specified and is interpreted as minimum, maximum, and step, e.g. [0,100,1].
+ <td bgcolor=#dfdfee valign=top><img src="tpix.gif" width=0>
+ <tr><td bgcolor=#dfdfee valign=top>PF_FONT<td bgcolor=#dfdfee valign=top>"Arial"<td
bgcolor=#dfdfee valign=top>A font name.
+ <tr><td bgcolor=#dfdfee valign=top>PF_STRING<td bgcolor=#dfdfee valign=top>"A string"<td
bgcolor=#dfdfee valign=top>A string</tr>
+ <tr><td bgcolor=#dfdfee valign=top>PF_COLOR<br>
+ PF_COLOUR<td bgcolor=#dfdfee valign=top>[255,127,0]<br>
+ <tt>#ff7f00</tt>
+ <td bgcolor=#dfdfee valign=top>A color may either be expressed as a reference
+ to an array of three components, or as a hexadecimal
+ triple, proceeded by the hash sign.</tr>
+ <tr><td bgcolor=#dfdfee valign=top>PF_TOGGLE<td bgcolor=#dfdfee valign=top>0<br>1<td
bgcolor=#dfdfee valign=top>A boolean toggle
+ <tr><td bgcolor=#dfdfee valign=top>PF_IMAGE<td bgcolor=#dfdfee valign=top>-<td bgcolor=#dfdfee
valign=top>An image
+ <tr><td bgcolor=#dfdfee valign=top>PF_DRAWABLE<td bgcolor=#dfdfee valign=top>-<td
bgcolor=#dfdfee valign=top>A drawable.
+ <tr><td bgcolor=#dfdfee valign=top>PF_BRUSH<td bgcolor=#dfdfee valign=top><img src="tpix.gif"
width=0><td bgcolor=#dfdfee valign=top>A brush
+ <tr><td bgcolor=#dfdfee valign=top>PF_GRADIENT<td bgcolor=#dfdfee valign=top><img
src="tpix.gif" width=0><td bgcolor=#dfdfee valign=top>A gradient
+ <tr><td bgcolor=#dfdfee valign=top>PF_PATTERN<td bgcolor=#dfdfee valign=top><img
src="tpix.gif" width=0><td bgcolor=#dfdfee valign=top>A pattern
+ </table>
+ </LI>
+ <LI> The name of the parameter - a string. </LI>
+ <LI> A help text for the parameter. </LI>
+ <LI> Default value for the parameter. This should be given in
+ the form listed in the table above.
+ </LI>
+ <LI> An array defining allowed range for the value. This is
+ only used for PF_SLIDER and PF_SPINNER.</LI>
+ </ol><P>
+ <LI> Optionally, the return types of the function can be provided,
+ from a <tt>RETURN VALUES</tt> section. This is specified in the
+ same way as the Parameters above. There is no default or extra
+ argument required. <p>
+ </LI>
+ <LI> The perl code implementing the function. This
+ will be called when the associated menu entry
+ declared through the <i>Menu path</i> described above.
+ When the sub is called it is passed a list
+ of parameters as declared in field 9. In
+ the case of a "<Image>..." script, the active image
+ and drawable (layer or channel) as first and second parameters.
+ Thanks to the magic of Perl source filtering, you do not need
+ to declare your variables but may simply use them:
+ <pre>
+ podregister {
+ $drawable->gauss_iir($radius, $horizontal, $vertical);
+ };
+ # ...
+ =head1 PARAMETERS
+
+ [ PF_FLOAT, 'radius', "Radius", 50.0 ],
+ [ PF_INT32, 'horizontal', 'Horizontal blur', 6 ],
+ [ PF_INT32, 'vertical', 'Vertical blur', 6 ],</pre>
+ <p>
+ You will also note that "plug_in_" has been omitted from the
+ method call above, and that not all its parameters appear
+ to be getting passed! This is thanks to the object-oriented
+ implementation in Gimp-Perl, which when given a method name,
+ searches various prefixes for the underlying function including
+ the plug-in related ones (including <tt>script_fu_</tt>).
+ <p>
+ A reference to a sub in perl may be declared in two ways.
+ Either by declaring a subroutine at a different place in the
+ source file, e.g. <tt>sub run</tt> and reference it by
+ writing <tt>\&run</tt>. An alternative way is to write it
+ inline by simply writing (since with Perl's prototyping,
+ you need not supply the "sub" keyword):
+ <pre>
+ podregister { ... };</pre>
+ The code will normally display a new image if it creates one,
+ and also return the new image, in accordance with the return
+ types declared in parameter 10 of the <tt>podregister</tt>
+ call described above. This enables Gimp::Fu scripts to be
+ used noninteractively by other scripts. More about that
+ behaviour below.
+ </LI>
+ </OL>
+ </LI>
+
+<h3><a name="SEC5.2">5.2. A commented script</a></h3>
+
+The following Gimp::Fu script example shows the steps described in the
+previous section. It registers a script that takes two values, the size
+of the image and a color, and then produces an image of the requested
+size with the requested color. Quite useless, but it shows the important steps
+of how to register a script, how to create a new image, and how
+to access some PDB functions.<p>
+
+<table border><tr><th bgcolor=#E0E0FF><a href="uni">uni</a><tr><td bgcolor=#FFE0E0><pre><font size=-1
color=red> 1: </font>#!/usr/bin/perl -w
+<font size=-1 color=red> 2: </font>
+<font size=-1 color=red> 3: </font>use strict;
+<font size=-1 color=red> 4: </font>use Gimp;
+<font size=-1 color=red> 5: </font>use Gimp::Fu;
+<font size=-1 color=red> 6: </font>
+<font size=-1 color=red> 7: </font>podregister {
+<font size=-1 color=red> 8: </font> # no need to have my ($size, $color) = @_;
+<font size=-1 color=red> 9: </font> my $img = Gimp::Image->new($size, $size, RGB); # Create a new
image
+<font size=-1 color=red> 10: </font> # Create a new layer
+<font size=-1 color=red> 11: </font> my $layer = $img->layer_new($size, $size, RGB, "Layer 1", 100,
NORMAL_MODE);
+<font size=-1 color=red> 12: </font> $img->insert_layer($layer, -1, 0); # add the layer to the image
+<font size=-1 color=red> 13: </font> Gimp::Context->set_background($color); # Set background to
required color
+<font size=-1 color=red> 14: </font> $layer->edit_fill(BACKGROUND_FILL); # Paint the layer
+<font size=-1 color=red> 15: </font> Gimp::Display->new($img);
+<font size=-1 color=red> 16: </font> return $img; # Return image - return implied by no IMAGE TYPES
+<font size=-1 color=red> 17: </font>};
+<font size=-1 color=red> 18: </font>
+<font size=-1 color=red> 19: </font>exit main;
+<font size=-1 color=red> 20: </font>__END__
+<font size=-1 color=red> 21: </font>
+<font size=-1 color=red> 22: </font>=head1 NAME
+<font size=-1 color=red> 23: </font>
+<font size=-1 color=red> 24: </font>img_uni - Create a uniform image
+<font size=-1 color=red> 25: </font>
+<font size=-1 color=red> 26: </font>=head1 SYNOPSIS
+<font size=-1 color=red> 27: </font>
+<font size=-1 color=red> 28: </font><Image>/File/Create/Tutorial/Img Uni
+<font size=-1 color=red> 29: </font>
+<font size=-1 color=red> 30: </font>=head1 DESCRIPTION
+<font size=-1 color=red> 31: </font>
+<font size=-1 color=red> 32: </font>A tutorial script.
+<font size=-1 color=red> 33: </font>
+<font size=-1 color=red> 34: </font>=head1 PARAMETERS
+<font size=-1 color=red> 35: </font>
+<font size=-1 color=red> 36: </font> [PF_INT32, "size", "Img size", 100],
+<font size=-1 color=red> 37: </font> [PF_COLOR, "color", "Img color", [255,127,0]]
+<font size=-1 color=red> 38: </font>
+<font size=-1 color=red> 39: </font>=head1 AUTHOR
+<font size=-1 color=red> 40: </font>
+<font size=-1 color=red> 41: </font>Dov Grobgeld
+<font size=-1 color=red> 42: </font>
+<font size=-1 color=red> 43: </font>=head1 DATE
+<font size=-1 color=red> 44: </font>
+<font size=-1 color=red> 45: </font>2004-03-27
+<font size=-1 color=red> 46: </font>
+<font size=-1 color=red> 47: </font>=head1 LICENSE
+<font size=-1 color=red> 48: </font>
+<font size=-1 color=red> 49: </font>Dov Grobgeld (c) </pre></table><br>
+
+Most of these commands are directly copied out the PDB. <p>
+
+This script shows the essential steps of producing a stand-alone
+script:
+<table>
+ <tr><th>line(s)</th><th>Description</th>
+ <tr><td>7</td><td> Registration of the extension</td></tr>
+ <tr><td>9</td><td> Creating a new image.</td></tr>
+ <tr><td>11</td><td> Creating one or more layers.</td></tr>
+ <tr><td>12</td><td> Attaching the layer to the image. </td></tr>
+ <tr><td>13-14</td><td> Do some painting operations in the layers. </td></tr>
+ <tr><td>15</td><td> Display the new image</td></tr>
+ <tr><td>16</td><td> Return the image to the caller</td></tr>
+</table>
+
+To test the script, save it in the directory <tt>$HOME/.gimp-2.8/plug-ins</tt>.
+It must then be made executable through the command:
+<pre>
+ chmod +x $HOME/.gimp-2.8/plug-ins/uni
</pre>
-<p class="images">
- <img src="hello-world1.png" alt=""/>
-</p>
+
+Then start GIMP. It is generally a good idea to test the
+syntax of the script with <tt>perl -c</tt> before starting GIMP.
+(A more official way to add scripts is to use the <tt>gimptool-2.0
+--install-bin</tt> command).
<p>
- The result above:
-</p>
+<b>Note:</b> Due to the way GIMP works,
+it is not possible to add scripts once GIMP is running. On the other hand,
+it is possible to change a script which has already been registered, as
+long as the parameters don't change.<p>
+
+The script is now accessible through the menu system through the
+<b>File/Create/Tutorial</b> top menu:
+<center>
+ <img src="uni-menu.png">
+</center>
<p>
- The script makes use of the function xlfd_size which extracts the size of the font from the X11 font name.
- This is necessary as the authors of gimp_text_fontname decided that the font size within the fontname is
ignored.
-</p>
+When choosing this menu entry the following screen is popped up:<p>
+<center>
+ <img src="uni-entry.png">
+</center>
<p>
- One thing to note in this script is that the text that is created on line 24 is a floating layer, than
needs to be anchored to its parent layer.
- This is done in line 27 through the call to gimp_floating_sel_anchor().
-</p>
+Choosing the default values results in the image:
<p>
- This script suffers from the problem that the image size is unrelated to the text size.
- This is taken care of in the following more complex example which shows the basic steps for a logo
generating script.
-</p>
-<ul>
- <li>Creation of an image arbitrary size</li>
- <li>Creation of a background drawable of an arbitrary size</li>
- <li>Creation of text layer which exactly fits the text with the command gimp_text_fontname().</li>
- <li>Resizing the image and the background to the size of the text layer.</li>
-</ul>
+<center>
+<img src="uni-result.png">
+</center>
+
+<h2><a name="SEC6">6. Object oriented syntax</a></h2>
+
+ Gimp-Perl provides an alternative object-oriented syntax for the
+ image and the drawable commands. Here is a table showing the procedural
+ vs the object oriented syntax for a few commands:<p>
+
+ <table>
+ <tr><th bgcolor=#E0E0E0>procedural syntax
+ <th bgcolor=#E0E0E0>object oriented syntax
+ <tr><td bgcolor=#FFE0E0>gimp_image_insert_layer($drw,0,0);
+ <td bgcolor=#FFE0E0>$img->insert_layer($drw,0,0);
+ <tr><td bgcolor=#FFE0E0>gimp_drawable_width($drw);
+ <td bgcolor=#FFE0E0>$drw->width;
+ </table>
+ <p>
+ The substitution rule for converting a PDB turning into a method is
+ as simple as erasing ``<tt>gimp_image_</tt>'' (or sometimes
+ ``<tt>gimp_</tt>'') from the beginning of the function call and
+ calling this method through the image object. Similarly for the
+ <tt>gimp_drawable_...</tt> functions. See the <a
+ href="http://search.cpan.org/dist/Gimp/Gimp.pm#OBJECT-ORIENTED_SYNTAX";>Gimp-Perl
+ docs</a> for more detail.<p>
+
+ Note that the object-oriented syntax appears to be only syntactic
+ sugar that makes the calling syntax cleaner. The error messages are
+ still given in the procedural format. What is going on is that GIMP,
+ and the library on which it is implemented (Glib), use C in an
+ object-oriented fashion.
+
+<h2><a name="SEC7">7. Painting areas with selections</a></h2>
+
+In the <tt>uni</tt> script the function <tt>gimp_edit_fill</tt> was called
+to fill the whole image. Looking at the info for
+<tt>gimp_edit_fill</tt> in the DB browser we find the following:
+<p><table><tr><td bgcolor=#e0e0e0>
+<table>
+<tr><th valign=top align=right>Name:</th><td bgcolor=#e0e0ff colspan=3>gimp_edit_fill</td></tr>
+<tr><th valign=top align=right>Blurb:</th><td valign=top colspan=3>Fill selected area of drawable</td></tr>
+<tr>
+<th valign=top align=right valign=top>In:</th><td valign=top>DRAWABLE</td><td valign=top>drawable</td><td
valign=top>The drawable to fill from</td>
+</tr>
+<tr>
+<th valign=top></th><td valign=top>INT32</td><td valign=top>fill_type</td><td valign=top>The type of fill {
FOREGROUND-FILL (0), BACKGROUND-FILL (1), WHITE-FILL (2), TRANSPARENT-FILL (3), PATTERN-FILL (4), NO-FILL (5)
}</td>
+</tr>
+<tr><th valign=top valign=top>Help:</th><td colspan=3>This procedure fills the specified drawable with the
fill mode. If the fill mode is foreground, the current foreground color is used. If the fill mode is
background, the current background color is used. Other fill modes should not be used. This procedure only
affects regions within a selection if there is a selection active. If you want to fill the whole drawable,
regardless of the selection, use 'gimp-drawable-fill'.</td></tr></table>
+</table></p>
+
+
<p>
- The result is an image composed of two layers; a transparent text layer on top of a uniform background.
-</p>
-
-<pre class="code">
-#!/usr/local/bin/perl
-use Gimp ":auto";
-use Gimp::Fu;
-sub basic_logo {
- my($font, $border, $text, $bgcolor, $fgcolor) = @_;
- # Create a new image of an arbitrary size with
- $img = gimp_image_new(100, 100, RGB);
- # Create a new layer for the background of arbitrary size, and
- # add it to the image
- my $background = gimp_layer_new($img, 100, 100,
- RGB, "Background", 100,
- NORMAL_MODE);
- gimp_image_add_layer($background, 1);
- # Choose color of text
- gimp_palette_set_foreground($fgcolor);
- # Create the text layer. Using -1 as the drawable creates a new layer.
- my $text_layer = gimp_text_fontname($img, -1, 0, 0, $text,
- $border, 1,
- xlfd_size($font), $font);
- # Get size of the text drawable and resize the image and the
- # background layer to this size.
- my($width, $height) = ($text_layer->width, $text_layer->height);
- gimp_image_resize($img, $width, $height, 0, 0);
- gimp_layer_resize($background, $width, $height, 0, 0);
- # Fill the background layer now when it has the right size.
- gimp_palette_set_background($bgcolor);
- gimp_edit_fill($background, BG_IMAGE_FILL);
- return $img;
-}
-# register the script
-register "basic_logo", "basic logo", "basic logo",
- "Dov Grobgeld", "Dov Grobgeld",
- "1999-06-09",
- "<Toolbox>/Xtns/Perl-Fu/Tutorial/Basic Logo",
- "",
- [
- [PF_FONT, "font", "font", "-*-utopia-bold-r-*-*-70-*-*-*-*-*-*-*"],
- [PF_INT, "border", "border", "10"],
- [PF_STRING, "text", "text", "Hello world!"],
- [PF_COLOR, "bg_color", "Background color", [40,180,160]],
- [PF_COLOR, "fg_color", "Background color", [255,255,0]],
- ],
- \&basic_logo;
-# Handle over control to GIMP
-exit main();
-</pre>
+Thus, if a selection is active when <tt>gimp_edit_fill</tt>
+is called, only the selection is painted. Note also that you must
+substitute "_" for "-" in the names.
+
+<p>There are lots of ways of choosing a selection as can be seen
+when searching for a ``select'' in the PDB. The example below uses
+<tt>gimp_image_select_rectangle</tt>, whose entry in the PDB looks as follows:
+<p><table><tr><td bgcolor=#e0e0e0>
+<table>
+<tr><th valign=top align=right>Name:</th><td bgcolor=#e0e0ff colspan=3>gimp-image-select-rectangle</td></tr>
+<tr><th valign=top align=right>Blurb:</th><td valign=top colspan=3>Create a rectangular selection over the
specified image</td></tr>
+<tr>
+<th valign=top align=right valign=top>In:</th><td valign=top>IMAGE</td><td valign=top>image</td><td
valign=top>The image</td>
+</tr>
+<tr>
+<th valign=top></th><td valign=top>INT32</td><td valign=top>operation</td><td valign=top>The selection
operation { CHANNEL-OP-ADD (0), CHANNEL-OP-SUBTRACT (1), CHANNEL-OP-REPLACE (2), CHANNEL-OP-INTERSECT (3)
}</td>
+</tr>
+<tr>
+<th valign=top></th><td valign=top>FLOAT</td><td valign=top>x</td><td valign=top>x coordinate of upper-left
corner of rectangle</td>
+</tr>
+<tr>
+<th valign=top></th><td valign=top>FLOAT</td><td valign=top>y</td><td valign=top>y coordinate of upper-left
corner of rectangle</td>
+</tr>
+<tr>
+<th valign=top></th><td valign=top>FLOAT</td><td valign=top>width</td><td valign=top>the width of the
rectangle: width >= 0</td>
+</tr>
+<tr>
+<th valign=top></th><td valign=top>FLOAT</td><td valign=top>height</td><td valign=top>the height of the
rectangle: width >= 0</td>
+</tr>
+<tr><th valign=top valign=top>Help:</th><td colspan=3>This tool creates a rectangular selection over the
specified image. The rectangular region can be either added to, subtracted from, or replace the contents of
the previous selection mask. This procedure is affected by the following context setters:
'gimp-context-set-feather', 'gimp-context-set-feather-radius'.</td></tr></table>
+</table></p>
+
+
+A simple use of this function which selects a rectangle in the middle
+of an image and paints that rectangle with a user defined color.
+This example also introduces a couple of new features we haven't seen
+before:
+<UL>
+ <LI> The script is associated with an image since its menu
+ path starts with "<Image>/...". Note that as a result of this
+ the callback sub in line 6 receives two additional
+ parameters, the active image and the selected drawable.</LI>
+
+ <LI> The use of the PDB functions <tt>gimp_image_undo_group_start</tt>
+ and <tt>gimp_image_undo_group_end</tt>. These functions declare
+ an undo group. When an undo is done on the image, instead of
+ having the individual operators undo, all the actions between
+ the undo start and the undo end calls will be undone at once.</LI>
+</UL>
+
+<table border><tr><th bgcolor=#E0E0FF><a href="paint-select">paint-select</a><tr><td
bgcolor=#FFE0E0><pre><font size=-1 color=red> 1: </font>#!/usr/bin/perl -w
+<font size=-1 color=red> 2: </font>
+<font size=-1 color=red> 3: </font>use Gimp;
+<font size=-1 color=red> 4: </font>use Gimp::Fu;
+<font size=-1 color=red> 5: </font>
+<font size=-1 color=red> 6: </font>podregister {
+<font size=-1 color=red> 7: </font> my ($width, $height) = ($image->width, $image->height);
+<font size=-1 color=red> 8: </font> # Select a rectangle inside the image and paint it with color
+<font size=-1 color=red> 9: </font> $image->undo_group_start;
+<font size=-1 color=red> 10: </font> $image->select_rectangle(
+<font size=-1 color=red> 11: </font> CHANNEL_OP_REPLACE, $width/4, $height/4, $width/2, $height/2,
+<font size=-1 color=red> 12: </font> );
+<font size=-1 color=red> 13: </font> Gimp::Context->set_background($color);
+<font size=-1 color=red> 14: </font> $drawable->edit_fill(BACKGROUND_FILL);
+<font size=-1 color=red> 15: </font> $image->selection_none;
+<font size=-1 color=red> 16: </font> $image->undo_group_end;
+<font size=-1 color=red> 17: </font> ();
+<font size=-1 color=red> 18: </font>};
+<font size=-1 color=red> 19: </font>
+<font size=-1 color=red> 20: </font>exit main;
+<font size=-1 color=red> 21: </font>__END__
+<font size=-1 color=red> 22: </font>
+<font size=-1 color=red> 23: </font>=head1 NAME
+<font size=-1 color=red> 24: </font>
+<font size=-1 color=red> 25: </font>img_paint_select - Paints the selection
+<font size=-1 color=red> 26: </font>
+<font size=-1 color=red> 27: </font>=head1 SYNOPSIS
+<font size=-1 color=red> 28: </font>
+<font size=-1 color=red> 29: </font><Image>/Filters/Tutorial/Paint Select
+<font size=-1 color=red> 30: </font>
+<font size=-1 color=red> 31: </font>=head1 DESCRIPTION
+<font size=-1 color=red> 32: </font>
+<font size=-1 color=red> 33: </font>Paints the selection
+<font size=-1 color=red> 34: </font>
+<font size=-1 color=red> 35: </font>=head1 PARAMETERS
+<font size=-1 color=red> 36: </font>
+<font size=-1 color=red> 37: </font> [PF_COLOR, "color", "Rectangle color", [0,0,255]],
+<font size=-1 color=red> 38: </font>
+<font size=-1 color=red> 39: </font>=head1 RETURN VALUES
+<font size=-1 color=red> 40: </font>
+<font size=-1 color=red> 41: </font>=head1 IMAGE TYPES
+<font size=-1 color=red> 42: </font>
+<font size=-1 color=red> 43: </font>*
+<font size=-1 color=red> 44: </font>
+<font size=-1 color=red> 45: </font>=head1 AUTHOR
+<font size=-1 color=red> 46: </font>
+<font size=-1 color=red> 47: </font>Dov Grobgeld
+<font size=-1 color=red> 48: </font>
+<font size=-1 color=red> 49: </font>=head1 DATE
+<font size=-1 color=red> 50: </font>
+<font size=-1 color=red> 51: </font>1999-05-14
+<font size=-1 color=red> 52: </font>
+<font size=-1 color=red> 53: </font>=head1 LICENSE
+<font size=-1 color=red> 54: </font>
+<font size=-1 color=red> 55: </font>Dov Grobgeld </pre></table><br>
+
+The result when run on our previous image:
+<center>
+<img src="paint-select.png">
+</center>
+
+<h3><a name="SEC7.1">7.1. Complex selections</a></h3>
-<p class="images">
- <img src="basic-logo-dialog.png" alt=""/>
- <img src="basic-logo.png" alt=""/>
-</p>
+ Besides rectangular selections elliptical selections may also be
+ created through the PDB functions <tt>gimp_image_select_ellipse</tt>
+ and <tt>gimp_image_select_polygon</tt> which allows the selection of
+ ellipses and polygons.
+ <p>
+ More complex selections may be created through the channel mechanism.
+ The PDB <tt>gimp_channel_new()</tt> (<tt>Gimp::Channel->new</tt>)
+ creates a new channel. The channel is a drawable that may be painted
+ into, just like any other drawable, but with the difference that
+ it is always a grey level image. Once the channel is finished, the
+ channel may be loaded into the selection through the PDB function
+ <tt>gimp_image_select_item</tt>.
+ <p>
+ Search for ``select'' in the DB Browser to see a list of all the
+ selection related functions.
+
+<h3><a name="SEC7.2">7.2. Loops</a></h3>
+
+In perl it is trivial to write loops that together with the various
+selection tools gives powerful creative possibilities. Here is
+an example that mixes colors in circles. There is nothing really new
+here, but it shows the power of what we have described above.
+<table border><tr><th bgcolor=#E0E0FF><a href="circles">circles</a><tr><td bgcolor=#FFE0E0><pre><font
size=-1 color=red> 1: </font>#!/usr/bin/perl
+<font size=-1 color=red> 2: </font>
+<font size=-1 color=red> 3: </font>use Gimp;
+<font size=-1 color=red> 4: </font>use Gimp::Fu;
+<font size=-1 color=red> 5: </font>
+<font size=-1 color=red> 6: </font>podregister {
+<font size=-1 color=red> 7: </font> # Create the background
+<font size=-1 color=red> 8: </font> my $img = Gimp::Image->new($size, $size, RGB);
+<font size=-1 color=red> 9: </font> $layer = $img->layer_new($size, $size, RGB, "Layer 1", 100,
NORMAL_MODE);
+<font size=-1 color=red> 10: </font> $img->insert_layer($layer, -1, 0);
+<font size=-1 color=red> 11: </font> Gimp::Context->set_background($bgcolor);
+<font size=-1 color=red> 12: </font> $layer->edit_fill(BACKGROUND_FILL);
+<font size=-1 color=red> 13: </font> my $ncircles = int($size/$radius/2);
+<font size=-1 color=red> 14: </font> for ($i=0; $i<$ncircles; $i++) {
+<font size=-1 color=red> 15: </font> for ($j=0; $j<$ncircles; $j++) {
+<font size=-1 color=red> 16: </font> # Select a circle
+<font size=-1 color=red> 17: </font> $img->select_ellipse(
+<font size=-1 color=red> 18: </font> CHANNEL_OP_REPLACE, $i*$radius*2, $j*$radius*2, $radius*2, $radius*2
+<font size=-1 color=red> 19: </font> );
+<font size=-1 color=red> 20: </font> my $color = [$i*30, ($ncircles-$j)*25, ($i+$j)*15]; # mix colors
+<font size=-1 color=red> 21: </font> Gimp::Context->set_background($color);
+<font size=-1 color=red> 22: </font> $layer->edit_fill(BACKGROUND_FILL);
+<font size=-1 color=red> 23: </font> }
+<font size=-1 color=red> 24: </font> }
+<font size=-1 color=red> 25: </font> Gimp::Display->new($img);
+<font size=-1 color=red> 26: </font> return $img;
+<font size=-1 color=red> 27: </font>};
+<font size=-1 color=red> 28: </font>
+<font size=-1 color=red> 29: </font>exit main;
+<font size=-1 color=red> 30: </font>__END__
+<font size=-1 color=red> 31: </font>
+<font size=-1 color=red> 32: </font>=head1 NAME
+<font size=-1 color=red> 33: </font>
+<font size=-1 color=red> 34: </font>circles - a loop
+<font size=-1 color=red> 35: </font>
+<font size=-1 color=red> 36: </font>=head1 SYNOPSIS
+<font size=-1 color=red> 37: </font>
+<font size=-1 color=red> 38: </font><Image>/File/Create/Tutorial/Circles
+<font size=-1 color=red> 39: </font>
+<font size=-1 color=red> 40: </font>=head1 DESCRIPTION
+<font size=-1 color=red> 41: </font>
+<font size=-1 color=red> 42: </font>a loop
+<font size=-1 color=red> 43: </font>
+<font size=-1 color=red> 44: </font>=head1 PARAMETERS
+<font size=-1 color=red> 45: </font>
+<font size=-1 color=red> 46: </font> [PF_INT32, "size", "Image size", 100],
+<font size=-1 color=red> 47: </font> [PF_COLOR, "bgcolor", "Background color", [40,180,60]],
+<font size=-1 color=red> 48: </font> [PF_INT32, "radius", "Circle radius", 10]
+<font size=-1 color=red> 49: </font>
+<font size=-1 color=red> 50: </font>=head1 AUTHOR
+<font size=-1 color=red> 51: </font>
+<font size=-1 color=red> 52: </font>Dov
+<font size=-1 color=red> 53: </font>
+<font size=-1 color=red> 54: </font>=head1 DATE
+<font size=-1 color=red> 55: </font>
+<font size=-1 color=red> 56: </font>1999-05-14
+<font size=-1 color=red> 57: </font>
+<font size=-1 color=red> 58: </font>=head1 LICENSE
+<font size=-1 color=red> 59: </font>
+<font size=-1 color=red> 60: </font>Dov </pre></table><br>
+The result:
+<center>
+<img src="circles.png">
+</center>
+
+<h2><a name="SEC8">8. Creating text</a></h2>
+
+
+<h3><a name="SEC8.1">8.1. Hello World - writing text in an image</a></h3>
+
+
+To create text the PDB function <tt>gimp_text_fontname()</tt> may be used.
+
+<p> Here is an example of a script that creates an image containing
+"Hello world".
+<table border><tr><th bgcolor=#E0E0FF><a href="hello-world1">hello-world1</a><tr><td
bgcolor=#FFE0E0><pre><font size=-1 color=red> 1: </font>#!/usr/bin/perl
+<font size=-1 color=red> 2: </font>
+<font size=-1 color=red> 3: </font>use Gimp;
+<font size=-1 color=red> 4: </font>use Gimp::Fu;
+<font size=-1 color=red> 5: </font>
+<font size=-1 color=red> 6: </font>podregister {
+<font size=-1 color=red> 7: </font> my $img = Gimp::Image->new(350, 100, RGB);
+<font size=-1 color=red> 8: </font> my $drw = $img->layer_new($img->width, $img->height,
+<font size=-1 color=red> 9: </font> RGB, "BG", 100, NORMAL_MODE);
+<font size=-1 color=red> 10: </font> $img->insert_layer($drw, -1, 0);
+<font size=-1 color=red> 11: </font> Gimp::Context->set_background("black");
+<font size=-1 color=red> 12: </font> $drw->edit_fill(BACKGROUND_FILL);
+<font size=-1 color=red> 13: </font> Gimp::Context->set_foreground([255,255,0]); # Choose color of text
+<font size=-1 color=red> 14: </font> # Create the text
+<font size=-1 color=red> 15: </font> my $textlayer = $drw->text_fontname(0, 0, $text, 10, 1, $size,
POINTS, $font);
+<font size=-1 color=red> 16: </font> $textlayer->floating_sel_anchor;
+<font size=-1 color=red> 17: </font> Gimp::Display->new($img);
+<font size=-1 color=red> 18: </font> return $img;
+<font size=-1 color=red> 19: </font>};
+<font size=-1 color=red> 20: </font>
+<font size=-1 color=red> 21: </font>exit main;
+<font size=-1 color=red> 22: </font>__END__
+<font size=-1 color=red> 23: </font>
+<font size=-1 color=red> 24: </font>=head1 NAME
+<font size=-1 color=red> 25: </font>
+<font size=-1 color=red> 26: </font>hello_world1 - basic text
+<font size=-1 color=red> 27: </font>
+<font size=-1 color=red> 28: </font>=head1 SYNOPSIS
+<font size=-1 color=red> 29: </font>
+<font size=-1 color=red> 30: </font><Image>/File/Create/Tutorial/Basic text 1
+<font size=-1 color=red> 31: </font>
+<font size=-1 color=red> 32: </font>=head1 DESCRIPTION
+<font size=-1 color=red> 33: </font>
+<font size=-1 color=red> 34: </font>basic text
+<font size=-1 color=red> 35: </font>
+<font size=-1 color=red> 36: </font>=head1 PARAMETERS
+<font size=-1 color=red> 37: </font>
+<font size=-1 color=red> 38: </font> [PF_FONT, "font", "Font", "Sans"],
+<font size=-1 color=red> 39: </font> [PF_INT32, "size", "Font size", 70],
+<font size=-1 color=red> 40: </font> [PF_STRING, "text", "Text", "Hello world!"]
+<font size=-1 color=red> 41: </font>
+<font size=-1 color=red> 42: </font>=head1 AUTHOR
+<font size=-1 color=red> 43: </font>
+<font size=-1 color=red> 44: </font>Dov
+<font size=-1 color=red> 45: </font>
+<font size=-1 color=red> 46: </font>=head1 DATE
+<font size=-1 color=red> 47: </font>
+<font size=-1 color=red> 48: </font>2004-03-27
+<font size=-1 color=red> 49: </font>
+<font size=-1 color=red> 50: </font>=head1 LICENSE
+<font size=-1 color=red> 51: </font>
+<font size=-1 color=red> 52: </font>Dov </pre></table><br>
+
+The result:
+<center>
+<img src="hello-world1.png">
+</center>
+One thing to note in this script is that the text that is created on
+line 15 is a <i>floating layer</i>, that needs to be anchored to its
+parent layer. This is done in line 16 through the call to
+<tt>gimp_floating_sel_anchor()</tt>.<p>
+
+This script suffers from the problem that the image size is unrelated
+to the text size. This is taken care of in the following more
+complex example which shows the basic steps for a logo generating
+script:
+<UL>
+ <LI> Creation of an image of arbitrary size </LI>
+ <LI> Creation of a background drawable of an arbitrary size </LI>
+ <LI> Creation of text layer which exactly fits the text with the command
+ <tt>gimp_text_fontname</tt>.
+ <LI> Resizing the image and the background to the size of the text layer. </LI>
+</UL>
+The result is an image composed of two layers; a transparent text layer
+on top of a uniform background.
<p>
- Note the special syntax of gimp_image_text_fontname() in line 23 in basic-logo with an
- image specified for a first parameter, and the drawable = -1.
- This is in contradiction to the rule above that the image should not be specified for PDB
- functions that take both an image and a drawable as the first two parameters.
- But since the drawable=-1, which has no image related to it, an image explicitly be provided.
- The special case drawable=-1 means that instead of creating a floating layer,
+
+<table border><tr><th bgcolor=#E0E0FF><a href="basic-logo">basic-logo</a><tr><td bgcolor=#FFE0E0><pre><font
size=-1 color=red> 1: </font>#!/usr/bin/perl
+<font size=-1 color=red> 2: </font>
+<font size=-1 color=red> 3: </font>use Gimp;
+<font size=-1 color=red> 4: </font>use Gimp::Fu;
+<font size=-1 color=red> 5: </font>
+<font size=-1 color=red> 6: </font>podregister {
+<font size=-1 color=red> 7: </font> my $img = Gimp::Image->new(100, 100, RGB); # any old size
+<font size=-1 color=red> 8: </font> my $background = $img->layer_new(
+<font size=-1 color=red> 9: </font> 100, 100, RGB, "Background", 100, NORMAL_MODE
+<font size=-1 color=red> 10: </font> );
+<font size=-1 color=red> 11: </font> $img->insert_layer($background, 0, 0);
+<font size=-1 color=red> 12: </font> Gimp::Context->set_foreground($fgcolor); # Choose color of text
+<font size=-1 color=red> 13: </font> # Create the text layer. Using -1 as the drawable creates a new
layer.
+<font size=-1 color=red> 14: </font> my $text_layer = $img->text_fontname(
+<font size=-1 color=red> 15: </font> -1, 0, 0, $text, $border, 1, $size, POINTS, $font
+<font size=-1 color=red> 16: </font> );
+<font size=-1 color=red> 17: </font> # Get size of the text drawable and resize the image and the
+<font size=-1 color=red> 18: </font> # background layer to this size.
+<font size=-1 color=red> 19: </font> my ($width, $height) = ($text_layer->width,
$text_layer->height);
+<font size=-1 color=red> 20: </font> $img->resize($width, $height, 0, 0);
+<font size=-1 color=red> 21: </font> $background->resize($width, $height, 0, 0);
+<font size=-1 color=red> 22: </font> # Fill the background layer now when it has the right size.
+<font size=-1 color=red> 23: </font> Gimp::Context->set_background($bgcolor);
+<font size=-1 color=red> 24: </font> $background->edit_fill(BACKGROUND_FILL);
+<font size=-1 color=red> 25: </font> Gimp::Display->new($img);
+<font size=-1 color=red> 26: </font> return $img;
+<font size=-1 color=red> 27: </font>};
+<font size=-1 color=red> 28: </font>
+<font size=-1 color=red> 29: </font>exit main;
+<font size=-1 color=red> 30: </font>__END__
+<font size=-1 color=red> 31: </font>
+<font size=-1 color=red> 32: </font>=head1 NAME
+<font size=-1 color=red> 33: </font>
+<font size=-1 color=red> 34: </font>basic_logo - Basic logo
+<font size=-1 color=red> 35: </font>
+<font size=-1 color=red> 36: </font>=head1 SYNOPSIS
+<font size=-1 color=red> 37: </font>
+<font size=-1 color=red> 38: </font><Image>/File/Create/Tutorial/Basic Logo
+<font size=-1 color=red> 39: </font>
+<font size=-1 color=red> 40: </font>=head1 DESCRIPTION
+<font size=-1 color=red> 41: </font>
+<font size=-1 color=red> 42: </font>Make a basic logo.
+<font size=-1 color=red> 43: </font>
+<font size=-1 color=red> 44: </font>=head1 PARAMETERS
+<font size=-1 color=red> 45: </font>
+<font size=-1 color=red> 46: </font> [PF_FONT, "font", "Font", "Utopia Bold"],
+<font size=-1 color=red> 47: </font> [PF_INT32, "size", "Font size", 10],
+<font size=-1 color=red> 48: </font> [PF_INT32, "border", "Border", 10],
+<font size=-1 color=red> 49: </font> [PF_STRING, "text", "Text", "Hello world!"],
+<font size=-1 color=red> 50: </font> [PF_COLOR, "bgcolor", "Background color", [40,180,160]],
+<font size=-1 color=red> 51: </font> [PF_COLOR, "fgcolor", "Foreground color", [255,255,0]],
+<font size=-1 color=red> 52: </font>
+<font size=-1 color=red> 53: </font>=head1 AUTHOR
+<font size=-1 color=red> 54: </font>
+<font size=-1 color=red> 55: </font>Dov Grobgeld
+<font size=-1 color=red> 56: </font>
+<font size=-1 color=red> 57: </font>=head1 DATE
+<font size=-1 color=red> 58: </font>
+<font size=-1 color=red> 59: </font>2004-03-27
+<font size=-1 color=red> 60: </font>
+<font size=-1 color=red> 61: </font>=head1 LICENSE
+<font size=-1 color=red> 62: </font>
+<font size=-1 color=red> 63: </font>Dov Grobgeld </pre></table><br>
+ <p>
+ Note the special syntax of <tt>gimp_image_text_fontname</tt>
+ in line 14 in <tt>basic-logo</tt> with the drawable = -1. The special
+ case drawable=-1 means that instead of creating a floating layer,
a new image layer will be created.
-</p>
-<p>
- The result shown in the dialog and the resulting image above.
-</p>
-<h2>8. Floating selections</h2>
-<p>
- When a region has been selected through one of the selection routines, the area outlined
- by the selection may be copied to the cut-buffer through the gimp_edit_copy command.
- The cut-buffer may subsequently be pasted into a different layer through the gimp_edit_paste command.
- When a layer is pasted it becomes a floating selection. This floating selection may be moved to its
required position by the command gimp_layer_set_offsets,
- and finally it is pasted by the gimp_floating_sel_anchor command. Another way of determining the position
of a pasted layer is to create a selection in the
- target image before the cut-buffer is pasted.
-</p>
-<p>
- This is illustrated in the following program, which works on one image and takes as a parameter an another
image,
- which it concatenates to the right of the first image. The lines 28-38 shows how the second image is
copied and glued into the first image.
-</p>
-<pre class="code">
-#!/usr/local/bin/perl
-use Gimp qw( :auto );
-use Gimp::Fu;
-sub horiz_cat {
- my($img1, $drw1, $drw2) = @_;
- # Get image 2
- $img1 = $drw1->image();
- my $img2 = gimp_drawable_image($drw2);
- # Get sizes through OO syntax
- my($w1, $h1) = ($drw1->width, $drw1->height);
- my($w2, $h2) = ($drw2->width, $drw2->height);
- # The new height is the maximum height of the images
- my $hmax = $h1 > $h2 ? $h1 : $h2;
- # Create an undo group
- gimp_undo_push_group_start($img1);
- # Resize the drawable layer to make room for the img
- gimp_image_resize($img1, $w1+$w2, $hmax, 0, ($hmax-$h1)/2);
- gimp_layer_resize($drw1, $w1+$w2, $hmax, 0, ($hmax-$h1)/2);
- # Copy $drawable2 and paste it into the new space of $drawable1
- # select all of img2
- gimp_selection_all($img2);
- # copy it to the clipboard
- gimp_edit_copy($drw2);
- # make a selection in img 1 in the position where it is to be pasted
- gimp_rect_select($img1, $w1, ($hmax-$h2)/2, $w2, $h2, 0,0,0);
- # paste and then anchor it
- my $floating_layer = gimp_edit_paste($drw1, 0);
- gimp_floating_sel_anchor($floating_layer);
- # Close the undo group
- gimp_undo_push_group_start($img1);
- # Update the display
- gimp_displays_flush();
- return undef;
-}
-# register the script
-register "horiz_cat", "Horizontal concat", "Horizontal Concat",
- "Dov Grobgeld", "Dov Grobgeld",
- "1999-05-4",
- "<Image>/Perl-Fu/Tutorial/Horizontal Concat",
- "*",
- [
- [PF_DRAWABLE, "drawable", "Drawable to concatenate", undef],
- ],
- \&horiz_cat;
-# Handle over control to GIMP
-exit main();
-</pre>
+ <p>
+ The dialog and the resulting image:
+ <p>
+<center>
+<img src="basic-logo-dialog.png"><img src="tpix.gif" width=20>
+<img src="basic-logo.png">
+</center>
+ <p>
-<h2>9. The Perl Server and stand-alone scripts</h2>
-<p>
- So far the scripts have all been started from the menu structure within GIMP.
- But there is another possibility and that is to run the scripts from the command line
- as a normal Perl program. When run this way the script tries to connect to the Perl-Server, and if it
fails, it will launch GIMP on its own.
- If you plan to run several scripts this way, it is obviously much faster to run the Perl-Server since
launching GIMP takes quite a bit of time.
- The Perl-server may be started from the Xtns menu.
-</p>
-<p>
- When a Perl-Fu script is run from the command line, the result is the same as when it is run through the
menus,
- except that it may be run with the --output (or -o) parameter in which case it will save the result to a
file instead of displaying it within GIMP.
- This is great for batch creation of logos, etc.
-</p>
-<p>
- The filename for the --output has some special magic that allows to set some special image saving
parameters, like interlace, quality factor, etc.
- See the Gimp::Fu man page for details. Note that the normal rules about image and file types are still
valid, thus, for example, in order to save
- an image as a gif file, it must be converted from RGB to an indexed image. Currently this functionality
must be included in each script,
- but it is possible that a future version of Gimp::Fu, will include this conversion as an option.
-</p>
-<p>
- Here are two invocations of the scripts declared above, but with output written to a jpg file and a png
file. As we said above,
- we can't save them as gif as the scripts do not index the images.
-</p>
-<p>
- Perl-GIMP-from-shell:
-</p>
-<pre>uni -o /tmp/uni.ppm -size 100 -color "#5050ff"</pre>
-<pre>basic-logo -font '-*-utopia-*-r-*-*-100-*-*-*-*-*-*-*' -o /tmp/bl.ppm -text "Perl rules"</pre>
-<p>
- <b>Note:</b> that due to a bug in my version of GIMP/Perl I was not able to output images in any format
but in ppm and gif. Your mileage may vary.
- Another important use of this interface is that it enables running of the Perl debugger on the Perl-Fu
scripts.
-</p>
-<p>
- <b>Note:</b>The image is saved to the directory where GIMP was started from
- and not to the directory in which the scripts were invoked, unless a complete path is given!
-</p>
+<h2><a name="SEC9">9. Floating selections</a></h2>
-<h2>10. End notes</h2>
-<p>
- This tutorial has covered only a small part of the possibilities available to a script writer.
- In particular the following issues available to Gimp::Perl scripts have not been covered:
-</p>
-<ul>
- <li>The possibility of writing customized Gtk interfaces.</li>
- <li>Writing fullfledged plug-ins that manipulate the tile data through the Perl Data Language (PDL)
module.</li>
- <li>Using Perl::GIMP in a CGI environment.</li>
- <li>How to fill with gradients in a plugin</li>
- <li>How to do "free selections".</li>
-</ul>
+ When a region has been selected through one of the selection routines,
+ the area outlined by the selection may be copied to the cut-buffer
+ through the <tt>gimp_edit_copy</tt> command. The cut-buffer may
+ subsequently be pasted into a different layer through the
+ <tt>gimp_edit_paste</tt> command. When a layer is pasted it becomes
+ a floating selection. This floating selection may be moved to
+ its required position by the command <tt>gimp_layer_set_offsets</tt>,
+ and finally it is pasted by the <tt>gimp_floating_sel_anchor</tt>
+ command. Another way of
+ determining the position of a pasted layer is to create a selection in
+ the target image before the cut-buffer is pasted. <p>
-<p>
- The original tutorial can be found <a href="http://imagic.weizmann.ac.il/~dov/gimp/perl-tut.html";>here</a>
and an updated version for GIMP 2.0 can be found <a
href="http://imagic.weizmann.ac.il/~dov/gimp/perl-tut-2.0/";>here</a>.
-</p>
+ This is illustrated in the following program, which works on one image
+ and takes as a parameter another image, which it concatenates to
+ the right of the first image. The lines 28-38 shows how the second
+ image is copied and glued into the first image.<p>
+ <table border><tr><th bgcolor=#E0E0FF><a href="horiz-cat">horiz-cat</a><tr><td bgcolor=#FFE0E0><pre><font
size=-1 color=red> 1: </font>#!/usr/bin/perl
+<font size=-1 color=red> 2: </font>
+<font size=-1 color=red> 3: </font>use Gimp;
+<font size=-1 color=red> 4: </font>use Gimp::Fu;
+<font size=-1 color=red> 5: </font>
+<font size=-1 color=red> 6: </font>podregister {
+<font size=-1 color=red> 7: </font> die "Must select layer.\n" unless $drawable->is_layer;
+<font size=-1 color=red> 8: </font> $drawable->become('Gimp::Layer');
+<font size=-1 color=red> 9: </font> my $image2 = $drawable2->get_image;
+<font size=-1 color=red> 10: </font> my ($w1, $h1) = ($drawable->width, $drawable->height);
+<font size=-1 color=red> 11: </font> my ($w2, $h2) = ($drawable2->width, $drawable2->height);
+<font size=-1 color=red> 12: </font> my $hmax = $h1 > $h2 ? $h1 : $h2; # new height is maximum height
of the images
+<font size=-1 color=red> 13: </font> $image->undo_group_start; # Create an undo group
+<font size=-1 color=red> 14: </font> # Resize the drawable layer to make room for the image
+<font size=-1 color=red> 15: </font> $image->resize($w1+$w2, $hmax, 0, ($hmax-$h1)/2);
+<font size=-1 color=red> 16: </font> $drawable->resize($w1+$w2, $hmax, 0, ($hmax-$h1)/2);
+<font size=-1 color=red> 17: </font> # Copy $drawable2 and paste it into the new space of $drawable1
+<font size=-1 color=red> 18: </font> $image2->selection_all; # select all of image2
+<font size=-1 color=red> 19: </font> $drawable2->edit_copy;
+<font size=-1 color=red> 20: </font> $image2->selection_none;
+<font size=-1 color=red> 21: </font> # make a selection in image 1 where $drawable2 is to be pasted
+<font size=-1 color=red> 22: </font> $image->select_rectangle(CHANNEL_OP_ADD, $w1, ($hmax-$h2)/2, $w2,
$h2);
+<font size=-1 color=red> 23: </font> $drawable->edit_paste(0)->floating_sel_anchor; # paste and then
anchor it
+<font size=-1 color=red> 24: </font> $image->undo_group_end; # Close the undo group
+<font size=-1 color=red> 25: </font> return;
+<font size=-1 color=red> 26: </font>};
+<font size=-1 color=red> 27: </font>
+<font size=-1 color=red> 28: </font>exit main;
+<font size=-1 color=red> 29: </font>__END__
+<font size=-1 color=red> 30: </font>
+<font size=-1 color=red> 31: </font>=head1 NAME
+<font size=-1 color=red> 32: </font>
+<font size=-1 color=red> 33: </font>horiz_cat - Horizontal concat
+<font size=-1 color=red> 34: </font>
+<font size=-1 color=red> 35: </font>=head1 SYNOPSIS
+<font size=-1 color=red> 36: </font>
+<font size=-1 color=red> 37: </font><Image>/Filters/Tutorial/Horizontal Concat
+<font size=-1 color=red> 38: </font>
+<font size=-1 color=red> 39: </font>=head1 DESCRIPTION
+<font size=-1 color=red> 40: </font>
+<font size=-1 color=red> 41: </font>Horizontal concatenation of images.
+<font size=-1 color=red> 42: </font>
+<font size=-1 color=red> 43: </font>=head1 PARAMETERS
+<font size=-1 color=red> 44: </font>
+<font size=-1 color=red> 45: </font> [PF_DRAWABLE, "drawable2", "Drawable to concatenate", undef],
+<font size=-1 color=red> 46: </font>
+<font size=-1 color=red> 47: </font>=head1 IMAGE TYPES
+<font size=-1 color=red> 48: </font>
+<font size=-1 color=red> 49: </font>*
+<font size=-1 color=red> 50: </font>
+<font size=-1 color=red> 51: </font>=head1 AUTHOR
+<font size=-1 color=red> 52: </font>
+<font size=-1 color=red> 53: </font>Dov Grobgeld
+<font size=-1 color=red> 54: </font>
+<font size=-1 color=red> 55: </font>=head1 DATE
+<font size=-1 color=red> 56: </font>
+<font size=-1 color=red> 57: </font>2004-03-27
+<font size=-1 color=red> 58: </font>
+<font size=-1 color=red> 59: </font>=head1 LICENSE
+<font size=-1 color=red> 60: </font>
+<font size=-1 color=red> 61: </font>Dov Grobgeld </pre></table><br>
+
+ You might notice something very important on lines 7 and 8: we
+ "know" that we'll always pass a layer as the first drawable,
+ but we're checking that anyway. Then we're telling Gimp-Perl the
+ drawable definitely <i>is</i> a layer. The reason for that is that
+ (obviously) <tt>Gimp::Layer</tt> and <tt>Gimp::Drawable</tt> have
+ different methods available to them, and what matters here is that
+ <tt>Gimp::Drawable</tt> does not have a resize method. (i.e. The PDB
+ does not have a <tt>gimp_drawable_resize</tt> function)
+
+<h2><a name="SEC10">10. The Perl Server and stand-alone scripts</a></h2>
+
+ So far the scripts have all been started from the menu structure
+ within GIMP. But using <tt>Gimp::Fu</tt> there is another possibility,
+ and that is to run the scripts from the command line, as a normal
+ Perl program. When run this way the script tries to connect to the
+ Perl-Server, and if it fails it will launch a GIMP of its own. If you
+ plan to run several scripts this way, it is obviously much faster to
+ run the Perl-Server since launching GIMP takes quite a bit of time. The
+ Perl-Server may be started from the <tt>Filters/Perl</tt> menu.
+ <p>
+
+ When a <tt>Gimp::Fu</tt> script is run from the command line, the
+ result is the same as when it is run through the menus, except
+ that it may be run with the <tt>--output</tt> parameter.
+ This will save the result to a file instead of displaying
+ it within GIMP. This is great for batch creation of logos, etc. <p>
+
+ The filename for the <tt>--output</tt> has some special magic that
+ allows to set some special image saving parameters, like interlace,
+ quality factor, etc. See the <a
+ href="http://search.cpan.org/dist/Gimp/Gimp/Fu.pm#MISCELLANEOUS_FUNCTIONS";><tt>Gimp::Fu</tt>
+ docs</a> for more detail<p>
+
+ Here are two invocations of the scripts declared above, but with output
+ written to a jpg file and a png file.<p>
+
+ <table border><tr><th bgcolor=#E0E0FF><a href="perl-gimp-from-shell">perl-gimp-from-shell</a><tr><td
bgcolor=#FFE0E0><pre><font size=-1 color=red> 1: </font>uni -o /tmp/uni.png --size 100 --color purple
+<font size=-1 color=red> 2: </font>basic-logo --font 'utopia 100' -o /tmp/bl.ppm --size 20 --text "Perl
rules" </pre></table><br>
+
+ Another important use of this interface is that it enables running
+ the Perl debugger on the perl-fu scripts.<p>
+
+<h3><a name="SEC10.1">10.1. A shell for Gimp-Perl</a></h3>
+
+ When using the Perl-Server it is not necessary to use <tt>Gimp::Fu</tt>
+ and the <tt>podregister</tt> function. Instead you may call
+ <tt>Gimp::on_net</tt>, which takes as a parameter a reference to a
+ sub routine that is called when your script has connected to a GIMP
+ (or started one up).
+ <p>
+ For a simple but powerful example of the use of the Gimp without
+ Fu, here is a an interactive Gimp-Perl shell that may be run from
+ the command line:
+ <p>
+ <table border><tr><th bgcolor=#E0E0FF><a href="pg-shell">pg-shell</a><tr><td bgcolor=#FFE0E0><pre><font
size=-1 color=red> 1: </font>#!/usr/bin/perl
+<font size=-1 color=red> 2: </font>
+<font size=-1 color=red> 3: </font># An interactive command line shell to GIMP.
+<font size=-1 color=red> 4: </font>use Gimp;
+<font size=-1 color=red> 5: </font>use Term::ReadLine;
+<font size=-1 color=red> 6: </font>
+<font size=-1 color=red> 7: </font>Gimp::on_net {
+<font size=-1 color=red> 8: </font> $term = new Term::ReadLine("Gimp");
+<font size=-1 color=red> 9: </font> while( defined ($_ = $term->readline("Gimp> "))) {
+<font size=-1 color=red> 10: </font> $res = eval($_) . "\n";
+<font size=-1 color=red> 11: </font> print("Error: $@"), next if $@;
+<font size=-1 color=red> 12: </font> print "\n";
+<font size=-1 color=red> 13: </font> Gimp->displays_flush();
+<font size=-1 color=red> 14: </font> }
+<font size=-1 color=red> 15: </font>};
+<font size=-1 color=red> 16: </font>
+<font size=-1 color=red> 17: </font>exit Gimp::main; </pre></table><br>
+ <p>
+ Here is an example of an interactive session with this shell:
+ <table border><tr><th bgcolor=#E0E0FF><a href="interact">interact</a><tr><td bgcolor=#FFE0E0><pre><font
size=-1 color=red> 1: </font>Gimp> $img = Gimp::Image->new(100,100,RGB)
+<font size=-1 color=red> 2: </font>Gimp> $drw = $img->layer_new(100,100,RGB_IMAGE, "bg", 100,
NORMAL_MODE)
+<font size=-1 color=red> 3: </font>Gimp> $img->insert_layer($drw,-1, 0)
+<font size=-1 color=red> 4: </font>Gimp> Gimp::Display->new($img)
+<font size=-1 color=red> 5: </font>Gimp> $drw->edit_clear
+<font size=-1 color=red> 6: </font>Gimp> print Gimp::Image->list
+<font size=-1 color=red> 7: </font>Gimp::Image->existing(1) </pre></table><br>
+
+<h2><a name="SEC11">11. End notes</a></h2>
+
+ This tutorial has covered only a small part of the possibilities
+ available to a script writer. In particular the following issues
+ available to Gimp::Perl scripts have not been covered:
+
+ <UL>
+ <LI> The possibility of writing customized Gtk interfaces (see <tt><a
href="http://search.cpan.org/dist/Gimp/examples/example-no-fu";>examples/example-no-fu</a></tt> in the
Gimp-Perl distribution). </LI>
+
+ <LI> Writing fully-fledged plug-ins that manipulate the tile data
+ through the Perl Data Language (PDL) module (see <tt><a
href="http://search.cpan.org/dist/Gimp/examples/map_to_gradient";>examples/map_to_gradient</a></tt> in the
Gimp-Perl distribution).</LI>
+ <LI> Using Gimp-Perl in a CGI environment. </LI>
+ <LI> How to fill with gradients in a plugin (see <tt><a
href="http://search.cpan.org/dist/Gimp/examples/randomblends";>examples/randomblends</a></tt> in the Gimp-Perl
distribution). </LI>
+ <LI> How to do polygon selections (see <tt><a
href="http://search.cpan.org/dist/Gimp/examples/triangle";>examples/triangle</a></tt> in the Gimp-Perl
distribution). </LI>
+ </UL>
+
+ <p>The Gimp-Perl distribution also has over 50 more example
+ scripts supplied. Take a look through those for further inspiration!
+
+<h2><a name="SEC12">12. Links and references</a></h2>
+
+ <UL>
+ <LI> <a href="http://search.cpan.org/dist/Gimp/";>The Gimp-Perl module</a></LI>
+ <LI> <a href="http://www.gimp.org";>The GIMP home page</a> </LI>
+
+ <LI> <A HREF="http://registry.gimp.org/";>GIMP Registry with Perl plug-ins</A> </LI>
+ </UL>
+
+<hr>
+<address>Please send your comments to <a href="mail:People-Grobgeld_Dov">dov grobgeld gmail com</a></address>
+</div>
<!--#include virtual="/includes/wgo-page-fini.xhtml" -->
<div>
<span id="footerleft">
diff --git a/tutorials/Basic_Perl/interact b/tutorials/Basic_Perl/interact
new file mode 100644
index 0000000..f7d9df6
--- /dev/null
+++ b/tutorials/Basic_Perl/interact
@@ -0,0 +1,7 @@
+Gimp> $img = Gimp::Image->new(100,100,RGB)
+Gimp> $drw = $img->layer_new(100,100,RGB_IMAGE, "bg", 100, NORMAL_MODE)
+Gimp> $img->insert_layer($drw,-1, 0)
+Gimp> Gimp::Display->new($img)
+Gimp> $drw->edit_clear
+Gimp> print Gimp::Image->list
+Gimp::Image->existing(1)
diff --git a/tutorials/Basic_Perl/paint-select b/tutorials/Basic_Perl/paint-select
new file mode 100755
index 0000000..6c426f8
--- /dev/null
+++ b/tutorials/Basic_Perl/paint-select
@@ -0,0 +1,55 @@
+#!/usr/bin/perl -w
+
+use Gimp;
+use Gimp::Fu;
+
+podregister {
+ my ($width, $height) = ($image->width, $image->height);
+ # Select a rectangle inside the image and paint it with color
+ $image->undo_group_start;
+ $image->select_rectangle(
+ CHANNEL_OP_REPLACE, $width/4, $height/4, $width/2, $height/2,
+ );
+ Gimp::Context->set_background($color);
+ $drawable->edit_fill(BACKGROUND_FILL);
+ $image->selection_none;
+ $image->undo_group_end;
+ ();
+};
+
+exit main;
+__END__
+
+=head1 NAME
+
+img_paint_select - Paints the selection
+
+=head1 SYNOPSIS
+
+<Image>/Filters/Tutorial/Paint Select
+
+=head1 DESCRIPTION
+
+Paints the selection
+
+=head1 PARAMETERS
+
+ [PF_COLOR, "color", "Rectangle color", [0,0,255]],
+
+=head1 RETURN VALUES
+
+=head1 IMAGE TYPES
+
+*
+
+=head1 AUTHOR
+
+Dov Grobgeld
+
+=head1 DATE
+
+1999-05-14
+
+=head1 LICENSE
+
+Dov Grobgeld
diff --git a/tutorials/Basic_Perl/paint-select.png b/tutorials/Basic_Perl/paint-select.png
index 812996c..ef42d4f 100644
Binary files a/tutorials/Basic_Perl/paint-select.png and b/tutorials/Basic_Perl/paint-select.png differ
diff --git a/tutorials/Basic_Perl/perl-gimp-from-shell b/tutorials/Basic_Perl/perl-gimp-from-shell
new file mode 100644
index 0000000..605e0a4
--- /dev/null
+++ b/tutorials/Basic_Perl/perl-gimp-from-shell
@@ -0,0 +1,2 @@
+uni -o /tmp/uni.png --size 100 --color purple
+basic-logo --font 'utopia 100' -o /tmp/bl.ppm --size 20 --text "Perl rules"
diff --git a/tutorials/Basic_Perl/pg-shell b/tutorials/Basic_Perl/pg-shell
new file mode 100755
index 0000000..c9eb308
--- /dev/null
+++ b/tutorials/Basic_Perl/pg-shell
@@ -0,0 +1,17 @@
+#!/usr/bin/perl
+
+# An interactive command line shell to GIMP.
+use Gimp;
+use Term::ReadLine;
+
+Gimp::on_net {
+ $term = new Term::ReadLine("Gimp");
+ while( defined ($_ = $term->readline("Gimp> "))) {
+ $res = eval($_) . "\n";
+ print("Error: $@"), next if $@;
+ print "\n";
+ Gimp->displays_flush();
+ }
+};
+
+exit Gimp::main;
diff --git a/tutorials/Basic_Perl/tpix.gif b/tutorials/Basic_Perl/tpix.gif
new file mode 100644
index 0000000..94185a4
Binary files /dev/null and b/tutorials/Basic_Perl/tpix.gif differ
diff --git a/tutorials/Basic_Perl/uni b/tutorials/Basic_Perl/uni
new file mode 100755
index 0000000..6eb7c3f
--- /dev/null
+++ b/tutorials/Basic_Perl/uni
@@ -0,0 +1,49 @@
+#!/usr/bin/perl -w
+
+use strict;
+use Gimp;
+use Gimp::Fu;
+
+podregister {
+ # no need to have my ($size, $color) = @_;
+ my $img = Gimp::Image->new($size, $size, RGB); # Create a new image
+ # Create a new layer
+ my $layer = $img->layer_new($size, $size, RGB, "Layer 1", 100, NORMAL_MODE);
+ $img->insert_layer($layer, -1, 0); # add the layer to the image
+ Gimp::Context->set_background($color); # Set background to required color
+ $layer->edit_fill(BACKGROUND_FILL); # Paint the layer
+ Gimp::Display->new($img);
+ return $img; # Return image - return implied by no IMAGE TYPES
+};
+
+exit main;
+__END__
+
+=head1 NAME
+
+img_uni - Create a uniform image
+
+=head1 SYNOPSIS
+
+<Image>/File/Create/Tutorial/Img Uni
+
+=head1 DESCRIPTION
+
+A tutorial script.
+
+=head1 PARAMETERS
+
+ [PF_INT32, "size", "Img size", 100],
+ [PF_COLOR, "color", "Img color", [255,127,0]]
+
+=head1 AUTHOR
+
+Dov Grobgeld
+
+=head1 DATE
+
+2004-03-27
+
+=head1 LICENSE
+
+Dov Grobgeld (c)
diff --git a/tutorials/Basic_Perl/uni-entry.png b/tutorials/Basic_Perl/uni-entry.png
index 4ad0419..491f487 100644
Binary files a/tutorials/Basic_Perl/uni-entry.png and b/tutorials/Basic_Perl/uni-entry.png differ
diff --git a/tutorials/Basic_Perl/uni-menu.png b/tutorials/Basic_Perl/uni-menu.png
index 0568f43..eef8a21 100644
Binary files a/tutorials/Basic_Perl/uni-menu.png and b/tutorials/Basic_Perl/uni-menu.png differ
diff --git a/tutorials/Basic_Perl/uni-result.png b/tutorials/Basic_Perl/uni-result.png
index d76fb27..07e8efc 100644
Binary files a/tutorials/Basic_Perl/uni-result.png and b/tutorials/Basic_Perl/uni-result.png differ
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
