Простой пример использования: некоторые игры спрашивают имя игрока в начале игры.  
Также ввод с клавиатуры используется при указании названия нового проекта в Лаунчере
или при редактировании мест в РПГ-Редакторе.

***

## Возможности

В скрине ввода, как и в консоли (открывается при нажатии `Shift+O`) поддерживается множество операций:
* Копирование (`Ctrl+C`);
* Вставка (`Ctrl+V`);
* Удаление текущей строки (`Ctrl+D`);
* Удаление символов работает как с `Backspace`, так и с `Delete`;
* Курсор ввода можно перемещать стрелками, а также кнопками `Home` (в начало строки) и `End` (в конец);
* При нажатии `Ctrl` во время перемещения и удаления используются не отдельные символы, а их группы (пробелы, буквы/цифры, знаки);
* `Enter` завершает ввод, как и кнопка `Ok`.

Есть ещё 2 кнопки (могут отключаться в параметрах вызова):
* Сброс вводимого текста на значение по умолчанию;
* Отмена ввода текста и закрытие скрина (отключено при вызове из сценария из-за отсутствия смысла).

***

## Вызов из сценария

`$ renpy.input(var_name, prompt, default = '', allow = None, exclude = '', length = None, mask = None, reset_btn = None)`  
Здесь:
* `var_name` - имя переменной (строка), в которую будет записан результат;
* `prompt` - "подсказка" о том, что требуется ввести (может быть пустой строкой);
* `default` - значение по умолчанию в поле ввода;
* `allow` - строка с допустимыми для ввода символами (`None` - разрешить все);
* `exclude` - строка с запрещёнными для ввода символами (используется при `allow is None`);
* `length` - максимальное кол-во символов в строке ввода (по умолчанию - `32`);
* `mask` - строка из `1` символа, которым будет заменяться содержимое при показе (например, `'*'` сделает вид пароля);
* `reset_btn` - нужно ли показывать кнопку для сброса (по умолчанию `True`, если указан `default`).

В renpy эта функция имеет более удобный вид:  
`$ var_name = renpy.input('prompt', 'default', ...)`  
К сожалению, по некоторым причинам на данный момент сделать такой же интерфейс этой функции в Ren-Engine невозможно.

Кроме того, **важно** отметить, что вызов этой функции должен быть последним в блоке `python` кода
(или единственным, как это обычно и бывает в команде `$`).

Кстати, параметр `var_name` не обязательно должен быть именно названием переменной.  
Это также может быть "путь" к ней: `'my_obj.params.some_prop'` или даже `'my_dict.some_key'` (да, у словаря тоже через точку).  
Реализовано это через `getset_attr`, подробности можно прочесть в [ScreenLang](./ScreenLang) (раздел "Действие").

Пример:
```renpy
label start:
	"My name is..."
	$ renpy.input('player_name', 'My Name', 'Alex')
	"Exactly - %s." % player_name
```

***

## Вызов из скрина

Для вызова из скрина удобнее использовать другую функцию, с помощью которой и работает `renpy.input`, показанная выше:  
`input.ask_str(callback, prompt, default = '', allow = None, exclude = '', length = None, mask = None, reset_btn = True, cancel_btn = True)`  
Здесь:
* `callback` - функция (или другой вызываемый объект), что принимает результат (строку);
* `cancel_btn` - нужно ли отображать кнопку отмены + должен ли к ней приводить клик по "затемнению фона";
* остальные параметры являются теми же самыми, что и в `renpy.input` выше.

Пример:
```renpy
init python:
	my_param = 'some'
	def set_my_param(value):
		global my_param
		my_param = value
	
	show_screen('my_screen')

screen my_screen:
	zorder 10
	
	textbutton my_param:
		xalign 0.5
		action input.ask_str(set_my_param, 'My Param', default = my_param, allow = alphabet + '_')
```

Также есть функции `input.ask_int` и `input.ask_float`, которые имеют те же параметры, но в `allow`
по умолчанию разрешаются только цифры и некоторые знаки.  
Внимание: адекватный порядок этих знаков или разумный диапазон значений не гарантируется, а `callback` по-прежнему принимает строку.  
Изменения касаются лишь символов, допустимых ко вводу - и не более.

***

## Наборы символов

Для параметров `allow` и `exclude` удобно использовать уже готовые наборы символов, что было показано в примере выше:
* `numbers` - цифры от `0` до `9`;
* `alphabet` - латинские буквы от `a` до `z`;
* `alphabet.upper()` - большие латинские буквы от `A` до `Z`.

Переменные `numbers` и `alphabet` являются обычными строками.  
Изменять их значения запрещается.

Что касается нелатинских символов (кириллица, иероглифы и т. д.), то их ввод возможен только копипастом (`Ctrl+V`).

***

[Далее ->](./ScreenLang)  
[<- Назад](./ATL-(анимации-и-трансформации))
