Список gui-параметров для настройки интерфейса игры: диалог-бокса, nvl-режима, окна с историей реплик,
кнопок внутри-игрового меню, экранов загрузки, сохранения и настроек и т. д.

Первое, что нужно знать - ни в коем случае не стоит пытаться брать файл `gui.rpy` от игры на renpy и
надеяться, что он будет воспринят хоть как-нибудь адекватно.  
Переносите каждый параметр вручную и вдумчиво, чётко понимая, что он делает и как он назван в Ren-Engine.  
Почему часть параметров имеет другие имена, будет объяснено в соответствующих разделах ниже.

Установка свойств по умолчанию производится в файле `Ren-Engine/rpy/gui.rpy`.  
Вносить изменения для своей игры рекомендуется в файле `resources/mods/common/gui.rpy`.  
Изменения для своего отдельного мода рекомендуется делать в `resources/mods/${your_mod}/gui.rpy`.

Изменения во время инициализации не требуют ручного вызова функции обновления,
но изменения во время уже запущенного сценария требуют вызова `db.update_styles()`.  
Впрочем, этот вызов происходит автоматически перед каждой новой репликой персонажей.

***

## align vs anchor

В названиях gui-параметров в renpy существует путаница между `align` и `anchor`.
См. [Введение в ScreenLang (GUI, интерфейс)](./ScreenLang) для объяснений этих свойств.

Чтобы избавиться от этой путаницы, `*align`-параметры,
на самом деле обозначающие `anchor`-свойства, переименованы в `*anchor`.

***

## Размеры и позиции

Ren-Engine всегда позволяет игроку менять разрешение окна, из-за чего интерфейс должен быть адаптивным,
т. е. адекватно выглядеть и при разрешении `640x360`, и при разрешении `1920x1080`.

Для этого многие параметры рекомендуется задавать не абсолютными (целыми, `int`) числами,
а частью (`float`) от ширины или высоты экрана.  
Свойства `xpos` и `width` (x-координата и ширина) считаются частью ширины окна,
а остальные (все остальные, включая `text_size` и `spacing`) - частью высоты.  
Очевидный пример: `*_xpos = 0.5` от ширины окна `1920` будет `960`, а от `640` - `320`.

Также все подобные значения имеют похожие свойства с суффиксами `_min` и `_max`,
задающие жёсткие ограничения для любых размеров экрана, и не дающие сделать нужные размеры
слишком большими и/или маленькими.  
Любое из этих 2 ограничительных свойств может отсутствовать или иметь значение `None` для своего отключения.  
Напоминание: свойство может существовать, даже если вы лично его не создавали
(но оно было присвоено в `Ren-Engine/rpy/gui.rpy`).

***

## Цвета

`*_color` - цвет текста.  
`*_outlinecolor` - цвет обводки текста (`None` - отключить обводку).

Цвет задаётся в форматах `'#RGB'`, `'#RRGGBB'`, `0xRRGGBB` или даже
`(0xRR, 0xGG, 0xBB)` для 16-ричной записи RGB-каналов и `(R, G, B)` для десятичной (где `R`, `G`, `B` от `0` до `255`).  
Но обычно проще всего использовать первый вариант.

***

## Изображения

Под изображениями понимаются свойства `*_bg`, `*_ground`, `*_hover` и `*_selected`.  
Эти свойства должны содержать пути к изображениям, либо результат
[im-функций](./Функции-для-изображений-(im-функции)).

Также вместо непосредственно значения можно использовать функцию (**но не лямбду!**),
которая будет это значение возвращать.  
Это может быть полезно, если ваш интерфейс должен меняться в зависимости от
[времени суток](./Времена-суток)
в игре, или по каким-либо иным соображениям.  
Но в этом случае не стоит забывать про ручной вызов `db.update_styles()`, о котором говорилось в начале статьи.

***

## Обозначения

![Interface](./images/gui.jpg)

1. `dialogue_box`,
2. `dialogue_text` внутри `dialogue_box`,
3. `name_box` внутри `dialogue_box` (по умолчанию с `yanchor = 1.0`, поэтому выше),
4. `name_text` внутри `name_box`,
5. `prev_btn` - кнопка для истории реплик,
6. `next_btn` - кнопка для перехода к след. реплике,
7. `menu_btn` - кнопка для вызова меню паузы.

