Экраны и Python

Функции для экранов

Следующие функции поддерживают различные операции, связанные с экранами.

renpy.call_screen(_screen_name, *args, _with_none=True, _mode='screen', **kwargs)

Программный эквивалент инструкции call screen.

Эта функция показывает _screen_name как экран, затем вызывает интеракцию . Экран скрывается в конце интеракции, и результат интеракции возвращается.

Позиционные аргументы и именованные аргументы, которые не начинаются с _ передаются на экран.

Если _with_none равно false, "with None" не выполняется в конце интеракции.

Если передан _mode, он будет режимом этой интеракции, в противном случае режимом будет "screen".

renpy.current_screen()

Возвращает информацию об экране, который в данный момент обновляется, отрисовывается или обрабатывается.

Документированные поля возвращаемого объекта см. в get_screen().

renpy.get_adjustment(bar_value)

Принимая bar_value, объект BarValue, возвращает используемый им ui.adjustment(). Объект adjustment имеет следующие определённые атрибуты:

value: Текущее значение ползунка.

range: Текущий диапазон ползунка.

renpy.get_displayable(screen, id, layer=None, base=False): Из screen на layer возвращает displayable с id. Возвращает None, если экран не существует, или на нём нет виджета с таким id.

renpy.get_displayable_properties(id, screen=None, layer=None)

Возвращает свойства для displayable с id на экране screen на слое layer. Если screen равно None, возвращает свойства для текущего экрана. Эту функцию можно использовать из Python или в коде свойств внутри экрана.

Обратите внимание, что она возвращает словарь, содержащий свойства виджета, поэтому для получения отдельного свойства необходимо обратиться к словарю.

renpy.get_screen(name, layer=None, tag_only=False)

Возвращает информацию об экране с заданным name на layer. name сначала интерпретируется как имя тега, а затем как имя экрана. Если экран не показывается, возвращает None.

Функция также может принимать список имён, и в этом случае первый показываемый экран возвращается.

tag_only: Если true, рассматривается только тег.

Эту функцию можно использовать для проверки, показывается ли экран:

if renpy.get_screen("say"):
    text "Экран say показывается."
else:
    text "Экран say скрыт."

Объекты, возвращаемые этой функцией, имеют следующие документированные поля:

layer: Слой, на котором отображается экран.

name: Имя экрана.

zorder: Z-порядок, с которым отображается экран.

Предупреждение

Как и в случае с другими подобными функциями, возвращаемый объект предназначен для краткосрочного использования после вызова функции. Включение его в данные сохранения или участие в откате не рекомендуется.

renpy.get_screen_docstring(name, variant=None)

Возвращает docstring для экрана с name и variant.

name: Имя экрана.
variant: Вариант экрана. Если None, используется вариант по умолчанию.

renpy.get_screen_variable(name, *, screen=None, layer=None)

Возвращает значение переменной в области видимости экрана.

name: Имя переменной для возврата.
screen: Имя экрана, из которого нужно вернуть переменную. Если None, используется текущий экран. (Текущий экран определён только при обновлении экрана и в действиях, выполняемых внутри экрана.)
layer: Слой, на котором нужно найти экран, если screen не None.

renpy.hide_screen(tag, layer=None, immediately=False)

Программный эквивалент инструкции hide screen.

Скрывает экран с тегом tag на слое layer.

Если immediately равно true, экран скрывается немедленно, без события 'on hide'.

renpy.set_focus(screen, id, layer='screens')

Эта функция пытается сфокусироваться на displayable с id на экране screen. Фокусировка не удастся, если displayable не найден, окно не в фокусе или что-то другое перехватывает фокус.

Фокус может измениться, если мышь переместится, даже незначительно, после обработки этого вызова.

renpy.set_screen_variable(name, value, *, screen=None, layer=None)

Устанавливает значение переменной в области видимости экрана. Обратите внимание, что это не обновит значение переменной немедленно — вызовите renpy.restart_interaction(), чтобы экран обновился.

name: Имя устанавливаемой переменной. Это должна быть переменная, созданная с помощью инструкции Default, так как оптимизация может помешать видимости изменений других переменных.
value: Значение, которое нужно присвоить переменной.
screen: Имя экрана, из которого нужно вернуть переменную. Если None, используется текущий экран. (Текущий экран определён только при обновлении экрана и в действиях, выполняемых внутри экрана.)
layer: Слой, на котором нужно найти экран, если screen не None.

