Экраны и Python (Screens and Python)

Материал из Ren'Py Wiki
Перейти к навигации Перейти к поиску

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" на английском языке.


На главную страницу Официальная документация движка Вернуться к началу статьи