3.4. Первый сценарий Script-Fu
| 3. Инструкция по Script-Fu |

### 3.4. Первый сценарий Script-Fu

В этом четвёртом уроке мы напишем первый сценарий Script-Fu

#### 3.4.1. Создание сценария рамки с текстом

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

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

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

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

До сих пор мы работали в консоли Script-Fu. Теперь мы переключимся на редактирование текстовых файлов сценариев.

Не важно, куда поместить сценарии: если у вас есть доступ к папке сценариев GIMP по умолчанию, можно поместить их туда, если хотите держать их отдельно от предустановленных, создайте свою папку.

In the `~/.config/GIMP/2.10/` directory that GIMP made off of your home directory, you should find a directory called `scripts`. GIMP will automatically look in your `~/.config/GIMP/2.10/` 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. Самое основное

Каждый сценарий Script-Fu определяет по крайней мере одну функцию, которая служит главной функцией сценария. Здесь и совершается главная работа.

Каждый сценарий должен зарегистрироваться с базой процедур, чтобы можно было получить к нему доступ из GIMP.

Мы создадим сначала главную функцию:

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

Здесь мы определили функцию с названием `script-fu-text-box`, которая берёт четыре параметра. Эти параметры позже соотнесутся с текстом, шрифтом, размером и цветом. Функция сейчас пустая и ничего не делает. Пока ничего нового.

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

Сохраните свои функции в файле с расширением `.scm` в вашей папке сценариев и вызовите команду Фильтры → Script-Fu → Обновить сценарии. Новый сценарий появится в меню Файл → Создать → Текст → Текст с рамкой.

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

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

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

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

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

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

- Место в меню, куда вставится сценарий. Точное положение сценария указывается как путь к файлу в Unix, где `<Изображение>` есть корень пути.[6]

  Если ваш сценарий не оперирует с существующим изображением (т.е. создаёт новое изображение, как наш сценарий Текст с рамкой), то лучше его вставить в меню окна изображения. Тогда достать его можно правым нажатием мышки в окне изображения, нажатием на пиктограмму кнопки меню в левом верхнем углу окна изображения, или нажатием клавишы F10.

  Если ваш сценарий работает с существующим изображением, лучше поместить его в меню окна изображения. Остаток пути указывает меню и подменю. Поэтому мы регистрируем наш сценарий в меню Текст меню Создать меню Файл.[7] (Файл → Создать → Текст → Текст с рамкой).

  Вы наверно заметили, что подменю Текст в меню Файл/Создать не существовало до регистрации сценария — GIMP автоматически создаёт недостающие подменю.

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

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

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

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

- Типы изображений, с которыми этот сценарий работает. Может быть любой из: RGB, RGBA, GRAY, GRAYA, INDEXED, INDEXEDA, или вообще никакой. В нашем случае мы создаём изображение, поэтому тип изображения можно не указывать.

Рисунок 13.4. Меню нашего сценария

#### 3.4.7. Регистрация параметров сценария

После объявления списка необходимых параметров нужно указать параметры, которые соответствуют параметрам сценария. При объявлении списка параметров, мы даём подсказку об их типах. Это делается для диалога параметров, который появится при вызове нашего сценария. Мы также предоставляем значения по умолчанию.

Эта часть процесса регистрации имеет следующий формат:

Тип параметра | Описание | Пример
--- | --- | ---
`SF-IMAGE` | Если ваш сценарий работает с открытым изображением, этот параметр должен быть первым после необходимых параметров. GIMP вставит ссылку на изображение в этот параметр. | 3
`SF-DRAWABLE` | Если ваш сценарий работает с открытым изображением, этот параметр должен быть вторым параметром, сразу после параметра `SF-IMAGE`. От указывает на активный слой. GIMP вставит ссылку на активный слой в этот параметр. | 17
`SF-VALUE` | Принимает числа и строки. Заметьте, что кавычки нужно специально маркировать для текста по умолчанию, тоэтому лучше использовать `SF-STRING`. | 42
`SF-STRING` | Принимает строки. | "Некий текст"
`SF-COLOR` | Укаывает что этот параметр требует значение цвета. | '(0 102 255)
`SF-TOGGLE` | Принимает логическое значение. Обычно показывается в виде галочки. | TRUE или FALSE

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

| Примечание
Кроме типов параметров, описаных выше, есть больше типов для интерактивного режима, каждый из которых создаст компонент введения значения в диалоге. Список этих параметров с их описанием и примерами их использования находятся в тестовом сценарии `plug-ins/script-fu/scripts/test-sphere.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 перечислений. Название перечисления, посланное с этим параметром, не должно содержать приставки «Gimp». Второй параметр содержит значение, выбранное по умолчанию. SF-ENUM "Interpolation" '("InterpolationType" "linear") Возвратное значение при вызове сценария будет выбранное значение из перечисления.

[6] До версии 2.6 можно также было использовать `<Toolbox>`, но теперь меню панели инструментов убрано, поэтому его не используйте.

[7] В оригинале этого руководства, написанном Майком, сказано вставлять пункт меню Script-Fu меню Дополнения панели инструментов, но с версии 2.6 меню панели инструментов было удалено и совмещено с меню изображения.

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

3.3. Списки, списки и ещё раз списки |  | 3.5. Придача сценарию формы

Report an error in the bug tracker