renpy.show_screen(_screen_name, *args, _layer=None, _zorder=None, _tag=None, _widget_properties={}, _transient=False, **kwargs)

Программный эквивалент инструкции show screen.

Показывает именованный экран. Принимает следующие именованные аргументы:

_screen_name

Имя экрана для показа.

_layer

Слой, на котором нужно показать экран. Это эквивалентно выражению onlayer инструкции Show Screen.

_zorder

Z-порядок, с которым нужно показать экран. Если не указан, по умолчанию используется z-порядок, связанный с экраном. Если он тоже не указан, по умолчанию равен 0.

_tag

Тег, с которым нужно показать экран. Если не указан, по умолчанию используется тег, связанный с экраном. Если он тоже не указан, по умолчанию используется имя экрана.

Это эквивалентно выражению as инструкции Show Screen.

_widget_properties

Словарь, сопоставляющий id виджета со словарем "имя свойства -> значение свойства". Когда виджет с этим id отображается на экране, к нему добавляются указанные свойства.

_transient

Если true, экран будет автоматически скрыт в конце текущей интеракции.

Позиционные аргументы и именованные аргументы, которые не начинаются с подчёркивания, передаются на экран.

renpy.start_predict_screen(_screen_name, *args, **kwargs)

Заставляет Ren'Py начать предсказание экрана с именем _screen_name с заданными аргументами. Это заменяет любое предыдущее предсказание _screen_name. Чтобы остановить предсказание экрана, вызовите renpy.stop_predict_screen().

Предсказание будет происходить во время обычного игрового процесса. Чтобы дождаться завершения предсказания, используйте аргумент predict в renpy.pause().

renpy.stop_predict_screen(name): Заставляет Ren'Py прекратить предсказание экрана с именем name.

renpy.variant(name)

Возвращает true, если name является вариантом экрана, который соответствует контексту, в котором в данный момент выполняется Ren'Py. См. Варианты экранов для получения более подробной информации. Эту функцию можно использовать в качестве условия в инструкции if для изменения поведения в зависимости от выбранного варианта экрана.

name также может быть списком вариантов, и в этом случае функция вернёт True, если хотя бы один из вариантов подходит.

class ui.adjustment(range=1, value=0, step=None, page=None, changed=None, adjustable=None, ranged=None, force_step=False, raw_changed=None)

Объекты adjustment представляют значение, которое можно изменять с помощью bar или viewport. Они содержат информацию о значении, его диапазоне, а также о том, как изменять его мелкими шагами и большими "страницами".

Следующие параметры соответствуют полям или свойствам объекта adjustment:

range

Диапазон регулировки, число.

value

Значение регулировки, число.

step

Размер шага регулировки, число. Если None, то по умолчанию равен 1/10 страницы, если она установлена. В противном случае, по умолчанию равен 1/20 диапазона.

Используется при прокрутке viewport колесом мыши.

page

Размер страницы регулировки. Если None, это значение устанавливается автоматически viewport. Если не установлен, по умолчанию равен 1/10 диапазона.

Может использоваться при клике на полосу прокрутки.

Следующие параметры управляют поведением adjustment.

adjustable

Если True, эту регулировку можно изменять с помощью bar. Если False, то нельзя.

По умолчанию считается изменяемым, если задана функция changed или если adjustment связан с viewport, и неизменяемым в противном случае.

changed

Эта функция вызывается с новым значением, когда значение adjustment изменяется.

raw_changed

Эта функция вызывается при изменении значения adjustment. В отличие от changed, эта функция вызывается с "сырым" значением, которое может выходить за пределы диапазона. Она вызывается с двумя аргументами: adjustment и новое значение.

ranged

Эта функция вызывается с объектом adjustment, когда viewport устанавливает его диапазон.

Эта функция может вызываться несколько раз в процессе компоновки.

force_step

Если True и adjustment изменяется перетаскиванием связанного viewport или bar, значение изменится только тогда, когда перетаскивание достигнет следующего шага. Если "release" и adjustment изменяется перетаскиванием связанного viewport или bar, то после отпускания кнопки мыши значение будет округлено до ближайшего шага. Если False, adjustment будет изменяться при перетаскивании, игнорируя значение шага.

change(value): Изменяет значение adjustment на value, обновляя все bar и viewport, которые его используют.

ui.interact(*, roll_forward=None, mouse=None)