***

## dialogue_box

Выравнивание диалог-бокса по осям X и Y:
* `gui.dialogue_box_xalign = 0.5`,
* `gui.dialogue_box_yalign = 0.99`.

Размеры:
* `gui.dialogue_box_width = None` - ширина (`None` - авто-рассчёт на основе других параметров),
* `gui.dialogue_box_height = 0.2` - высота.

Изображение для диалог-бокса:
* `gui.dialogue_box_bg = 'images/gui/dialogue/voice.png'`.

## dialogue_text

Свойства этого блока - это свойства по умолчанию для реплик всех персонажей.  
Чтобы изменить их для отдельного персонажа, следует передать ему при создании нужные `what_*`-параметры.  
Пример изменения шрифта:  
`rn = Character('Ren', what_font = 'Arial')`

Префикс и суффикс:
* `gui.dialogue_text_prefix = ''`,
* `gui.dialogue_text_suffix = ''`.

* `gui.dialogue_text_font = 'Calibri'` - шрифт,
* `gui.dialogue_text_size = 0.035` - размер шрифта,
* `gui.dialogue_text_color = '#FF0'` - цвет,
* `gui.dialogue_text_outlinecolor = None` - цвет обводки (`None` - отсутствует),
* `gui.dialogue_text_align = 'left'` - горизонтальное выравнивание текста.

Координаты текста в диалог-боксе:
* `gui.dialogue_text_xpos = 15`,
* `gui.dialogue_text_ypos = 10`.

Размеры текстового поля:
* `gui.dialogue_text_width = None` - ширина (`None` - auto),
* `gui.dialogue_text_height = None` - высота (`None` - auto).

***

## name_box

Позиция - относительно диалог-бокса.
Т. е. если xpos = ypos = 0, то name_box будет у левого-верхнего угла диалог-бокса.

Координаты:
* `gui.name_box_xpos = 0.1`,
* `gui.name_box_ypos = 0`.

Якорь (точка отсчёта, нулевая (x = 0, y = 0) точка объекта):
* `gui.name_box_xanchor = 0.0`,
* `gui.name_box_yanchor = 1.0`.

Размеры:
* `gui.name_box_width = 0.2` - ширина (`None` - auto для каждого конкретного имени),
* `gui.name_box_height = 0.06` - высота.

Изображение:
* `gui.name_box_bg = 'images/gui/dialogue/name.png'`.

***

## name_text

Свойства этого блока - это свойства по умолчанию для имён всех персонажей.  
Чтобы изменить их для отдельного персонажа, следует передать ему при создании нужные `who_*`-параметры.  
Пример изменения шрифта:  
`rn = Character('Ren', who_font = 'Arial')`

Для обратной совместимости параметры без префикса считаются за `who_*`-параметры.  
Т. е. следующие 2 строки делают одно и то же:  
`rn = Character('Ren', color = '#FFF')`  
`rn = Character('Ren', who_color = '#FFF')`


Префикс и суффикс:
* `gui.name_text_prefix = ''`
* `gui.name_text_suffix = ''`

* `gui.name_text_font = 'Calibri'` - шрифт,
* `gui.name_text_size = 0.04` - размер шрифта,
* `gui.name_text_color = '#F00'` - цвет,
* `gui.name_text_outlinecolor = None` - цвет обводки (`None` - отсутствует),
* `gui.name_text_xalign = 0.5` - выравнивание текста в нейм-боксе по оси X.
* `gui.name_text_yalign = 0.8` - и по оси Y.



***

## Кнопки назад и далее

Все свойства, указанные в этом и следующем абзаце (т. е. начинающиеся с `dialogue_`) могут быть
переданы персонажу при создании вместе с `what_*`- и `who_*`-параметрами (см. выше).

* `gui.dialogue_button_spacing = 5` - отступы слева и справа от этих кнопок,
* `gui.dialogue_button_yalign = 0.5` - выравнивание кнопок по вертикали относительно диалог-бокса.

