|
 |
|
| |
3.4.
Your First Script-Fu Script
Do you not need to stop and catch your breath? No? Well then,
let's proceed with your fourth lesson -- your first Script-Fu
Script.
3.4.1.
Creating A Text Box Script
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.
3.4.2.
Editing And Storing Your Scripts
Up until now, we've been working in the Script-Fu Console. Now,
however, we're going to switch to editing script text files.
Where you place your scripts is a matter of preference -- if you have
access to GIMP's default script directory, you can place your scripts
there. However, I prefer keeping my personal scripts in my own script
directory, to keep them separate from the factory-installed scripts.
In the .gimp-2.4 directory that GIMP made
off of your home directory, you should find a directory called
scripts. GIMP will automatically look in
your .gimp-2.4 directory for a scripts
directory, and add the
scripts in this directory to the Script-Fu database. You
should place your personal scripts here.
3.4.3.
The Bare Essentials
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.
3.4.4.
Naming Conventions
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.
3.4.5.
Registering The Function
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" ;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
)
(script-fu-menu-register "script-fu-text-box" "<Toolbox>/Xtns/Script-Fu/Text")
If you save these functions in a text file with a
.scm suffix
in your script directory, then choose
→ → ,
this new script will appear as
→ → → .
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 (
→ ),
you'll notice that our script now
appears in the database.
3.4.6.
Steps For Registering The Script
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.
The Required Parameters
-
The name of the function we
defined. This is the function called when our script is invoked
(the entry-point into our script). This is necessary because we may
define additional functions within the same file, and GIMP needs to
know which of these functions to call. In our example, we only
defined one function, text-box, which we registered.
-
The location in the menu where
the script will be inserted. The exact location of the script is
specified like a path in Unix, with the root of the path being
either toolbox or right-click.
If your script does not operate on an existing image (and thus
creates a new image, like our Text Box script will), you'll want
to insert it in the toolbox menu -- this is the menu in GIMP's
main window (where all the tools are located: the selection tools,
magnifying glass, etc.).
If your script is intended to work on an image being edited,
you'll want to insert it in the menu that appears when you
right-click on an open image. The rest of the path points to
the menu lists, menus and sub-menus. Thus, we registered our
Text Box script in the Text menu of the Script-Fu menu of
the Xtns menu of the toolbox (
→ → → ).
If you notice, the Text sub-menu in the Script-Fu menu wasn't
there when we began -- GIMP automatically creates any menus not
already existing.
-
A description of your
script, to be displayed in the Procedure Browser.
-
Your name (the author of
the script).
-
Copyright information.
-
The date the script was
made, or the last revision of the script.
-
The types of images the script
works on. This may be any of the following: RGB, RGBA, GRAY,
GRAYA, INDEXED, INDEXEDA. Or it may be none at all -- in our case,
we're creating an image, and thus don't need to define the type of
image on which we work.
3.4.7.
Registering The Script's Parameters
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:
3.4.8.
The Script-Fu parameter API[]
![[Note]](images/note.png)
|
Note |
|
Beside the above parameter types there are more types for the
interactive mode, each of them will create a widget in the control
dialog. You will find a list of these parameters with descriptions and
examples in the test script
plug-ins/script-fu/scripts/test-sphere.scm
shipped with the GIMP source code.
|
|
|
|