Вызывает взаимодействие с пользователем и возвращает его результат. Это заставляет Ren'Py перерисовать экран и начать обработку событий ввода. Когда отображаемый объект возвращает значение в ответ на событие, это значение возвращается из ui.interact, и взаимодействие завершается.

Эта функция редко вызывается напрямую. Обычно её вызывают другие части Ren'Py, включая операторы say, menu, with, pause, call screen, функцию renpy.input() и многие другие функции. Однако при необходимости её можно вызвать напрямую.

Когда взаимодействие заканчивается, transient слой и все экраны, показанные с _transient равным true, очищаются из списков сцен.

Ниже описаны документированные аргументы. Поскольку существуют и другие, недокументированные аргументы для внутреннего использования Ren'Py, пожалуйста, передавайте все аргументы как именованные.

roll_forward: Информация, которая будет возвращена этой функцией при перемотке вперёд. (Если None, перемотка игнорируется.) Сюда обычно следует передавать результат функции renpy.roll_forward_info().
mouse: Стиль курсора мыши для использования во время выполнения этой функции. Если None, выбирает между 'default', 'mainmenu' и 'gamemenu' в зависимости от того, активно ли главное меню или игровое меню.

Действия

Многие из отображаемых объектов, созданных на экранном языке, принимают действия в качестве аргументов. Действие — это одна из трёх вещей:

Вызываемый Python-объект (например, функция или связанный метод), который не принимает аргументов.
Объект класса, который наследуется от класса Action.
Список других Действий.

Преимущество наследования от класса Action заключается в том, что это позволяет вам переопределить методы, которые определяют, когда кнопка должна быть активной, и когда она выбрана.

class Action

Чтобы определить новое действие, наследуйтесь от этого класса. Переопределите методы в этом классе, чтобы изменить поведение действия.

__call__(self)

Этот метод вызывается, когда действие активируется. Во многих случаях возврат значения, отличного от None, из действия приведёт к завершению текущего взаимодействия.