Размеры кнопок:
* `gui.dialogue_button_width  = 50`,
* `gui.dialogue_button_height = 50`.

Изображения кнопки назад:
* `gui.dialogue_prev_ground = 'images/gui/dialogue/to_prev.png'` - обычное состояние,
* `gui.dialogue_prev_hover = None` - наведена мышь (`None` - auto).

Изображения кнопки вперёд:
* `gui.dialogue_next_ground = 'images/gui/dialogue/to_next.png'` - обычное состояние,
* `gui.dialogue_next_hover = None` - наведена мышь (`None` - auto).

***

## Кнопка вызова паузы

Позиция кнопки:
* `gui.dialogue_menu_button_xpos = 1.0`,
* `gui.dialogue_menu_button_ypos = 0.0`.

Якорь/anchor:
* `gui.dialogue_menu_button_xanchor =  70`,
* `gui.dialogue_menu_button_yanchor = -20`.

Размеры:
* `gui.dialogue_menu_button_width  = 50`,
* `gui.dialogue_menu_button_height = 50`.

Изображения:
* `gui.dialogue_menu_button_ground = 'images/gui/dialogue/to_menu.png'` - обычное состояние,
* `gui.dialogue_menu_button_hover  = None` - наведена мышь (`None` - auto).

***

## Отключение кнопок

Для отключения кнопок далее/назад и кнопки меню нужно просто установить их ширину или высоту в `0`:
* `gui.dialogue_button_width = 0` - для кнопок далее/назад,
* `gui.dialogue_menu_button_width = 0` - для кнопки паузы.

***

## Настройка nvl-мода

![nvl-mode interface](./images/nvl-mode_example.jpg)

В режиме `nvl` текст отображается "стеной", а не по 1 реплике за раз, как в `adv`.  
Вместо отдельно располагающегося имени, здесь оно находится в той же строке, что и текст реплики.  
Далее под понятием "запись" будет подразумеваться сочетание имени (если есть) и текста реплики.

Включить `nvl`-режим: `$ set_mode_nvl()`.  
Очистить экран от предыдущих реплик: `$ nvl_clear()`.  
Включить обычный (`adv`) режим: `$ set_mode_adv()`.

* `gui.nvl_height = None` - высота записи (`None` - auto),
* `gui.nvl_spacing = 10` - расстояние между записями (учитывается, если `nvl_height = None`).

Координаты текстового поля для имени (относительно "контейнера" записи):
* `gui.nvl_name_xpos = 0.25`,
* `gui.nvl_name_ypos = 0`.

Также есть свойства:
* `gui.nvl_name_width = 150` - ширина текстового поля,
* `gui.nvl_name_xalign = 1.0` - используется одновременно для `xanchor` и для `text_align`.

Аналогичные свойства для текстового поля реплики:
* `gui.nvl_text_xpos = 0.27`,
* `gui.nvl_text_ypos = 0`,
* `gui.nvl_text_width = 0.6`,
* `gui.nvl_text_xalign = 0.0`.

И отдельно свойства для текстового поля реплики при условии, что имя является пустым:
* `gui.nvl_thought_xpos = 0.1`,
* `gui.nvl_thought_ypos = 0`,
* `gui.nvl_thought_width = 0.8`,
* `gui.nvl_thought_xalign = 0.0`.

Обычно это применяется для 2 персонажей:
1. Для рассказчика (`narrator`, используемый, если не указан другой персонаж),
2. Для мыслей главного героя (персонаж `th` - от англ. thoughts, использует символ `~` для обрамления текста).

Кнопки меню выбора (см. ниже `choice_button`) в `nvl`-режиме должны располагаться под репликами.  
Расположение этих кнопок должно настраиваться этими свойствами:
* `gui.nvl_button_xpos = 0.5`
* `gui.nvl_button_xanchor = 0.5`

Но пока что это не реализовано, и используется самое обычное меню из `adv`-режима.  
Этот момент будет исправлен позже.

***

## История

История чем-то похожа на `nvl`-режим (см. выше),
поэтому многие понятия будут взяты оттуда без повторных объяснений.

