### 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. Создание сценария Text Box

Создание текста для веб-страницы, логотипа — довольно часто используемая операция в GIMP. Однако трудно предугадать, какого размера нужно создать исходное изображение, чтобы весь текст поместился без лишнего места с указанным шрифтом и размером.

Такую задачу довольно легко решить и автоматизировать с помощью Script-Fu.

Мы создадим сценарий под названием Text Box который создаст изображение с правильным размером для текста, введённого пользователем. Пользователь также может указать шрифт, размер шрифта и цвет текста.

#### 3.4.2. Редактирование и сохранение сценариев

До сих пор мы работали в консоли Script-Fu. Теперь же перейдём к редактированию файлов сценариев. Файлы сценариев должны быть простыми текстовыми файлами, которые можно редактировать в текстовом или кодовом редакторе. Имя, которое вы зададите файлу, не так важно, главное, чтобы вы могли его узнать. Файлу сценария следует задать расширение «.scm».

Место хранения сценариев выбираете по своему усмотрению. В настройках папок GIMP можно увидеть, в каких папках GIMP ищет сценарии. Там же можно добавить новую папку. Папка, в которой GIMP хранит собственные сценарии, обычно не является лучшим выбором для ваших сценариев, но в остальном можно выбрать то, что вам больше подходит.

#### 3.4.3. Самое основное

Каждый сценарий 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».

Согласно своему порядку, GIMP именует пользовательские сценарные функции по типу `script-fu-abc`, поскольку, когда они присутствуют в процедурной базе данных, они показываются в списке Script-Fu при запросе списка функций. Также, такой порядок наименования помогает отличать их от расширений.

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

Сохраните эти функции в файле с расширением `.scm` в подкаталоге вашего каталога сценариев с тем же именем, что и у вашего файла сценария, и перезапустите GIMP. Новый сценарий появится в меню Фильтры → Инструкция → Text Box.

Если вы вызовите этот сценарий, он естественно ничего не сделает, но вы увидите все запросы, созданные во время регистрации сценария. Об этом ниже.

И наконец, если вы вызовете просмотрщик процедур (Справка → Просмотрщик процедур), вы увидите там свой новый сценарий.

#### 3.4.6. Шаги по регистрации сценария

Чтобы зарегистрировать сценарий с GIMP, нужно вызвать функцию `script-fu-register`, заполнить семь необходимых параметров, добавить параметры сценария с описанием и значением по умолчанию для каждого.

Необходимые параметры

- Название нашей функции. Эта функция вызывается при запуске нашего сценария (точка входа в наш сценарий). Этот параметр необходим, потому что можно создать много функций в сценарии, и GIMP должен знать, какая функция главная. В нашем примере мы декларируем только одну функцию, text-box, которую мы и регистрируем.

- Метка меню — это имя, которое будет показано в меню. Чтобы указать расположение, см. Раздел 3.4.9, «Регистрация расположения в меню».

- Описание сценария покажется в просмотрщике процедур.

- Ваше имя (автор сценария).

- Информация об Авторском праве.

- Дата создания сценария или его последнего изменения.

