[gimp-help-2] Enhance Script-Fu tutorial
- From: Ulf-D. Ehlert <ulfehlert src gnome org>
- To: svn-commits-list gnome org
- Cc:
- Subject: [gimp-help-2] Enhance Script-Fu tutorial
- Date: Sun, 15 Nov 2009 13:34:09 +0000 (UTC)
commit e69f00290f2555fbb129e78938a9d5e8b2f9d60c
Author: SimaMoto,RyÅ?Ta <liangtai s4 gmail com>
Date: Thu Nov 12 21:24:04 2009 +0900
Enhance Script-Fu tutorial
* At the beginning, use <blockquote> tags for the three
important notices rather than <emphasis>, because oblique text
is less easy to read and not much impressive than regular
paragraphs on other language(s) (especially in Japanese).
* Change the registration path of sample scripts,
<Toolbox>/Xtns/Script-Fu/Text/ to <Image>/File/Create/Text/.
Add us after the original author on the copyright parameter.
* Remove colons ':' from labels of sample scripts, since
a colon sign will be automatically appended after its term.
* Truncate leading spaces of the <programlisting> sample
script code so that the verbatim window would not be too wide
on html browser.
* Put the word "GIMP" with <acronym> tags.
* Replace "--" by —.
* Remove <phrase> tags in <title>.
Signed-off-by: Ulf-D. Ehlert <ulfehlert svn gnome org>
src/using/script-fu-tutorial.xml | 958 +++++++++++++++++++-------------------
1 files changed, 477 insertions(+), 481 deletions(-)
---
diff --git a/src/using/script-fu-tutorial.xml b/src/using/script-fu-tutorial.xml
index a12b208..2b3aa4c 100644
--- a/src/using/script-fu-tutorial.xml
+++ b/src/using/script-fu-tutorial.xml
@@ -1,14 +1,14 @@
<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.docbook.org/xml/4.3/docbookx.dtd";>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.docbook.org/xml/4.3/docbookx.dtd";>
<!-- section history:
2007-06-14 alex falappa: finished italian translation
2007-04-13 alex falappa: started it translation
2008-03-12 jpl : french update
-->
-<sect1 xmlns:xi="http://www.w3.org/2001/XInclude"; id="gimp-using-script-fu-tutorial">
- <title>
- <phrase>A Script-Fu Tutorial</phrase>
- </title>
+<sect1 id="gimp-using-script-fu-tutorial"
+ xmlns:xi="http://www.w3.org/2001/XInclude";>
+ <title>A Script-Fu Tutorial</title>
<indexterm>
<primary>Script-Fu</primary>
<secondary>Tutorial</secondary>
@@ -24,100 +24,101 @@
</para>
<note>
<para>
- This section as adapted from a tutorial written for the GIMP 1 User
+ This section as adapted from a tutorial written for the
+ <application><acronym>GIMP</acronym> 1</application> User
Manual by Mike Terry.
</para>
</note>
+
<sect2 id="gimp-using-script-fu-tutorial-scheme">
- <title>
- <phrase>Getting Acquainted With Scheme</phrase>
- </title>
+ <title>Getting Acquainted With Scheme</title>
<sect3>
- <title>
- <phrase>Let's Start Scheme'ing</phrase>
- </title>
+ <title>Let's Start Scheme'ing</title>
<para>The first thing to learn is that:</para>
- <para>
- <emphasis>
+ <blockquote>
+ <para>
Every statement in Scheme is surrounded by parentheses ().
- </emphasis>
- </para>
+ </para>
+ </blockquote>
<para>The second thing you need to know is that:</para>
- <para>
- <emphasis>
+ <blockquote>
+ <para>
The function name/operator is always the first item in the
parentheses, and the rest of the items are parameters to the
function.
- </emphasis>
- </para>
+ </para>
+ </blockquote>
<para>
- However, not everything enclosed in parentheses is a function -- they
- can also be items in a list -- but we'll get to that later. This
- notation is referred to as prefix notation, because the function
+ However, not everything enclosed in parentheses is a function —
+ they can also be items in a list — but we'll get to that later.
+ This notation is referred to as prefix notation, because the function
prefixes everything else. If you're familiar with postfix notation, or
own a calculator that uses Reverse Polish Notation (such as most HP
calculators), you should have no problem adapting to formulating
expressions in Scheme.
</para>
<para>The third thing to understand is that:</para>
- <para>
- <emphasis>
+ <blockquote>
+ <para>
Mathematical operators are also considered functions, and thus are
listed first when writing mathematical expressions.
- </emphasis>
- </para>
+ </para>
+ </blockquote>
<para>
This follows logically from the prefix notation that we just
mentioned.
</para>
</sect3>
+
<sect3>
- <title>
- <phrase>
- Examples Of Prefix, Infix, And Postfix Notations
- </phrase>
- </title>
+ <title>Examples Of Prefix, Infix, And Postfix Notations</title>
<para>
Here are some quick examples illustrating the differences between
<emphasis>prefix</emphasis>, <emphasis>infix</emphasis>, and
- <emphasis>postfix</emphasis> notations. We'll add a 1 and 3 together:
+ <emphasis>postfix</emphasis> notations. We'll add a 1 and 23 together:
</para>
<itemizedlist>
<listitem>
<para>
- Prefix notation: + 1 3 (the way Scheme will want it)
+ Prefix notation: <userinput>+ 1 23</userinput>
+ (the way Scheme will want it)
</para>
</listitem>
<listitem>
<para>
- Infix notation: 1 + 3 (the way we "normally" write it)
+ Infix notation: <userinput>1 + 23</userinput>
+ (the way we <quote>normally</quote> write it)
</para>
</listitem>
<listitem>
<para>
- Postfix notation: 1 3 + (the way many HP calculators will want it)
+ Postfix notation: <userinput>1 23 +</userinput>
+ (the way many <acronym>HP</acronym> calculators will want it)
</para>
</listitem>
</itemizedlist>
</sect3>
+
<sect3>
- <title>
- <phrase>Practicing In Scheme</phrase>
- </title>
- <para>
- Now, let's practice what we have just learned. Start up GIMP,
- if you have not already done so, and choose <menuchoice><guimenu>Xtns</guimenu><guisubmenu>Script-Fu</guisubmenu><guimenuitem>Console</guimenuitem></menuchoice>. This will start
- up the Script-Fu Console window, which allows us to work
- interactively in Scheme. In a matter of moments, the Script-Fu
+ <title>Practicing In Scheme</title>
+ <para>
+ Now, let's practice what we have just learned. Start up
+ <acronym>GIMP</acronym>, if you have not already done so, and choose
+ <menuchoice>
+ <guimenu>Filters</guimenu>
+ <guisubmenu>Script-Fu</guisubmenu>
+ <guimenuitem>Console</guimenuitem>
+ </menuchoice>.
+ This will start up the Script-Fu Console window, which allows us to
+ work interactively in Scheme. In a matter of moments, the Script-Fu
Console will appear:
</para>
</sect3>
+
<sect3 id="gimp-using-script-fu-tutorial-console">
- <title>
- <phrase>The Script-Fu Console Window</phrase>
- </title>
+ <title>The Script-Fu Console Window</title>
<para>
- At the bottom of this window is an entry-field entitled
+ At the bottom of this window is an entry-field ought to be entitled
<guilabel>Current Command</guilabel>.
Here, we can test out simple Scheme commands interactively. Let's
start out easy, and add some numbers:
@@ -128,36 +129,34 @@
yields the expected answer of 8 in the center window.
</para>
<figure>
- <title>
- <phrase>
- Use Script-Fu Console.
- </phrase>
- </title>
+ <title>Use Script-Fu Console.</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/using/script-fu-console.png" format="PNG"/>
+ <imagedata format="PNG"
+ fileref="images/using/script-fu-console.png"/>
</imageobject>
</mediaobject>
</figure>
<para>
- Now, what if we wanted to add more than one number? The <quote>+</quote>
+ Now, what if we wanted to add more than one number? The
+ <quote>+</quote>
function can take two or more arguments, so this is not a problem:
</para>
<programlisting>(+ 3 5 6)</programlisting>
<para>This also yields the expected answer of 14.</para>
<para>
- So far, so good -- we type in a Scheme statement and it's executed
+ So far, so good — we type in a Scheme statement and it's executed
immediately in the Script-Fu Console window. Now for a word of
- caution....
+ caution…
</para>
</sect3>
+
<sect3>
- <title>
- <phrase>Watch Out For Extra Parentheses</phrase>
- </title>
+ <title>Watch Out For Extra Parentheses</title>
<para>
If you're like me, you're used to being able to use extra parentheses
- whenever you want to -- like when you're typing a complex mathematical
+ whenever you want to — like when you're typing a complex
+ mathematical
equation and you want to separate the parts by parentheses to make it
clearer when you read it. In Scheme, you have to be careful and not
insert these extra parentheses incorrectly. For example, say we wanted
@@ -170,21 +169,18 @@
</para>
<programlisting>(+ 3 (5 6) 7)</programlisting>
<para>
- However, this is incorrect -- remember, every statement in Scheme
+ However, this is incorrect — remember, every statement in Scheme
starts and ends with parens, so the Scheme interpreter will think that
you're trying to call a function named <quote>5</quote> in the second
group of parens, rather than summing those numbers before adding them
to 3.
</para>
- <para>
- The correct way to write the above statement would be:
- </para>
+ <para>The correct way to write the above statement would be:</para>
<programlisting>(+ 3 (+ 5 6) 7)</programlisting>
</sect3>
+
<sect3>
- <title>
- <phrase>Make Sure You Have The Proper Spacing, Too</phrase>
- </title>
+ <title>Make Sure You Have The Proper Spacing, Too</title>
<para>
If you are familiar with other programming languages, like C/C++, Perl
or Java, you know that you don't need white space around mathematical
@@ -205,23 +201,22 @@
</para>
</sect3>
</sect2>
+
<sect2 id="gimp-using-script-fu-tutorial-identifier">
- <title>
- <phrase>Variables And Functions</phrase>
- </title>
+ <title>Variables And Functions</title>
<para>
Now that we know that every Scheme statement is enclosed in parentheses,
and that the function name/operator is listed first, we need to know how
to create and use variables, and how to create and use functions. We'll
start with the variables.
</para>
+
<sect3>
- <title>
- <phrase>Declaring Variables</phrase>
- </title>
+ <title>Declaring Variables</title>
<para>
Although there are a couple of different methods for declaring
- variables, the preferred method is to use the let* construct. If
+ variables, the preferred method is to use the <command>let*</command>
+ construct. If
you're familiar with other programming languages, this construct is
equivalent to defining a list of local variables and a scope in which
they're active. As an example, to declare two variables, a and b,
@@ -251,10 +246,9 @@
prints the sum of the two variables.
</para>
</sect3>
+
<sect3>
- <title>
- <phrase>What Is A Local Variable?</phrase>
- </title>
+ <title>What Is A Local Variable?</title>
<para>
You'll notice that we wrote the summation <code>(+ a b)</code> within
the parens of the <code>let*</code> expression, not after it.
@@ -262,38 +256,36 @@
<para>
This is because the <code>let*</code>
statement defines an area in your script in which the declared
- variables are usable; if you type the (+ a b) statement after the
- (let* ...) statement, you'll get an error, because the declared
+ variables are usable; if you type the <userinput>(+ a b)</userinput>
+ statement after the <userinput>(let* …)</userinput> statement,
+ you'll get an error, because the declared
variables are only valid within the context of the <code>let*</code>
statement; they are what programmers call local variables.
</para>
</sect3>
+
<sect3>
- <title>
- <phrase>The General Syntax Of <code>let*</code></phrase>
- </title>
- <para>
- The general form of a <code>let*</code> statement is:
- </para>
+ <title>The General Syntax Of <code>let*</code></title>
+ <para>The general form of a <code>let*</code> statement is:</para>
<programlisting>
(let* ( <replaceable>variables</replaceable> )
<replaceable>expressions</replaceable> )
</programlisting>
<para>
- where variables are declared within parens, e.g., (a 2), and
+ where variables are declared within parens, e.g.,
+ <userinput>(a 2)</userinput>, and
expressions are any valid Scheme expressions. Remember that the
variables declared here are only valid within the
- <code>let*</code> statement -- they're local variables.
+ <code>let*</code> statement — they're local variables.
</para>
</sect3>
+
<sect3>
- <title>
- <phrase>White Space</phrase>
- </title>
+ <title>White Space</title>
<para>
Previously, we mentioned the fact that you'll probably want to use
indentation to help clarify and organize your scripts. This is a good
- policy to adopt, and is not a problem in Scheme -- white space is
+ policy to adopt, and is not a problem in Scheme — white space is
ignored by the Scheme interpreter, and can thus be liberally applied
to help clarify and organize the code within a script. However, if
you're working in Script-Fu's Console window, you'll have to enter an
@@ -302,14 +294,13 @@
Script-Fu Console window.
</para>
</sect3>
+
<sect3>
- <title>
- <phrase>Assigning A New Value To A Variable</phrase>
- </title>
+ <title>Assigning A New Value To A Variable</title>
<para>
Once you've initialized a variable, you might need to change its value
- later on in the script. Use the set! statement to change the
- variable's value:
+ later on in the script. Use the <code>set</code>! statement to change
+ the variable's value:
</para>
<programlisting>
(let* ( (theNum 10) ) (set! theNum (+ theNum theNum)) )
@@ -320,16 +311,15 @@
</para>
<note>
<para>
- The <quote>\</quote> indicates that there is no line break. Ignore it (don't type
- it in your Script-Fu console and don't hit Enter), just continue
- with the next line.
+ The <quote><code>\</code></quote> indicates that there is no line
+ break. Ignore it (don't type it in your Script-Fu console and don't
+ hit <keycap>Enter</keycap>), just continue with the next line.
</para>
</note>
</sect3>
+
<sect3>
- <title>
- <phrase>Functions</phrase>
- </title>
+ <title>Functions</title>
<para>
Now that you've got the hang of variables, let's get to work with some
functions. You declare a function with the following syntax:
@@ -351,7 +341,8 @@
called. For example:
</para>
<programlisting>(define (AddXY inX inY) (+ inX inY) )</programlisting>
- <para><varname>AddXY</varname> is the function's name and
+ <para>
+ <varname>AddXY</varname> is the function's name and
<varname>inX</varname> and <varname>inY</varname>
are the variables. This function takes its two parameters and adds
them together.
@@ -364,7 +355,8 @@
<itemizedlist>
<listitem>
<para>
- First, notice that the parameters don't have any "types" (that is,
+ First, notice that the parameters don't have any
+ <quote>types</quote> (that is,
we didn't declare them as strings, or integers, etc.). Scheme is a
type-less language. This is handy and allows for quicker script
writing.
@@ -372,9 +364,10 @@
</listitem>
<listitem>
<para>
- Second, notice that we don't need to worry about how to "return"
- the result of our function -- the last statement is the value
- "returned" when calling this function. Type the function into the
+ Second, notice that we don't need to worry about how to
+ <quote>return</quote> the result of our function — the last
+ statement is the value <quote>returned</quote> when calling this
+ function. Type the function into the
console, then try something like:
</para>
<programlisting>(AddXY (AddXY 5 6) 4)</programlisting>
@@ -382,18 +375,16 @@
</itemizedlist>
</sect3>
</sect2>
+
<sect2 id="gimp-using-script-fu-tutorial-lists">
- <title>
- <phrase>Lists, Lists And More Lists</phrase>
- </title>
+ <title>Lists, Lists And More Lists</title>
<para>
We've trained you in variables and functions, and now enter the
murky swamps of Scheme's lists.
</para>
+
<sect3>
- <title>
- <phrase>Defining A List</phrase>
- </title>
+ <title>Defining A List</title>
<para>
Before we talk more about lists, it is necessary that you know
the difference between atomic values and lists.
@@ -401,14 +392,15 @@
<para>
You've already seen atomic values when we initialized
variables in the previous lesson. An atomic value is a single
- value. So, for example, we can assign the variable "x" the
+ value. So, for example, we can assign the variable
+ <quote><varname>x</varname></quote> the
single value of 8 in the following statement:
</para>
<programlisting>(let* ( (x 8) ) x)</programlisting>
<para>
(We added the expression <varname>x</varname> at the end to print out
- the value assigned to <varname>x</varname>-- normally you won't need
- to do this. Notice how <code>let*</code> operates just like a
+ the value assigned to <varname>x</varname>—normally you won't
+ need to do this. Notice how <code>let*</code> operates just like a
function: The value of the last statement is the value returned.)
</para>
<para>
@@ -431,7 +423,8 @@
<para>
When it replies with the value 8 it is informing you that
<varname>x</varname> contains the atomic value 8. However,
- when it replies with (1 3 5), it is then informing you that
+ when it replies with <computeroutput>(1 3 5)</computeroutput>, it is
+ then informing you that
<varname>x</varname> contains not a single value, but a list
of values. Notice that there are no commas in our declaration
or assignment of the list, nor in the printed result.
@@ -440,7 +433,8 @@
<programlisting>'(a b c)</programlisting>
<para>
where <varname>a</varname>, <varname>b</varname>, and
- <varname>c</varname> are literals. We use the apostrophe (')
+ <varname>c</varname> are literals. We use the apostrophe
+ (<code>'</code>)
to indicate that what follows in the parentheses is a list of
literal values, rather than a function or expression.
</para>
@@ -448,9 +442,7 @@
<programlisting>'()</programlisting>
<para>or simply:</para>
<programlisting>()</programlisting>
- <para>
- Lists can contain atomic values, as well as other lists:
- </para>
+ <para>Lists can contain atomic values, as well as other lists:</para>
<programlisting>
(let*
(
@@ -472,30 +464,26 @@
<code>("The GIMP")</code>, the list <code>(1 2 3)</code>, etc.
</para>
</sect3>
+
<sect3>
- <title>
- <phrase>How To Think Of Lists</phrase>
- </title>
+ <title>How To Think Of Lists</title>
<para>
- It's useful to think of lists as composed of a <quote>head</quote> and a
- <quote>tail</quote>.
+ It's useful to think of lists as composed of a <quote>head</quote>
+ and a <quote>tail</quote>.
The head is the first element of the list, the tail the rest of the
list. You'll see why this is important when we discuss how to add to
lists and how to access elements in the list.
</para>
</sect3>
+
<sect3>
- <title>
- <phrase>
- Creating Lists Through Concatenation (The Cons Function)
- </phrase>
- </title>
+ <title>Creating Lists Through Concatenation (The Cons Function)</title>
<para>
One of the more common functions you'll encounter is the cons
function. It takes a value and places it to its second argument, a
list. From the previous section, I suggested that you think of a list
as being composed of an element (the head) and the remainder of the
- list (the tail). This is exactly how cons functions -- it adds an
+ list (the tail). This is exactly how cons functions — it adds an
element to the head of a list. Thus, you could create a list as
follows:
</para>
@@ -508,15 +496,12 @@
you would expect.
</para>
</sect3>
+
<sect3>
- <title>
- <phrase>
- Defining A List Using The <code>list</code> Function
- </phrase>
- </title>
+ <title>Defining A List Using The <code>list</code> Function</title>
<para>
To define a list composed of literals or previously declared
- variables, use the list function:
+ variables, use the <function>list</function> function:
</para>
<programlisting>(list 5 4 3 a b c)</programlisting>
<para>
@@ -538,23 +523,22 @@
This code creates the list <code>(5 4 3 1 2 3)</code>.
</para>
</sect3>
+
<sect3>
- <title>
- <phrase>Accessing Values In A List</phrase>
- </title>
+ <title>Accessing Values In A List</title>
<para>
To access the values in a list, use the functions
- <code>car</code> and <code>cdr</code>,
+ <function>car</function> and <function>cdr</function>,
which return the first element of the list and the rest of the list,
respectively. These functions break the list down into the head::tail
construct I mentioned earlier.
</para>
</sect3>
+
<sect3>
- <title>
- <phrase>The <code>car</code> Function</phrase>
- </title>
- <para><code>car</code> returns the first element of the list (the
+ <title>The <function>car</function> Function</title>
+ <para>
+ <function>car</function> returns the first element of the list (the
head of the list). The list needs to be non-null. Thus, the
following returns the first element of the list:
</para>
@@ -562,11 +546,12 @@
<para>which is:</para>
<programlisting>"first"</programlisting>
</sect3>
+
<sect3>
- <title>
- <phrase>The <code>cdr</code> function</phrase>
- </title>
- <para><code>cdr</code> returns the rest of the list after the first element
+ <title>The <function>cdr</function> function</title>
+ <para>
+ <function>cdr</function> returns the rest of the list after the first
+ element
(the tail of the list). If there is only one element in the list, it
returns an empty list.
</para>
@@ -578,10 +563,9 @@
<para>returns:</para>
<programlisting>()</programlisting>
</sect3>
+
<sect3>
- <title>
- <phrase>Accessing Other Elements In A List</phrase>
- </title>
+ <title>Accessing Other Elements In A List</title>
<para>
OK, great, we can get the first element in a list, as well as
the rest of the list, but how do we access the second, third
@@ -600,8 +584,8 @@
<para>
To get some practice with list-accessing functions, try typing in the
following (except all on one line if you're using the console); use
- different variations of car and cdr to access the different elements
- of the list:
+ different variations of <function>car</function> and
+ <function>cdr</function> to access the different elements of the list:
</para>
<programlisting>
(let* (
@@ -618,7 +602,7 @@
</para>
<note>
<para>
- In Scheme, a semicolon (";") marks a comment. It, and
+ In Scheme, a semicolon (<code>;</code>) marks a comment. It, and
anything that follows it on the same line, are ignored by the
script interpreter, so you can use this to add comments to jog
your memory when you look at the script later.
@@ -626,22 +610,20 @@
</note>
</sect3>
</sect2>
+
<sect2 id="gimp-using-script-fu-tutorial-first-script">
- <title>
- <phrase>Your First Script-Fu Script</phrase>
- </title>
+ <title>Your First Script-Fu Script</title>
<para>
Do you not need to stop and catch your breath? No? Well then,
- let's proceed with your fourth lesson -- your first Script-Fu
+ let's proceed with your fourth lesson — your first Script-Fu
Script.
</para>
+
<sect3>
- <title>
- <phrase>Creating A Text Box Script</phrase>
- </title>
+ <title>Creating A Text Box Script</title>
<para>
- 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
+ One of the most common operations I perform in <acronym>GIMP</acronym>
+ 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
@@ -659,58 +641,58 @@
font, font size and text color.
</para>
</sect3>
+
<sect3>
- <title>
- <phrase>Editing And Storing Your Scripts</phrase>
- </title>
+ <title>Editing And Storing Your Scripts</title>
<para>
Up until now, we've been working in the Script-Fu Console. Now,
however, we're going to switch to editing script text files.
</para>
<para>
- 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
+ Where you place your scripts is a matter of preference — if you
+ have access to <acronym>GIMP</acronym>'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.
</para>
<para>
- In the <filename>.gimp-2.4</filename> directory that GIMP made
- off of your home directory, you should find a directory called
- <filename>scripts</filename>. GIMP will automatically look in
- your <filename>.gimp-2.4</filename> directory for a scripts
- directory, and add the
- scripts in this directory to the Script-Fu database. You
- should place your personal scripts here.
+ In the <filename class="directory">.gimp-2.6</filename> directory that
+ <acronym>GIMP</acronym> made off of your home directory, you should
+ find a directory called <filename class="directory">scripts</filename>.
+ <acronym>GIMP</acronym> will automatically look in your
+ <filename class="directory">.gimp-2.6</filename> directory for a
+ <filename class="directory">scripts</filename> directory, and add the
+ scripts in this directory to the
+ Script-Fu database. You should place your personal scripts here.
</para>
</sect3>
+
<sect3>
- <title>
- <phrase>The Bare Essentials</phrase>
- </title>
+ <title>The Bare Essentials</title>
<para>
Every Script-Fu script defines at least one function, which is the
script's main function. This is where you do the work.
</para>
<para>
Every script must also register with the procedural database, so you
- can access it within GIMP.
+ can access it within <acronym>GIMP</acronym>.
</para>
<para>We'll define the main function first:</para>
<programlisting>
(define (script-fu-text-box inText inFont inFontSize inTextColor))
</programlisting>
<para>
- Here, we've defined a new function called script-fu-text-box that
+ Here, we've defined a new function called
+ <function>script-fu-text-box</function> 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.
+ empty and thus does nothing. So far, so good — nothing new,
+ nothing fancy.
</para>
</sect3>
+
<sect3>
- <title>
- <phrase>Naming Conventions</phrase>
- </title>
+ <title>Naming Conventions</title>
<para>
Scheme's naming conventions seem to prefer lowercase letters with
hyphens, which I've followed in the naming of the function. However,
@@ -721,20 +703,20 @@
prefix "the" for variables defined within the script.
</para>
<para>
- It's GIMP convention to name your script functions script-fu-abc,
+ It's <acronym>GIMP</acronym> convention to name your script functions
+ <function>script-fu-abc</function>,
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.
</para>
</sect3>
+
<sect3>
- <title>
- <phrase>Registering The Function</phrase>
- </title>
+ <title>Registering The Function</title>
<para>
- Now, let's register the function with GIMP. This is done by
- calling the function <code>script-fu-register</code>. When
- GIMP reads in a
+ Now, let's register the function with <acronym>GIMP</acronym>. This is
+ done by calling the function <function>script-fu-register</function>.
+ When <acronym>GIMP</acronym> 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
@@ -745,31 +727,41 @@
explain all its parameters in a minute):
</para>
<programlisting><![CDATA[
- (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")
+ (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;\
+ 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")
]]></programlisting>
<para>
If you save these functions in a text file with a
- <filename>.scm</filename> suffix
+ <filename class="extension">.scm</filename> suffix
in your script directory, then choose
- <menuchoice><guimenu>Xtns</guimenu><guisubmenu>Script-Fu</guisubmenu><guimenuitem>Refresh Scripts</guimenuitem></menuchoice>,
+ <menuchoice>
+ <guimenu>Filters</guimenu>
+ <guisubmenu>Script-Fu</guisubmenu>
+ <guimenuitem>Refresh Scripts</guimenuitem>
+ </menuchoice>,
this new script will appear as
- <menuchoice><guimenu> Xtns</guimenu><guisubmenu>Script-Fu</guisubmenu><guisubmenu>Text</guisubmenu><guimenuitem>Text Box</guimenuitem></menuchoice>.
+ <menuchoice>
+ <guimenu>File</guimenu>
+ <guisubmenu>Create</guisubmenu>
+ <guisubmenu>Text</guisubmenu>
+ <guimenuitem>Text Box</guimenuitem>
+ </menuchoice>.
</para>
<para>
If you invoke this new script, it won't do anything, of course, but
@@ -778,31 +770,31 @@
</para>
<para>
Finally, if you invoke the Procedure Browser (
- <menuchoice><guimenu> Xtns</guimenu><guimenuitem>Procedure Browser</guimenuitem></menuchoice>),
- you'll notice that our script now
- appears in the database.
+ <menuchoice>
+ <guimenu>Help</guimenu>
+ <guimenuitem>Procedure Browser</guimenuitem>
+ </menuchoice>),
+ you'll notice that our script now appears in the database.
</para>
</sect3>
+
<sect3>
- <title>
- <phrase>Steps For Registering The Script</phrase>
- </title>
+ <title>Steps For Registering The Script</title>
<para>
- 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.
+ To register our script with <acronym>GIMP</acronym>, we call the
+ function <function>script-fu-register</function>, fill in the seven
+ required parameters and add our script's own parameters, along with a
+ description and default value for each parameter.
</para>
<itemizedlist>
- <title>
- <phrase>The Required Parameters</phrase>
- </title>
+ <title>The Required Parameters</title>
<listitem>
<para>
The <emphasis>name</emphasis> 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
+ define additional functions within the same file, and
+ <acronym>GIMP</acronym> needs to
know which of these functions to call. In our example, we only
defined one function, text-box, which we registered.
</para>
@@ -812,28 +804,42 @@
The <emphasis>location</emphasis> 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.
+ image menu as <code><Image></code>.<footnote><para>
+ Before version 2.6, <code><Toolbox></code> could be also
+ used, but now the toolbox menu is removed, so don't use it.
+ </para></footnote>
</para>
<para>
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.).
+ to insert it in the image window menu, which you can access
+ through the image menu bar, by right-clicking the image window,
+ by clicking the menu button icon at the left-top corner of the
+ image window, or by pressing <keycap>F10</keycap>.
</para>
- <para><!--FIXME: en needs a review-->
+ <para><!--FIXME: en needs more review!-->
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 (
- <menuchoice><guimenu> Xtns</guimenu><guisubmenu>Script-Fu</guisubmenu><guisubmenu>Text</guisubmenu><guimenuitem>Text Box</guimenuitem></menuchoice> ).
+ you'll want to insert it in the image window menu.
+ The rest of the path points to the menu lists, menus and sub-menus.
+ Thus, we registered our Text Box script in the
+ <guisubmenu>Text</guisubmenu> menu of the
+ <guisubmenu>Create</guisubmenu> menu of the <guimenu>File</guimenu>
+ menu.<footnote><para>
+ The original, written by Mike, says put the menu entry in the
+ Script-Fu menu of the <guimenu>Xtns</guimenu> menu at the
+ Toolbox, but since version 2.6, the Toolbox menu had been removed
+ and merged with the image window menubar.</para></footnote> (
+ <menuchoice>
+ <guimenu>File</guimenu>
+ <guisubmenu>Create</guisubmenu>
+ <guisubmenu>Text</guisubmenu>
+ <guimenuitem>Text Box</guimenuitem>
+ </menuchoice> ).
</para>
<para>
- 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.
+ If you notice, the Text sub-menu in the File/Create menu wasn't
+ there when we began — <acronym>GIMP</acronym> automatically
+ creates any menus not already existing.
</para>
</listitem>
<listitem>
@@ -843,13 +849,12 @@
</para>
</listitem>
<listitem>
- <para><emphasis>Your name</emphasis> (the author of
- the script).
+ <para>
+ <emphasis>Your name</emphasis> (the author of the script).
</para>
</listitem>
<listitem>
- <para><emphasis>Copyright</emphasis> information.
- </para>
+ <para><emphasis>Copyright</emphasis> information.</para>
</listitem>
<listitem>
<para>
@@ -861,27 +866,26 @@
<para>
The <emphasis>types</emphasis> 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,
+ 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.
</para>
</listitem>
</itemizedlist>
<figure>
- <title>
- <phrase>The menu of our script.</phrase>
- </title>
+ <title>The menu of our script.</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/using/script-fu-menu.png" format="PNG"/>
+ <imagedata format="PNG"
+ fileref="images/using/script-fu-menu.png"/>
</imageobject>
</mediaobject>
</figure>
</sect3>
+
<sect3>
- <title>
- <phrase>Registering The Script's Parameters</phrase>
- </title>
+ <title>Registering The Script's Parameters</title>
<para>
Once we have listed the required parameters, we then need to list the
parameters that correspond to the parameters our script needs. When we
@@ -910,12 +914,13 @@
<tbody>
<row>
<entry>
- <para>SF-IMAGE</para>
+ <para><type>SF-IMAGE</type></para>
</entry>
<entry>
<para>
If your script operates on an open image, this should be the
- first parameter after the required parameters. GIMP will
+ first parameter after the required parameters.
+ <acronym>GIMP</acronym> will
pass in a reference to the image in this parameter.
</para>
</entry>
@@ -925,14 +930,14 @@
</row>
<row>
<entry>
- <para>SF-DRAWABLE</para>
+ <para><type>SF-DRAWABLE</type></para>
</entry>
<entry>
<para>
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.
+ second parameter after the <type>SF-IMAGE</type> param. It
+ refers to the active layer. <acronym>GIMP</acronym> will pass
+ in a reference to the active layer in this parameter.
</para>
</entry>
<entry>
@@ -941,12 +946,13 @@
</row>
<row>
<entry>
- <para>SF-VALUE</para>
+ <para><type>SF-VALUE</type></para>
</entry>
<entry>
<para>
Accepts numbers and strings. Note that quotes must be
- escaped for default text, so better use SF-STRING.
+ escaped for default text, so better use
+ <type>SF-STRING</type>.
</para>
</entry>
<entry>
@@ -955,7 +961,7 @@
</row>
<row>
<entry>
- <para>SF-STRING</para>
+ <para><type>SF-STRING</type></para>
</entry>
<entry>
<para>Accepts strings.</para>
@@ -966,7 +972,7 @@
</row>
<row>
<entry>
- <para>SF-COLOR</para>
+ <para><type>SF-COLOR</type></para>
</entry>
<entry>
<para>
@@ -979,7 +985,7 @@
</row>
<row>
<entry>
- <para>SF-TOGGLE</para>
+ <para><type>SF-TOGGLE</type></para>
</entry>
<entry>
<para>
@@ -996,41 +1002,42 @@
</sect3>
<xi:include href="script-fu-gui-api.xml"/>
</sect2>
+
<sect2 id="gimp-using-script-fu-tutorial-script">
- <title>
- <phrase>Giving Our Script Some Guts</phrase>
- </title>
+ <title>Giving Our Script Some Guts</title>
<para>
Let us continue with our training and add some functionality to our
script.
</para>
+
<sect3>
- <title>
- <phrase>Creating A New Image</phrase>
- </title>
+ <title>Creating A New Image</title>
<para>
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.
+ with <acronym>GIMP</acronym>. 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.
</para>
<para>
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'!
+ members, the rest is all downhill — all you need to do is
+ familiarize yourself with the functions available in
+ <acronym>GIMP</acronym>'s procedural database and call those functions
+ directly. So fire up the
+ <xref linkend="plug-in-dbbrowser"/> and let's get cookin'!
</para>
<para>
Let's begin by making a new image. We'll create a new variable,
- <varname>theImage</varname>, set to the result of calling GIMP's
- built-in function <code>gimp-image-new</code>.
+ <varname>theImage</varname>, set to the result of calling
+ <acronym>GIMP</acronym>'s
+ built-in function <function>gimp-image-new</function>.
</para>
<para>
As you can see from the DB Browser, the function
- <code>gimp-image-new</code> takes three parameters -- the
+ <function>gimp-image-new</function> 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
+ later resize the image to fit the text, we'll make a 10x10 pixels
+ <acronym>RGB</acronym>
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.
@@ -1055,25 +1062,26 @@
;we create later
</programlisting>
<para>
- 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.
+ Note: We used the value <code>RGB</code> to specify that the image
+ is an <acronym>RGB</acronym> image. We could have also used
+ <code>0</code>, but <acronym>RGB</acronym> is more descriptive
+ when we glance at the code.
</para>
<para>
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
+ tells us that it returns only one value — the ID of the newly
+ created image. However, all <acronym>GIMP</acronym> functions return a
+ list, even if there is
only one element in the list, so we need to get the head of the list.
</para>
</sect3>
+
<sect3>
- <title>
- <phrase>Adding A New Layer To The Image</phrase>
- </title>
+ <title>Adding A New Layer To The Image</title>
<para>
Now that we have an image, we need to add a layer to it. We'll
- call the <code>gimp-layer-new</code> function to create the
+ call the <function>gimp-layer-new</function> function to create the
layer, passing
in the ID of the image we just created. (From now on, instead
of listing the complete function, we'll only list the lines
@@ -1100,9 +1108,7 @@
)
) ;end of our local variables
</programlisting>
- <para>
- Once we have the new layer, we need to add it to the image:
- </para>
+ <para>Once we have the new layer, we need to add it to the image:</para>
<programlisting>
(gimp-image-add-layer theImage theLayer 0)
</programlisting>
@@ -1110,24 +1116,25 @@
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:
</para>
- <programlisting>
- (gimp-display-new theImage)
- </programlisting>
+ <programlisting>(gimp-display-new theImage)</programlisting>
<para>
Save your work, select
- <menuchoice><guimenu>Xtns</guimenu><guisubmenu>Script-Fu</guisubmenu><guimenuitem>Refresh Scripts</guimenuitem></menuchoice>,
+ <menuchoice>
+ <guimenu>Filters</guimenu>
+ <guisubmenu>Script-Fu</guisubmenu>
+ <guimenuitem>Refresh Scripts</guimenuitem>
+ </menuchoice>,
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.
</para>
</sect3>
+
<sect3>
- <title>
- <phrase>Adding The Text</phrase>
- </title>
+ <title>Adding The Text</title>
<para>
Go ahead and remove the line to display the image (or comment
- it out with a ; as the first character of the line).
+ it out with a (<code>;</code>) as the first character of the line).
</para>
<para>
Before we add text to the image, we need to set the background
@@ -1147,9 +1154,7 @@
<programlisting>
(gimp-drawable-fill theLayer BACKGROUND-FILL)
</programlisting>
- <para>
- With the image cleared, we're ready to add some text:
- </para>
+ <para>With the image cleared, we're ready to add some text:</para>
<programlisting>
(set! theText
(car
@@ -1201,18 +1206,18 @@
Save your work, refresh the database and give your first script a run!
</para>
</sect3>
+
<sect3>
- <title>
- <phrase>Clearing The Dirty Flag</phrase>
- </title>
+ <title>Clearing The Dirty Flag</title>
<para>
If you try to close the image created without first saving the file,
- GIMP will ask you if you want to save your work before you close the
+ <acronym>GIMP</acronym> will ask you if you want to save your work
+ before you close the
image. It asks this because the image is marked as dirty, or unsaved.
In the case of our script, this is a nuisance for the times when we
simply give it a test run and don't add or change anything in the
- resulting image -- that is, our work is easily reproducible in such a
- simple script, so it makes sense to get rid of this dirty flag.
+ resulting image — that is, our work is easily reproducible in
+ such a simple script, so it makes sense to get rid of this dirty flag.
</para>
<para>
To do this, we can clear the dirty flag after displaying the image:
@@ -1221,8 +1226,8 @@
(gimp-image-clean-all theImage)
</programlisting>
<para>
- This will set dirty count to 0, making it appear to be a "clean"
- image.
+ This will set dirty count to 0, making it appear to be a
+ <quote>clean</quote> image.
</para>
<para>
Whether to add this line or not is a matter of personal taste. I use
@@ -1232,24 +1237,21 @@
</para>
</sect3>
</sect2>
+
<sect2 id="gimp-using-script-fu-tutorial-extending-text-box">
- <title>
- <phrase>Extending The Text Box Script</phrase>
- </title>
+ <title>Extending The Text Box Script</title>
<sect3>
- <title>
- <phrase>Handling Undo Correctly</phrase>
- </title>
+ <title>Handling Undo Correctly</title>
<para>
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
- <code>gimp-undo-push-group-start</code>
- and <code>gimp-undo-push-group-end</code>
+ <function>gimp-undo-push-group-start</function>
+ and <function>gimp-undo-push-group-end</function>
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.
+ matched statements that let <acronym>GIMP</acronym> know when to start
+ and stop recording manipulations on the image, so that those
+ manipulations can later be undone.
</para>
<para>
If you are creating a new image entirely, it doesn't make sense to use
@@ -1261,10 +1263,9 @@
Undoing a script works nearly flawlessly when using these functions.
</para>
</sect3>
+
<sect3>
- <title>
- <phrase>Extending The Script A Little More</phrase>
- </title>
+ <title>Extending The Script A Little More</title>
<para>
Now that we have a very handy-dandy script to create text
boxes, let's add two features to it:
@@ -1273,7 +1274,7 @@
<listitem>
<para>
Currently, the image is resized to fit exactly around the
- text -- there's no room for anything, like drop shadows or
+ text — there's no room for anything, like drop shadows or
special effects (even though many scripts will automatically
resize the image as necessary). Let's add a buffer around
the text, and even let the user specify how much buffer to
@@ -1290,81 +1291,80 @@
</listitem>
</itemizedlist>
</sect3>
+
<sect3>
<title>
- <phrase>
- Modifying The Parameters And The Registration Function
- </phrase>
+ Modifying The Parameters And The Registration Function
</title>
<para>
To let the user specify the amount of buffer, we'll add a parameter to
our function and the registration function:
</para>
<programlisting>
- (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
+ (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) ;<emphasis>added</emphasis>
+ (theBuffer) ;<emphasis>added</emphasis>
- (theLayer
- (car
- (gimp-layer-new
- theImage
- theImageWidth
- theImageHeight
- RGB-IMAGE
- "layer 1"
- 100
- NORMAL
- )
- )
- )
- ) ;end of our local variables
+ (theLayer
+ (car
+ (gimp-layer-new
+ theImage
+ theImageWidth
+ theImageHeight
+ RGB-IMAGE
+ "layer 1"
+ 100
+ NORMAL
+ )
+ )
+ )
+ ) ;end of our local variables
- <replaceable>[Code here]</replaceable>
- )
+ <replaceable>[Code here]</replaceable>
+ )
</programlisting>
<programlisting><![CDATA[
- (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")
+ (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;\
+ 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
+ SF-ADJUSTMENT "Buffer amount" '(35 0 100 1 10 1 0)
+ ;a slider
+ )
+ (script-fu-menu-register "script-fu-text-box" "<Image>/Font/Create/Text")
]]></programlisting>
</sect3>
+
<sect3>
- <title>
- <phrase>Adding The New Code</phrase>
- </title>
+ <title>Adding The New Code</title>
<para>
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
@@ -1375,8 +1375,8 @@
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.
+ there's no reason why the user can't enter a value like
+ <quote>200</quote> as the percent of buffer to add.
</para>
<programlisting>
(set! theBuffer (* theImageHeight (/ inBufferAmount 100) ) )
@@ -1408,9 +1408,7 @@
All that is left to do is return our image, the layer, and the text
layer. After displaying the image, we add this line:
</para>
- <programlisting>
- (list theImage theLayer theText)
- </programlisting>
+ <programlisting>(list theImage theLayer theText)</programlisting>
<para>
This is the last line of the function, making this list available to
other scripts that want to use it.
@@ -1434,107 +1432,105 @@
</para>
</sect3>
</sect2>
+
<sect2 id="gimp-using-script-fu-tutorial-result">
- <title>
- <phrase>Your script and its working</phrase>
- </title>
+ <title>Your script and its working</title>
<sect3>
- <title>
- <phrase>What you write</phrase>
- </title>
+ <title>What you write</title>
<para>Below the complete script:</para>
<programlisting><![CDATA[
- (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-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;\
+ 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
+ SF-ADJUSTMENT "Buffer amount" '(35 0 100 1 10 1 0)
+ ;a slider
+ )
+ (script-fu-menu-register "script-fu-text-box" "<Image>/File/Create/Text")
+ (define (script-fu-text-box inText inFont inFontSize inTextColor inBufferAmount)
+ (let*
+ (
+ ; define our local variables
+ ; create a new image:
+ (theImageWidth 10)
+ (theImageHeight 10)
+ (theImage)
+ (theImage
+ (car
+ (gimp-image-new
+ theImageWidth
+ theImageHeight
+ RGB
+ )
+ )
)
- (script-fu-menu-register "script-fu-text-box" "<Toolbox>/Xtns/Script-Fu/Text")
- (define (script-fu-text-box inText inFont inFontSize inTextColor inBufferAmount)
- (let*
- (
- ; define our local variables
- ; create a new image:
- (theImageWidth 10)
- (theImageHeight 10)
- (theImage)
- (theImage
- (car
- (gimp-image-new
- theImageWidth
- theImageHeight
- RGB
- )
- )
- )
- (theText) ;a declaration for the text
- (theBuffer) ;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
- (gimp-image-add-layer theImage theLayer 0)
- (gimp-context-set-background '(255 255 255) )
- (gimp-context-set-foreground inTextColor)
- (gimp-drawable-fill theLayer BACKGROUND-FILL)
- (set! theText
- (car
- (gimp-text-fontname
- theImage theLayer
- 0 0
- inText
- 0
- TRUE
- inFontSize PIXELS
- "Sans")
- )
- )
- (set! theImageWidth (car (gimp-drawable-width theText) ) )
- (set! theImageHeight (car (gimp-drawable-height theText) ) )
- (set! theBuffer (* theImageHeight (/ inBufferAmount 100) ) )
- (set! theImageHeight (+ theImageHeight theBuffer theBuffer) )
- (set! theImageWidth (+ theImageWidth theBuffer theBuffer) )
- (gimp-image-resize theImage theImageWidth theImageHeight 0 0)
- (gimp-layer-resize theLayer theImageWidth theImageHeight 0 0)
- (gimp-layer-set-offsets theText theBuffer theBuffer)
- (gimp-display-new theImage)
- (list theImage theLayer theText)
- )
+ (theText) ;a declaration for the text
+ (theBuffer) ;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
+ (gimp-image-add-layer theImage theLayer 0)
+ (gimp-context-set-background '(255 255 255) )
+ (gimp-context-set-foreground inTextColor)
+ (gimp-drawable-fill theLayer BACKGROUND-FILL)
+ (set! theText
+ (car
+ (gimp-text-fontname
+ theImage theLayer
+ 0 0
+ inText
+ 0
+ TRUE
+ inFontSize PIXELS
+ "Sans")
+ )
)
+ (set! theImageWidth (car (gimp-drawable-width theText) ) )
+ (set! theImageHeight (car (gimp-drawable-height theText) ) )
+ (set! theBuffer (* theImageHeight (/ inBufferAmount 100) ) )
+ (set! theImageHeight (+ theImageHeight theBuffer theBuffer) )
+ (set! theImageWidth (+ theImageWidth theBuffer theBuffer) )
+ (gimp-image-resize theImage theImageWidth theImageHeight 0 0)
+ (gimp-layer-resize theLayer theImageWidth theImageHeight 0 0)
+ (gimp-layer-set-offsets theText theBuffer theBuffer)
+ (gimp-display-new theImage)
+ (list theImage theLayer theText)
+ )
+ )
]]></programlisting>
</sect3>
+
<sect3>
<title>What you obtain</title>
<figure>
- <title>
- <phrase>And the result on the screen.</phrase>
- </title>
+ <title>And the result on the screen.</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/using/script-fu-screen.png" format="PNG"/>
+ <imagedata format="PNG"
+ fileref="images/using/script-fu-screen.png"/>
</imageobject>
</mediaobject>
</figure>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
