Экраны и Python (Screens and Python)
Ren'Py поддерживает определение экранов в языке программирования Python, а также в языке экрана Ren'Py. Экран Python создаётся путём предоставления функции экрана функции renpy.define_screen(). Затем его можно использовать, как и любой другой экран.
Функция экрана должна иметь параметры, соответствующие ожидаемой области видимости переменных, и должна игнорировать дополнительные именованные аргументы. То есть она должна иметь **kwargs в конце своего списка параметров. Затем ожидается вызов функций UI для добавления отображаемых объектов на экран. Функция экрана вызывается при каждом запуске или перезапуске взаимодействия.
Чтобы гарантировать, что этот перезапуск будет бесшовным для пользователя (и не приведёт к сбросу), важно, чтобы каждый вызов функции UI предоставлял аргумент id. По мере воссоздания экрана Ren'Py будет обновлять каждый отображаемый объект с помощью содержимого старого отображаемого объекта с тем же идентификатором. Идентификаторы автоматически генерируются языком экрана, но при выполнении действий вручную они должны быть определены вручную.
Предупреждение! Функции UI устарели и не рекомендуются.
Вот пример экрана на языке Python:
init python:
def say_screen(who, what, **kwargs):
ui.window(id="window")
ui.vbox(id="say_vbox")
ui.text(who, id="who")
ui.text(what, id="what")
ui.close()
renpy.define_screen("say", say_screen)
Функции экрана (Screen Functions)[править | править код]
Следующие функции поддерживают определение, отображение и скрытие экранов.
renpy.call_screen(_screen_name, *args, **kwargs)
- Программный эквивалент оператора call screen.
- Отображает _screen_name как экран, а затем вызывает взаимодействие. В конце взаимодействия экран скрывается и результат взаимодействия возвращается.
- Позиционные и именованные аргументы, которые не начинаются _, передаются на экран.
- Если именованный аргумент _with_none принимает значение False, "with None" не запускается в конце взаимодействия.
- Если именованный аргумент _mode в kwargs, то это будет режим этого взаимодействия, иначе это будет «экранный» режим.
renpy.define_screen(name, function, modal="False", zorder="0", tag=None, variant=None)
- Определяет экран с name, которое должно быть строкой.
- function
- Функция, вызываемая для отображения экрана. Функция вызывается с областью видимости экрана в качестве именованных аргументов. Следует игнорировать дополнительные именованные аргументы.
- Функция должна вызывать функции ui для добавления объектов на экран.
- modal
- Строка, которая при оценке результатов определяет созданный экран, должна быть модальной. Модальный экран не позволяет экранам под ним принимать входные события.
- zorder
- Строка, которая при оценке результатов должна быть целым числом. Целое число определяет порядок отображения экранов. Экран с большим числом zorder отображается над экранами с меньшим числом zorder.
- tag
- Тег, связанный с этим экраном. Когда экран отображается, он заменяет любой другой экран с тем же тегом. Тег по умолчанию соответствует имени экрана.
- predict
- Если принимает значение True, этот экран может быть загружен для прогнозирования изображения. Если принимает значение False, это не так. По умолчанию принимает значение True.
- variant
- Строка. Предоставляет вариант экрана для использования.
renpy.get_screen(name, layer=None)
- Возвращает ScreenDisplayable с заданным name на слой, name cначала интерпретируется как имя тега, а затем как имя экрана. Если экран не отображается, возвращается значение None.
- Также может принимать список имён, и в этом случае возвращается первый отображаемый экран.
- Функция может использоваться для проверки отображения экрана:
if renpy.get_screen("say"): text "Экран say отображается." else: text "Экран say не отображается."
renpy.get_widget(screen, id, layer=None)
- С screen на layer, возвращает виджет с id. Возвращает значение None, если экран не существует или на экране нет виджета с таким id.
renpy.get_widget_properties(id, screen=None, layer=None)
- Возвращает свойства виджета с id на screen в layer. Если screen принимает значение None, возвращает свойства текущего экрана. Это можно использовать языком Python или свойствами кода внутри экрана.
- Обратите внимание, что при этом возвращается словарь, содержащий свойства виджета, и поэтому для получения отдельного свойства необходимо получить доступ к словарю.
renpy.hide_screen(tag, layer=None)
- Программный эквивалент оператора hide screen.
- Скрывает экран с tag на layer.
renpy.predicting()
- Возвращает значение True, если в настоящее время Ren'Py прогнозирует экран.
renpy.show_screen(_screen_name, *_args, **kwargs)
- Программный эквивалент оператора show screen.
- Показывает именованный экран. Для этого нужны следующие именованные аргументы:
- _screen_name
- Имя экрана для отображения.
- _layer
- Слой для отображения экрана.
- _zorder
- Zorder для отображения экрана. Если не указан, по умолчанию используется zorder, связанный с экраном. Если не указан, это 0 по умолчанию.
- _tag
- Тег для отображения экрана. Если не указан, по умолчанию используется тег, связанный с экраном. Если не указан, по умолчанию используется имя экрана.
- _widget_properties
- Карта от идентификатора виджета до имени свойства -> карта значения свойства. Когда виджет с таким идентификатором отображается на экране, к нему добавляются указанные свойства.
- _transient
- Если принимает значение True, экран будет автоматически скрыт в конце текущего взаимодействия.
- Неименованные и именованные аргументы, не начинающиеся с подчеркивания, передаются на экран.
renpy.start_predict_screen(_screen_name, *args, **kwargs)
- Даёт команду Ren'Py начать прогнозировать экран с именем _screen_name, который должен быть показан с заданными аргументами. Заменяет любой предыдущий прогноз _screen_name. Чтобы остановить прогнозирование экрана, вызовите renpy.stop_predict_screen().
renpy.stop_predict_screen(name)
- Даёт команду Ren'Py прекратить прогнозировать экран с именем name, который должен быть показан.
renpy.variant(name)
- Возвращает значение True, если name является вариантом экрана, который может быть выбран Ren'Py. Дополнительные сведения смотрите в разделе «Варианты экрана». Эта функция может использоваться в качестве условия в языке Python, если оператор устанавливает соответствующие стили для выбранного варианта экрана.
- name также может быть списком вариантов, в этом случае эта функция возвращает значение True, если выбран любой из вариантов.
Функции UI (UI Functions)[править | править код]
- Заметка: Реализация Ren'Py изменилась и функции UI, создающие отображаемые объекты, теперь могут быть намного медленнее, чем их эквиваленты языка экрана.
Функции UI являются эквивалентами операторов языка экрана в синтаксисе Python. Для каждого оператора языка экрана существует функция UI с тем же именем. Например, ui.text соответствует оператору text и ui.add соответствует оператору add.
Существует простое сопоставление между параметрами и аргументами языка экрана и аргументами в Python. Параметры языка экрана становятся позиционными аргументами, а свойства – именованными аргументами. Например, оператор языка экрана:
text "Привет, мир" size 40 xalign 0.5
становится:
ui.text("Привет, мир", size=40, xalign=0.5)
(На самом деле должен быть добавлен параметр id.)
Существует три группы функций UI, соответствующие количеству дочерних элементов, которые они принимают.
Следующие функции UI не принимают никаких дочерних элементов:
- ui.add
- ui.bar
- ui.imagebutton
- ui.input
- ui.key
- ui.label
- ui.null
- ui.text
- ui.textbutton
- ui.timer
- ui.vbar
- ui.hotspot
- ui.hotbar
- ui.spritemanager
Следующие функции UI принимают один дочерний элемент. Необходимо предоставить дочерний элемент, используйте ui.null(), если дочерний элемент отсутствует.
- ui.button
- ui.frame
- ui.transform
- ui.window
- ui.drag
Следующие функции UI принимают несколько дочерних элементов. Они продолжают принимать дочерние элементы до тех пор, пока не будет вызвана функция ui.close().
- ui.fixed
- ui.grid
- ui.hbox
- ui.side
- ui.vbox
- ui.imagemap
- ui.draggroup
Есть несколько функций UI, которые не соответствуют операторам языка экрана, поскольку они соответствуют понятиям, которых нет в языке экрана.
ui.adjustment(range=1, value=0, step=None, page=None, changed=None, adjustable=None, ranged=None, force_step=False)
- Объекты корректировок представляют собой значение, которое можно настроить с помощью панели или области просмотра. Они содержат информацию о значении, диапазоне значений и способах настройки значения с помощью небольших шагов и больших страниц.
- Следующие параметры соответствуют полям или свойствам объекта корректировки:
- range
- Диапазон корректировки, число.
- value
- Значение корректировки, число.
- step
- Величина шага корректировки, число. Если принимает значение None, то по умолчанию используется 1/10 страницы, если задан. Иначе по умолчанию используется 1/20 диапазона.
- Это используется при прокрутке области просмотра с помощью колесика мыши.
- page
- Размер страницы корректировки. Если принимает значение None, автоматически устанавливается с помощью окна просмотра. Если никогда не задаётся, по умолчанию используется 1/10 диапазона.
- Можно использовать при нажатии на полосу прокрутки.
- Следующие параметры контролируют поведение корректировки.
- adjustable
- Если принимает значение True, эта корректировка может быть изменена с помощью панели. Если принимает значение False, то не может.
- По умолчанию регулируется, если задана функция changed или если корректировка связана с окном просмотра, а не настраивается иначе.
- changed
- Эта функция вызывается с новым значением при изменении значения корректировки.
- ranged
- Эта функция вызывается с объектом корректировки, когда диапазон корректировки устанавливается с помощью окна просмотра.
- force_step
- Если принимает значение True и эта корректировка изменяется путём перетаскивания соответствующего окна просмотра или панели, значение изменится только в том случае, если перетаскивание достигло следующего шага. Если "релиз" и эта корректировка изменяются путём перетаскивания окна просмотра или панели, после выпуска, значение будет округлено до ближайшего шага. Если принимает значение False, эта корректировка будет изменяться путём перетаскивания, игнорируя значение шага.
- change(value)
- Изменяет значение корректировки на value, обновляя любые панели и окна просмотра, использующие корректировку.
ui.at(transform)
- Задаёт преобразование, которое применяется к следующему отображаемому объекту, который будет создан. В значительной степени устарело, поскольку все функции UI теперь принимают аргумент at.
ui.close()
- Закрывает отображаемый объект, созданный с помощью функции UI. Когда отображаемый объект закрыт, мы добавляем новые отображаемые элементы к его родительскому элементу или в слой, если отображаемый элемент не открыт.
ui.detached()
- Не добавляйте следующий отображаемый объект в более поздний или контейнер. Используйте, если хотите присвоить результат функции UI переменной.
ui.interact(roll_forward=None, mouse='default')
- Вызывает взаимодействие с пользователем и возвращает результат этого взаимодействия. Это приводит к тому, что Ren'Py перерисовывает экран и начинает обработку входных событий. Когда отображаемый объект возвращает значение в ответ на событие, это значение возвращается из ui.interact и взаимодействие заканчивается.
- Эта функция редко вызывается напрямую. Обычно она вызывается другими частями Ren'Py, в том числе оператором say, оператором menu, оператором with, оператором pause, экраном вызова, renpy.input() и многими другими функциями. Однако при необходимости её можно вызвать напрямую.
- Когда взаимодействие заканчивается, переходный слой и все экраны, показанные с параметром transient=True, удаляются из списков сцен.
- Следующие аргументы задокументированы. Поскольку существуют другие недокументированные аргументы для внутреннего использования Ren'Py, пожалуйста, передайте все аргументы как именованные аргументы.
- roll_forward
- Информация, которая будет возвращена этой функцией при выполнении прокрутки вперёд. Если принимает значение None, прокрутка вперёд игнорируется. Обычно должна передаваться в результате выполнения функции renpy.roll_forward_info().
- mouse
- Стиль курсора мыши, используемый во время этой функции.
ui.layer(name)
- Добавляет отображаемые объекты в слой с именем name. Последний должен быть закрыт с помощью ui.close().
ui.screen_id(id_, d)
- Присваивает отображаемому d идентификатор экранного виджета id_, как если бы он был создан оператором screen с этим идентификатором.
Действия (Actions)[править | править код]
Многие отображаемые объекты, созданные на языке экрана, принимают действия в качестве аргументов. Действие – одно из трёх элементов:
- Вызываемый объект в Python (например, функция или связанный метод), который не принимает аргументов.
- Объект класса, наследующий от класса Action.
- Список других действий.
Преимущество наследования от класса Action заключается в том, что он позволяет переопределять методы, определяющие, когда кнопка должна быть чувствительна к нажатию, а когда выбрана.
- class Action
- Для определения новое действие, необходимо наследование от этого класса. Переопределите методы в этом классе, чтобы изменить поведение действия.
- __call__(self)
- Метод, который вызывается при активации действия. Во многих случаях возврат значения не None из действия приведёт к завершению текущего взаимодействия.
- Метод должен быть переопределен, так как по умолчанию он вызовет NotImplemented и, следовательно, вызовет сообщение об ошибке 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 для кнопки (или аналогичного объекта), этот метод вызывается, когда объект теряет фокус.
Чтобы запустить действие из Python, используйте renpy.run().
renpy.is_selected(action)
- Возвращает значение True, если action указывает на то, что он выбран, иначе значение False.
renpy.is_sensitive(action)
- Возвращает значение True, если action указывает на то, что он чувствителен к нажатию, иначе значение False.
renpy.run(action)
- Выполняет действие или список действий. Одно действие вызывается без аргументов, список действий выполняется в порядке использования этой функции и значение None игнорируется.
- Возвращает результат первого действия для возврата значения.
BarValue[править | править код]
При создании bar, vbar или hotbar, объект BarValue может быть указан как свойство value. Для получения настроек и стилей вызываются методы объекта BarValue.
- class BarValue
- Для определения нового BarValue, необходимо наследование от этого класса и замена некоторых методов.
- get_adjustment(self)
- Метод вызывается для получения объекта корректировки для панелей. Он должен создать корректировку с помощью ui.adjustment(), а затем вернуть объект, созданный таким образом.
- Метод должен быть переопределен, так как по умолчанию он вызовет NotImplemented и, следовательно, вызовет сообщение об ошибке Ren'Py.
- get_style(self)
- Используется для определения стиля панелей, использующих это значение. Должен вернуть кортеж из двух имён стилей или объектов стиля.
- По умолчанию это ("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 должен хранить корректировку, а periodic должен вызывать измененный метод корректировки.
InputValue[править | править код]
При создании ввода в качестве свойства value можно указать объект InputValue. Методы объекта InputValue вызываются для получения и задания текста, определения возможности редактирования ввода и обработки нажатия клавиши Enter.
- class InputValue
- Чтобы определить новый InputValue, наследуйте от этого класса, переопределите некоторые или все методы и задайте значение поля по умолчанию.
- default
- Если принимает значение True, то по умолчанию вводимые данные можно редактировать. То есть, когда экран ввода отображается, может быть задан курсор для редактирования.
- get_text(self)
- Возвращает текст ввода по умолчанию. Это должно выполняться.
- set_text(self, s)
- Вызывается при изменении текста ввода с новым текстом. Это должно выполняться.
- enter(self)
- Вызывается, когда пользователь нажимает Enter. Если возвращает значение, отличное от None, это значение возвращается из взаимодействия. Может также вызвать renpy.IgnoreEvent(), чтобы игнорировать нажатие. Иначе нажатие клавиши Enter распространяется на другие отображаемые объекты.
- Следующие действия доступны как методы для InputValue:
- Enable()
- Возвращает действие, которое позволяет редактировать текст при вводе.
- Disable()
- Возвращает действие, которое отключает редактирование текста при вводе.
- Toggle()
- Возвращает действие, которое переключает редактирование текста при вводе.
Операторы языка экрана, определяемые разработчиком (Creator-Defined Screen Language Statements)[править | править код]
Ren'Py поддерживает определение пользовательских операторов языка экрана. Операторы языка экрана, определяемые разработчиком, являются оболочками для оператора use языка экрана. Позиционные аргументы остаются позиционными аргументами, свойства становятся именованными аргументами, и если оператор принимает блок, то это делает оператор use. Например, пользовательский оператор языка экрана:
titledwindow "Тестовое окно":
icon "icon.png"
text "Это проверка."
становится:
use titledwindow("Тестовое окно", icon="icon.png"):
text "Это проверка."
Операторы языка экрана, определяемые разработчиком, должны регистрироваться в блоке 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)
- Регистрирует оператор языка экрана, который создаёт отображаемый объект.
- name
- Имя оператора языка экрана. Строка, содержащая ключевое слово Ren'Py. Это ключевое слово используется для введения нового оператора.
- displayable
- Функция, которая при вызове возвращает отображаемый объект. Все аргументы позиции, свойства и свойства стиля передаются в качестве аргументов этой функции. Другие именованные аргументы также принимаются этой функцией, описанной ниже.
- Должна вернуть Displayable. Если возвращает несколько отображаемых объектов, атрибут _main наиболее удаленного отображаемого объекта должен быть установлен в "main" отображаемого объекта, к которому должны быть добавлены дочерние элементы.
- style
- Базовое имя стиля этого отображаемого объекта. Если свойство стиля не задано, к нему будет добавлен префикс стиля. Вычисляемый стиль передается функции displayable в качестве именованного аргумента style.
- nchildren
- Количество дочерних элементов этого отображаемого объекта. Один из:
- 0
- Отображаемый объект не принимает дочерние элементы.
- 1
- Отображаемый объект принимает один дочерний элемент. Если предоставляется более одного дочернего элемента, они помещаются в Fixed.
- "many"
- Отображаемому объекты нужно более одного дочернего элемента.
- Следующие аргументы должны быть переданы с помощью именованных аргументов:
- replaces
- Если принимает значение True, а отображаемый объект заменяет предыдущий отображаемый объект, то этот отображаемый объект передаётся в качестве параметра новому отображаемому объекту.
- default_keywords
- Набор именованных аргументов по умолчанию для отображаемого объекта.
- default_properties
- Если принимает значение True, свойства пользовательского интерфейса и позиции добавляются по умолчанию.
- Возвращает объект, который может иметь позиционные аргументы и свойства, добавленные к нему, путём вызова следующих методов. Каждый из этих методов возвращает объект, для которого он был вызван, что позволяет объединять методы в цепочку.
- add_positional(name)
- Добавляет позиционный аргумент с name.
- add_property(name)
- Добавляет свойство с name. Свойства передаются в качестве именованных аргументов.
- add_style_property(name)
- Добавляет семейство свойств, заканчивающихся name и префиксами с различными префиксами свойств стиля. Например, если вызван с ("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"
- Они соответствуют группам свойств стиля. Группой также может быть "ui", в этом случае она добавляет общие свойства пользовательского интерфейса.
class renpy.register_sl_statement(name, positional=0, children='many', screen=None)
- Регистрирует пользовательский оператор языка экрана в Ren'Py.
- name
- Это должно быть слово. Это имя пользовательского оператора языка экрана.
- positional
- Количество позиционных параметров, которое принимает этот оператор.
- children
- Количество дочерних элементов, которое принимает этот пользовательский оператор. Это должно быть 0, 1 или "many", что означает ноль или больше.
- screen
- Экран для использования. Если не задан, по умолчанию используется name.
- Возвращает объект, к которому могут быть добавлены позиционные аргументы и свойства. Этот объект имеет те же методы .add_, что и объекты, возвращаемые renpy.register_sl_displayable.
В качестве примера оператора языка экрана, созданного разработчиком, приведена реализация оператора titledwindow, приведенного выше. Во-первых, оператор должен быть зарегистрирован в блоке python early, который загружается на ранней стадии - имя, подобное 01custom.rpy, часто загружается достаточно быстро. Регистрационный вызов выглядит так:
python early:
renpy.register_sl_statement("titledwindow", positional=1, children=1).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
Источник[править | править код]
Статья "Screens and Python" на английском языке.
На главную страницу | Официальная документация движка | Вернуться к началу статьи |