- 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` | Принимает строки. | "Некий текст"
`SF-COLOR` | Указывает на то, что этот параметр требует значение цвета. | '(0 102 255)
`SF-TOGGLE` | Принимает логическое значение. Обычно показывается в виде галочки. | TRUE или FALSE

#### 3.4.8. API параметров Script-Fu[5]

| Примечание
Кроме типов параметров, описанных выше, есть больше типов для интерактивного режима, каждый из которых создаст компонент введения значения в диалоге. Список этих параметров с их описанием и примерами их использования находятся в тестовом сценарии `plug-ins/script-fu/scripts/test-sphere-v3.scm`, поставляемом с исходным кодом GIMP.

Тип параметра | Описание
--- | ---

`SF-ADJUSTMENT`

Создаёт компонент изменения в диалоге.

SF-ADJUSTMENT "название" '(value lower upper step_inc page_inc digits type)

Список параметров компонента

Элемент | Описание
--- | ---
"название" | Текст, показываемый до компонента ввода.
value | Начальное значение.
lower / upper | Нижнее/верхнее значения (диапазон значений).
step_inc | Насколько уменьшать/увеличивать значение за один шаг.
page_inc | Насколько уменьшать/увеличивать значение с помощью клавиш страниц вверх и вниз.
digits | Число цифр после запятой.
type | Один из: SF-SLIDER или 0, SF-SPINNER или 1

`SF-COLOR`

Создаёт кнопку цвета в диалоге.

SF-COLOR "название" '(красный зелёный синий)

или

SF-COLOR "название" "цвет"

Список параметров компонента

Элемент | Описание
--- | ---
"название" | Текст, показываемый до компонента ввода.
'(red green blue) | Список трёх значений для компонентов красного, зелёного и синего.
"цвет" | Название цветов в нотации CSS.

`SF-FONT`

Создаёт в диалоге компонент выбора шрифта. Возвращает название шрифта как строку. Есть две функции, которые облегчают работу с этим параметром:

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

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

где font — название шрифта. Размер, указанный в названии шрифта, не принимается во внимание. Он используется только в выборщике шрифта. Поэтому его нужно установить на какое-либо полезное значение, например 24 точек.

SF-FONT "название" "название шрифта"

Список параметров компонента

Элемент | Описание
--- | ---
"название" | Текст, показываемый до компонента ввода.
"название шрифта" | Название шрифта по умолчанию.

`SF-BRUSH`

Компонент, созданный этим параметром, содержит несколько элементов. Во-первых, окно просмотра, которое при нажатии на нём вызовет диалог просмотра. Во-вторых, кнопку с названием "...". Эта кнопка вызывает диалог выбора кисти, где каждое свойство кисти можно изменить.

SF-BRUSH "Кисть" '("Circle (03)" 100 44 0)

В этом случае появится диалог выбора кисти с выбранной кистью Circle (03), непрозрачностью 100, промежутком 44 и в нормальном режиме рисования (значение 0).

Если эту кисть не изменить, то значение, которое получит функция, будет '("Circle (03)" 100 44 0).

`SF-PATTERN`

Компонент, созданный этим параметром, содержит несколько элементов. Во-первых, окно просмотра, которое при нажатии на нём вызовет диалог просмотра. Во-вторых, кнопку с названием "...". Эта кнопка вызывает диалог выбора шаблона.

SF-PATTERN "Шаблон" "Maple Leaves"

Возвращаемым значением при вызове сценария будет строка, содержащая название шаблона. Если выбранный по умолчанию шаблон не был изменён, то эта строка будет содержать "Maple Leaves".

`SF-GRADIENT` | Созданный компонент-кнопка в диалоге будет показывать выбранный градиент. При нажатии кнопки появится диалог выбора градиента. SF-GRADIENT "Градиент" "Deep Sea" Возвращаемым значением при вызове сценария будет строка, содержащая название градиента. Если выбранный по умолчанию градиент не был изменён, то эта строка будет содержать "Deep Sea".
`SF-PALETTE` | Созданный компонент-кнопка в диалоге будет показывать название выбранной палитры. При нажатии на кнопку появится диалог выбора палитры. SF-PALETTE "Палитра" "Named Colors" Возвращаемым значением при вызове сценария будет строка, содержащая название палитры. Если выбранная по умолчанию палитра не была изменена, то эта строка будет содержать "Named Colors".
`SF-FILENAME` | Созданный компонент-кнопка в диалоге будет показывать название файла. При нажатии кнопки появится диалог выбора файла. SF-FILENAME "название" (string-append "" gimp-data-directory "/scripts/beavis.jpg") Возвращаемым значением при вызове сценария будет строка, содержащая путь к файлу.
`SF-DIRNAME` | Этот параметр может пригодиться только в интерактивном режиме. Очень похож на SF-FILENAME, но созданный компонент ввода позволяет выбрать папку вместо файла. SF-DIRNAME "название" "/var/tmp/images" Возвращаемым значением при вызове сценария будет строка, содержащая путь к папке.
`SF-OPTION` | Этот параметр создаёт раскрывающийся список с элементами из данного с параметром списка. Первая запись выбрана по умолчанию. SF-OPTION "название" '("запись1" "запись2") Возвращаемым значением при вызове сценария будет порядковый номер выбранной записи. У первой записи порядковый номер 0.

`SF-ENUM`

Этот параметр создаст виджет в диалоговом окне управления. Виджет представляет собой выпадающий список со всеми значениями данного перечислимого типа. Это должно быть имя зарегистрированного перечислимого типа без префикса «Gimp». Второй параметр указывает значение по умолчанию, используя псевдоним значения перечислимого типа.

SF-ENUM "Interpolation" '("InterpolationType" "linear")

Возвращаемым значением при вызове сценария будет выбранное значение перечислимого типа.

#### 3.4.9. Регистрация расположения в меню

После регистрации сценария необходимо указать GIMP, где он должен находиться в меню.

Оптимальное расположение сценария зависит от его функции. Большинство сценариев находится в меню Фильтры и Цвет.

Для текущего сценария, который создаёт новое изображение, мы выбираем подменю Фильтры → Инструкция. Именно это делает строка с функцией `script-fu-menu-register`. Таким образом, мы зарегистрировали наш сценарий Text Box здесь: Фильтры → Инструкция → Text Box.

Любое подменю, которое вы укажете в своём сценарии и которое ещё не существует, будет автоматически создано GIMP.

[5] Этой части нет в исходном руководстве.

3.3. Списки, списки и ещё раз списки |  | 3.5. Добавление дополнительных функций

Report a bug in GIMP Сообщите об ошибке в нашем баг-трекере