One of the most common operations I perform in GIMP is creating a box with some text in it for a web page, a logo or whatever. However, you never quite know how big to make the initial image when you start out. You don't know how much space the text will fill with the font and font size you want.

The Script-Fu Master (and student) will quickly realize that this problem can easily be solved and automated with Script-Fu.

We will, therefore, create a script, called Text Box, which creates an image correctly sized to fit snugly around a line of text the user inputs. We'll also let the user choose the font, font size and text color.

Up until now, we've been working in the Script-Fu Console. Now, however, we're going to switch to editing script files. Script files should be plain text files that you can edit in a text or code editor. The name you give is not that important, except for being able to recognize the script. You should give your script file the extension “.scm”.

Where you place your scripts is a matter of preference. In GIMP's folder preferences you can see in which folders GIMP looks for scripts. It is also possible to add a new folder there. The folder where GIMP stores its own scripts is usually not the best choice for your scripts, but for the rest feel free to choose what suits you best.

Every Script-Fu script defines at least one function, which is the script's main function. This is where you do the work.

Every script must also register with the procedural database, so you can access it within GIMP.

We'll define the main function first:

        (define (script-fu-text-box inText inFont inFontSize inTextColor))
      

Here, we've defined a new function called script-fu-text-box that takes four parameters, which will later correspond to some text, a font, the font size, and the text's color. The function is currently empty and thus does nothing. So far, so good — nothing new, nothing fancy.

Scheme's naming conventions seem to prefer lowercase letters with hyphens, which I've followed in the naming of the function. However, I've departed from the convention with the parameters. I like more descriptive names for my parameters and variables, and thus add the "in" prefix to the parameters so I can quickly see that they're values passed into the script, rather than created within it. I use the prefix "the" for variables defined within the script.

It's GIMP convention to name your script functions script-fu-abc, because then when they're listed in the procedural database, they'll all show up under Script-Fu when you're listing the functions. This also helps distinguish them from plug-ins.

Now, let's register the function with GIMP. This is done by calling the function script-fu-register. When GIMP reads in a script, it will execute this function, which registers the script with the procedural database. You can place this function call wherever you wish in your script, but I usually place it at the end, after all my other code.

Here's the listing for registering this function (I will explain all its parameters in a minute):

  (script-fu-register
    "script-fu-text-box"                        ;function 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;\
      2009, the GIMP Documentation Team"        ;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
  )
  (script-fu-menu-register "script-fu-text-box" "<Image>/File/Create/Text")
      

If you save these functions in a text file with a .scm suffix in your script directory, then choose Filters → Script-Fu → Refresh Scripts, this new script will appear as File → Create → Text → Text Box.

If you invoke this new script, it won't do anything, of course, but you can view the prompts you created when registering the script (more information about what we did is covered next).

Finally, if you invoke the Procedure Browser ( Help → Procedure Browser), you'll notice that our script now appears in the database.

To register our script with GIMP, we call the function script-fu-register, fill in the seven required parameters and add our script's own parameters, along with a description and default value for each parameter.

Once we have listed the required parameters, we then need to list the parameters that correspond to the parameters our script needs. When we list these params, we give hints as to what their types are. This is for the dialog which pops up when the user selects our script. We also provide a default value.

This section of the registration process has the following format:

Once we have registered our script, we need to tell GIMP where it should be found in the menu.

The best menu location of your script depends on its function. Most scripts are found in the Filters and Colors menus.

For the current script, which creates a new image, we choose a submenu of File → Create. This is what the line with the script-fu-menu-register function does. Thus, we registered our Text Box script here: File → Create → Text → Text Box.

If you notice, the Text sub-menu in the File/Create menu wasn't there when we began — GIMP automatically creates any menus not already existing.

Figure 13.2. The menu of our script.