1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
|
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>10.4. Your First Script-Fu Script</title>
<link rel="stylesheet" href="gimp-help-plain.css" type="text/css" />
<link rel="stylesheet" href="gimp-help-screen.css" type="text/css" />
<meta name="generator" content="DocBook XSL Stylesheets V1.66.1" />
<link rel="start" href="index.html" title=" " />
<link rel="up" href="ch02s10.html" title="10. A Script-Fu Tutorial" />
<link rel="prev" href="ch02s10s03.html" title="10.3. Lists, Lists And More Lists" />
<link rel="next" href="ch02s10s05.html" title="10.5. Giving Our Script Some Guts" />
</head>
<body>
<div xmlns="" class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center" id="chaptername">10.4. Your First Script-Fu Script</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="ch02s10s03.html">Prev</a> </td>
<th width="60%" align="center" id="sectionname">10.4. Your First Script-Fu Script</th>
<td width="20%" align="right"> <a accesskey="n" href="ch02s10s05.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="id3317499"></a>10.4. Your First Script-Fu Script</h3>
</div>
</div>
</div>
<p>
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.
</p>
<div class="simplesect" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id3317642"></a>Creating A Text Box Script</h4>
</div>
</div>
</div>
<p>
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.
</p>
<p>
The Script-Fu Master (and student) will quickly realize that
this problem can easily be solved and automated with
Script-Fu.
</p>
<p>
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.
</p>
</div>
<div class="simplesect" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id3317063"></a>Editing And Storing Your Scripts</h4>
</div>
</div>
</div>
<p>
Up until now, we've been working in the Script-Fu
Console. Now, however, we're going to switch to editing script
text files.
</p>
<p>
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.
</p>
<p>
In the <tt class="filename">.gimp-2.0</tt> directory that Gimp made
off of your home directory, you should find a directory called
<tt class="filename">scripts</tt>. Gimp will automatically look in
your <tt class="filename">.gimp-2.0</tt> directory for a scripts
directory, and add the
scripts in this directory to the Script-Fu database. You
should place your personal scripts here.
</p>
</div>
<div class="simplesect" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id3317167"></a>The Bare Essentials</h4>
</div>
</div>
</div>
<p>
Every Script-Fu script defines at least one function, which is
the script's main function. This is where you do the work.
</p>
<p>
Every script must also register with the procedural database,
so you can access it within Gimp.
</p>
<p>
We'll define the main function first:
</p>
<pre class="programlisting">
(define (script-fu-text-box inText inFont inFontSize inTextColor))
</pre>
<p>
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.
</p>
</div>
<div class="simplesect" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id3317586"></a>Naming Conventions</h4>
</div>
</div>
</div>
<p>
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.
</p>
<p>
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.
</p>
</div>
<div class="simplesect" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id3315935"></a>Registering The Function</h4>
</div>
</div>
</div>
<p>
Now, let's register the function with Gimp. This is done by
calling the function <tt class="code">script-fu-register</tt>. 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.
</p>
<p>
Here's the listing for registering this function (I will
explain all its parameters in a minute):
</p>
<pre class="programlisting">
(script-fu-register
"script-fu-text-box" ;func name
"<Toolbox>/Xtns/Script-Fu/Text/Text Box" ;menu pos
"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-VALUE "Text:" "\"Text Box\"" ;a text variable
SF-VALUE "Font:" "\"Charter\"" ;a text variable
SF-VALUE "Font size:" "45" ;a text variable
SF-COLOR "Color:" '(0 0 0) ;color variable
)
</pre>
<p>
If you save these functions in a text file with a
<tt class="filename">.scm</tt> suffix
in your script directory, then choose
<span class="guimenu">Xtns</span>-><span class="guisubmenu">Script-Fu</span>-><span class="guimenuitem">Refresh</span>,
this new script will appear as
<span class="guimenu"> Xtns</span>-><span class="guisubmenu">Script-Fu</span>-><span class="guisubmenu">Text</span>-><span class="guimenuitem">Text Box</span>.
</p>
<p>
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).
</p>
<p>
Finally, if you invoke the DB Browser (the procedural database
browser --
<span class="guimenu"> Xtns</span>-><span class="guimenuitem">DB Browser</span>),
you'll notice that our script now
appears in the database.
</p>
</div>
<div class="simplesect" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id3317220"></a>Steps For Registering The Script</h4>
</div>
</div>
</div>
<p>
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.
</p>
<div class="itemizedlist">
<p class="title">
<b>The Required Parameters</b>
</p>
<ul type="disc">
<li>
<p>
The <span class="bold"><b>name</b></span> 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.
</p>
</li>
<li>
<p>
The <span class="bold"><b>location</b></span> 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.
</p>
</li>
<li>
<p>
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.).
</p>
<p>
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 (
<span class="guimenu"> Xtns</span>-><span class="guisubmenu">Script-Fu</span>-><span class="guisubmenu">Text</span>-><span class="guimenuitem">Text Box</span>
).
</p>
<p>
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.
</p>
</li>
<li>
<p>
A <span class="bold"><b>description</b></span> of your
script, to be displayed in the DB Browser.
</p>
</li>
<li>
<p>
<span class="bold"><b>Your name</b></span> (the author of
the script).
</p>
</li>
<li>
<p>
<span class="bold"><b>Copyright</b></span> information.
</p>
</li>
<li>
<p>
The <span class="bold"><b>date</b></span> the script was
made, or the last revision of the script.
</p>
</li>
<li>
<p>
The <span class="bold"><b>types</b></span> 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.
</p>
</li>
</ul>
</div>
</div>
<div class="simplesect" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id3317894"></a>Registering The Script's Parameters</h4>
</div>
</div>
</div>
<p>
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.
</p>
<p>
This section of the registration process has the following format:
</p>
<div class="informaltable">
<table border="1">
<colgroup>
<col />
<col />
<col />
</colgroup>
<thead>
<tr>
<th>
<p>Param Type</p>
</th>
<th>
<p>Description</p>
</th>
<th>
<p>Example</p>
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p>SF-VALUE</p>
</td>
<td>
<p>
Accepts numbers and strings. Note that quotes must be
escaped for default text.
</p>
</td>
<td>
<p>"\"Some text\""</p>
</td>
</tr>
<tr>
<td>
<p>SF-COLOR</p>
</td>
<td>
<p>
Indicates that a color is requested in this parameter
</p>
</td>
<td>
<p>'(0 102 255)</p>
</td>
</tr>
<tr>
<td>
<p>SF-TOGGLE</p>
</td>
<td>
<p>
A checkbox is displayed, to get a Boolean value.
</p>
</td>
<td>
<p>TRUE or FALSE</p>
</td>
</tr>
<tr>
<td>
<p>SF-IMAGE</p>
</td>
<td>
<p>
If your script operates on an open image, this should be
the first parameter after the required parameters. Gimp
will pass in a reference to the image in this parameter.
</p>
</td>
<td>
<p>3</p>
</td>
</tr>
<tr>
<td>
<p>SF-DRAWABLE</p>
</td>
<td>
<p>
If your script operates on an open image, this should be
the second parameter after the SF-IMAGE param. It refers
to the active layer. Gimp will pass in a reference to the
active layer in this parameter.
</p>
</td>
<td>
<p>17</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="ch02s10s03.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="ch02s10.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="ch02s10s05.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">10.3. Lists, Lists And More Lists </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> 10.5. Giving Our Script Some Guts</td>
</tr>
</table>
</div>
</body>
</html>
|
