# Привязки клавиш — `api.keymap`

Привязки живут у трёх видов объектов:

- у приложения — `api.keymap` (глобальные привязки);
- у редактора — `api.editor` (срабатывают, когда фокус в редакторе);
- у каждого блока панели — `tree` (срабатывают, когда фокус на этом блоке).

Встроенные сочетания можно заменить или удалить: обработчиком принимается
Lua-функция, имя встроенной команды или `nil`.

```lua
api.keymap:map_key(modes, keys, handler)          -- глобальные
api.editor:map_key(modes, keys, handler)          -- только когда фокус в редакторе
api.keymap:map_completion_key(keys, handler)      -- список автодополнения
```

Слой автодополнения режимами не управляется: `map_completion_key` принимает
только клавишу и обработчик.

Порядок обработки всегда такой: сначала глобальные привязки, затем — если
фокус в редакторе — привязки редактора, а если фокус на блоке панели —
привязки этого блока. Привязки неактивного объекта не срабатывают.

## Запись клавиши

| Запись | Значение |
| --- | --- |
| `"a"` | нажатие A |
| `"1"` | нажатие 1 |
| `"!a"` | отпускание A |
| `"<S-c>"` | C при зажатом Shift |
| `"<C-z>"` | Z при зажатом Ctrl |
| `"<A-!r>"` | отпускание R при зажатом Alt |
| `"<D-s>"` | S при зажатом Cmd на macOS или Super на Linux |

Клавиша сравнивается с именем клавиши от GPUI. Caps Lock не важен. На Linux
и Windows буквы берутся по аппаратному keycode, поэтому `<C-q>` работает
и на русской раскладке.

## Режимы

У каждого объекта своя текущая режимная метка: один символ (`n`, `i`, `v`, `r`
или любой другой) либо `-` — режим по умолчанию. Режимы динамические: заранее
создавать их не нужно, достаточно переключить метку.

| Значение `modes` | Когда срабатывает |
| --- | --- |
| `""` | во всех режимах |
| `"-"` | только в режиме по умолчанию |
| `"niv"` | в режимах `n`, `i`, `v` |
| `"-iv"` | в режиме по умолчанию, а также `i` и `v` |

Текущий режим меняется методами `set_mode(mode)` и читается методом `mode()`.
Режимы у приложения, редактора и каждого блока независимы.

```lua
api.keymap:set_mode("n")
api.editor:set_mode("i")

api.keymap:map_key("n", "<C-n>", "next_tab")       -- только в режиме n
api.editor:map_key("i", "<C-s>", "save")           -- только в режиме i редактора
api.editor:map_key("", "<C-space>", function() end) -- в любом режиме
```

## Встроенные команды

| Имя | Действие |
| --- | --- |
| `"save"` | Сохранить активную вкладку |
| `"next_tab"` | Следующая вкладка |
| `"previous_tab"` | Предыдущая вкладка |
| `"open_tab"` | Новая пустая вкладка |
| `"close_tab"` | Закрыть активную вкладку |
| `"toggle_left_panel"` | Переключить левую панель |
| `"toggle_right_panel"` | Переключить правую панель |
| `"toggle_bottom_panel"` | Переключить нижнюю панель |

Встроенные команды списка автодополнения:

| Имя | Действие |
| --- | --- |
| `"completion_trigger"` | Открыть список |
| `"completion_next"` / `"completion_previous"` | Сдвинуть выделение |
| `"completion_page_down"` / `"completion_page_up"` | Пролистать список |
| `"completion_accept"` | Вставить выбранный элемент |
| `"completion_cancel"` | Закрыть список |
| `"completion_dismiss"` | Закрыть список и передать клавишу редактору |

При запуске уже назначены:

- `Ctrl/Cmd+S` → `save` во всех режимах;
- `Ctrl/Cmd+Space` → `completion_trigger`;
- `Enter`/`Tab`, `Esc`, `↑`/`↓`, `PageUp`/`PageDown`, `←`/`→`, `Home`/`End`
  → команды слоя автодополнения.

## Примеры

```lua
-- Переопределить сохранение своей функцией во всех режимах.
api.keymap:map_key("", "<C-s>", function() api.editor:save() end)

-- Убрать встроенную привязку.
api.keymap:map_key("", "<C-s>", nil)

-- Назначить встроенную команду на другую клавишу.
api.keymap:map_key("", "<C-n>", "next_tab")
api.keymap:map_key("", "<C-b>", "toggle_left_panel")

-- Навигация по списку автодополнения на Ctrl+N / Ctrl+P.
api.keymap:map_completion_key("<C-n>", "completion_next")
api.keymap:map_completion_key("<C-p>", "completion_previous")

-- Привязка, которая срабатывает только при фокусе в редакторе.
api.editor:map_key("", "<A-r>", function()
  api.editor:set_active_text("editor mode")
end)

-- Привязка блока дерева: работает, когда фокус на этом дереве.
tree:map_key("v", "<A-f>", function() print("tree v") end)
```

Пока список автодополнения открыт, его слой проверяется раньше действий
редактора. Сочетания с модификаторами и горизонтальные стрелки закрывают
список, даже если для них нет своей привязки, — так `Shift+↑` продолжает
выделять текст.