### 3.4. Váš první Script-Fu skript

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. Vytvoření skriptu Text Box

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.

This problem can be solved and automated with Script-Fu.

Proto vytvoříme skript, který pojmenujeme Text Box a který vytvoří obrázek o velikosti přesně odpovídající zadanému textu. Uživatel bude mít možnost zvolit i řez písma, jeho velikost a barvu.

#### 3.4.2. Editace a ukládání skriptů

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.

#### 3.4.3. Úplné základy

Každý Script-Fu skript definuje alespoň jednu funkci, hlavní funkci skriptu. Ta je zodpovědná za činnost skriptu.

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

Nejprve definujeme hlavní funkci:

            (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. Jmenné konvence

Konvence jazyka Scheme pro vytváření jmen upřednostňují malá písmena a pomlčky, tak jako jsme učinili při výběru jména funkce. Při pojmenovávání jejích parametrů jsme se však od konvence odchýlili. Mám rád jména popisná, která o funkci nebo parametru hodně říkají, proto jsme pro parametry použili předponu `in`, která naznačuje, že parametry obsahují hodnoty předávané skriptu, nikoliv skriptem vytvořené. Pro proměnné vytvořené uvnitř skriptu používám předponu `the`.

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

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.

Zde je výpis naší registrační funkce (její parametry vzápětí vysvětlím):

      (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>/Filters/Tutorial")

Save these functions in a text file with a `.scm` suffix in a subdirectory of your script directory, with the same name as your script file, then restart GIMP. The new script will appear as Filters → Tutorial → Text Box.

Pokud ale skript spustíte, neudělá samozřejmě nic užitečného, ale uvidíte výzvy vytvořené při registraci skriptu (podrobnosti dále).

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

#### 3.4.6. Jednotlivé kroky registrace skriptu

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.

Povinné parametry

- 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 menu label is the name that will be shown in the menu. To specify the location, see 3.4.9 – „Registering the Menu Location“.

- Popis skriptu, který se zobrazuje v Prohlížeči procedur.

- Vaše jméno (jméno autora skriptu).

- Copyright, informace o autorských právech.

- Datum, kdy byl skript napsán nebo naposledy revidován.

- 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. Registrace parametrů skriptu

Po uvedení obecných, povinných parametrů je třeba uvést parametry, které vyžaduje náš skript. V seznamu těchto parametrů je také třeba uvést jejich typ, což umožní správně zobrazit dialog, ve kterém uživatel parametry nastavuje. Také zadáme výchozí hodnoty těchto parametrů.

Tato část registračního procesu používá následující formát:

Typ parametru | Popis | Příklad
--- | --- | ---
`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-STRING` | Přijímá řetězce. | "Nějaký text"
`SF-COLOR` | Označuje parametr vyžadující barvu. | '(0 102 255)
`SF-TOGGLE` | Přijímá booleovskou hodnotu (pravda či nepravda). V dialogu se zobrazuje jako zaškrtávací políčko, přepínač. | TRUE nebo FALSE

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

| Poznámka
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-v3.scm` shipped with the GIMP source code.

Typ parametru | Popis
--- | ---
`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 | Popis
--- | ---
"label" | Text printed before the widget.
jas | 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 | Popis
--- | ---
"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 notation.
`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 | Popis
--- | ---
"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` | It will create a widget in the control dialog. The widget is a combo-box showing all enum values for the given enum type. This has to be the name of a registered enum, without the "Gimp" prefix. The second parameter specifies the default value, using the enum value's nick. SF-ENUM "Interpolation" '("InterpolationType" "linear") The value returned when the script is invoked corresponds to chosen enum value.

#### 3.4.9. Registering the Menu Location

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 Filters → Tutorial. This is what the line with the `script-fu-menu-register` function does. Thus, we registered our Text Box script here: Filters → Tutorial → Text Box.

Any submenu that you specify in your script that doesn't exist yet will be automatically created by GIMP.

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

3.3. Seznamy, seznamy a zase seznamy |  | 3.5. Adding Additional Functionality

Report a bug in GIMP Report a documentation error