3. Script-Fu and The GIMP

You can call the PDB-functions straightforwardly, but you have to keep in mind that they always return a list, even when this list contains just one element. Colors are represented by a list '(red green blue).

(set! new-layer (car (plug-in-pagecurl 1 img drw 1 1 0 1)))
(gimp-palette-set-foreground '(255 0 0))
(gimp-image-add-layer img (car (gimp-layer-copy drw 1)) -1)
        

These commands are not always equivalent to their GUI counterpart. For example: When creating a new layer, this layer is neither clean, nor automatically added to the image. In a script you have to do this:

(set! new-layer (car (gimp-layer-new img 100 100 RGBA_IMAGE "New Layer" 50.7 0)))
(gimp-edit-clear new-layer)
(gimp-image-add-layer img new-layer -1)
        

The scripts in /usr/share/gimp/1.2/scripts/ are a valuable resource when you are trying to write your own scripts. Generally it is a good idea to look and learn from them. If your script does not behave as expected you might want to search for a script that solves a similiar task. Maybe you can find a better solution there.

To make a script callable via the menu it must be registered with the PDB. This looks like this:

(script-fu-register "script-fu-simple-drop-shadow"
                    _"<Image>/Script-Fu/Shadow/Drop-Shadow (simple)..."
                    "Add a simple drop-shadow of the alpha-channel"
                    "Simon Budig <simon@gimp.org>"  ; author
                    "Simon Budig"                ; copyright holder
                    "2002/2/3"                   ; date
                    "RGBA GRAYA"                 ; image types
                    SF-IMAGE "Image" 0
                    SF-DRAWABLE "Drawable" 0
                    SF-ADJUSTMENT _"Offset X" '(8 -4096 4096 1 10 0 1)
                    SF-ADJUSTMENT _"Offset Y" '(8 -4096 4096 1 10 0 1)
                    SF-COLOR      _"Color" '(0 0 0)
                    SF-ADJUSTMENT _"Opacity" '(75 0 100 1 10 0 0))
	

This enters the script in the PDB. The first argument is the name in the PDB, the second is the Menu-Path (the underscore indicates that it should be translated). The next arguments are a short description, name of the author and copyright notice, date of creation and a specification of the valid image types (RGB* is a shortcut for "RGB and RGBA").

The subsequent entries specify the parameters, with additional information for the generated GUI. If the script registers in the <Image> hierarchy of the menu it has to accept an IMAGE and a DRAWABLE as its first two arguments. They get filled by The GIMP's framework.

Further parameters are optional. You can specify SF-COLOR for colors, SF-TEXT for text and some other stuff. A complete list of all available parameter types is in the test-sphere.scm script, delivered with The GIMP source code.

These specifications get translated in a nice GUI when the user invokes the Script via the Menu. SF-COLOR gets connected to a color selector, SF-FONT to a font selector. The ADJUSTMENT Parameters accept a list that defines the behaviour of the GUI: '(default_value, lower_bound, upper_bound, small_increment, big_increment, prescision, slider_or_entry).