# SplitOverlay

**Русский** · [English below](#english)

> Название репозитория — **SplitOverlay**. В коде, в имени exe, установщика и в папке настроек приложение называется **KeyOverlay**.

Полупрозрачный оверлей для Windows, который поверх всех окон показывает раскладку программируемой
(Vial / QMK) split-клавиатуры, например [Silakka54](https://github.com/Squalius-cephalus/silakka54).
Нужен, чтобы учить слои: смотришь на экран и видишь, что где лежит.

![Слой 0, нажаты Shift+1](docs/screenshot-layer0.png)

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

- Рисует плату по файлу раскладки Vial (`.vil`): все слои, `MO`/`TG`/`LT`/mod-tap, `Shift+цифра` и т.д.
- Прозрачные клавиши слоя (`KC_TRNS`) показываются приглушённо с нижнего слоя, как в QMK.
- **Автоопределение слоя с платы** (нужна прошивка с командой из [`firmware/`](firmware/)); без неё слой переключается вручную.
- **Символы по языку ввода**: буквы на клавишах меняются вместе с раскладкой Windows (RU, EN и любая другая). Нужные символы выдаёт сама Windows.
- **Разделение половинок**: каждая половина отдельным окном, двигаются независимо.
- Подсветка нажатых клавиш, регулировка прозрачности и размера, значок в трее.
- Оверлей прозрачен для мыши и не забирает фокус.

| Слой 1 | Разделение половинок | Язык ввода |
|---|---|---|
| ![](docs/screenshot-layer1.png) | ![](docs/screenshot-split-left.png) | ![](docs/screenshot-lang-ru.png) |

## Установка

Скачай со страницы [Releases](../../releases) установщик `KeyOverlay-<версия>-setup.exe`
или портативный `KeyOverlay-<версия>-portable.zip`. Установка идёт без прав администратора.
Exe не подписан, поэтому SmartScreen может предупредить («Подробнее» → «Выполнить в любом случае»).

Раскладку сохрани в Vial: **File → Save current layout** (`.vil`). При первом запуске приложение
попросит выбрать этот файл; можно также передать путь аргументом: `KeyOverlay.exe "путь\к\раскладке.vil"`.

## Управление

| Действие | Как |
|---|---|
| Следующий / предыдущий слой | Ctrl+Alt+PgDn / Ctrl+Alt+PgUp (отключает автоопределение) |
| Показать / скрыть | Ctrl+Alt+K или двойной клик по значку в трее |
| Прозрачность, размер, слой, язык, разделение, перечитать файл | меню значка в трее |
| Переместить оверлей | трей → «Режим перемещения», тащить мышью, колесо меняет размер |

## Прошивка (для автоопределения слоя)

Обычная клавиатура не сообщает ПК, какой слой активен, и в протоколе Vial такой команды нет.
Поэтому в [`firmware/`](firmware/) лежит небольшое дополнение для QMK/Vial: команда HID `0xE0`,
которая возвращает активный слой. Подробности, сборка и инструкция по прошивке: [`firmware/README.md`](firmware/README.md).
Готовые `.uf2` для Silakka54 (LED, v1.4led) лежат в Releases.

## Сборка из исходников

Нужен [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0) под Windows.

```
git clone https://gittea.khad1997pav.ru/khadzhibekovpa/SplitOverlay.git
cd SplitOverlay
dotnet test tests/KeyOverlay.Core.Tests
dotnet run --project src/KeyOverlay -- "путь\к\раскладке.vil"
```

Установщик и портативная сборка (Inno Setup берётся из NuGet, в систему ничего не ставится):

```
dotnet publish src/KeyOverlay -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true -p:EnableCompressionInSingleFile=true -o dist/app
dotnet restore installer/tools.csproj
installer/packages/tools.innosetup/6.4.3/tools/ISCC.exe /DAppVersion=1.0.0 installer/KeyOverlay.iss
```

Установщик кладёт в пакет файлы прошивки из `firmware/*.uf2`: соберите их (см. `firmware/README.md`)
или скачайте из Releases и положите в `firmware/`.

## Устройство проекта

```
src/KeyOverlay.Core   парсер .vil, подписи кейкодов, геометрия платы, протокол слоя (без зависимости от Windows)
src/KeyOverlay        WPF-оверлей: окна, хук клавиатуры, опрос платы по HID, язык ввода, трей
tests/                тесты Core (xUnit)
firmware/             команда слоя для QMK/Vial и сборка прошивки в Docker
installer/            скрипт Inno Setup
```

## Как это работает

**Core** (`src/KeyOverlay.Core`, .NET 8, без зависимости от Windows, покрыт тестами):

- `Keymap` читает `.vil` (JSON): поле `layout` — слои × 10 строк матрицы × 6 колонок. Строки 0–4 — левая половина,
  5–9 — правая, `-1` — клавиши нет. Прозрачные клавиши (`KC_TRNS`) проваливаются на нижний слой, как в QMK.
- `Keycodes` превращает кейкоды Vial/QMK в подписи (`KC_BSPACE` → «Bksp», `LSFT(KC_1)` → «!», `MO(2)` → «MO 2»).
- `BoardGeometry` — положение клавиш Silakka54: 4×6 с шагом по колонкам и 3 больших пальца на половину.
- `ScanCodes` и `PressedKeys` — разбор скан-кодов (физическая клавиша не зависит от языка) и учёт нажатых.
- `LayerProtocol` — формат команды слоя для прошивки; `KeyLocalizer` — замена подписей по языку ввода.

**Приложение** (`src/KeyOverlay`, WPF):

- Окно прозрачное, без рамки, поверх всех окон; стили `WS_EX_TRANSPARENT | WS_EX_NOACTIVATE | WS_EX_TOOLWINDOW`
  делают его прозрачным для мыши, без фокуса и без значка в панели задач.
- `KeyboardHook` — глобальный low-level hook: подсветка нажатых клавиш и горячие клавиши. События всегда передаются дальше.
- `LayerPoller` — раз в ~80 мс спрашивает плату по Raw HID (usage page `0xFF60`, usage `0x61`, библиотека HidSharp), реконнект при отключении.
- `InputLanguage` — язык берётся у окна на переднем плане (`GetKeyboardLayout`), символы клавиш вычисляет Windows (`ToUnicodeEx`).
- `OverlayController` связывает окна, хук, опрос платы, трей и настройки; режим разделения создаёт второе окно для правой половины.

## Поддерживаемые кейкоды

| Что | Примеры |
|---|---|
| Буквы, цифры, знаки, F1–F24 | `KC_A`, `KC_1`, `KC_SCOLON`, `KC_F12` |
| Навигация и служебные | `KC_ENTER`, `KC_BSPACE`, `KC_DELETE`, стрелки, `KC_PGUP`, `KC_HOME`, `KC_PSCREEN` |
| Модификаторы | `KC_LSHIFT`, `KC_RCTRL`, `KC_LALT`, `KC_LGUI` |
| Медиа | `KC_MPLY`, `KC_VOLU`, `KC_BRIU` |
| Обёртки с модификаторами | `LSFT(KC_1)`, `LCTL(KC_C)` (а также `S`, `C`, `A`, `G`, правые варианты) |
| Слои | `MO(n)`, `TG(n)`, `TO(n)`, `TT(n)`, `OSL(n)`, `DF(n)`, `LT(n, kc)` |
| Mod-tap | `LCTL_T(kc)`, `MT(MOD_LSFT, kc)` |
| Прозрачная / пустая | `KC_TRNS`, `KC_NO` |

Всё остальное (макросы, tap dance, `QK_BOOT` и т.п.) показывается сокращённым именем кейкода без расшифровки.
Сейчас геометрия рассчитана на **Silakka54** (матрица 10×6, 54 клавиши); для других плат нужна своя геометрия.

## Настройки

Файл `%APPDATA%\KeyOverlay\settings.json` создаётся автоматически и меняется через меню трея.

| Поле | Значение |
|---|---|
| `VilPath` | путь к файлу раскладки `.vil` |
| `Opacity` | прозрачность 0.2–1.0 |
| `Scale` | размер 0.5–2.0 |
| `Left`, `Top` | позиция окна (левой половины в режиме разделения) |
| `RightLeft`, `RightTop` | позиция правой половины в режиме разделения |
| `Layer` | последний выбранный вручную слой |
| `AutoLayer` | определять слой по данным платы |
| `HighlightPressed` | подсвечивать нажатые клавиши |
| `LocalizeKeys` | показывать символы выбранного языка ввода |
| `SplitHalves` | показывать половинки отдельными окнами |

Чтобы сбросить настройки, закрой приложение и удали этот файл.

## Если что-то не работает

- **В подписи «плата не отвечает».** Авто-определение слоя работает только с прошивкой из [`firmware/`](firmware/). Проверь, что прошиты обе половины,
  кабель подключён к главной (для файла LEFT — левой), а Vial закрыт. Пока слой можно выбрать вручную (Ctrl+Alt+PgUp/PgDn).
- **Оверлея не видно.** Нажми Ctrl+Alt+K или двойной клик по значку в трее. Если окно осталось за пределами экрана, удали `settings.json`.
- **SmartScreen / антивирус ругается.** Exe не подписан, а приложение использует глобальный перехват клавиш (нужен для подсветки). Исходники открыты, собрать можно самому.
- **Поверх игры оверлея нет.** Окно показывается поверх оконных и borderless-приложений, но не поверх эксклюзивного полноэкранного режима.
- **Буквы не меняются при смене языка.** Проверь пункт «Символы по языку ввода» в меню трея. Язык берётся у окна, в которое ты печатаешь.

## Идеи и планы

- Геометрия других плат (описание в JSON), имена слоёв.
- Подпись exe и автообновление.
- Автоматическое отслеживание изменений файла `.vil`.

## Участие

Issues и pull request приветствуются. Перед отправкой запусти `dotnet test tests/KeyOverlay.Core.Tests`; CI делает то же самое и собирает приложение.

## Приватность

Перехват клавиш (low-level hook) нужен только для подсветки нажатых клавиш и горячих клавиш.
Нажатия нигде не сохраняются и не отправляются, события всегда передаются дальше без изменений.
Приложение ничего не отправляет в сеть. Настройки лежат в `%APPDATA%\KeyOverlay\settings.json`.

## Ограничения

- Только Windows (WPF), x64.
- Определение слоя с платы работает через Raw HID и требует прошивки с командой `0xE0`; половина, подключённая к ПК, должна быть главной.
- Caps Lock на подписях не отражается; мёртвые клавиши показываются знаком акцента.
- Vial GUI и оверлей не стоит держать открытыми одновременно: оба общаются с одним HID-интерфейсом.

## Лицензия

Приложение: [MIT](LICENSE). Дополнение для прошивки (`firmware/keyoverlay_hid.c`) собирается внутрь
QMK/Vial и распространяется под GPL-2.0-or-later. Исходники плат и Vial принадлежат их авторам:
[vial-qmk](https://github.com/vial-kb/vial-qmk), [Squalius-cephalus/silakka54](https://github.com/Squalius-cephalus/silakka54).

---

## English

KeyOverlay is a semi-transparent, click-through Windows overlay that shows the keymap of a programmable
(Vial / QMK) split keyboard such as the Silakka54, always on top, to help you learn your layers.

**Features:** draws the board from a Vial `.vil` layout (all layers, `MO`/`TG`/`LT`/mod-tap, transparent keys
falling through to lower layers); **detects the active layer from the keyboard** via a small QMK/Vial firmware
command (`firmware/`); **shows the characters of the active Windows input language**; can **split the two halves
into separate windows**; highlights pressed keys; tray icon with opacity/size options.

**Install:** download the setup or portable zip from [Releases](../../releases); save your layout in Vial via
*File → Save current layout* and pick that `.vil` on first run. **Build:** .NET 8 SDK, `dotnet test tests/KeyOverlay.Core.Tests`,
`dotnet run --project src/KeyOverlay`. Windows only (x64). Key hook is used only for highlighting and hotkeys; nothing is stored or sent.

License: MIT for the app; the firmware add-on is GPL-2.0-or-later (it is compiled into QMK/Vial).