3.4. Your First Script-Fu Script
| 3. A Script-Fu Tutorial |

### 3.4. Your First Script-Fu Script

Do you not need to stop and catch your breath? No? Well then, let's proceed with your fourth lesson -- your first Script-Fu Script.

#### 3.4.1. Creating A Text Box Script

One of the most common operations I perform in GIMP is creating a box with some text in it for a web page, a logo or whatever. However, you never quite know how big to make the initial image when you start out. You don't know how much space the text will fill with the font and font size you want.

The Script-Fu Master (and student) will quickly realize that this problem can easily be solved and automated with Script-Fu.

We will, therefore, create a script, called Text Box, which creates an image correctly sized to fit snugly around a line of text the user inputs. We'll also let the user choose the font, font size and text color.

#### 3.4.2. Editing And Storing Your Scripts

Up until now, we've been working in the Script-Fu Console. Now, however, we're going to switch to editing script text files.

Where you place your scripts is a matter of preference -- if you have access to GIMP's default script directory, you can place your scripts there. However, I prefer keeping my personal scripts in my own script directory, to keep them separate from the factory-installed scripts.

In the `.gimp-2.4` directory that GIMP made off of your home directory, you should find a directory called `scripts`. GIMP will automatically look in your `.gimp-2.4` directory for a scripts directory, and add the scripts in this directory to the Script-Fu database. You should place your personal scripts here.

#### 3.4.3. The Bare Essentials

Every Script-Fu script defines at least one function, which is the script's main function. This is where you do the work.

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

We'll define the main function first:

            (define (script-fu-text-box inText inFont inFontSize inTextColor))

Here, we've defined a new function called script-fu-text-box that takes four parameters, which will later correspond to some text, a font, the font size, and the text's color. The function is currently empty and thus does nothing. So far, so good -- nothing new, nothing fancy.

#### 3.4.4. Naming Conventions

Scheme's naming conventions seem to prefer lowercase letters with hyphens, which I've followed in the naming of the function. However, I've departed from the convention with the parameters. I like more descriptive names for my parameters and variables, and thus add the "in" prefix to the parameters so I can quickly see that they're values passed into the script, rather than created within it. I use the prefix "the" for variables defined within the script.

It's GIMP convention to name your script functions script-fu-abc, because then when they're listed in the procedural database, they'll all show up under script-fu when you're listing the functions. This also helps distinguish them from plug-ins.

#### 3.4.5. Registering The Function

Now, let's register the function with GIMP. This is done by calling the function `script-fu-register`. When GIMP reads in a script, it will execute this function, which registers the script with the procedural database. You can place this function call wherever you wish in your script, but I usually place it at the end, after all my other code.

Here's the listing for registering this function (I will explain all its parameters in a minute):

            (script-fu-register
              "script-fu-text-box"                        ;func name
              "Text Box"                                  ;menu label
              "Creates a simple text box, sized to fit\
                around the user's choice of text,\
                font, font size, and color."              ;description
              "Michael Terry"                             ;author
              "copyright 1997, Michael Terry"             ;copyright notice
              "October 27, 1997"                          ;date created
              ""                     ;image type that the script works on
              SF-STRING      "Text:"         "Text Box"   ;a string variable
              SF-FONT        "Font:"         "Charter"    ;a font variable
              SF-ADJUSTMENT  "Font size"     '(50 1 1000 1 10 0 1)
                                                          ;a spin-button
              SF-COLOR       "Color:"        '(0 0 0)     ;color variable
            )
            (script-fu-menu-register "script-fu-text-box" "<Toolbox>/Xtns/Script-Fu/Text")

If you save these functions in a text file with a `.scm` suffix in your script directory, then choose Xtns → Script-Fu → Refresh Scripts, this new script will appear as Xtns → Script-Fu → Text → Text Box.

If you invoke this new script, it won't do anything, of course, but you can view the prompts you created when registering the script (more information about what we did is covered next).

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

#### 3.4.6. Steps For Registering The Script

To register our script with GIMP, we call the function script-fu-register, fill in the seven required parameters and add our script's own parameters, along with a description and default value for each parameter.

The Required Parameters

- The name of the function we defined. This is the function called when our script is invoked (the entry-point into our script). This is necessary because we may define additional functions within the same file, and GIMP needs to know which of these functions to call. In our example, we only defined one function, text-box, which we registered.

- The location in the menu where the script will be inserted. The exact location of the script is specified like a path in Unix, with the root of the path being either toolbox or right-click.

  If your script does not operate on an existing image (and thus creates a new image, like our Text Box script will), you'll want to insert it in the toolbox menu -- this is the menu in GIMP's main window (where all the tools are located: the selection tools, magnifying glass, etc.).

  If your script is intended to work on an image being edited, you'll want to insert it in the menu that appears when you right-click on an open image. The rest of the path points to the menu lists, menus and sub-menus. Thus, we registered our Text Box script in the Text menu of the Script-Fu menu of the Xtns menu of the toolbox ( Xtns → Script-Fu → Text → Text Box ).

  If you notice, the Text sub-menu in the Script-Fu menu wasn't there when we began -- GIMP automatically creates any menus not already existing.