Этот метод должен быть переопределен, так как метод по умолчанию вызовет NotImplementedError (и, следовательно, вызовет ошибку в Ren'Py).

get_sensitive(self)

Вызывается для определения, должна ли кнопка с этим действием быть активной. Должен возвращать true, если кнопка активна.

Обратите внимание, что __call__ может быть вызван, даже если этот метод возвращает False.

Реализация по умолчанию возвращает True.

get_selected(self)

Должен возвращать true, если кнопка должна отображаться как выбранная, и false в противном случае.

Реализация по умолчанию возвращает False.

get_tooltip(self)

Получает всплывающую подсказку по умолчанию для этой кнопки, если конкретная подсказка не назначена. Должен возвращать значение подсказки, или None, если подсказка не известна.

По умолчанию возвращает None.

periodic(self, st)

Этот метод вызывается один раз в начале каждого взаимодействия, а затем вызывается периодически. Если он возвращает число, он будет вызван до истечения этого количества секунд, но может быть вызван и раньше.

Основное применение этого метода — вызов renpy.restart_interaction(), если значение get_selected или get_sensitive должно измениться.

Он принимает один аргумент:

st: Количество секунд с момента, когда экран или отображаемый объект, с которым связано это действие, был впервые показан.

unhovered(self): Когда действие используется как параметр hovered для кнопки (или аналогичного объекта), этот метод вызывается, когда объект теряет фокус.

alt: Текст для преобразования в речь, используемый для кнопок, которые используют это действие, если у кнопки не установлено свойство alt. Это может быть строка в классе, в конструкторе, или это может быть свойство Python, которое возвращает строку.

Чтобы запустить действие из Python, используйте renpy.run().

renpy.is_selected(action): Возвращает истинное значение, если предоставленное действие или список действий указывают на то, что они выбраны, и ложное в противном случае.

renpy.is_sensitive(action): Возвращает истинное значение, если предоставленное действие или список действий указывают на то, что они активны, и ложное в противном случае.

renpy.run(action)

Запускает действие или список действий. Одно действие вызывается без аргументов, список действий выполняется по порядку с помощью этой функции, и None игнорируется.

Возвращает результат последнего действия, которое вернуло значение.

BarValues

При создании bar, vbar или hotbar, объект BarValue может быть предоставлен в качестве свойства value. Методы объекта BarValue вызываются для получения adjustment и стилей.

class BarValue

Чтобы определить новый BarValue, наследуйтесь от этого класса и переопределите некоторые из методов.

get_adjustment(self)

Этот метод вызывается для получения объекта adjustment для шкалы. Он должен создать adjustment с помощью ui.adjustment(), а затем вернуть созданный таким образом объект.

Этот метод должен быть переопределен, так как метод по умолчанию вызовет NotImplementedError (и, следовательно, вызовет ошибку в Ren'Py).

get_style(self)

Используется для определения стиля шкал, которые используют это значение. Должен возвращать кортеж из двух имен стилей или объектов стилей. Первый используется для bar, а второй для vbar.

По умолчанию возвращает ("bar", "vbar").

get_tooltip(self)

Получает всплывающую подсказку по умолчанию для этой кнопки, если конкретная подсказка не назначена. Должен возвращать значение подсказки, или None, если подсказка не известна.

По умолчанию возвращает None.

replaces(self, other)

Вызывается, когда BarValue заменяет другой BarValue, например, когда экран обновляется. Может использоваться для обновления этого BarValue из другого. Вызывается перед get_adjustment.

Обратите внимание, что other не обязательно того же типа, что и self.

periodic(self, st)

Этот метод вызывается один раз в начале каждого взаимодействия. Если он возвращает количество секунд, он будет вызван до истечения этого количества секунд, но может быть вызван и раньше. Он вызывается после get_adjustment.

Он может быть использован для обновления значения шкалы со временем, как это делает AnimatedValue(). Для этого get_adjustment должен сохранить adjustment, а periodic должен вызывать метод changed объекта adjustment.

alt: Текст для преобразования в речь, используемый для шкал, которые используют этот BarValue, если у шкалы не установлено свойство alt. Это может быть строка в классе, в конструкторе, или это может быть свойство Python, которое возвращает строку.

InputValue

При создании input, объект InputValue может быть предоставлен в качестве свойства value. Методы объекта InputValue вызываются для получения и установки текста, определения, является ли поле ввода редактируемым, и обработки нажатия клавиши Enter.

class InputValue

Чтобы определить новый InputValue, наследуйтесь от этого класса, переопределите некоторые или все методы, и установите значение поля default.

editable: Если не true, полностью запрещает редактирование поля ввода.

default: Если true, поле ввода может быть редактируемым по умолчанию. (То есть, ему может быть передан курсор при показе экрана.)

get_text(self): Возвращает текст поля ввода по умолчанию. Этот метод должен быть реализован.

set_text(self, s): Вызывается, когда текст поля ввода изменяется, с новым текстом. Этот метод должен быть реализован.

enter(self): Вызывается, когда пользователь нажимает Enter. Если этот метод возвращает значение, отличное от None, это значение возвращается из взаимодействия. Этот метод также может вызвать renpy.IgnoreEvent, чтобы игнорировать нажатие. В противном случае, нажатие Enter передается другим отображаемым объектам.

Следующие действия доступны как методы на InputValue:

Enable(): Возвращает действие, которое включает редактирование текста в поле ввода.

Disable(): Возвращает действие, которое отключает редактирование текста в поле ввода.

Toggle(): Возвращает действие, которое переключает режим редактирования текста в поле ввода.

Инструкции экранного языка, определяемые разработчиком

Ren'Py поддерживает определение пользовательских инструкций экранного языка. Определяемые разработчиком инструкции экранного языка являются обёртками для инструкции экранного языка use. Позиционные аргументы остаются позиционными аргументами, свойства становятся именованными аргументами, и если инструкция принимает блок, то и инструкция use также его принимает. Например, пользовательская инструкция экранного языка:

titledwindow "Test Window":
    icon "icon.png"

    text "This is a test."

становится:

use titledwindow("Test Window", icon="icon.png"):
    text "This is a test."

Определяемые разработчиком инструкции экранного языка должны быть зарегистрированы в блоке python early. Более того, файл, содержащий определяемую разработчиком инструкцию, должен быть загружен раньше любого файла, который её использует. Поскольку Ren'Py загружает файлы в порядке сортировки их путей по Unicode, обычно имеет смысл добавлять префикс, такой как 01 или другое небольшое число, к имени любого файла, регистрирующего пользовательскую инструкцию.

Определяемые разработчиком инструкции экранного языка регистрируются с помощью функции renpy.register_sl_statement:

class renpy.register_sl_displayable(name, displayable, style, nchildren=0, scope=False, *, replaces=False, default_keywords={}, default_properties=True, unique=False)

Регистрирует инструкцию языка экранов (screen language), которая создаёт displayable.

name

Имя инструкции языка экранов, строка, содержащая ключевое слово Ren'Py. Это ключевое слово используется для введения новой инструкции.

displayable

Функция, которая при вызове возвращает объект displayable. Все позиционные аргументы, свойства и свойства стиля передаются в эту функцию в качестве аргументов. Другие именованные аргументы также передаются этой функции, как описано ниже.

Эта функция должна возвращать Displayable. Если она возвращает несколько displayable, атрибут _main самого внешнего из них должен быть установлен на "главный" displayable — тот, к которому должны добавляться дочерние элементы.

style

Базовое имя стиля этого displayable. Если свойство style не задано, к этому имени будет добавлен префикс стиля. Вычисленный стиль передаётся функции displayable в качестве именованного аргумента style.

nchildren

Количество дочерних элементов этого displayable. Одно из:

0: Displayable не принимает дочерних элементов.
1: Displayable принимает 1 дочерний элемент. Если передано больше одного, они помещаются в Fixed.
"many": Displayable принимает более одного дочернего элемента.

unique

Следует установить в True, если функция возвращает displayable, на который нет других ссылок.

Следующие аргументы должны передаваться как именованные:

replaces: Если True, и displayable заменяет предыдущий, то предыдущий displayable передаётся в качестве параметра новому.
default_keywords: Набор именованных аргументов по умолчанию, передаваемых в displayable.
default_properties: Если True, свойства ui и position добавляются по умолчанию.

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

add_positional(name): Добавляет позиционный аргумент с именем name

add_property(name): Добавляет свойство с именем name. Свойства передаются как именованные аргументы.

add_style_property(name): Добавляет семейство свойств, оканчивающихся на name и имеющих различные префиксы свойств стиля. Например, при вызове с ("size") будут определены size, idle_size, hover_size и т.д.

add_prefix_style_property(prefix, name): Добавляет семейство свойств с именами, состоящими из prefix, префикса свойства стиля и name. Например, при вызове с префиксом text_ и именем size будут созданы text_size, text_idle_size, text_hover_size и т.д.

add_property_group(group, prefix='')

Добавляет группу свойств с префиксом prefix. group может быть одной из следующих строк:

"bar"
"box"
"button"
"position"
"text"
"window"

Они соответствуют группам Свойства стилей. group также может быть "ui", в этом случае добавляются общие свойства UI.

copy_properties(name): Добавляет все стили и позиционные/именованные аргументы, которые можно передать инструкции экрана name.

class renpy.register_sl_statement(name, children='many', screen=None)

Регистрирует пользовательскую инструкцию языка экранов в Ren'Py.

name: Должно быть словом. Это имя пользовательской инструкции языка экранов.
children: Количество дочерних элементов, которое принимает эта инструкция. Должно быть 0, 1 или "many", что означает ноль или больше.
screen: Экран для использования. Если не указан, по умолчанию используется name.

Возвращает объект, в который можно добавлять позиционные аргументы и свойства. Этот объект имеет те же методы .add_, что и объекты, возвращаемые renpy.register_sl_displayable.

В качестве примера инструкции экранного языка, определяемой разработчиком, вот реализация инструкции titledwindow, приведенной выше. Во-первых, инструкция должна быть зарегистрирована в блоке python early в файле, который загружается рано — имя вроде 01custom.rpy часто загружается достаточно рано. Вызов регистрации выглядит так:

python early:
    renpy.register_sl_statement("titledwindow", children=1).add_positional("title").add_property("icon").add_property("pos")

Затем мы определяем экран, который реализует пользовательскую инструкцию. Этот экран может быть определен в любом файле. Один из таких экранов:

screen titledwindow(title, icon=None, pos=(0, 0)):
    drag:
        pos pos

        frame:
            background "#00000080"

            has vbox

            hbox:
                if icon is not None:
                    add icon

                text title

            null height 15

            transclude

Когда используются большие группы свойств, такие как add_property_group, имеет смысл использовать синтаксис **properties с ключевым словом properties в каком-то месте. Например:

screen titledwindow(title, icon=None, **properties):
    frame:
        # When background not in properties it will use it as default value.
        background "#00000080"

        properties properties

        has vbox

        hbox:
            if icon is not None:
                add icon

            text title

        null height 15

        transclude

Пользовательские инструкции экранного языка поддерживают предложение as, которое принимает имя переменной. Если оно присутствует, этой переменной будет присвоено значение main в области видимости экрана.