Длина истории:  
`config.history_length = 50`

* `gui.history_height = None` - высота записи (`None` - auto),
* `gui.history_spacing = 5` - расстояние между записями (учитывается, если `history_height = None`).

Параметры текстового поля для имени:
* `gui.history_name_xpos = 150`,
* `gui.history_name_ypos = 0`,
* `gui.history_name_width = 150`,
* `gui.history_name_xalign = 1.0`.

Для реплик:
* `gui.history_text_xpos = 170`,
* `gui.history_text_ypos = 0`,
* `gui.history_text_width = 0.5`,
* `gui.history_text_xalign = 0.0`.

Для реплик персонажей с пустым именем:
* `gui.history_thought_xpos = 0.1`,
* `gui.history_thought_ypos = 0`,
* `gui.history_thought_width = 0.6`,
* `gui.history_thought_xalign = 0.0`.

***

## Заглавие

Эти свойства используются для надписи "Загрузка" на экране загрузки и в прочих подобных обстоятельствах:
* `gui.title_text_font = 'Calibri'` - шрифт,
* `gui.title_text_size = 0.1` - размер шрифта,
* `gui.title_text_color = '#FFF'` - цвет,
* `gui.title_text_outlinecolor = '#000'` - цвет обводки (`None` - отключить обводку).


***

## Текст интерфейса

Эти свойства принимают "обычные" текстовые поля во многих частях интерфейса:
* `gui.interface_text_font = 'Calibri'` - шрифт,
* `gui.interface_text_size = 25` - размер шрифта,
* `gui.interface_text_color = '#FFF'` - цвет,
* `gui.interface_text_outlinecolor = '#000'` - цвет обводки (`None` - отключить обводку),
* `gui.interface_text_xalign = 'left'` - горизонтальное выравнивание текста в текстовом поле.

***

## Слоты сохранения

![Save screen](./images/save_screen.jpg)

* `gui.file_slot_cols = 4` - кол-во столбцов в экранах сохранения и загрузки,
* `gui.file_slot_rows = 3` - кол-во рядов ("строк"),
* `gui.slot_pages = 10` - кол-во страниц сохранений.

Фоны для экранов загрузки и сохранения:
* `gui.load_bg = 'images/gui/menu/main/back.png'`,
* `gui.save_bg = 'images/gui/menu/main/back.png'`.

Свойства для каждого отдельного слота:
* `gui.slot_hover    = 'images/gui/save_load/hover.png'` - обычное наложение,
* `gui.slot_selected = 'images/gui/save_load/selected.png'` - наложение для "выделенного" слота,
* `gui.slot_spacing = 0.01` - расстояние между слотами.

Свойства для текста слота (дата его создания):
* `gui.slot_text_xpos = 5` - X-координата в слоте,
* `gui.slot_text_ypos = 5` - Y-координата,
* `gui.slot_text_font = 'Calibri'` - шрифт,
* `gui.slot_text_size = 0.04` - размер шрифта,
* `gui.slot_text_color = '#FFF'` - цвет,
* `gui.slot_text_outlinecolor = '#000'` - цвет обводки (`None` - отключить обводку).

***

## Обычная кнопка

Эти свойства используются в "обычных" местах интерфейса - в скринах загрузки, сохранения и в настройках:
* `gui.button_width = 175` - ширина,
* `gui.button_height = 25` - высота,
* `gui.button_ground = style.textbutton.ground` - путь к изображению с обычным состоянием,
* `gui.button_hover  = style.textbutton.hover` - с изображением при наведённом курсоре мыши,
* `gui.button_text_font = 'Calibri'` - шрифт,
* `gui.button_text_size = 15` - размер шрифта,
* `gui.button_text_color = '#FFF'` - цвет,
* `gui.button_text_outlinecolor = None` - цвет обводки (`None` - отключить обводку),
* `gui.button_text_xalign = 0.5` - горизонтальное выравнивание текста в кнопке.

***

## Кнопка меню выбора

![Choice menu](./images/choice_menu.jpg)