- A description of your script, to be displayed in the Procedure Browser.

- Your name (the author of the script).

- Copyright information.

- The date the script was made, or the last revision of the script.

- The types of images the script works on. This may be any of the following: RGB, RGBA, GRAY, GRAYA, INDEXED, INDEXEDA. Or it may be none at all -- in our case, we're creating an image, and thus don't need to define the type of image on which we work.

図 12.4. The menu of our script.

#### 3.4.7. Registering The Script's Parameters

Once we have listed the required parameters, we then need to list the parameters that correspond to the parameters our script needs. When we list these params, we give hints as to what their types are. This is for the dialog which pops up when the user selects our script. We also provide a default value.

This section of the registration process has the following format:

Param Type | Description | Example
--- | --- | ---
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 | Accepts strings. | "Some text"
SF-COLOR | Indicates that a color is requested in this parameter. | '(0 102 255)
SF-TOGGLE | A checkbox is displayed, to get a Boolean value. | TRUE or FALSE

#### 3.4.8. Script-FuパラメータAPI[6]

| 注意
上記のパラメータ型に加え、 操作盤ダイアログ上に使えるさらに多くの相互モード用のウィジェットの型があります。 GIMPのソースコードとともに配布されているテスト用スクリプト `plug-ins/script-fu/scripts/test-sphere.scm` にそういったパラメータの説明や使用例があります。

パラメータの型 | 説明
--- | ---

`SF-ADJUSTMENT`

ダイアログ上に値を調節するためのウィジェットを作成します。

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

ウィジェット変数表

要素 | 説明
--- | ---
_"`label`" | ウィジェットの前に貼られる語句 (_記号でgettextを用いて訳語へ交換が可能になる)
`value` | 当初の数値 デフォルト
`lower`; `upper` | 最低値と最高値 (選べる値の範囲)
`step_inc` | 最小変動値、 公差
`page_inc` | PgUp キーと PgDn キーによる操作での公差
`digits` | 小数点以下の桁数 (十進数)
`type` | スライダは `SF-SLIDER` もしくは 0、 スピンボックスは `SF-SPINNER` もしくは 1

SF-COLOR

ダイアログにカラーボタンを作成します。

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

もしくは

    SF-COLOR _"label" "color"

ウィジェット変数表

要素 | 説明
--- | ---
_"`label`" | ウィジェットの前に貼られる語句 (_記号でgettextを用いて訳語へ交換が可能になる)
'(`red green blue`) | 赤緑青の3つの成分
"`color`" | CSSnotatationの色名

`SF-FONT`

ダイアログにフォント選択ウィジェットを作成します。 フォント名を文字列変数形式で返します。

GIMPにはこの返し値を手軽に扱えるテキスト処理プロシージャが2つ備わっています。

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

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

いずれも `fontname` に得られたフォント名を入れます。 フォントの大きさには有益な値を設定しておくと良いでしょう。 24 ピクセルがおすすめです。

    SF-FONT _"label" "fontname"

ウィジェット変数表

要素 | 説明
--- | ---
_"`label`" | ウィジェットの前に貼られる語句 (_記号でgettextを用いて訳語へ交換が可能になる)
"`fontname`" | 初期状態でのフォント名

`SF-BRUSH`

ダイアログにブラシ選択ウィジェットを作成します。 このウィジェットは縮小見本表示があります。 ここはクリックしたまま待つと大きく表示されます。 さらに ... のラベルがついたボタンが作られます。 このボタンをクリックするとブラシ選択ダイアログが開かれ、 ブラシを選んだりその特徴を変更できるしくみになっています。

    SF-BRUSH _"label" '("Brush Name" opacity spacing mode)

ウィジェット変数表

要素 | 説明
--- | ---
_"`label`" | ウィジェットの前に貼られる語句(_記号でgettextを用いて訳語へ置換が可能になる)
"`brush name`" | ブラシの名前。 例えば "Circle (03)"
`opacity` | 不透明度 (0-100)
`spacing` | 間隔 (対ブラシ高さ%)
`mode` | 描画モード番号。 例えば 0 なら標準モード

例えば「`SF-BRUSH _"Brush" '("Circle (03)" 100 44 0)`」として呼び出してダイアログで何も変更しなかった場合、 返ってくるパラメータは「`'("Circle (03)" 100 44 0)`」となります。

`SF-PATTERN`

ダイアログにパターン選択ウィジェットを作成します。 このウィジェットは縮小見本表示があります。 ここはクリックしたまま待つと大きく表示されます。 さらに ... のラベルがついたボタンが作られます。 このボタンをクリックするとパターン選択ダイアログが開かれ、 パターンを選んだりその特徴を変更できるしくみになっています。

    SF-PATTERN _"label" "Pattern Name"

ウィジェット変数表

要素 | 説明
--- | ---
_"`label`" | ウィジェットの前に貼られる語句 (_記号でgettextを用いて訳語へ置換が可能になる)
"`brush name`" | パターンの名前。 例えば "Maple Leaves"

