In the previous lesson, we created an empty function and registered it with Gimp. In this lesson, we want to provide functionality to our script -- we want to create a new image, add the user's text to it and resize the image to fit the text exactly.

Once you know how to set variables, define functions and access list members, the rest is all downhill -- all you need to do is familiarize yourself with the functions available in Gimp's procedural database and call those functions directly. So fire up the DB Browser and let's get cookin'!

Let's begin by making a new image. We'll create a new variable, theImage, set to the result of calling Gimp's built-in function gimp-image-new.

As you can see from the DB Browser, the function gimp-image-new takes three parameters -- the image's width, height and the type of image. Because we'll later resize the image to fit the text, we'll make a 10x10 RGB image. We'll store the image's width and sizes in some variables, too, as we'll refer to and manipulate them later in the script.

        (define (script-fu-text-box inTest inFont inFontSize inTextColor)
        (let*
              (
                 ; define our local variables
                 ; create a new image:
                 (theImageWidth  10)
                 (theImageHeight 10)
                 (theImage (car 
                                (gimp-image-new
                                 theImageWidth
                                 theImageHeight
                                 RGB
                                )
                           )
                 )
                 (theText)     ;a declaration for the text
                               ;we create later
      

Note: We used the value RGB to specify that the image is an RGB image. We could have also used 0, but RGB is more descriptive when we glance at the code.

You should also notice that we took the head of the result of the function call. This may seem strange, because the database explicitly tells us that it returns only one value -- the ID of the newly created image. However, all Gimp functions return a list, even if there is only one element in the list, so we need to get the head of the list.

        ;create a new layer for the image:
           (theLayer 
                     (car
                          (gimp-layer-new
                           theImage
                           theImageWidth
                           theImageHeight
                           RGB_IMAGE
                           "layer 1"
                           100
                           NORMAL
                          )
                      )
            )
         ) ;end of our local variables
      

Once we have the new layer, we need to add it to the image:

       (gimp-image-add-layer theImage theLayer 0)
      

Now, just for fun, let's see the fruits of our labors up until this point, and add this line to show the new, empty image:

        (gimp-display-new theImage)
      

Save your work, select Xtns->Script-Fu->Refresh, run the script and a new image should pop up. It will probably contain garbage (random colors), because we haven't erased it. We'll get to that in a second.

Before we add text to the image, we need to set the background and foreground colors so that the text appears in the color the user specified. We'll use the gimp-palette-set-back/foreground functions:

        (gimp-palette-set-background '(255 255 255) )
        (gimp-palette-set-foreground inTextColor)
      

With the colors properly set, let's now clean out the garbage currently in the image. We'll select everything in the image, and call clear:

        (gimp-selection-all theImage)
        (gimp-edit-clear theImage theLayer)
        (gimp-selection-none theImage)
      

With the image cleared, we're ready to add some text:

        (set! theText
                      (car
                           (gimp-text
                            theImage
                            theLayer
                            0 0
                            inText
                            0
                            TRUE
                            inFontSize
                            PIXELS
                            "*" "*" "*"
                           )
                       )
        )  
      

Although a long function call, it's fairly straightforward if you go over the parameters while looking at the function's entry in the DB Browser. Basically, we're creating a new text layer and assigning it to the variable theText.

Now that we have the text, we can grab its width and height and resize the image and the image's layer to the text's size:

        (set! theImageWidth   (car (gimp-drawable-width  theText) ) )  	
        (set! theImageHeight  (car (gimp-drawable-height theText) ) )

        (gimp-image-resize theImage theImageWidth theImageHeight 0 0)	
  	
        (gimp-layer-resize theLayer theImageWidth theImageHeight 0 0)
      

If you're like me, you're probably wondering what a drawable is when compared to a layer. The difference between the two is that a drawable is anything that can be drawn into, including layers but also channels, layer masks, the selection, etc; a layer is a more specific version of a drawable. In most cases, the distinction is not important.

With the image ready to go, we can now re-add our display line:

        (gimp-display-new theImage)
      

Save your work, refresh the database and give your first script a run!

To do this, we can clear the dirty flag after displaying the image:

        (gimp-image-clean-all theImage)
      

This will set dirty count to 0, making it appear to be a "clean" image.

Whether to add this line or not is a matter of personal taste. I use it in scripts that produce new images, where the results are trivial, as in this case. If your script is very complicated, or if it works on an existing image, you will probably not want to use this function.