chordgen.ru.md

chordgen

chordgen (chord generator) — программа, которая генерирует код для обработки аккордов в QMK, который затем нужно добавить в свою программу.

Предварительная настройка

В терминологии QMK аккорды называются combos, но в QMK Bonus используется слово chord или аккорд.

Сначала надо включить поддержку аккордов в QMK в файле rules.mk:

COMBO_ENABLE=yes

Также в файле config.h надо указать количество используемых аккордов. chordgen может помочь их посчитать, если вызвать её так:

ruby chordgen.rb --count-chords

Вывод этой команды надо вставить в config.h:

#define COMBO_COUNT 1 // любое число

Также можно настроить время, в течение которого нужно нажать клавиши аккорда. По умолчанию оно равно TAPPING_TERM, и это можно не менять, но если хочется, то делается это в том же config.h:

#define COMBO_TERM 300 // любое число, в разумных пределах

Если планируется использовать русские буквы, то надо добавить в свой проект другую библиотеку QMK Bonus — rusmap.h. Узнать подробнее можно в документации к библиотеке.

Формат конфигурации

Формат конфигурации основан на формате INI, широко применяемом на Windows. Файл конфигурации называется chords.ini и находится в той же директории, что и программа chordgen, но это можно настроить, указав путь к своему конфигу после опции --config:

ruby chordgen.rb --config ~/my-config.ini

Этот файл должен выглядеть примерно так:

[LATIN]
q=rf

Здесь [LATIN] начинает секцию аккордов, которые работают, только когда активен слой LATIN. Строка q=rf значит, что в компьютер будет отправлен сканкод KC_Q, когда пользователь нажимает одновременно KC_R и KC_F.

Использование нескольких слоёв

Это особенно нужно, если реализуются аккорды с буквами нескольких языков.

[CYRILLIC]
ф=рь

[LATIN]
q=rf

Такой конфиг значит, что введётся буква Ф, если нажаты Р и Ь, и текущий слой CYRILLIC. Если этот слой неактивен, будут проверяться следующие секции, и так до последней.

Исполнение аккорда на любом слою

Аккорды, которые будут исполняться независимо от слоя нужно вставить в секцию [any]:

[any]
1=qw

Я не рекомендую так делать, лучше для этой цели использовать стандартный слой, который обычно называется _DEFAULT. Но это на вкус пользователя.

Исполнение произвольного кода в аккордах

Если нужно, чтобы при нажатии аккорда отправлялся не просто сканкод, а исполнялся произвольный код, то нужно этот код обернуть в скобки и вот так:

[any]
(if (1 == 1) short_circuit();)=qw

Код внутри скобок не проверяется на валидность, поэтому надо быть осторожным и писать правильный код:

// Плохо!
[any]
(if (1 == 1 short_circuit();)=qw

Переопределение набора символов

По умолчанию chordgen поддерживает только первые и вторые слои стандартных раскладок ЙЦУКЕН и QWERTY, за исключением скобок (то есть, a-z0-9а-я). Если хочется, можно переопределить существующие символы или задать свои в секции [override]. Можно использовать любой символ юникода. Заглавные буквы свободны, кстати.:

[override]
π=KC_P
i=KC_O

[any]
π=ui

Получится аккорд, который срабатывает при нажатии KC_U и KC_O и отправляет KC_P.

Комментарии

Строки, которые начинаются с // считаются за пустые, то есть за комментарии. В них можно писать что угодно.

Печать таблицы символов

Есть возможность узнать полную таблицу символов, включая определённые пользователем в конфиге. Для этого надо передать опцию --print-syms:

ruby chordgen.rb --print-syms

Справка

В программу встроенная справка по опциям:

ruby chordgen.rb -h
ruby chordgen.rb --help