スクリプトが呼び出されたときに返される値はパターンの名前をもつ文字列変数です。 例えば「SF-PATTERN _"Pattern" "Maple Leaves"」として呼び出してダイアログで何も変更しなかった場合、 返ってくるパタメータは「`"Maple Leaves"`」となります。

`SF-GRADIENT`

ダイアログにグラデーション選択ウィジェットを作成します。 グラデーションボタンが設置され現在選ばれているグラデーションが表示されます。

このボタンはクリックするとグラデーション変更ダイアログが開かれ他のグラデーションも選べるしくみになっています。

    SF-GRADIENT _"label" "gradientname"

ウィジェット変数表

要素 | 説明
--- | ---
_"`label`" | ウィジェットの前に貼られる語句 (_記号でgettextを用いて訳語へ置換が可能になる)
"`gradientname`" | 初期状態でのグラデーション名

スクリプトが呼び出されたときに返される値はグラデーションの名前をもつ文字列変数です。 例えば「`SF-GRADIENT _"Gradient" "Deep Sea"`」として呼び出してダイアログで何も変更しなかった場合、 返ってくるパタメータは「`"Deep Sea"`」となります。

`SF-PALETTE`

ダイアログにパレット選択ウィジェットを作成します。 このウィジェットは縮小見本とパレット名を表示します。 縮小見本はボタンになっておりクリックするとパレット選択ダイアログが開かれ他のパレットも選べるしくみになっています。

    SF-PALETTE _"label" "Palette Name"

ウィジェット変数表

要素 | 説明
--- | ---
_"`label`" | ウィジェットの前に貼られる語句 (_記号でgettextを用いて訳語へ置換が可能になる)
"`Palette Name`" | パレットの名前。 例えば "Named Colors"

スクリプトが呼び出されたときに返される値はパレットの名前をもつ文字列変数です。 例えば「`SF-PALETTE _"Palette" "Named Colors"`」として呼び出してダイアログで何も変更しなかった場合、 返ってくるパタメータは「`"Named Colors"`」となります。

`SF-FILENAME`

ダイアログにファイル選択ウィジェットを作成します。 ファイル名が記されたボタンが設置されます。 このボタンをクリックするとファイルブラウザが開かれ、 ファイルを探してひとつ選ぶ操作ができるしくみになっています。

    SF-FILENAME _"label" (string-append "" gimp-data-directory "path/to/file.ext")

ウィジェット変数表

要素 | 説明
--- | ---
_"`label`" | ウィジェットの前に貼られる語句 (_記号でgettextを用いて訳語へ置換が可能になる)
"`path/to/file.ext`" | gimp-data-directory からの相対パスとファイル名

スクリプトが呼び出されたときに返される値はファイルの名前と保管場所を記した文字列変数です。

`SF-DIRNAME`

対話式操作でのみ有益です。 ファイルではなくディレクトリを選択するウィジェットであることのほかは `SF-FILENAME` と酷似しています。

    SF-DIRNAME _"label" (string-append "" gimp-data-directory "path")

ウィジェット変数表

要素 | 説明
--- | ---
_"`label`" | ウィジェットの前に貼られる語句 (_記号でgettextを用いて訳語へ置換が可能になる)
"`path`" | gimp-data-directory からの相対パス

スクリプトが呼び出されたときに返される値はディレクトリ名とそれまでの筋道を記した文字列変数です。

`SF-OPTION`

ダイアログに数々の選択肢からひとつを選ぶコンボボックスウィジェットを作成します。

選択肢はまとめてリストにして渡し、 ウィジェットは最初の項目を初期値として表示します。

    SF-OPTION _"label" '("option 1" "option 2" [... "option n"])

ウィジェット変数表

要素 | 説明
--- | ---
_"`label`" | ウィジェットの前に貼られる語句 (_記号でgettextを用いて訳語へ置換が可能になる)
"`option 1`" | 最初のオプション。 初期設定値となる
"`option 2`" | 第2のオプション
"`option n`" | それ以上のオプション。 無くても良いが、 いくつでも増やせる

スクリプトが呼び出されたときに返される値はオプション項目の番号です。 最初のオプションが 0 番です。

`SF-ENUM`

ダイアログに列挙型リストの選択ウィジェットを作成します。 指定された列挙型の項目を並べたコンボボックスが設けられます。 使える列挙型は登録済のものに限られ、 その名前から冒頭の「Gimp」を取り除いた語で指定します。 第2のパラメータには初期設定値を、 その略称で指定します。

    SF-ENUM _"label" '("enum type" "default choice")

ウィジェット変数表

要素 | 説明
--- | ---
_"`label`" | ウィジェットの前に貼られる語句 (_記号でgettextを用いて訳語へ置換が可能になる)
"`enum type`" | 列挙型の登録名
"`default choice`" | 初期設定値。 略称で指定する

スクリプトが呼び出されたときに返される値は扱われる列挙型での値です。

[6] この節は原文の演習には含まれていません。

3.3. Lists, Lists And More Lists |  | 3.5. Giving Our Script Some Guts