### 3.4. はじめての 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. テキストボックススクリプトを作成

GIMP を使った私の経験では一番多い使い道のひとつがウェブ用にテキストの入ったロゴやら何やらの作成でした。 でもみなさんにとっては新規画像をどれ位の寸法で作ったら良いか全然判らないはずです。 テキストに使いたい文字の大きさが判ってもそれが画像をどれ位占めるのか見当がつきません。

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

したがってテキストボックスという名前でスクリプトを書いて、 これに画像を作らせ、 テキストを与えたらちょうどぴったり囲む頃合いの寸法になるようなスクリプトにしましょう。 それから好みのフォントやフォントサイズや文字色が選べるようにしましょう。

#### 3.4.2. スクリプトを書いて保存

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. 肝心要

どんな Script-Fu スクリプトもそのメイン関数として少なくとも 1 つの関数を定義します。 この作業にとりかかりましょう。

またどんな Script-Fu もプロシージャーデータベースに登録して GIMP から呼び出せるようにもしなければなりません。

ではメイン関数をまず定義しましょう。

            (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. 命名規則

Scheme の変数や関数の名前は小文字の英字を適宜ハイフンでつないだ表現が好まれているようです。 それで私も同じ規則でこの関数の名前をつけました。 ただしパラメーターについてはその規則から外れた方法をとることにします。 私は変数やパラメーターにはもっと説明的な書き方をするのが好きなので、 パラメーターの頭に「in」をつけて関数が受け取った変数だとすぐ判るようにして、 他のところで作った変数と区別します。 またスクリプト内で定義した変数の頭には「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. 関数を登録

ではこの関数を GIMP に登録しましょう。 この操作には `script-fu-register` という関数を起用します。 GIMP はスクリプトを見るとこの関数を実行しプロシージャーデータベースに登録させます。 この関数の実行コードはスクリプトのどの位置に置いても構いませんが、 私なら他のコードを全部書き終えたあとの最後に置きます。

関数を登録している様子をつぎに示します。 パラメーターに関してはまもなく説明します。

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

この新しいスクリプトは実行しても何も起こりません。 もちろんメニューを辿れば説明文が表示されますし、 呼び出せばウィンドウも現れます。 スクリプトの登録が反映されたからなのですが、 何が起きたかの情報についてはあとで詳しく説明します。

最後にプロシージャーブラウザーを画像ウィンドウのメニューより ヘルプ → プロシージャーブラウザー と辿って開き、 作ったばかりのスクリプトがデータベースに登録されていることをご確認ください。

#### 3.4.6. スクリプトを登録するための工程

GIMP にスクリプトを登録するために登録関数 `script-fu-register` を起用しますが、 これには 7 つの必須パラメーターとスクリプト独自のパラメーター、 そして説明文とそれぞれのパラメーターの初期設定値を加えることになります。

必須のパラメーター

- 関数の name (名前) を定めました。 スクリプトを起用したときに呼び出される関数がこれです。 スクリプトへの入口の役目を果たしています。 同じファイル内に他にも関数を書き加えることになるかもしれないので、 GIMP がどの関数をまず呼び出すべきか判断できるよう、 こうして定義することが重要です。 先の例で登録したのは text-box というたったひとつの関数です。

- The menu label is the name that will be shown in the menu. To specify the location, see 「Registering the Menu Location」.

- スクリプトの 説明 文をつけると、 プロシージャーブラウザーで表示されます。

- あなたのお名前 はスクリプトの作者を書きます。

- 著作権 を明示します。

- スクリプトの 作成日 には作成した日付か最近の改訂日付を記します。

- 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. スクリプトのパラメーターを登録

必須のパラメーターを列挙したので、 ここでスクリプトが使うパラメーターについて一覧表にまとめておきます。 これらの媒介変数を紹介するにあたりその型式がわかるようにしました。 これはスクリプトが呼ばれると現れるダイアログを構成するために使います。 また変数には初期設定値を与えておきます。

この節で行なわれる登録処理にはつぎの型式が関わります。

パラメーターの型 | 説明 | 例
--- | --- | ---
`SF-IMAGE` | 既に開いてある画像を操作するためのスクリプトを作るときは、 必須のパラメーターの直後にこのパラメーターを置かねばなりません。 GIMP は画像を参照するための情報をこのパラメーターに乗せてスクリプトに渡します。 | 3
`SF-DRAWABLE` | 既に開いてある画像を操作するためのスクリプトを作るときは、 `SF-IMAGE` 型のパラメーターのつぎにこのパラメーターを置かなくてはなりません。 これは活性レイヤーを参照します。 GIMP は活性レイヤーを参照するための情報をこのパラメーターに乗せてスクリプトに渡します。 | 17
`SF-STRING` | 文字列を収める変数です。 | "Some text"
`SF-COLOR` | このパラメーターが要求する色の情報を示します。 | '(0 102 255)
`SF-TOGGLE` | 真理 2 値をとるチェックボックスを表示します。 | 有効なら TRUE、 無効なら FALSE

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

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

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

`SF-ADJUSTMENT`

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

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

ウィジェット変数表

要素 | 説明
--- | ---
"`label`" | ウィジェットの前に貼られる語句
`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`" | ウィジェットの前に貼られる語句
'(`red green blue`) | 赤・緑・青の 3 つの成分
"`color`" | Color name in CSS notation.

`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`" | ウィジェットの前に貼られる語句
"`fontname`" | 初期状態でのフォント名

`SF-BRUSH`

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

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

ウィジェット変数表

要素 | 説明
--- | ---
"`label`" | ウィジェットの前に貼られる語句
"`brush name`" | ブラシの名前。 たとえば "Pencil 01"
`opacity` | 不透明度 (0-100)
`spacing` | 間隔 (対ブラシ高さ%)
`mode` | 描画モード番号。 たとえば 0 なら標準モード

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

`SF-PATTERN`

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

    SF-PATTERN "label" "Pattern Name"

ウィジェット変数表

要素 | 説明
--- | ---
"`label`" | ウィジェットの前に貼られる語句
"`Pattern Name`" | パターンの名前。 たとえば "Maple Leaves"

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

`SF-GRADIENT`

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

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

    SF-GRADIENT "label" "gradientname"

ウィジェット変数表

要素 | 説明
--- | ---
"`label`" | ウィジェットの前に貼られる語句
"`gradientname`" | 初期状態でのグラデーション名

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

`SF-PALETTE`

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

    SF-PALETTE "label" "Palette Name"

ウィジェット変数表

要素 | 説明
--- | ---
"`label`" | ウィジェットの前に貼られる語句
"`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`" | ウィジェットの前に貼られる語句
"`path/to/file.ext`" | gimp-data-directory からの相対パスとファイル名

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

`SF-DIRNAME`

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

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

ウィジェット変数表

要素 | 説明
--- | ---
"`label`" | ウィジェットの前に貼られる語句
"`path`" | gimp-data-directory からの相対パス

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

`SF-OPTION`

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

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

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

ウィジェット変数表

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

スクリプトが呼び出されたときに返される値はオプション項目の番号です。 最初のオプションが 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 "label" '("enum type" "default choice")

ウィジェット変数表

要素 | 説明
--- | ---
"`label`" | ウィジェットの前に貼られる語句
"`enum type`" | 列挙型の登録名
"`default choice`" | 初期設定値。 略称で指定する

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

#### 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] この節は原文の演習には含まれていません。

3.3. リストにリストもそのまたリスト |  | 3.5. Adding Additional Functionality

Report a bug in GIMP Report a documentation error