Продвинутый GUI

Этот раздел содержит разрозненную информацию о продвинутом использовании GUI.

Функции Python

Существуют некоторые функции Python, которые поддерживают GUI.

gui.button_properties(kind)

Для заданного kind (вида) кнопки, возвращает словарь, содержащий стандартные свойства стиля для этой кнопки. Устанавливает:

background: Как описано ниже.
padding: В gui.kind_borders.padding (если существует).
xsize: В gui.kind_width (если существует).
ysize: В gui.kind_height (если существует).

(Обратите внимание, что если kind — это строка "nvl_button", будет искаться переменная gui.nvl_button_background.)

Фон представляет собой рамку, изображение для которой берётся из первого существующего файла из списка:

gui/button/kind_[prefix_].background.png
gui/button/[prefix_].background.png

Если существует переменная GUI с именем gui.kind_borders, она используется. В противном случае используется gui.button_borders. Если существует gui.kind_tile, она определяет, будут ли рамки замощены (tiled), иначе gui.button_tile контролирует замощение.

Чтобы узнать, что означает [prefix_], ознакомьтесь с документацией по поиску по префиксам стилей.

gui.init(width, height, fov=75)

Инициализирует GUI.

width: Ширина окна по умолчанию.
height: Высота окна по умолчанию.
fov: Поле зрения 3D-сцены.

gui.rebuild()

Пересобирает GUI.

Примечание: Это очень медленная функция.

gui.text_properties(kind=None, accent=False)

Для заданного kind (вида) текстовой кнопки, возвращает словарь, содержащий стандартные свойства стиля для текста внутри этой кнопки. Устанавливает:

font: В gui.kind_text_font, если существует.
size: В gui.kind_text_size, если существует.
xalign: В gui.kind_text_xalign, если существует.
textalign: В gui.kind_text_xalign, если существует.
layout: В "subtitle", если gui.kind_text_xalign больше нуля и меньше единицы.

Также существует ряд переменных, которые устанавливают свойство стиля color для текста:

color: В gui.kind_text_color, если существует. Если переменная не установлена, и accent равно True, устанавливает цвет текста в акцентный цвет по умолчанию.
insensitive_color: В gui.kind_text_insensitive_color, если существует.
idle_color: В gui.kind_text_idle_color, если существует.
hover_color: В gui.kind_text_hover_color, если существует.
selected_color: В gui.kind_text_selected_color, если существует.

Доступны все остальные свойства стиля текста. Когда kind не None, также доступны свойства стиля позиции. Например, gui.kind_text_outlines устанавливает свойство стиля outlines, gui.kind_text_kerning устанавливает kerning, и так далее.

gui.variant(f, variant=None)

Декоратор, который заставляет функцию вызываться при первой инициализации GUI, и повторно каждый раз, когда GUI пересобирается. Предназначен для использования как декоратор функции, в виде:

@gui.variant
def small():
    gui.text_size = 30
    # ...

Его также можно вызвать с f (функция) и variant (строка), задавая имя варианта.

gui.button_text_properties(kind=None, accent=False):: Устаревший псевдоним для gui.text_properties().

Подробнее о gui.rebuild

Функция gui.rebuild — это довольно медленная функция, которая обновляет GUI в соответствии с текущим состоянием Ren'Py. Она делает следующее:

Перезапускает все операторы define, которые определяют переменные в пространстве имён gui.
Перезапускает все блоки translate python для текущего языка.
Перезапускает все операторы style.
Пересоздаёт все стили в системе.

Обратите внимание, что блоки init python не перезапускаются при вызове gui.rebuild. В этом смысле,

define gui.text_size = persistent.text_size

и:

init python:
    gui.text_size = persistent.text_size

отличаются.

Оператор default, пространство имён gui и gui.rebuild

Оператор default имеет изменённую семантику применительно к пространству имён gui. Когда он применяется к переменной в пространстве имён gui, оператор default выполняется вперемежку с операторами define, и операторы default не перезапускаются при вызове gui.rebuild().

Это означает, что если у нас есть:

default gui.accent_color = "#c04040"
define gui.hover_color = gui.accent_color

При первом запуске игры будет установлен accent_color, а затем hover_color будет присвоен цвет accent_color. (Оба цвета затем используются для установки различных цветов стиля.)

Однако если в рамках игрового скрипта у нас есть:

$ gui.accent_color = "#4040c0"
$ gui.rebuild()

Ren'Py перезапустит только define, поэтому он установит hover_color равным accent_color, а затем обновит стили. Это позволяет создавать части GUI, которые меняются по ходу игры.

При установке переменных gui во время выполнения может потребоваться вызывать gui.rebuild в метке after_load:

label after_load:
    $ gui.rebuild()
    return

Это относится только к переменным, установленным с помощью default. Все переменные в пространстве имён gui должны устанавливаться с помощью default или define.

Настройки GUI

Ren'Py также поддерживает систему настроек GUI, состоящую из одной функции и пары действий.

gui.SetPreference(name, value, rebuild=True)

Это Действие (Action) устанавливает настройку GUI с именем name в значение value.

rebuild: Если true (по умолчанию), вызывается gui.rebuild(), чтобы изменения вступили в силу. Обычно это значение должно быть true, за исключением случаев с несколькими действиями gui.SetPreference, где оно должно быть False для всех, кроме последнего.

Это очень медленное действие и, вероятно, не подходит для использования при наведении курсора на кнопку.

gui.TogglePreference(name, a, b, rebuild=True)

Это Действие (Action) переключает настройку GUI с именем name между значением a и значением b. Оно считается выбранным, если значение равно a.

rebuild: Если true (по умолчанию), вызывается gui.rebuild(), чтобы изменения вступили в силу. Обычно это значение должно быть true, за исключением случаев с несколькими действиями gui.SetPreference, где оно должно быть False для всех, кроме последнего.

Это очень медленное действие и, вероятно, не подходит для использования при наведении курсора на кнопку.

gui.preference(name, default=...)

Эта функция возвращает значение настройки GUI с именем name.

default: Если задано, это значение становится значением по умолчанию для настройки GUI. Значение по умолчанию должно быть указано при первом использовании настройки.

Пример

Система настроек GUI используется путём вызова gui.preference() при определении переменных, с указанием имени настройки и значения по умолчанию. Например, можно использовать настройки GUI для определения шрифта и размера текста.

define gui.text_font = gui.preference("font", "DejaVuSans.ttf")
define gui.text_size = gui.preference("size", 22)

Затем можно использовать действия gui.SetPreference и gui.TogglePreference для изменения значений настроек. Вот несколько примеров, которые можно добавить на экран настроек.

vbox:
    style_prefix "check"
    label _("Options")
    textbutton _("OpenDyslexic") action gui.TogglePreference("font", "OpenDyslexic-Regular.otf", "DejaVuSans.ttf")

vbox:
    style_prefix "radio"
    label _("Text Size")
    textbutton _("Small") action gui.SetPreference("size", 20)
    textbutton _("Medium") action gui.SetPreference("size", 22)
    textbutton _("Big") action gui.SetPreference("size", 24)