194 lines
15 KiB
Markdown
194 lines
15 KiB
Markdown
# SplitOverlay
|
||
|
||
**Русский** · [English below](#english)
|
||
|
||
> Название репозитория — **SplitOverlay**. В коде, в имени exe, установщика и в папке настроек приложение называется **KeyOverlay**.
|
||
|
||
Полупрозрачный оверлей для Windows, который поверх всех окон показывает раскладку программируемой
|
||
(Vial / QMK) split-клавиатуры, например [Silakka54](https://github.com/Squalius-cephalus/silakka54).
|
||
Нужен, чтобы учить слои: смотришь на экран и видишь, что где лежит.
|
||
|
||
|
||
|
||
## Возможности
|
||
|
||
- Рисует плату по файлу раскладки Vial (`.vil`): все слои, `MO`/`TG`/`LT`/mod-tap, `Shift+цифра` и т.д.
|
||
- Прозрачные клавиши слоя (`KC_TRNS`) показываются приглушённо с нижнего слоя, как в QMK.
|
||
- **Автоопределение слоя с платы** (нужна прошивка с командой из [`firmware/`](firmware/)); без неё слой переключается вручную.
|
||
- **Символы по языку ввода**: буквы на клавишах меняются вместе с раскладкой Windows (RU, EN и любая другая). Нужные символы выдаёт сама Windows.
|
||
- **Разделение половинок**: каждая половина отдельным окном, двигаются независимо.
|
||
- Подсветка нажатых клавиш, регулировка прозрачности и размера, значок в трее.
|
||
- Оверлей прозрачен для мыши и не забирает фокус.
|
||
|
||
| Слой 1 | Разделение половинок | Язык ввода |
|
||
|---|---|---|
|
||
|  |  |  |
|
||
|
||
## Установка
|
||
|
||
Скачай со страницы [Releases](https://gittea.khad1997pav.ru/khadzhibekovpa/SplitOverlay/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](https://gittea.khad1997pav.ru/khadzhibekovpa/SplitOverlay/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).
|