3.4. Su primer código de Script-Fu
| 3. Un tutorial de Script-Fu |

### 3.4. Su primer código de Script-Fu

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. Crear un código: una caja de texto

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.

Los maestros de Script-Fu (y los estudiantes), rapidamente, reconocen que este problema puede resolverse, facilmente, y automatizando con Script-Fu.

Crearemos un script, llamado Text Box, que creará una imagen, con el tamaño correctamente ajustado a una linea de texto, que el usuario introduce. También, dejaremos al usuario elegir la fuente, el tamaño de la fuente y el color del texto.

#### 3.4.2. Editar y guardar su código

Hasta ahora, hemos trabajado en la consola de Script-Fu. Ahora, sin embargo, vamos a cambiar para editar códigos de archivos de texto.

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.6` directory that GIMP made off of your home directory, you should find a directory called `scripts`. GIMP will automatically look in your `.gimp-2.6` 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. Lo esencial al descubierto

Cada script Script-Fu define al menos una función, la cual es la función principal del script. Esta es donde haces el trabajo.

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

Definiremos la función principal, primero:

            (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. Convenciones de nombres

Las convenciones de nombres en Scheme parecen preferir minúsculas con guiones, en el nombre de la función. Sin embargo, parto de la convención con los parámetros. Quiero nombres más descriptivos para mis parámetros y variables, y añado el prefijo "in" a los parámetros, así que, puedo, rapidamente, ver que valores entran en el script, más bien que los que se crean en el. Uso el prefijo "the" para las variables definidas en el 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. Registro de la función

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.

Aquí está el listado de registro de esta función (explicaré todos estos parámetros en un minuto):

      (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")

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.

Si llama a este nuevo script, no hará nada, desde luego, pero puede ver los apuntes creados cuando se registra el script (más información de lo que hicimos, se descubrirá luego).

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

#### 3.4.6. Pasos para registrar el código

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.

Los parámetros requeridos

- 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 image menu as `<Image>`.[5]

  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 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 F10.

  If your script is intended to work on an image being edited, 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 Text menu of the Create menu of the File menu.[6] (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.

- Una descripción de su script, para ser mostrada en el Examinador de Procedimientos.

- Su nombre (el autor del código).

- Información del copyright.

- La fecha en que se hizó el código, o la última revisión del mismo.

- 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.

Figura 12.4. The menu of our script.

#### 3.4.7. Registro de los parámetros del código

Una vez que hemos listado los parámetros requeridos, necesitamos listar los parámetros que corresponden a los parámetros que nuestro script necesita. Cuando listamos estos parámetros, les damos indicación de como son. Esto es por el diálogo que surge cuando el usuario selecciona nuestro script. También podemos proporcionar valores predefinidos.

Esta sección del proceso de registro tiene el siguiente formato:

Tipo de parámetro | Descripción | Ejemplo
--- | --- | ---
`SF-IMAGE` | 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. | 3
`SF-DRAWABLE` | 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. | 17
`SF-VALUE` | Accepts numbers and strings. Note that quotes must be escaped for default text, so better use `SF-STRING`. | 42
`SF-STRING` | Acepta cadenas. | "Un texto"
`SF-COLOR` | Indica que color se requiere en este parámetro. | '(0 102 255)
`SF-TOGGLE` | Se muestra una caja, para obtener un valor Booleano | TRUE o FALSE

#### 3.4.8. The Script-Fu parameter API[7]

| Nota
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.

Tipo de parámetro | Descripción
--- | ---

`SF-ADJUSTMENT`

Creates an adjustment widget in the dialog.

SF-ADJUSTMENT "label" '(value lower upper step_inc page_inc digits type)

Widget arguments list

Element | Descripción
--- | ---
"label" | Text printed before the widget.
value | Value print at the start.
lower / upper | The lower / upper values (range of choice).
step_inc | Increment/decrement value.
page_inc | Increment/decrement value using page key.
digits | Digits after the point (decimal part).
type | One of: SF-SLIDER or 0, SF-SPINNER or 1

`SF-COLOR`

TODO: Description

SF-COLOR "label" '(red green blue)

or

SF-COLOR "label" "color"

Widget arguments list

Element | Descripción
--- | ---
"label" | Text printed before the widget.
'(red green blue) | List of three values for the red, green and blue components.
"color" | Color name in CSS notatation.

`SF-FONT`

TODO: Description

(gimp-text-fontname image drawable x-pos y-pos text border antialias size unit font)

(gimp-text-get-extents-fontname text size unit font)

where font is the fontname you get. The size specified in the fontname is silently ignored. It is only used in the font-selector. So you are asked to set it to a useful value (24 pixels is a good choice).

SF-FONT "label" "fontname"

Widget arguments list

Element | Descripción
--- | ---
"label" | Text printed before the widget.
"fontname" | Name of the default font.

`SF-BRUSH` | TODO: Description SF-BRUSH "Brush" '("Circle (03)" 100 44 0) Here the brush dialog will be popped up with a default brush of Circle (03) opacity 100 spacing 44 and paint mode of Normal (value 0). If this selection was unchanged the value passed to the function as a parameter would be '("Circle (03)" 100 44 0).
`SF-PATTERN` | TODO: Description SF-PATTERN "Pattern" "Maple Leaves" The value returned when the script is invoked is a string containing the pattern name. If the above selection was not altered the string would contain "Maple Leaves".
`SF-GRADIENT` | TODO: Description If the button is pressed a gradient selection dialog will popup. SF-GRADIENT "Gradient" "Deep Sea" The value returned when the script is invoked is a string containing the gradient name. If the above selection was not altered the string would contain "Deep Sea".
`SF-PALETTE` | TODO: Description If the button is pressed a palette selection dialog will popup. SF-PALETTE "Palette" "Named Colors" The value returned when the script is invoked is a string containing the palette name. If the above selection was not altered the string would contain "Named Colors".
`SF-FILENAME` | TODO: Description If the button is pressed a file selection dialog will popup. SF-FILENAME "label" (string-append "" gimp-data-directory "/scripts/beavis.jpg") The value returned when the script is invoked is a string containing the filename.
`SF-DIRNAME` | TODO: Description SF-DIRNAME "label" "/var/tmp/images" The value returned when the script is invoked is a string containing the dirname.
`SF-OPTION` | TODO: Description The first option is the default choice. SF-OPTION "label" '("option1" "option2") The value returned when the script is invoked is the number of the chosen option, where the option first is counted as 0.
`SF-ENUM` | TODO: Description SF-ENUM "Interpolation" '("InterpolationType" "linear") The value returned when the script is invoked corresponds to chosen enum value.

[5] Before version 2.6, `<Toolbox>` could be also used, but now the toolbox menu is removed, so don't use it.

[6] The original, written by Mike, says put the menu entry in the Script-Fu menu of the Xtns menu at the Toolbox, but since version 2.6, the Toolbox menu had been removed and merged with the image window menubar.

[7] This section is not part of the original tutorial.

3.3. Listas, listas y más listas |  | 3.5. Dar algo de sustancia a nuestro script