## Добавление своих горячих клавиш

Общая схема такая:
```python
# сначала определяем сочетания клавиш (1 или несколько) для наших хоткеев your_name1 и your_name2
config.keymap['your_name1'] = ['hotkey1']
config.keymap['your_name2'] = ['hotkey2', 'hotkey3']

# затем назначаем функции, которые нужно выполнить при их срабатывании
config.underlay.append(renpy.Keymap(
	your_name1 = your_function1,
	your_name2 = your_function2,
	
	# опционально можно указать звук для всех указанных выше хоткеев
	activate_sound = 'path/to/sound.ogg',
))
```

Здесь можно обнаружить довольно большую совместимость с renpy.  
Собственно, даже класс `renpy.Keymap` нужен лишь для этого - на самом деле в Ren-Engine это просто ссылка на `dict`.

В качестве хоткея (сочетания клавиш) может использоваться
1 опциональная клавиша-модификатор (`Ctrl`, `Shift` или `Alt`) + 1 обязательная обычная клавиша.

***

## Клавиша-модификатор

Почему клавиша-модификатор может быть только одна?  
Сразу несколько в одном хоткее зачастую используются ОС и прочими системо-образующими вещами (DE, WM и проч.),
поэтому даже если у вашей игры на конкретно вашей системе нет конфликтов хоткеев, то это не значит,
что их не будет у ваших пользователей, и чтобы максимально снизить число этих конфликтов,
введено ограничение на кол-во клавиш-модификаторов.

Если ОЧЕНЬ нужно, то это ограничение можно снять, поставив свойство `hotkeys.only_one_mod_key` в `False`
(тогда обязателен порядок `Ctrl`, затем `Shift` и затем `Alt`), но делать так НАСТОЯТЕЛЬНО НЕ РЕКОМЕНДУЕТСЯ.

***

## Примеры

Названия всех клавиш регистронезависимы, т. е. `a`/`A` или `shift`/`Shift`/`SHIFT` воспринимаются одинаково.  
Кроме того, для обратной совместимости с renpy допускается префикс `K_`: `K_F5`, например.

Несколько клавиш в одном хоткее записываются через `_` (нижнее подчёркивание - и оно тоже доступно для использования).  
При использовании символов, набираемых с помощью `Shift`, прямое указание этого шифта не нужно (тем не менее, оно
не является ошибкой и просто игнорируется).

Спец. клавиши (обычные клавиши с собственными названиями):  
* `ESCAPE`, `TAB`, `BACKSPACE`, `DELETE`, `INSERT`,  
* `HOME`, `END`, `PAGEUP`, `PAGEDOWN`,  
* `RETURN`, `SPACE` - кнопки Enter и Пробел,  
* `MENU` - кнопка контекстного меню (около правого `Ctrl`),  
* `LEFT`, `RIGHT`, `UP`, `DOWN` - стрелки.

Наконец, список примеров:  
`A`, `n`, `F2`, `5`, `Shift_T`, `K_o`, `K_CTRL_K_T`, `alt_u`, `$`, `shift_$`, `'`, `ESCAPE`, `CTRL_TAB`, `_`, `+`.

***

## Инициализация

По умолчанию инициализация "таблицы хоткеев" происходит после всех `init`-блоков, т. е. если вы добавляете или
обновляете хоткей в метке (`label`) или в функции, которая вызывается уже после инициализации игры, то вам нужно будет
реинициализировать её вручную: `hotkeys.init()`.

***

## Код вместо функции

Вместо функции (`your_function1` из 1 абзаца) можно указать строку, содержащую код, который нужно выполнить.  
В некоторых случаях это может быть полезно.  
Например, если нужно вызвать метод объекта, который может быть сменён другим объектом, и поэтому нельзя заранее
знать, метод какого объекта нужно сохранять в `renpy.Keymap`:
```python
rival = Rival(level = 1)
def set_new_rival(level):
	global rival
	rival = Rival(level)

# ...

config.underlay.append(renpy.Keymap(
	# некорректно, т. к. навсегда запоминается метод от начального объекта
#	call_rival = rival.call,
	
	# ок, каждый раз вызывается метод текущего объекта
	call_rival = 'rival.call()',
))
```

***

## Выключение всех хоткеев при скрине

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

Для этого нужно добавить название этого скрина в спец. список:  
`hotkeys.disable_on_screens.append('my_screen')`

***

## Выключение одного хоткея при скрине

Иногда нужно отключить только 1 хоткей при наличии определённого скрина, оставив все остальные в рабочем состоянии.  
Например, при показе истории диалога клавиша `ESCAPE` должна убирать эту историю (это ловит сам скрин `history`),
но при этом не открывать скрин паузы, который открывается по умолчанию на ту же `ESCAPE`.

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

Решается это так:  
`hotkeys.disable_key_on_screens['ESCAPE'].append('my_screen')`

***

## Получить хоткей для функции

Иногда (например, в скрине настроек) нужно получить хоткей, по которому будет выполнена некоторая функция
(к примеру, переключение полноэкранного режима).

`hotkeys.get_key_for(func, get_list = False)`  
Здесь:
* `func` - функция, которая была указана в `renpy.Keymap`,
* `get_list` - определяет, нужно ли возвращать список хоткеев (`True`) или строку с ними (`False`, по умолчанию).

***

[Далее ->](./Сохранение-и-загрузка)  
[<- Назад](./Экран-настроек)