Описание свойств см. выше в абзаце "Обычная кнопка":
* `gui.choice_button_width = None` - ширина (`None` - auto),
* `gui.choice_button_height = 34`,
* `gui.choice_button_ground = style.textbutton.ground`,
* `gui.choice_button_hover  = style.textbutton.hover`,
* `gui.choice_button_text_font = 'Calibri'`,
* `gui.choice_button_text_size = 20`,
* `gui.choice_button_text_color = '#FFF'`,
* `gui.choice_button_text_outlinecolor = None`,
* `gui.choice_button_text_xalign = 0.5`.

`gui.choice_spacing = 10` - расстояние между кнопками этой группы кнопок.

***

## Кнопка быстрого меню

Быстрое меню содержит часто используемые кнопки и находится снизу экрана.

Описание свойств см. выше в абзаце "Обычная кнопка":
* `gui.quick_button_width  = None` - ширина (`None` - auto),
* `gui.quick_button_height = 20`,
* `gui.quick_button_ground = im.rect('#00000002')`,
* `gui.quick_button_hover  = im.rect('#00000002')`,
* `gui.quick_button_text_font = 'Calibri'`,
* `gui.quick_button_text_size = 16`,
* `gui.quick_button_text_color = '#DDD'`,
* `gui.quick_button_text_outlinecolor = '#000'`,
* `gui.quick_button_text_xalign = 0.5`.

***

## Страничная кнопка

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

Описание свойств см. выше в абзаце "Обычная кнопка":
* `gui.page_button_width = 0.10`,
* `gui.page_button_height = 0.06`,
* `gui.page_button_ground = style.textbutton.ground`,
* `gui.page_button_hover  = style.textbutton.hover`,
* `gui.page_button_text_font = 'Calibri'`,
* `gui.page_button_text_size = 0.035`,
* `gui.page_button_text_color = '#FFF'`,
* `gui.page_button_text_outlinecolor = None`,
* `gui.page_button_text_xalign = 0.5`.

`gui.page_spacing = 0.007` - расстояние между кнопками этой группы кнопок.

***

## Элементы экрана настроек

* `gui.prefs_bg = 'images/gui/menu/main/back.png'` - фон,
* `gui.prefs_xindent = 0.1` - отступ от краёв, который учитывается в размере группы кнопок для переключения разделов.

Свойства кнопки для булевых/логических состояний (да/нет, включено/отключено),
описание свойств см. выше в абзаце "Обычная кнопка":
* `gui.prefs_bool_width = 0.6`,
* `gui.prefs_bool_height = 25`,
* `gui.prefs_bool_ground = im.rect('#00000002')`,
* `gui.prefs_bool_hover  = im.rect('#00000010')`,
* `gui.prefs_bool_text_font = 'Calibri'`,
* `gui.prefs_bool_text_size = 20`,
* `gui.prefs_bool_text_color = '#FFF'`,
* `gui.prefs_bool_text_outlinecolor = '#000'`,
* `gui.prefs_bool_text_xalign = 0.5`.

Свойства для полосы:
* `gui.prefs_bar_width = 0.3` - ширина,
* `gui.prefs_bar_height = 25` - высота.

Для настроек текста см. свойства `gui.interface_text_*` выше (абзац "Текст интерфейса").  
Для настроек кнопок см. свойства `gui.button_*` выше (абзац "Обычная кнопка").


***

## checkbox

* `gui.checkbox_yes = 'images/gui/std/checkbox/yes.png'` - состояние да/включено,
* `gui.checkbox_no  = 'images/gui/std/checkbox/no.png'` - состояние нет/отключено.

***

## Полоса для слайдера

* `gui.bar_ground = 'images/gui/std/bar/ground.png'` - "пустое" состояние,
* `gui.bar_hover  = 'images/gui/std/bar/hover.png'` - "заполненное" состояние.

***

## Полоса для вертикального слайдера

Аналогично предыдущему абзацу - по умолчанию изображения берутся оттуда и поворачиваются на 90 градусов:
* `gui.vbar_ground = im.rotozoom(gui.bar_ground, 90, 1)`,
* `gui.vbar_hover  = im.rotozoom(gui.bar_hover , 90, 1)`.

***

[Далее ->](./Быстрое-меню)
