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

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

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

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

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

Такую задача довольно легко автоматизировать с помощью 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 определяет по крайней мере одну функцию, которая служит главной функцией сценария. Здесь и совершается главная работа.

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

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

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

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

#### 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>/File/Create/Text")

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

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

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

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

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

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

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

- The menu label is the name that will be shown in the menu. In previous versions of GIMP you could specify the menu location here, but that has changed. How to specify the location will be shown below.

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

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

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

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

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

#### 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[6]

| Примечание
Кроме типов параметров, описаных выше, есть больше типов для интерактивного режима, каждый из которых создаст компонент введения значения в диалоге. Список этих параметров с их описанием и примерами их использования находятся в тестовом сценарии `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) | Список трёх значений для компонентов красного, зелёного и синего.
"цвет" | Color name in CSS notation.
`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` | 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") Возвратное значение при вызове сценария будет выбранное значение из перечисления.

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

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

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

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

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

Report a bug in GIMP Report a documentation error