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

Общая схема такая:

    # сначала определяем сочетания клавиш (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`:

    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`, по умолчанию).

Далее ->
<- Назад