When creating a script, you want to give your users the ability to undo their actions, should they make a mistake. This is easily accomplished by calling the functions gimp-undo-push-group-start and gimp-undo-push-group-end around the code that manipulates the image. You can think of them as matched statements that let GIMP know when to start and stop recording manipulations on the image, so that those manipulations can later be undone.

If you are creating a new image entirely, it doesn't make sense to use these functions because you're not changing an existing image. However, when you are changing an existing image, you most surely want to use these functions.

Undoing a script works nearly flawlessly when using these functions.

Now that we have a very handy-dandy script to create text boxes, let's add two features to it:

To let the user specify the amount of buffer, we'll add a parameter to our function and the registration function:

        (define (script-fu-text-box inTest inFont inFontSize inTextColor inBufferAmount)
        (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

                 (theBuffer)        ;added

                 (theLayer
                           (car
                               (gimp-layer-new
                                theImage
                                theImageWidth
                                theImageHeight
                                RGB-IMAGE
                                "layer 1"
                                100
                                NORMAL
                               )
                           )
                 )
              ) ;end of our local variables

         [Code here]
       )
      

        (script-fu-register
          "script-fu-text-box"                        ;func name
          "Text Box"                                  ;menu label
          "Creates a simple text box, sized to fit\
            around the user's choice of text,\
            font, font size, and color."              ;description
          "Michael Terry"                             ;author
          "copyright 1997, Michael Terry"             ;copyright notice
          "October 27, 1997"                          ;date created
          ""                     ;image type that the script works on
          SF-STRING      "Text:"         "Text Box"   ;a string variable
          SF-FONT        "Font:"         "Charter"    ;a font variable
          SF-ADJUSTMENT  "Font size"     '(50 1 1000 1 10 0 1)
                                                      ;a spin-button
          SF-COLOR       "Color:"        '(0 0 0)     ;color variable
          SF-ADJUSTMENT  "Buffer amount" '(35 0 100 1 10 1 0)
                                                      ;a slider
        )
        (script-fu-menu-register "script-fu-text-box" "<Toolbox>/Xtns/Script-Fu/Text")
      

We're going to add code in two places: right before we resize the image, and at the end of the script (to return the new image, the layer and the text).

After we get the text's height and width, we need to resize these values based on the buffer amount specified by the user. We won't do any error checking to make sure it's in the range of 0-100% because it's not life-threatening, and because there's no reason why the user can't enter a value like "200" as the percent of buffer to add.

        (set! theBuffer (* theImageHeight (/ inBufferAmount 100) ) )

        (set! theImageHeight (+ theImageHeight theBuffer theBuffer) )
        (set! theImageWidth  (+ theImageWidth  theBuffer theBuffer) )
      

All we're doing here is setting the buffer based on the height of the text, and adding it twice to both the height and width of our new image. (We add it twice to both dimensions because the buffer needs to be added to both sides of the text.)

Now that we have resized the image to allow for a buffer, we need to center the text within the image. This is done by moving it to the (x, y) coordinates of (theBuffer, theBuffer). I added this line after resizing the layer and the image:

        (gimp-layer-set-offsets theText theBuffer theBuffer)
      

Go ahead and save your script, and try it out after refreshing the database.

All that is left to do is return our image, the layer, and the text layer. After displaying the image, we add this line:

        (list theImage theLayer theText)
      

This is the last line of the function, making this list available to other scripts that want to use it.

To use our new text box script in another script, we could write something like the following:

        (set! theResult (script-fu-text-box
                         "Some text"
                         "Charter" "30"
                         '(0 0 0)
                         "35"
                        )
        )
        (gimp-image-flatten (car theResult))
      

Congratulations, you are on your way to your Black Belt of Script-Fu!