Skip to content

Instantly share code, notes, and snippets.

@aljustiet

aljustiet/gist:92a80e38ac66b8c39a4c0d6d03492b9a

Created April 1, 2024 19:35
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save aljustiet/92a80e38ac66b8c39a4c0d6d03492b9a to your computer and use it in GitHub Desktop.
Save aljustiet/92a80e38ac66b8c39a4c0d6d03492b9a to your computer and use it in GitHub Desktop.
Download ZIP
Raw
gistfile1.txt
= Configuration
:toc:
:toc-placement!:
:toc-title!:
This document describes how to create a kanata configuration file. The kanata
configuration file will determine your keyboard behaviour upon running kanata.
NOTE: The configuration guide you are reading
may have content not applicable to the version you are using.
See below for links to specific guide versions.
.Links to specific guide versions
[%collapsible]
====
* https://github.com/jtroo/kanata/blob/v1.6.0-prerelease-2/docs/config.adoc[v1.6.0-prerelease-2]
* https://github.com/jtroo/kanata/blob/v1.6.0-prerelease-1/docs/config.adoc[v1.6.0-prerelease-1]
* https://github.com/jtroo/kanata/blob/v1.5.0/docs/config.adoc[v1.5.0]
====
The configuration file uses S-expression syntax from Lisps. If you are not
familiar with any Lisp-like programming language, do not be too worried. This
document will hopefully be a sufficient guide to help you customize your
keyboard behaviour to your exact liking.
If you have any questions, confusions, suggestions, etc., feel free to
https://github.com/jtroo/kanata/discussions/new/choose[start a discussion]
or https://github.com/jtroo/kanata/issues/new/choose[file an issue].
If you have ideas for how to improve this document or any other part of the project,
please be welcome to make a pull request or file an issue.
'''
[[table-of-contents]]
== Table of contents
toc::[]
== Forcefully exit kanata [[force-exit]]
<<table-of-contents,Back to ToC>>
Though this isn't configuration-related,
it may be important for you to know that pressing and holding all of the
three following keys together at the same time will cause kanata to exit:
- Left Control
- Space
- Escape
This mechanism works on the key input **before** any remappings done by kanata.
[[comments]]
== Comments
<<table-of-contents,Back to ToC>>
You can add comments to your configuration file. Comments are prefixed with two
semicolons. E.g:
[source]
----
;; This is a comment in a kanata configuration file.
;; Comments will be ignored and are intended for you to help understand your
;; own configuration when reading it later.
----
You can begin a multi-line comment block with `+#|+` and end it with `+|#+`:
[source]
----
#|
This is
a multi-line comment block
|#
----
[[required-configuration-entries]]
== Required configuration entries
[[defsrc]]
=== defsrc
<<table-of-contents,Back to ToC>>
Your configuration file must have exactly one `defsrc` entry. This defines the
order of keys that the `+deflayer+` entries will operate on.
A `defsrc` entry is composed of `defsrc` followed by key names that are
separated by whitespace.
It should be noted that the `defsrc` entry is treated as a long sequence; the
amount of whitespace (spaces, tabs, newlines) are not relevant. You may use
spaces, tabs, or newlines however you like to visually format `defsrc` to your
liking.
The primary source of all key names are the
`str_to_oscode` and `default_mappings` functions in
https://github.com/jtroo/kanata/blob/main/parser/src/keys/mod.rs[the source].
Please feel welcome to file an issue
if you're unable to find the key you're looking for.
An example `defsrc` containing the US QWERTY keyboard keys as an
approximately 60% keyboard layout:
[source]
----
(defsrc
grv 1 2 3 4 5 6 7 8 9 0 - = bspc
tab q w e r t y u i o p [ ] \
caps a s d f g h j k l ; ' ret
lsft z x c v b n m , . / rsft
lctl lmet lalt spc ralt rmet rctl
)
----
Note that some keyboards have a Compose/Menu key instead of a right Meta key.
In this case you can use `comp` instead of `rmet`.
For non-US keyboards, see <<non-us-keyboards,this section>>.
[[deflayer]]
=== deflayer
<<table-of-contents,Back to ToC>>
Your configuration file must have at least one `+deflayer+` entry. This defines
how each physical key mapped in `+defsrc+` behaves when kanata runs.
A `+deflayer+` configuration entry is followed by the layer name then a list of
keys or actions. The usable key names are the same as in defsrc. Actions are
explained further on in this document. The whitespace story is the same as with
`+defsrc+`. The order of keys/actions in `+deflayer+` corresponds to the
physical key in the same sequence position defined in `+defsrc+`.
The first layer defined in your configuration file will be the starting layer
when kanata runs. Other layers can be temporarily activated or switched to
using actions.
An example `defsrc` and `deflayer` that remaps QWERTY to the Dvorak layout
would be:
[source]
----
(defsrc
grv 1 2 3 4 5 6 7 8 9 0 - = bspc
tab q w e r t y u i o p [ ] \
caps a s d f g h j k l ; ' ret
lsft z x c v b n m , . / rsft
lctl lmet lalt spc ralt rmet rctl
)
(deflayer dvorak
grv 1 2 3 4 5 6 7 8 9 0 [ ] bspc
tab ' , . p y f g c r l / = \
caps a o e u i d h t n s - ret
lsft ; q j k x b m w v z rsft
lctl lmet lalt spc ralt rmet rctl
)
----
==== deflayermap
An alternative method for defining a layer exists: `deflayermap`.
This method does not rely on `defsrc`.
The very first item must be the layer name,
but the layer name must be in parentheses unlike before.
The reason for this is for better error messages when forgetting the name.
After the layer name, the layer is configured via triples of items:
* input key
* map string
* output action
An example complete configuration that maps Caps Lock to Escape is:
[source]
----
;; defsrc is still necessary
(defsrc spc)
(deflayermap (base-layer)
caps : esc
)
----
The input key takes the same role as `defsrc` keys.
The output action takes the role that items in the normal `deflayer` have.
Instead of specifying an input key,
you can use either `&#95;`, `&#95;&#95;`, or `&#95;&#95;&#95;` to map all
the keys that are not explicitly mapped in the layer
(`caps` in the example above).
`&#95;` maps only keys that are in defsrc.
`&#95;&#95;` excludes mapping keys that are in defsrc.
`&#95;&#95;&#95;` maps all keys that are not explicitly mapped in the layer.
The map string can be any of the following strings, to your liking:
[source]
----
=
:
->
>>
maps-to
→
🞂
----
[[review-of-required-configuration-entries]]
=== Review of required configuration entries
<<table-of-contents,Back to ToC>>
If you're reading in order, you have now seen all of the required entries:
* `+defsrc+`
* `+deflayer+`
An example minimal configuration is:
[source]
----
(defsrc a b c)
(deflayer start 1 2 3)
----
This will make kanata remap your `a b c` keys to `1 2 3`. This is almost
certainly undesirable but is a valid configuration.
NOTE: Please have a read through link:./platform-known-issues.adoc[the known platform issues]
because they may have implications on what you should include/exclude in `defsrc`.
The Windows LLHOOK I/O mechanism has the most issues by far.
[[non-us-keyboards]]
== Non-US keyboards
<<table-of-contents,Back to ToC>>
For non-US keyboard users, you may have some keys on your keyboard with characters
that are not allowed in `defsrc` by default, at least according to the symbol shown
on the physical keys.
The two sections below can help you understand how to remap all your keys.
=== Browser event.code
Ensure kanata and other key remapping programs are **not** running.
Then you can use https://www.toptal.com/developers/keycode[this link]
and press the key.
The `event.code` field tells you the key name.
Alternatively, you can read through
https://www.w3.org/TR/uievents-code/[this reference].
Due to the lengthy key names,
you may want to use `deflayermap` if remapping using these key names.
WARNING: On Windows, you should use either `kanata_winIOv2.exe`
or Interception when using key names according to the browser `event.code`.
The default `kanata.exe` does not do mappings according to the browser `event.code`
key names.
=== deflocalkeys
You can use `deflocalkeys` to define additional key names that can be
used in `defsrc`, `deflayer` and anywhere else in the configuration.
There are five variants of deflocalkeys:
- `deflocalkeys-win`
- `deflocalkeys-winiov2`
- `deflocalkeys-wintercept`
- `deflocalkeys-linux`
- `deflocalkeys-macos`
Only one of each deflocalkeys-* variant is allowed. The variants that are not
applicable will be ignored, e.g. `deflocalkeys-linux` and `deflocalkeys-wintercept`
are both ignored when using the default Windows kanata binary.
You can find configurations that others have made in
https://github.com/jtroo/kanata/blob/main/docs/locales.adoc[this document].
If you do not see your keyboard there and are not confident in using
the available tools,
please feel welcome to ask for help in a discussion or issue.
Please contribute to the document if you are able!
.Example:
[source]
----
(deflocalkeys-win
ì 187
)
(deflocalkeys-winiov2
ì 187
)
(deflocalkeys-wintercept
ì 187
)
(deflocalkeys-linux
ì 13
)
(deflocalkeys-macos
ì 13
)
(defsrc
grv 1 2 3 4 5 6 7 8 9 0 - ì bspc
)
----
The number used for a custom key represents the converted value for an OsCode in
base 10. This differs between Windows-hooks, Windows-interception, and Linux.
In Linux, `evtest` will give the correct number for the physical key you press.
In Windows using the default hook mechanism, the non-interception version of the
keyboard tester in the kanata repository will give the correct number
in the `code: <number>` section.
(https://github.com/jtroo/kanata/releases/tag/win-keycode-tester-v0.3.0[prebuilt binary])
In Windows uning `winIOv2`, the winIOv2 executable variant
will give the correct number in the `code: <number>` section.
In Windows using Interception, the interception version of the keyboard tester
will give the correct number i the `num: <number>` section.
Between the hook and interception versions, some
keys may agree but others may not; do be aware that they are **not** compatible!
However, Interception and winIOv2 should generally agree with each other.
Ideas for improving the user-friendliness of this system are welcome! As
mentioned before, please ask for help in an issue or discussion if needed, and
help with https://github.com/jtroo/kanata/blob/main/docs/locales.adoc[this document]
is very welcome so that future users can have an easier time 🙂.
[[introduction-defcfg]]
== Introduction to defcfg
<<table-of-contents,Back to ToC>>
Your configuration file may include a single `defcfg` entry.
The `defcfg` can be empty or omitted.
There are options that change kanata's behaviour,
but this introduction will introduce
only the most prevalent entry: `process-unmapped-keys`.
All other options can be found later in the <<optional-defcfg-options>> section.
.Example of an empty defcfg:
[source]
----
(defcfg)
----
[[process-unmapped-keys]]
=== process-unmapped-keys
<<table-of-contents,Back to ToC>>
The `process-unmapped-keys` option in `defcfg` is probably the most
generally impactful option.
Enabling this configuration makes kanata process keys
that are not defined in `defsrc`.
This might be useful
if you are only mapping a few keys in defsrc
instead of most of the keys on your keyboard.
Without this, some actions like `+rpt+`, `+tap-hold-release+`, `+one-shot+`,
will not work correctly for subsequent key presses that are not in defsrc.
This option is disabled by default.
The reason this is not enabled by default is
because some keys may not work correctly if they are intercepted.
For example, see <<windows-only-windows-altgr>>.
.Example:
[source]
----
(defcfg
process-unmapped-keys yes
)
----
== Aliases and variables[[aliases-and-vars]]
<<table-of-contents,Back to ToC>>
Before learning about actions,
it will be useful to first learn about aliases and variables.
[[aliases]]
=== Aliases
<<table-of-contents,Back to ToC>>
Using the `defalias` configuration entry, you can introduce a shortcut label
for an action.
The `defalias` entry reads pairs of items in a sequence
where the first item in the pair is the alias name and the second item is the
action it can be substituted for.
A list is a sequence of strings
or nested lists separated by whitespace,
surrounded by parentheses.
All of the configuration entries we've looked at so far are lists;
`defalias` is where we'll first see nested lists in this guide.
.Example:
[source]
----
(defalias
;; tap for caps lock, hold for left control
cap (tap-hold 200 200 caps lctl)
)
----
This alias can be used in `deflayer` as a substitute for the long action. The
alias name is prefixed with `@` to signify that it's an alias as opposed to a
normal key.
[source]
----
(deflayer example
@cap a s d f
)
----
You may have multiple `defalias` entries and multiple aliases within a single
`defalias`. Aliases may also refer to other aliases that were defined earlier
in the configuration file.
.Example:
[source]
----
(defalias one (tap-hold 200 200 caps lctl))
(defalias two (tap-hold 200 200 esc lctl))
(defalias
three C-A-del ;; Ctrl+Alt+Del
four (tap-hold 200 200 @three ralt)
)
----
You can choose to put actions without aliasing them right into `deflayer`.
However, for long actions it is recommended not to do so to keep a nice visual
alignment. Visually aligning your `deflayer` entries will hopefully make your
configuration file easier to read.
.Example:
[source]
----
(deflayer example
;; this is equivalent to the previous deflayer example
(tap-hold 200 200 caps lctl) a s d f
)
----
[[variables]]
=== Variables
<<table-of-contents,Back to ToC>>
Using the `defvar` configuration entry,
you can introduce a shortcut label for an arbitrary string or list.
Unlike an alias, a variable does not need to be a valid standalone action.
In other words,
a variable can be used as components of actions.
The most common use case is to define common number strings
for actions such as `tap-hold`, `tap-dance`, and `one-shot`.
Similar to how `defalias` works,
`defvar` reads pairs of items in a sequence
where the first item in the pair is the variable name
and the second item is a string or list.
Variables are allowed to refer to previously defined variables.
Variables can be used to substitute most values.
Some notable exceptions are:
- variables cannot be used in `defcfg`, `defsrc`, or `deflocalkeys`
- variables cannot be used to substitute a layer name
- variables cannot be used to substitute an action name
Variables are referred to by prefixing their name with `$`.
.Example:
[source]
----
(defvar
tap-timeout 100
hold-timeout 200
tt $tap-timeout
ht $hold-timeout
)
(defalias
th1 (tap-hold $tt $ht caps lctl)
th2 (tap-hold $tt $ht spc lsft)
)
----
[[concat-in-defvar]]
==== concat in defvar
Within the second item of `defvar`,
a list that begins with the special keyword `concat` will concatenate all
subsequent items in the list together into a single string value.
Without using `concat`, lists are saved as-is.
.Example:
[source]
----
(defvar
rootpath "/home/myuser/mysubdir"
;; $otherpath will be the string: /home/myuser/mysubdir/helloworld
otherpath (concat $rootpath "/helloworld")
)
----
[[actions]]
== Actions
The actions kanata provides are what make it truly customizable.
This section explains the available actions.
[[live-reload]]
=== Live reload
<<table-of-contents,Back to ToC>>
You can put the `+lrld+` action onto a key to live reload your configuration file.
If kanata can't parse the file,
the previous configuration will continue to be used.
When live reload is activated,
the active kanata layer will be the first `deflayer` defined in the configuration.
NOTE: live reload does not read or apply changes to device-related configurations,
such as `linux-dev`, `macos-dev-names-include`,
or `windows-only-windows-interception-keyboard-hwids`.
.Example:
[source]
----
(deflayer has-live-reload
lrld a s d f
)
----
There are variants of `lrld`: `lrld-prev` and `lrld-next`. These will cycle
through different configuration files that you specify on kanata's startup.
The first configuration file specified will be the one loaded on startup.
The prev/next variants can be used with shortened names of `lrpv` and `lrnx` as
well.
Another variant is the list action `lrld-num`.
This reloads the configuration file specified by the number,
according to the order that the configuration file arguments
are passed into kanata's startup command.
.Example:
[source]
----
(deflayer has-live-reloads
lrld lrpv lrnx (lrld-num 3)
)
----
Example specifying multiple config files in the command line:
[source]
----
kanata -c startup.cfg -c 2nd.cfg -c 3rd.cfg
----
Given the above startup command,
activating `(lrld-num 2)` would reload the `2nd.cfg` file.
[[layer-switch]]
=== layer-switch
<<table-of-contents,Back to ToC>>
This action allows you to switch to another "base" layer. This is permanent
until a `layer-switch` to another layer is activated. The concept of a base
layer makes more sense when looking at the next action: `layer-while-held`.
This action accepts a single subsequent string which must be a layer name
defined in a `deflayer` entry.
.Example:
[source]
----
(defalias dvk (layer-switch dvorak))
----
[[layer-while-held]]
=== layer-while-held
<<table-of-contents,Back to ToC>>
This action allows you to temporarily change to another layer while the key
remains held. When the key is released, you go back to the currently active
"base" layer.
This action accepts a single subsequent string which must be a layer name
defined in a `deflayer` entry.
.Example:
[source]
----
(defalias nav (layer-while-held navigation))
----
You may also use `layer-toggle` in place of `layer-while-held`; they behave
exactly the same. The `layer-toggle` name is slightly shorter but is a bit
inaccurate with regards to its meaning.
[[transparent-key]]
=== Transparent key
<<table-of-contents,Back to ToC>>
If you use a single underscore for a key `+_+` then it acts as a "transparent"
key in a `+deflayer+`. The behaviour depends if `+_+` is on a base layer or a
while-held layer. When `+_+` is pressed on the active base layer, the key will
default to the corresponding `defsrc` key. If `+_+` is pressed on the active
while-held layer, the base layer's behaviour will activate.
(alternatively you can use `+‗+` `+≝+`)
.Example:
[source]
----
(defsrc
a b c d
)
(deflayer remap-only-c-to-d
_ ‗ d ≝
)
----
[[no-op]]
=== No-op
<<table-of-contents,Back to ToC>>
You may use the action `+XX+` as a "no operation" key, meaning pressing the key
will do nothing. This might be desirable in place of a transparent key on a
layer that is not fully mapped so that a key that is intentionally not mapped
will do nothing as opposed to typing a letter.
(alternatively you can use `+✗+` `+∅+` `+•+`)
.Example:
[source]
----
(deflayer contains-no-op
XX ✗ • f
)
----
[[unicode]]
=== Unicode
<<table-of-contents,Back to ToC>>
The `+unicode+` (or `+🔣+`) action accepts a single unicode character (but not
a composed character, so 🤲, but not 🤲🏿). The character will not be repeatedly
typed if you hold the key down.
You may use a unicode character as an alias if desired or in its simplified form `+🔣😀+`
(vs the usual `+(🔣 😀)+`).
NOTE: The unicode action may not be correctly accepted by the active
application.
NOTE: If using Linux, make sure to look at the
<<linux-only-linux-unicode-u-code,unicode behaviour customization>> in defcfg.
[source]
----
(defalias
sml (unicode 😀)
😀 (🔣 😀)
🙁 (unicode 🙁)
)
(deflayer has-happy-sad
@sml @🙁 @😀 🔣😀 d f
)
----
[[output-chordscombos]]
=== Output chords/combos
<<table-of-contents,Back to ToC>>
You may want to remap a key to automatically be pressed in combination with
modifiers such as Control or Shift. You can achieve this by prefixing the
normal key name with one or more of:
* `+C-+`: Left Control (also `+‹⎈+` `+‹⌃+` or without the `+‹+` side indicator)
* `+RC-+`: Right Control (also `+⎈›+` `+⌃›+`)
* `+A-+`: Left Alt (also `+‹⎇+` `+‹⌥+` or without the `+‹+` side indicator))
* `+RA-+`: Right Alt, a.k.a. AltGr (also `+AG+` `+⎇›+` `+⌥›+`)
* `+S-+`: Left Shift (also `+‹⇧+` or without the `+‹+` side indicator))
* `+RS-+`: Right Shift (also `+⇧›+`)
* `+M-+`: Left Meta, a.k.a. Windows, GUI, Command, Super (also `+‹⌘+` `+‹❖+` `+‹◆+` or without the `+‹+` side indicator))
* `+RM-+`: Right Meta (also `+⌘›+` `+❖›+` `+◆›+`)
These modifiers may be combined together if desired.
NOTE: A special behaviour of output chords is that if another key is pressed,
all of the chord keys will be released
before the newly pressed key action activates.
The modifier keys are often not desired for subsequent actions
and without this behaviour,
rapid typing can result in undesired modified key presses.
If you want keys to remain pressed, use <<multi>> instead.
Output chords are typically used do one-off actions such as:
- type a symbol, e.g. `S-1`
- type a special/accented character, e.g. `RA-a`
- do a special action like `C-c` to send `SIGTERM` in the terminal
.Example:
[source]
----
(defalias
;; Type exclamation mark (US layout)
ex! S-1
;; Ctrl+C: send SIGINT to a Linux terminal program
int C-c
;; Win+Tab: open Windows' Task View
tsk M-tab
;; Ctrl+Shift+(C|V): copy or paste from certain terminal programs
cpy C-S-c
pst C-S-v
)
----
[[repeat-key]]
=== Repeat key
<<table-of-contents,Back to ToC>>
The action `+rpt+` repeats the most recently typed key. Holding down this key
will not repeatedly send the key. The intended use case is to be able to use a
different finger or even thumb key to repeat a typed key, as opposed to
double-tapping a key.
.Example:
[source]
----
(deflayer has-repeat
rpt a s d f
)
----
The `rpt` action only repeats the last key output.
For example, it won't output a chord like `ctrl+c`
if the previous key pressed was `C-c`.
The `rpt` action will only output `c` in this case.
There is a variant `rpt-any`
which will repeat any previous action
and would output `ctrl+c` in the example case.
----
(deflayer has-repeat-any
rpt-any a s d f
)
----
[[release-a-key-or-layer]]
=== Release a key or layer
<<table-of-contents,Back to ToC>>
You can release a held key or layer via these actions:
* `release-key`: release a key, accepts `defsrc` compatible names
* `release-layer`: release a while-held layer
NOTE:
A lower-level detail of these actions is that they operate on output states
as opposed to virtually releasing an input key.
This does have some practical significance but for the most part it is not important.
An example practical use case for `release-key` is seen in the `multi` section
directly below.
There is currently no known practical use case for
`release-layer`, but it exists nonetheless.
[[multi]]
=== multi
<<table-of-contents,Back to ToC>>
The `+multi+` action executes multiple keys or actions in order but also
simultaneously. It accepts one or more actions.
An example use case is to press the "Alt" key while also activating another
layer.
In the example below, holding the physical "Alt" key will result in a held
layer being activated while also holding "Alt" itself. The held layer operates
nearly the same as the standard keyboard, so for example the sequence (hold
Alt)+(Tab+Tab+Tab) will work as expected. This is in contrast to having a layer
where `tab` is mapped to `A-tab`, which results in repeated press+release of
the two keys and has different behaviour than expected. Some special keys will
release the "Alt" key and do some other action that requires "Alt" to be
released. In other words, the "Alt" key serves a dual purpose of still
fulfilling the "Alt" key role for some button presses (e.g. Tab), but also as a
new layer for keys that aren't typically used with "Alt" to have added useful
functionality.
[source]
----
(defalias
atl (multi alt (layer-while-held alted-with-exceptions))
lft (multi (release-key alt) left) ;; release alt if held and also press left
rgt (multi (release-key alt) rght) ;; release alt if held and also press rght
)
(defsrc
alt a s d f
)
(deflayer base
@atl _ _ _ _
)
(deflayer alted-with-exceptions
_ _ _ @lft @rgt
)
----
WARNING: This action can sometimes behave in surprising ways
with regards to simultaneity and order of actions.
For example, an action like `(multi sldr ')` will not behave as expected.
Due to implementation details, `sldr` will activate after the `'`
even though it is listed before.
This example could instead be written as `(macro sldr 10 ')`,
and that would work as intended.
It is recommended to avoid `multi` if it can be replaced
with a different action like `macro` or an output chord.
[[mouse-actions]]
=== Mouse actions
<<table-of-contents,Back to ToC>>
You can click the left, middle, and right buttons using kanata actions, do
vertical/horizontal scrolling, and move the mouse.
[[mouse-buttons]]
==== Mouse buttons
<<table-of-contents,Back to ToC>>
The mouse button actions are:
* `mlft`: left mouse button
* `mmid`: middle mouse button
* `mrgt`: right mouse button
* `mfwd`: forward mouse button
* `mbck`: backward mouse button
The mouse button will be held while the key mapped to it is held.
Using Linux and Windows-Interception,
the above actions are also usable in `defsrc`
to enable remapping specified mouse actions in your layers,
like you would with keyboard keys.
If there are multiple mouse click actions within a single multi action, e.g.
`+(multi mrgt mlft)+`
then all the buttons except the last will be clicked then unclicked. The last
button will remain held until key release. In the example above, pressing then
releasing the key mapped to this action will result in the following event
sequence:
. press key mapped to `+multi+`
. click right mouse button
. unclick right mouse button
. click left mouse button
. release key mapped to `+multi+`
. release left mouse button
There are variants of the standard mouse buttons which "tap" the button. Rather
than holding the button while the key is held, a mouse click will be
immediately followed by the release. Nothing happens when the key is released.
The actions are as follows:
* `mltp`: tap left mouse button
* `mmtp`: tap middle mouse button
* `mrtp`: tap right mouse button
* `mftp`: tap forward mouse button
* `mbtp`: tap bacward mouse button
[[mouse-wheel]]
==== Mouse wheel
<<table-of-contents,Back to ToC>>
The mouse wheel actions are:
* `mwheel-up`: vertical scroll up
* `mwheel-down`: vertical scroll down
* `mwheel-left`: horizontal scroll left
* `mwheel-right`: horizontal scroll right
All of these actions accept two number strings. The first is the interval
(unit: ms) between scroll actions. The second number is the distance
(unit: arbitrary). In both Windows and Linux, 120 distance units is equivalent
to a notch movement on a physical wheel. You can play with the parameters to
see what feels correct to you. Both numbers must be in the range [1,65535].
NOTE: In Linux, not all desktop environments support the `REL_WHEEL_HI_RES` event.
If this is the case for yours,
it will likely be a better experience to use a distance value that is a multiple of 120.
On Linux and Interception, you can also choose to read from a mouse device.
When doing so, using the `mwu`, `mwd`, `mwl`, `mwr` key names in `defsrc`
allow you to remap the mouse scroll up/down/left/right actions like you would
with keyboard keys.
NOTE: If you are using a high-resolution mouse in Linux,
only a full "notch" of the scroll wheel will activate the action.
NOTE: If you are using a high-resolution mouse with Interception,
you will probably get way more events than you intended.
[[mouse-movement]]
==== Mouse movement
<<table-of-contents,Back to ToC>>
The mouse movement actions are:
* `movemouse-up`
* `movemouse-down`
* `movemouse-left`
* `movemouse-right`
Similar to the mouse wheel actions, all of these actions accept two number strings.
The first is the interval (unit: ms) between movement actions and the second number
is the distance (unit: pixels) of each movement.
The following are variants of the above mouse movements that apply linear mouse
acceleration from the minimum distance to the maximum distance as the mapped key is held.
* `movemouse-accel-up`
* `movemouse-accel-down`
* `movemouse-accel-left`
* `movemouse-accel-right`
All these actions accept four number strings. The first number is the
interval (unit: ms) between movement actions. The second number is the time it
takes (unit: ms) to linearly ramp up from the minimum distance to the maximum
distance. The third and fourth numbers are the minimum and maximum distances
(unit: pixels) of each movement.
There is a toggable defcfg option related to `movemouse-accel` - <<movemouse-inherit-accel-state>>. You might want to enable it, especially if you're coming from QMK.
[[set-mouse]]
==== Set absolute mouse position
<<table-of-contents,Back to ToC>>
The action `setmouse` sets the absolute mouse position.
WARNING: This is only supported in Windows right now.
For an interesting keyboard-centric mouse solution in Linux,
try looking at
https://github.com/rvaiya/warpd[warpd].
This list action takes two parameters which are `x` and `y` positions
of the absolute movement.
The values go from 0,0 which is the upper-left corner of the screen
to 65535,65535 which is the lower-right corner of the screen.
If you have multiple monitors,
`setmouse` treats them all as a single large screen.
This can make it a little confusing for how to set the `x, y` values
to get the positions that you want.
Experimentation will be needed.
[[mouse-speed]]
==== Modify the speed of mouse movements
<<table-of-contents,Back to ToC>>
The action `movemouse-speed` modifies the speed at which `movemouse` and
`movemouse-accel` function at runtime. It does this by expanding or shrinking
`min_distance` and `max_distance` while the action key is pressed.
This action accepts one number (unit: percentage) by which the
mouse movements will be accelerated.
WARNING: Due to the nature of pixels being whole numbers, some values such as
33 may not result in an exact third of the distance.
.Example:
[source]
----
(defalias
fst (movemouse-speed 200)
slw (movemouse-speed 50)
)
----
[[mouse-all-actions-example]]
==== Mouse all actions example
<<table-of-contents,Back to ToC>>
[source]
----
(defalias
mwu (mwheel-up 50 120)
mwd (mwheel-down 50 120)
mwl (mwheel-left 50 120)
mwr (mwheel-right 50 120)
ms↑ (movemouse-up 1 1)
ms← (movemouse-left 1 1)
ms↓ (movemouse-down 1 1)
ms→ (movemouse-right 1 1)
ma↑ (movemouse-accel-up 1 1000 1 5)
ma← (movemouse-accel-left 1 1000 1 5)
ma↓ (movemouse-accel-down 1 1000 1 5)
ma→ (movemouse-accel-right 1 1000 1 5)
sm (setmouse 32228 32228)
fst (movemouse-speed 200)
)
(deflayer mouse
_ @mwu @mwd @mwl @mwr _ _ _ _ _ @ma↑ _ _ _
_ pgup bck _ fwd _ _ _ _ @ma← @ma↓ @ma→ _ _
_ pgdn mlft _ mrgt mmid _ mbck mfwd _ @ms↑ _ _
@fst _ mltp _ mrtp mmtp _ mbtp mftp @ms← @ms↓ @ms→
_ _ _ _ _ _ _
)
----
[[tap-dance]]
=== tap-dance
<<table-of-contents,Back to ToC>>
The `+tap-dance+` action allows repeated tapping of a key to result in
different actions. It is followed by a timeout (unit: ms) and a list
of keys or actions. Each time the key is pressed, its timeout will reset. The
action will be chosen if one of the following events occur:
* the timeout expires
* a different key is pressed
* the key is repeated up to the final action
You may put normal keys or other actions in `+tap-dance+`.
.Example:
[source]
----
(defalias
;; 1 tap : "A" key
;; 2 taps: Control+C
;; 3 taps: Switch to another layer
;; 4 taps: Escape key
td (tap-dance 200 (a C-c (layer-switch l2) esc))
)
----
There is a variant of `tap-dance` with the name `tap-dance-eager`. The variant
is parsed identically but the difference is that it will activate every
action in the sequence as the taps progress.
In the example below, repeated taps will, in order:
1. type `a`
2. erase the `a` and type `bb`
3. erase the `bb` and type `ccc`
[source]
----
(defalias
td2 (tap-dance-eager 500 (
(macro a) ;; use macro to prevent auto-repeat of the key
(macro bspc b b)
(macro bspc bspc c c c)
))
)
----
[[one-shot]]
=== one-shot
<<table-of-contents,Back to ToC>>
The `+one-shot+` action is similar to "sticky keys", if you know what that is.
This activates an action or key until either the timeout expires or a different
key is used. The `+one-shot+` action must be followed by a timeout (unit:
ms) and another key or action.
Some of the intended use cases are:
* press a modifier for exactly one following key press
* switch to another layer for exactly one following key press
If a `+one-shot+` key is held then it will act as the regular key. E.g. holding
a key assigned with `+@os1+` in the example below will keep Left Shift held for
every key, not just one, as long as it's still physically pressed.
Pressing multiple `+one-shot+` keys in a row within the timeout will combine
the actions of those keys and reset the timeout to the value of the most
recently pressed `+one-shot+` key.
There are four variants of the `+one-shot+` action:
- `+one-shot-press+`:
end on the first press of another key
- `+one-shot-release+`:
end on the first release of another key
- `+one-shot-press-pcancel+`:
end on the first press of another key
or on re-press of another active one-shot key
- `+one-shot-release-pcancel+`:
end on the first release of another key
or on re-press of another active one-shot key
It is important to note that the first activation of a one-shot key
determines the behaviour with regards to the 4 variants
for all subsequent one-shot key activations,
even if a following one-shot key has a different configuration
than the initial key pressed.
The default name `+one-shot+` corresponds to `+one-shot-press+`.
.Example:
[source]
----
(defalias
os1 (one-shot 500 (layer-while-held another-layer))
os2 (one-shot-press 2000 lsft)
os3 (one-shot-release 2000 lctl)
os4 (one-shot-press-pcancel 2000 lalt)
os5 (one-shot-release-pcancel 2000 lmet)
)
----
[[tap-hold]]
=== tap-hold
<<table-of-contents,Back to ToC>>
WARNING: The `tap-hold` action and all variants can behave unexpectedly on Linux
with respect to repeat of antecedent key presses.
The full context is in https://github.com/jtroo/kanata/discussions/422[discussion #422].
In brief, the workaround is to use `tap-hold` inside of <<multi,multi>>,
combined with another key action that behaves as a no-op like `f24`. +
Example: `(multi f24 (tap-hold ...))`
The `+tap-hold+` action allows you to have one action/key for a "tap" and a
different action/key for a "hold". A tap is a rapid press then release of the
key whereas a hold is a long press.
The action takes 4 parameters in the listed order:
. tap timeout (unit: ms)
. hold timeout (unit: ms)
. tap action
. hold action
The tap timeout is the number of milliseconds within which a rapid
press+release+press of a key will result in the tap action being held instead
of the hold action activating.
.Tap timeout in more detail
[%collapsible,indent=4]
====
The way a `tap-hold` action works with respect to the tap timeout
is often unclear to newcomers.
To make it concrete, the output event sequence of the `tap-hold` action
`(tap-hold $tap-timeout 200 a lctl)`
for varying values of `$tap-timeout`
with a fixed input event sequence will be described.
The input event sequence is:
- press
- 50 ms elapses
- release
- 50 ms elapses
- press
- 300 ms elapses
- release
With `(defvar $tap-timeout 0)`, the output event sequence is:
- 50 ms elapses
- press `a`
- release `a`
- 250 ms elapses
- press `lctl`
- 100 ms elapses
- release `lctl`
The above output sequence is the same for all `$tap-timeout` values
between and including `0` and `99`.
For a value of `100` or greater for `$tap-timeout`,
the output event sequence is instead:
- 50 ms elapses
- press `a`
- release `a`
- 50 ms elapses
- press `a`
- 300 ms elapses
- release `a`
====
The hold timeout is the number of milliseconds after which the hold action will
activate.
There are two additional variants of `+tap-hold+`:
* `+tap-hold-press+`
** If there is a press of a different key, the hold action is activated even if
the hold timeout hasn't expired yet
* `+tap-hold-release+`
** If there is a press+release of a different key, the hold action is activated
even if the hold timeout hasn't expired yet
These variants may be useful if you want more responsive tap-hold keys,
but you should be wary of activating the hold action unintentionally.
.Example:
[source]
----
(defalias
anm (tap-hold 200 200 a @num) ;; tap: a hold: numbers layer
oar (tap-hold-press 200 200 o @arr) ;; tap: o hold: arrows layer
ech (tap-hold-release 200 200 e @chr) ;; tap: e hold: chords layer
)
----
There are further additional variants of `tap-hold-press` and `tap-hold-release`:
- `tap-hold-press-timeout`
- `tap-hold-release-timeout`
These variants take a 5th parameter, in addition to the same 4 as the other
variants. The 5th parameter is another action, which will activate if the hold
timeout expires as opposed to being triggered by other key actions, whereas the
non `-timeout` variants will activate the hold action in both cases.
- `tap-hold-release-keys`
This variant takes a 5th parameter which is a list of keys
that trigger an early tap
when they are pressed while the `tap-hold-release-keys` action is waiting.
Otherwise this behaves as `tap-hold-release`.
The keys in the 5th parameter correspond to the physical input keys,
or in other words the key that corresponds to `defsrc`.
This is in contrast to the `fork` and `switch` actions
which operates on outputted keys, or in other words the outputs
that are in `deflayer`, `defalias`, etc. for the corresponding `defsrc` key.
.Example:
[source]
----
(defalias
;; tap: o hold: arrows layer timeout: backspace
oat (tap-hold-press-timeout 200 200 o @arr bspc)
;; tap: e hold: chords layer timeout: esc
ect (tap-hold-release-timeout 200 200 e @chr esc)
;; tap: u hold: misc layer early tap if any of: (a o e) are pressed
umk (tap-hold-release-keys 200 200 u @msc (a o e))
)
----
- `tap-hold-except-keys`
This variant takes a 5th parameter which is a list of keys
that always trigger a tap
when they are pressed while the `tap-hold-except-keys` action is waiting.
No key is ever output until there is either a release of the key or any other
key is pressed. This differs from `tap-hold` behaviour.
The keys in the 5th parameter correspond to the physical input keys,
or in other words the key that corresponds to `defsrc`.
This is in contrast to the `fork` and `switch` actions
which operates on outputted keys, or in other words the outputs
that are in `deflayer`, `defalias`, etc. for the corresponding `defsrc` key.
.Example:
[source]
----
(defalias
;; tap: o hold: arrows layer timeout: backspace
oat (tap-hold-press-timeout 200 200 o @arr bspc)
;; tap: e hold: chords layer timeout: esc
ect (tap-hold-release-timeout 200 200 e @chr esc)
;; tap: u hold: misc layer always tap if any of: (a o e) are pressed
umk (tap-hold-except-keys 200 200 u @msc (a o e))
)
----
[[macro]]
=== macro
<<table-of-contents,Back to ToC>>
The `+macro+` action will tap a sequence of keys with optional
delays. This is different from `+multi+` because in the `+multi+` action,
all keys are held, whereas in `+macro+`, keys are pressed then released.
This means that with `+macro+` you can have some letters capitalized and others
not. This is not possible with `+multi+`.
The `+macro+` action accepts one or more keys, some actions, chords, and delays
(unit: ms). It also accepts a list prefixed with <<output-chordscombos,output chord>>
modifiers where the list is subject to the aforementioned restrictions. The
number keys will be parsed as delays, so they must be aliased to be used in a macro.
Up to 4 macros can be active at the same time.
The actions supported in `+macro+` are:
* <<cmd, cmd>>
* <<unicode, unicode>>
* <<mouse-actions,mouse actions>>
* <<repeat-key,repeat>>
* <<live-reload,live reload>>
* <<fake-keys,virtual keys/fake keys>>
* <<sequences,sequence leader>>
* <<arbitrary-code,arbitrary keycode>>
* <<dynamic-macro,dynamic macro>>
* <<unmod,unmod>>
NOTE: Some of these actions may need short delays between.
For example, `(macro a (unmod b) 5 (unmod c) d))`
needs the delay of `5` to work correctly.
.Example:
[source]
----
(defalias
: S-;
8 8
0 0
🙃 (unicode 🙃)
;; Type "http://localhost:8080"
lch (macro h t t p @: / / 100 l o c a l h o s t @: @8 @0 @8 @0)
;; Type "I am HAPPY my FrIeNd 🙃"
hpy (macro S-i spc a m spc S-(h a p p y) spc m y S-f r S-i e S-n d spc @🙃)
;; alt-tab(x3) and alt-shift-tab(x3) with macro
tfd (macro A-(tab 200 tab 200 tab))
tbk (macro A-S-(tab 200 tab 200 tab))
)
----
There is a variant of the `+macro+` action that will cancel all active macros
upon releasing the key: `+macro-release-cancel+`. It is parsed identically to
the non-cancelling version. An example use case for this action is holding down
a key to get different outputs, similar to tap-dance but one can see which keys
are being outputted.
E.g. in the example below, when holding the key, first `1` is typed, then
replaced by `!` after 500ms, and finally that is replaced by `@` after another
500ms. However, if the key is released, the last character typed will remain
and the rest of the macro does not run.
[source]
----
(defalias
1 1
;; macro-release-cancel to output different characters with visual feedback
;; after holding for different amounts of time.
1!@ (macro-release-cancel @1 500 bspc S-1 500 bspc S-2)
)
----
There are further variants of the two `macro` actions which repeat while held.
The repeat will only occur once all macros have completed,
including the held macro key.
If multiple repeating macros are being held simulaneously,
only the most recently pressed macro will be repeated.
[source]
----
(defalias
mr1 (macro-repeat mltp)
mr2 (macro-repeat-release-cancel mltp)
)
----
[[dynamic-macro]]
=== dynamic-macro
<<table-of-contents,Back to ToC>>
The dynamic-macro actions allow for recording and playing key presses. The
dynamic macro records physical key presses, as opposed to kanata's outputs.
This allows the dynamic macro to replicate any action, but it means that if
the macro starts and ends on different layers, then the macro might not be
properly repeatable.
The action `dynamic-macro-record` accepts one number (0-65535), which represents
the macro ID. Activating this action will begin recording physical key inputs.
If `dynamic-macro-record` with the same ID is pressed again, the recording will
end and be saved. If `dynamic-macro-record` with a different ID is pressed then
the current recording will end and be saved, then a new recording with the new
ID will begin.
The action `dynamic-macro-record-stop` will stop and save any active recording.
There is a variant of this:
`dynamic-macro-record-stop-truncate`
This is a list action that takes a single parameter:
the number of key actions to remove at the end of a dynamic macro.
This variant is useful if the macro stop button is on a different layer.
The action `dynamic-macro-play` accepts one number (0-65535), which represents
the macro ID. Activating this action will play the saved recording of physical
keys from a previous `dynamic-macro-record` with the same macro ID, if it exists.
One can nest dynamic macros within each other, e.g. activate
`(dynamic-macro-play 1)` while recording with `(dynamic-macro-record 0)`.
However, dynamic macros cannot recurse; e.g. activating `(dynamic-macro-play 0)`
while recording with `(dynamic-macro-record 0)` will be ignored.
.Example:
[source]
----
(defalias
dr0 (dynamic-macro-record 0)
dr1 (dynamic-macro-record 1)
dr2 (dynamic-macro-record 2)
dp0 (dynamic-macro-play 0)
dp1 (dynamic-macro-play 1)
dp2 (dynamic-macro-play 2)
dms dynamic-macro-record-stop
dst (dynamic-macro-record-stop-truncate 1)
)
----
[[fork]]
=== fork
<<table-of-contents,Back to ToC>>
The fork action accepts two actions and a key list.
The first (left) action will activate by default.
The second (right) action will activate
if any of the keys in the third parameter (right-trigger-keys) are currently active.
.Example:
[source]
----
(defalias
frk (fork k @special (lalt ralt))
)
----
[[caps-word]]
=== caps-word
<<table-of-contents,Back to ToC>>
The `caps-word` action triggers a state where the `lsft` key
will be added to the active key list
when a set of specific keys are active.
The keys are: `a-z` and `-`, which will be outputted as `A-Z` and `_`
respectively when using the US layout.
Examples where this is helpful
is capitalizing a single important word
like in `IMPORTANT!`
or defining a constant in code
like `const P99_99_VALUE: ...`.
This has an advantage over the regular caps lock
because it automatically ends
so it doesn't need to be toggled off manually,
and it also shifts `-` to `_`
which caps lock does not do.
The `caps-word` state ends when the keyboard is idle
for the duration of the defined timeout (1st parameter),
or a terminating key is pressed.
Every key is a terminating key
except the keys which get capitalized
and the extra keys in this list:
- `0-9`
- `kp0-kp9`
- `bspc del`
- `up down left rght`
You can use `caps-word-custom` instead of `caps-word`
if you want to manually define which keys are capitalized (2nd parameter)
and what the extra non-terminal+non-capitalized keys should be (3rd parameter).
[source]
----
(defalias
cw (caps-word 2000)
;; This example is similar to the default caps-word behaviour but it moves the
;; 0-9 keys to the capitalized key list from the extra non-terminating key list.
cwc (caps-word-custom
2000
(a b c d e f g h i j k l m n o p q r s t u v w x y z 0 1 2 3 4 5 6 7 8 9)
(kp0 kp1 kp2 kp3 kp4 kp5 kp6 kp7 kp8 kp9 bspc del up down left rght)
)
)
----
=== unmod[[unmod]]
<<table-of-contents,Back to ToC>>
The `unmod` action will release all modifiers temporarily
and send one or more keys.
After the `unmod` key is released, the released modifiers are pressed again.
The modifiers affected are: `lsft,rsft,lctl,rctl,lmet,rmet,lalt,ralt`.
A variant of `unmod` is `unshift`.
This action only releases the `lsft,rsft` keys.
This can be useful for forcing unshifted keys while AltGr is still held.
.Example:
[source]
----
(defalias
;; holding shift and tapping a @um1 key will still output 1.
um1 (unmod 1)
;; dead keys é (as opposed to using AltGr) that outputs É when shifted
dké (macro (unmod ') e)
;; In ISO German QWERTZ, force unshifted symbols even if shift is held
{ (unshift ralt 7)
[ (unshift ralt 8)
)
----
[[cmd]]
=== cmd
<<table-of-contents,Back to ToC>>
WARNING: This action does not work unless you use the appropriate binary
or - if compiling yourself - the appropriate feature flag.
Additionally you must add the <<danger-enable-cmd>> `defcfg` option.
The `+cmd+` action executes a program with arguments. It accepts one or more
strings. The first string is the program that will be run and the following
strings are arguments to that program. The arguments are provided to the
program in the order written in the config file.
Lists may also be used within `cmd`
which you may desire to do for reuse via `defvar`.
Lists will be flattened such that arguments are provided to the program
in the order written in the config file, regardless of list nesting.
To be technical, it would be a depth-first flattening (similar to DFS).
NOTE: commands are executed directly and not via a shell, so you cannot make
use of environment variables or symbols with special meaning.
For example `+~+` or `+$HOME+` in Linux will not be
substituted with your home directory.
If you want to execute with a shell program
use the shell as the first parameter, e.g. `bash` or `powershell.exe`.
.Example:
[source]
----
(defalias
cm1 (cmd rm -fr /tmp/testing)
;; You can use bash -c and then a quoted string to execute arbitrary text in
;; bash. All text within double-quotes is treated as a single string.
cm2 (cmd bash -c "echo hello world")
)
----
There is a variant of `cmd`: `cmd-output-keys`. This variant reads the output
of the executed program and reads it as an S-expression, similarly to the
<<macro, macro action>>. However — unlike macro — only keys, chords, and
chorded lists are supported. Delays and other actions are not supported.
[source]
----
(defalias
;; bash: type date-time as YYYY-MM-DD HH:MM
pdb (cmd-output-keys bash -c "date +'%F %R' | sed 's/./& /g' | sed 's/:/S-;/g' | sed 's/\(.\{20\}\)\(.*\)/\(\1 spc \2\)/'")
;; powershell: type date-time as YYYY-MM-DD HH:MM
pdp (cmd-output-keys powershell.exe "echo '(' (((Get-Date -Format 'yyyy-MM-dd HH:mm').toCharArray() -join ' ').insert(20, ' spc ') -replace ':','S-;') ')'")
)
----
[[arbitrary-code]]
=== arbitrary-code
<<table-of-contents,Back to ToC>>
The `arbitrary-code` action allows sending an arbitrary number to kanata's
output mechanism. The press is sent when pressed, and the release sent when
released. This action can be useful for testing keys that are not yet named or
mapped in kanata. Please contribute findings with names and mappings, either in
a GitHub issue or as a pull request!
WARNING: This is not cross platform!
WARNING: When using the Interception driver, this action is still sent over
SendInput.
[source]
----
(defalias
ab1 (arbitrary-code 700)
)
----
[[global-overrides]]
== Global overrides
<<table-of-contents,Back to ToC>>
The `defoverrides` optional configuration item allows you to create global
key overrides, irrespective of what actions are used to generate those keys.
It accepts pairs of lists:
1. the input key list that gets replaced
2. the output key list to replace the input keys with
Both input and output lists accept 0 or more modifier keys (e.g. lctl, rsft)
and exactly 1 non-modifier key (e.g. 1, bspc).
Only zero or one `defoverrides` is allowed in a configuration file.
.Example:
[source]
----
;; Swap numbers and their symbols with respect to shift
(defoverrides
(1) (lsft 1)
(2) (lsft 2)
;; repeat for all remaining numbers
(lsft 1) (1)
(lsft 2) (2)
;; repeat for all remaining numbers
)
----
== Include other files[[include]]
<<table-of-contents,Back to ToC>>
The `include` optional configuration item
allows you to include other files into the configuration.
This configuration accepts a single string which is a file path.
The file path can be an absolute path or a relative path.
The path will be relative to the defined configuration file.
At the time of writing, includes can only be placed at the top level.
The included files also cannot contain includes themselves.
.Example:
----
;; This is in the file initially read by kanata, e.g. kanata.kbd
(include other-file.kbd)
;; This is in the other file
(defalias
included-alias XX
;; ...
)
;; This is in the other file
(deflayer included-layer
;; ...
)
----
[[optional-defcfg-options]]
== defcfg options
[[danger-enable-cmd]]
=== danger-enable-cmd
<<table-of-contents,Back to ToC>>
This option can be used to enable the `cmd` action in your configuration. The
`+cmd+` action allows kanata to execute programs with arguments passed to them.
This requires using a kanata program that is compiled with the `cmd` action
enabled. The reason for this is so that if you choose to, there is no way for
kanata to execute arbitrary programs even if you download some random
configuration from the internet.
This configuration is disabled by default and can be enabled by giving it the
value `yes`.
.Example:
[source]
----
(defcfg
danger-enable-cmd yes
)
----
[[sequence-timeout]]
=== sequence-timeout
<<table-of-contents,Back to ToC>>
This option customizes the key sequence timeout (unit: ms). Its default value
is 1000. The purpose of this item is explained in <<sequences>>.
.Example:
[source]
----
(defcfg
sequence-timeout 2000
)
----
[[sequence-input-mode]]
=== sequence-input-mode
<<table-of-contents,Back to ToC>>
This option customizes the key sequence input mode. Its default value when not
configured is `hidden-suppressed`.
The options are:
- `visible-backspaced`: types sequence characters as they are inputted. The
typed characters will be erased with backspaces for a valid sequence termination.
- `hidden-suppressed`: hides sequence characters as they are typed. Does not
output the hidden characters for an invalid sequence termination.
- `hidden-delay-type`: hides sequence characters as they are typed. Outputs the
hidden characters for an invalid sequence termination either after a
timeout or after a non-sequence key is typed.
For `visible-backspaced` and `hidden-delay-type`, a sequence leader input will
be ignored if a sequence is already active. For historical reasons, and in case
it is desired behaviour, a sequence leader input using `hidden-suppressed` will
reset the key sequence.
See <<sequences>> for more about sequences.
.Example:
[source]
----
(defcfg
sequence-input-mode visible-backspaced
)
----
[[sequence-backtrack-modcancel]]
=== sequence-backtrack-modcancel
<<table-of-contents,Back to ToC>>
This option customizes the behaviour of key sequences
when modifiers are used.
The default is `yes` and can be overridden to `no` if desired.
Setting it to `yes` allows both `fk1` and `fk2` to be activated
in the following configuration, but with `no`,
`fk1` will be impossible to activate
----
(defseq
fk1 (lsft a b)
fk2 (S-(c d))
)
----
See <<sequences>> for more about sequences and
https://github.com/jtroo/kanata/blob/main/docs/sequence-adding-chords-ideas.md[this document]
for more context about this specific configuration.
.Example:
[source]
----
(defcfg
sequence-backtrack-modcancel no
)
----
[[log-layer-changes]]
=== log-layer-changes
<<table-of-contents,Back to ToC>>
By default, kanata will log layer changes. However, logging has some processing
overhead. If you do not care for the logging, you can choose to disable it.
.Example:
[source]
----
(defcfg
log-layer-changes no
)
----
[[delegate-to-first-layer]]
=== delegate-to-first-layer
<<table-of-contents,Back to ToC>>
By default, transparent keys on layers
will delegate to the corresponding defsrc key
when found on a layer activated by `layer-switch`.
This config entry changes the behaviour
to delegate to the action in the same position on the first layer defined
in the configuration, which is the active layer on startup.
For more context, see https://github.com/jtroo/kanata/issues/435.
.Example:
[source]
----
(defcfg
delegate-to-first-layer yes
)
----
[[movemouse-inherit-accel-state]]
=== movemouse-inherit-accel-state
<<table-of-contents,Back to ToC>>
By default `movemouse-accel` actions will track the acceleration
state for vertical and horizontal axes separately.
When this setting is enabled, `movemouse-accel` will behave exactly like mouse movements in https://qmk.fm[QMK],
i.e. the acceleration state of new mouse
movement actions will be inherited if others are already being pressed.
.Example:
[source]
----
(defcfg
movemouse-inherit-accel-state yes
)
----
[[movemouse-smooth-diagonals]]
=== movemouse-smooth-diagonals
<<table-of-contents,Back to ToC>>
By default, mouse movements move one direction at a time
and vertical/horizontal movements are on independent timers.
This can result in non-smooth diagonals when drawing a line in some app.
This option adds a small imperceptible amount of latency to
synchronize the mouse movements.
.Example:
[source]
----
(defcfg
movemouse-smooth-diagonals yes
)
----
=== dynamic-macro-max-presses [[dynamic-macro-max-presses]]
<<table-of-contents,Back to ToC>>
This configuration allows you to customize the length limit on dynamic macros.
The default length limit is 128 keys.
.Example:
[source]
----
(defcfg
dynamic-macro-max-presses 1000
)
----
=== concurrent-tap-hold [[concurrent-tap-hold]]
This configuration makes multiple tap-hold actions
that are activated near in time expire their timeout quicker.
By default this is disabled.
When disabled, the timeout for a following tap-hold
will start from 0ms **after** the previous tap-hold expires.
When enabled, the timeout will start
as soon as the tap-hold action is pressed
even if a previous tap-hold action is still held and has not expired.
.Example:
[source]
----
(defcfg
concurrent-tap-hold yes
)
----
[[block-unmapped-keys]]
=== block-unmapped-keys
<<table-of-contents,Back to ToC>>
If you desire to use only a subset of your keyboard
you can use `block-unmapped-keys` to make every key
other than those that exist in `defsrc` a no-op.
NOTE: this only functions correctly if you also set
<<process-unmapped-keys>> to yes.
.Example:
[source]
----
(defcfg
block-unmapped-keys yes
)
----
[[rapid-event-delay]]
=== rapid-event-delay
<<table-of-contents,Back to ToC>>
This configuration applies to the following events:
* the release of one-shot-press activation
* the release of the tapped key in a tap-hold activation
These events are delayed the defined number of milliseconds (approximate).
The default value is 5.
While the release is delayed, further processing of inputs is also paused.
This means that there will be a minor input latency impact in the mentioned scenarios.
Since 5ms is 1 frame for a 200 Hz refresh rate,
in most scenarios this will not be perceptible.
The reason for this configuration existing is that some environments
do not process the scenarios correctly due to the rapidity of the release.
Kanata does send the events in the correct order,
so the fault is more in the environment,
but kanata provides a workaround anyway.
If you are negatively impacted by the latency increase of these events
and your environment is not impacted by increased rapidity,
you can set reduce the value to a number 0 to 4.
.Example:
[source]
----
(defcfg
;; If your environment is particularly buggy, might need to delay even more
rapid-event-delay 20
)
----
[[linux-only-linux-dev]]
=== Linux only: linux-dev
<<table-of-contents,Back to ToC>>
By default, kanata will try to detect which input devices are keyboards and try
to intercept them all. However, you may specify exact keyboard devices from the
`/dev/input` directories using the `linux-dev` configuration.
.Example:
[source]
----
(defcfg
linux-dev /dev/input/by-path/platform-i8042-serio-0-event-kbd
)
----
If you want to specify multiple keyboards, you can separate the paths with a
colon `+:+`.
.Example:
[source]
----
(defcfg
linux-dev /dev/input/dev1:/dev/input/dev2
)
----
Due to using the colon to separate devices, if you have a device with colons in
its file name, you must escape those colons with backslashes:
[source]
----
(defcfg
linux-dev /dev/input/path-to\:device
)
----
Alternatively, you can use list syntax, where both backslashes and colons
are parsed literally. List items are separated by spaces or newlines.
Using quotation marks for each item is optional, and only required if an
item contains spaces.
[source]
----
(defcfg
linux-dev (
/dev/input/path:to:device
"/dev/input/path to device"
)
)
----
[[linux-only-linux-dev-names-include]]
=== Linux only: linux-dev-names-include
<<table-of-contents,Back to ToC>>
In the case that `linux-dev` is omitted,
this option defines a list of device names that should be included.
Device names that do not exist in the list will be ignored.
This option is parsed identically to `linux-dev`.
Kanata will print device names on startup with log lines that look like below:
----
registering /dev/input/eventX: "Name goes here"
----
.Example:
[source]
----
(defcfg
linux-dev-names-include (
"Device name 1"
"Device name 2"
)
)
----
[[linux-only-linux-dev-names-exclude]]
=== Linux only: linux-dev-names-exclude
<<table-of-contents,Back to ToC>>
In the case that `linux-dev` is omitted,
this option defines a list of device names that should be excluded.
This option is parsed identically to `linux-dev`.
The `linux-dev-names-include` and `linux-dev-names-exclude` options
are not mutually exclusive
but in practice it probably only makes sense to use one and not both.
.Example:
[source]
----
(defcfg
linux-dev-names-exclude (
"Device Name 1"
"Device Name 2"
)
)
----
[[linux-only-linux-continue-if-no-devs-found]]
=== Linux only: linux-continue-if-no-devs-found
<<table-of-contents,Back to ToC>>
By default, kanata will crash if no input devices are found. You can change
this behaviour by setting `linux-continue-if-no-devs-found`.
.Example:
[source]
----
(defcfg
linux-continue-if-no-devs-found yes
)
----
[[linux-only-linux-unicode-u-code]]
=== Linux only: linux-unicode-u-code
<<table-of-contents,Back to ToC>>
Unicode on Linux works by pressing Ctrl+Shift+U, typing the unicode hex value,
then pressing Enter. However, if you do remapping in userspace, e.g. via
xmodmap/xkb, the keycode "U" that kanata outputs may not become a keysym "u"
after the userspace remapping. This will be likely if you use non-US,
non-European keyboards on top of kanata. For unicode to work, kanata needs to
use the keycode that outputs the keysym "u", which might not be the keycode
"U".
You can use `evtest` or `kanata --debug`, set your userspace key remapping,
then press the key that outputs the keysym "u" to see which underlying keycode
is sent. Then you can use this configuration to change kanata's behaviour.
.Example:
[source]
----
(defcfg
linux-unicode-u-code v
)
----
[[linux-only-linux-unicode-termination]]
=== Linux only: linux-unicode-termination
<<table-of-contents,Back to ToC>>
Unicode on Linux terminates with the Enter key by default. This may not work in
some applications. The termination is configurable with the following options:
- `enter`
- `space`
- `enter-space`
- `space-enter`
.Example:
[source]
----
(defcfg
linux-unicode-termination space
)
----
=== Linux only: linux-x11-repeat-delay-rate[[linux-only-x11-repeat-rate]]
<<table-of-contents,Back to ToC>>
On Linux, you can tell kanata to run `xset r rate <delay> <rate>`
on startup and on live reload
via the configuration item `linux-only-x11-repeat-rate`.
This takes two numbers separated by a comma.
The first number is the delay in ms
and the second number is the repeat rate in repeats/second.
This configuration item does not affect Wayland or no-desktop environments.
.Example:
[source]
----
(defcfg
linux-x11-repeat-delay-rate 400,50
)
----
[[macos-only-macos-dev-names-include]]
=== macOS only: macos-dev-names-include
<<table-of-contents,Back to ToC>>
This option defines a list of device names that should be included.
By default, kanata will try to detect which input devices are keyboards and try
to intercept them all. However, you may specify exact keyboard devices to intercept
using the `macos-dev-names-include` configuration.
Device names that do not exist in the list will be ignored.
This option is parsed identically to `linux-dev`.
Use `kanata -l` or `kanata --list` to list the available keyboards.
.Example:
[source]
----
(defcfg
macos-dev-names-include (
"Device name 1"
"Device name 2"
)
)
----
[[windows-only-windows-altgr]]
=== Windows only: windows-altgr
<<table-of-contents,Back to ToC>>
There is an option for Windows to help mitigate the strange behaviour of AltGr
(ralt) if you're using that key in your defsrc. This is applicable for many
non-US layouts. You can use one of the listed values to change what kanata does
with the key:
* `cancel-lctl-press`
** This will remove the `lctl` press that is generated alonside `ralt`
* `add-lctl-release`
** This adds an `lctl` release when `ralt` is released
.Example:
[source]
----
(defcfg
windows-altgr add-lctl-release
)
----
For more context, see: https://github.com/jtroo/kanata/issues/55.
NOTE: Even with these workarounds, putting `+lctl+`+`+ralt+` in your defsrc may not
work properly with other applications that also use keyboard interception.
Known application with issues: GWSL/VcXsrv
=== Windows only: windows-interception-mouse-hwid[[windows-only-windows-interception-mouse-hwid]]
<<table-of-contents,Back to ToC>>
This defcfg item allows you to intercept mouse buttons for a specific mouse device.
This only works with the Interception driver
(the -wintercept variants of the release binaries).
The original use case for this is for laptops such as a Thinkpad,
which have mouse buttons that may be desirable to activate kanata actions with.
To know what numbers to put into the string, you can run the variant with this
defcfg item defined with any numbers. Then when a button is first pressed on
the mouse device, kanata will print its hwid in the log; you can then
copy-paste that into this configuration entry. If this defcfg item is not
defined, the log will not print.
Hwids in Kanata are byte array representations of a concatenation of the
ASCII hardware ids, which can be seen in Device Manager on Windows. As such,
they are an arbitrary length and can be very long.
https://github.com/jtroo/kanata/issues/108[Relevant issue].
.Example:
[source]
----
(defcfg
windows-interception-mouse-hwid "70, 0, 60, 0"
)
----
=== Windows only: windows-interception-mouse-hwids[[windows-only-windows-interception-mouse-hwids]]
<<table-of-contents,Back to ToC>>
This item has a similar purpose as the singular version documented above,
but is instead a list of strings that allows multiple mice to be intercepted.
If both the singular and list items are used,
the singular version will behave as if added to the list.
.Example:
[source]
----
(defcfg
windows-interception-mouse-hwids (
"70, 0, 60, 0"
"71, 0, 62, 0"
)
)
----
=== Windows only: windows-interception-keyboard-hwids[[windows-only-windows-interception-keyboard-hwids]]
<<table-of-contents,Back to ToC>>
This defcfg item allows you to intercept only specific keyboards.
Its value must be a list of strings
with each string representing one hardware ID.
To know what numbers to put into the string,
you can run the variant with this defcfg item empty.
Then when a button is first pressed on the keyboard,
kanata will print its hwid in the log.
You can then copy-paste that into this configuration entry.
If this defcfg item is not defined, the log will not print.
Hwids in Kanata are byte array representations of a concatenation of the
ASCII hardware ids, which can be seen in Device Manager on Windows. As such,
they are an arbitrary length and can be very long.
.Example:
[source]
----
(defcfg
windows-interception-keyboard-hwids (
"70, 0, 60, 0"
"71, 72, 73, 74"
)
)
----
[[using-multiple-defcfg-options]]
=== Using multiple defcfg options
<<table-of-contents,Back to ToC>>
The `defcfg` entry is treated as a list with pairs of strings. For example:
[source]
----
(defcfg a 1 b 2)
----
This will be treated as configuration `a` having value `1` and configuration
`b` having value `2`.
An example defcfg containing many of the options is shown below. It should be
noted options that are Linux-only, Windows-only, or macOS-only will be ignored when used on
a non-applicable operating system.
[source]
----
;; Don't actually use this exact configuration,
;; it's almost certainly not what you want.
(defcfg
process-unmapped-keys yes
danger-enable-cmd yes
sequence-timeout 2000
sequence-input-mode visible-backspaced
sequence-backtrack-modcancel no
log-layer-changes no
delegate-to-first-layer yes
movemouse-inherit-accel-state yes
movemouse-smooth-diagonals yes
dynamic-macro-max-presses 1000
linux-dev (/dev/input/dev1 /dev/input/dev2)
linux-dev-names-include ("Name 1" "Name 2")
linux-dev-names-exclude ("Name 3" "Name 4")
linux-continue-if-no-devs-found yes
linux-unicode-u-code v
linux-unicode-termination space
linux-x11-repeat-delay-rate 400,50
windows-altgr add-lctl-release
windows-interception-mouse-hwid "70, 0, 60, 0"
)
----
== Advanced/weird features[[advanced-weird-features]]
[[fake-keys]]
=== Virtual keys (a.k.a. fake keys)
<<table-of-contents,Back to ToC>>
You can define up to 767 virtual keys.
These keys are not directly mapped to any physical key presses or releases.
Virtual keys can be activated via special actions:
* `(on-press <action> <virtual key name>)`:
Activate a virtual key action when pressing the associated input key.
* `(on-release <action> <virtual key name>)`:
Activate a virtual key action when releasing the associated input key.
* `(on-idle <milliseconds> <action> <virtual key name>)`:
Activate a virtual key action when kanata has been idle
for at least `idle time` milliseconds.
The `<action>` parameter can be one of:
* `tap-virtualkey | tap-vkey`:
Press and release the virtual key. If the key is already pressed, this only releases it.
* `press-virtualkey | press-vkey`:
Press the virtual key. It will not be released until another action triggers a release or tap.
If the key is already pressed, this does nothing.
* `release-virtualkey | release-vkey`:
Release the virtual key. If it is not already pressed, this does nothing.
* `toggle-virtualkey | toggle-vkey`:
Press the virtual key if it is not already pressed, otherwise release it.
A virtual key can be defined in a `defvirtualkeys` configuration entry.
Configuring this entry is similar to `+defalias+`,
but you cannot make use of aliases inside to shorten an action.
You can refer to previously defined virtual keys.
Expanding on the `on-idle` action some more,
the wording that "kanata" has been idle is important.
Even if the keyboard is idle, kanata may not yet be idle.
For example, if a long-running macro is playing,
or kanata is waiting for the timeout of actions such as `caps-word` or `tap-dance`,
kanata is not yet idle, and the tick count for the `<idle time>` parameter
will not yet be counting even if you no longer have any keyboard keys pressed.
.Example:
[source]
----
(defvirtualkeys
;; Define some virtual keys that perform modifier actions
ctl lctl
sft lsft
met lmet
alt lalt
;; A virtual key that toggles all modifier virtual keys above
tal (multi
(on-press toggle-virtualkey ctl)
(on-press toggle-virtualkey sft)
(on-press toggle-virtualkey met)
(on-press toggle-virtualkey alt)
)
;; Virtual key that activates a macro
vkmacro (macro h e l l o spc w o r l d)
)
(defalias
psf (on-press press-virtualkey sft)
rsf (on-press release-virtualkey sft)
tal (on-press tap-vkey tal)
mac (on-press tap-vkey vkmacro)
isf (on-idle 1000 tap-vkey sft)
)
(deflayer use-fake-keys
@psf @rsf @tal @mac a s d f @isf
)
----
.Older fake keys documentation
[%collapsible]
====
The older configuration style of fake keys are still supported
but the new style is preferred due to (hopefully) clearer naming.
Fake keys can be defined inside of `deffakekeys`.
The actions are:
* `+(on-press-fakekey <fake key name> <action>)+`: Activate a fake key
action when pressing the key mapped to this action.
* `+(on-release-fakekey <fake key name> <action>)+`: Activate a fake key
action when releasing the key mapped to this action.
* `+(on-idle-fakekey <fake key name> <action> <idle time>)+`:
Activate a fake key action when kanata has been idle
for at least `idle time` milliseconds.
The aforementioned `+<key action>+` can be one of four values:
* `+press+`: Press the fake key. It will not be released until another action
triggers a release or tap.
* `+release+`: Release the fake key. If it's not already pressed, this does nothing.
* `+tap+`: Press and release the fake key. If it's already pressed, this only releases it.
* `+toggle+`: Press the fake key if not already pressed, otherwise release it.
.Example:
[source]
----
(deffakekeys
ctl lctl
sft lsft
met lmet
alt lalt
;; Press all modifiers
pal (multi
(on-press fakekey ctl press)
(on-press-fakekey sft press)
(on-press-fakekey met press)
(on-press-fakekey alt press)
)
;; Release all modifiers
ral (multi
(on-press-fakekey ctl release)
(on-press-fakekey sft release)
(on-press-fakekey met release)
(on-press-fakekey alt release)
)
)
(defalias
psf (on-press-fakekey sft press)
rsf (on-press-fakekey sft release)
pal (on-press-fakekey pal tap)
ral (on-press-fakekey ral tap)
isf (on-idle-fakekey sft tap 1000)
)
(deflayer use-fake-keys
@psf @rsf @pal @ral a s d f @isf
)
----
====
For more context, you can read the
https://github.com/jtroo/kanata/issues/80[issue that sparked the creation of virtual keys].
Something notable about virtual keys is that they don't always interrupt the state
of an active `+tap-dance-eager+`. If a `macro` action is assigned to a fake
key, this won't interrupt a tap dance. However, most other action types,
notably a "normal" key action like `+rsft+` will still interrupt a tap dance.
[[sequences]]
=== Sequences
<<table-of-contents,Back to ToC>>
The `+sldr+` action makes kanata go into "sequence" mode. The action name is
short for "sequence leader". This comes from Vim which has the concept of a configurable
sequence leader key. When in sequence mode, keys are not typed
(<<sequence-input-mode,by default>>)
but are saved until one of the following happens:
* A key is typed that does not match any sequence
* `+sequence-timeout+` milliseconds elapses since the most recent key press
Sequences are configured similarly to `+deffakekeys+`. The first parameter of a
pair must be a defined virtual key name. The second parameter is a list of keys
that will activate a virtual key tap when typed in the defined order. More
precisely, the action triggered is:
`+(on-press-fakekey <virtual key name> tap)+`
.Example:
[source]
----
(defseq git-status (g s t))
(deffakekeys git-status (macro g i t spc s t a t u s))
(defalias rcl (tap-hold-release 200 200 sldr rctl))
(defseq
dotcom (. S-3)
dotorg (. S-4)
)
(deffakekeys
dotcom (macro . c o m)
dotorg (macro . o r g)
)
----
For more context, you can read the
https://github.com/jtroo/kanata/issues/97[design and motivation of sequences].
You may also be interested in
https://github.com/jtroo/kanata/blob/main/docs/sequence-adding-chords-ideas.md[the document describing chords in sequences]
to read about how chords in sequences behave.
==== Override the global timeout and input mode
An alternative to using `sldr` is the `sequence` action.
The syntax is `(sequence <timeout>)`.
This enters sequence mode with a sequence timeout
different from the globally configured one.
The `sequence` action can also be called with a second parameter.
The second parameter is an override for `sequence-input-mode`:
----
(sequence <timeout> <input-mode>)
----
.Example:
[source]
----
;; Enter sequence mode and input . with a timeout of 250
(defalias dot-sequence (macro (sequence 250) 10 .))
;; Enter sequence mode and input . with a timeout of 250 and using hidden-delay-type
(defalias dot-sequence (macro (sequence 250 hidden-delay-type) 10 .))
----
[[input-chords]]
=== Input chords
<<table-of-contents,Back to ToC>>
Not to be confused with <<output-chords-combos,output chords>>, `+chord+`
actions allow you to perform various actions based on which specific combination
of input keys are pressed together. Such an unordered combination of keys
is called a "chord". Each chord can perform a different action, allowing you
to bind up to `+2^n - 1+` different actions to just `+n+` keys.
Input chords are configured similarly to `+defalias+` with two extra parameters
at the beginning of each `+defchords+` group: the name of the group and a
timeout value after which a chord triggers if it isn't triggered by a key release
or press of a non-chord key before the timeout expires.
[source]
----
(defsrc a b c)
(deflayer default
@cha @chb @chc
)
(defalias
cha (chord example a)
chb (chord example b)
chc (chord example c)
)
(defchords example 500
(a ) a
( b ) b
(a c) C-v
(a b c) @three
)
----
The first item of each pair specifies the keys that make up a given chord.
The second item of each pair is the action to be executed when the given chord
is pressed and may be any regular or advanced action, including aliases. It
currently cannot however contain another `+chord+` action.
Note that unlike with `+defseq+`, these keys do not directly correspond to real
keys and are merely arbitrary labels that make sense within the context of the
chord.
They are mapped to real keys in layers by configuring the key in the layer to
map to a `+(chord name key)+` action where `+name+` is the name of the chords
group (above `+example+`) and `+key+` is one of these arbitrary labels.
It is perfectly valid to nest these `+chord+` actions that enter "chording mode"
within other actions like `+tap-dance+` and that will work as one would expect.
However, this only applies to the first key used to enter "chording mode".
Once "chording mode" is active, all other keys will be directly handled by
"chording mode" with no regard for wrapper actions; e.g. if a key is pressed
and it maps to a tap-hold with a chord as the hold action within, that chord
key will immediately activate instead of the key needing to be held for the
timeout period.
**Release behaviour**
For single key actions and output chords — like `lctl` or `S-tab` —
and for `layer-while-held`,
an input chord will release the action only when all keys that are part of
the input chord have been released.
In other words, if even one key is held for the input chord
then the output action will be continued to be held,
but only for the mentioned action categories.
The behaviour also applies to the actions mentioned above
when used inside of `multi` but not within any other action.
An exception to the behaviour described above
for the action categories that would normally apply
is if a chord decomposition occurs.
A chord decomposition occurs when you input a chord
that does not correspond to any action.
When this happens, kanata splits up the key presses to activate
other actions from the components of the input chord.
In this scenario, the behaviour described in the next paragraph will occur.
For chord decompositions and all other action categories,
the release behaviour is more confusing:
the output action will end when any key is released during the timeout,
or if the timeout expires, the output action ends when the *first* key
that was pressed in the chord gets released.
This inconsistency is a limitation of the current implementation.
In these scenarios it is recommended
to hold down all keys if you want to keep holding
and to release all keys if you want to do a release.
This is because it will probably be difficult
to know which key was pressed first.
If you want to bypass the behaviour of keys being held for chord outputs,
you could change the chord output actions to be <<macro,macros>> instead.
Using a macro will guarantee a rapid press+release for the output keys.
[[defaliasenvcond]]
=== defaliasenvcond
<<table-of-contents,Back to ToC>>
There is a variant of `defalias`: `defaliasenvcond`.
This variant is parsed similarly,
but there must be an extra list parameter
that comes before all of the name-action pairs.
The list must contain two strings.
In order, these strings are:
an environment variable name,
and the environment variable value.
When the environment variable defined by the name
has the corresponding value when starting kanata,
the aliases within will be active.
Otherwise, the aliases will be skipped.
A use case for `defaliasenvcond` is when one has multiple devices
which vary in layout of keys,
e.g. different special keys on the bottom row.
Using environment variables, one can use the same kanata
configuration across those multiple devices
while changing key behaviours to keep consistent behaviour
of specific key positions across the multiple devices,
when the hardware keys at those physical key positions are not
the same.
.Example:
[source]
----
(defaliasenvcond (LAPTOP lp1)
met @lp1met
)
(defaliasenvcond (LAPTOP lp2)
met @lp2met
)
----
.Set environment variables in the current terminal process:
[source]
----
# powershell
$env:VAR_NAME = "var_value"
# bash
VAR_NAME=var_value
----
[[switch]]
=== switch
<<table-of-contents,Back to ToC>>
The `switch` action accepts multiple cases.
One case is a triple of:
- keys check
- action: to activate if keys check succeeds
- `fallthrough|break`: choose to continue vs. stop evaluating cases
The default use of keys check behaves similarly to fork.
For example, the keys check `(a b c)` will activate the corresponding action
if any of a, b, or c are currently pressed.
The keys check also accepts the boolean operators `and|or|not` to allow more
complex use cases.
The order of cases matters.
For example, if two different cases match the currently pressed keys,
the case listed earlier in the configuration will activate first.
If the early case uses break, the second case will not activate.
Otherwise if fallthrough is used,
the second case will activate sequentially after the first case.
This idea generalizes to more than two cases,
but the two case example is hopefully simple and effective enough.
.Example:
[source]
----
(defalias
swt (switch
;; case 1
((and a b (or c d) (or e f))) @ac1 break
;; case 2
(a b c) @ac2 fallthrough
;; case 3
() @ac3 break
)
)
----
Below is a description of how this example behaves.
==== Case 1
----
((and a b (or c d) (or e f))) a break
----
Translating case 1's keys check to some other common languages
might look like:
----
(a && b && (c || d) && (e || f))
----
If the keys check passes, the action `@ac1` will activate.
No other action will activate since `break` is used.
==== Cases 2 and 3
----
(a b c) c fallthrough
() b break
----
Case 2's key check behaves like that of `fork`, i.e.
(or a b c)
or for some other common languages:
a || b || c
If this keys check passes and the case 1 does not pass,
the action `@ac2` will activate first.
Since the keys check of case 3 always passes, `@ac3` will activate next.
If neither case 1 or case 2 pass their keys checks,
case 3 will always activate with `@ac3`.
[[key-history-and-key-timing]]
==== key-history and key-timing
In addition to simple keys there are two list items
that can be used within the case keys check
that compare against your typed key history:
* `key-history`
* `key-timing`
The `key-history` item compares the order that keys were typed.
It accepts, in order:
* a key
* the key recency
The key recency must be in the range 1-8,
where 1 is the most recent key that was pressed
and 8 is 8th most recent key pressed.
.Example:
[source]
----
(defalias
swh (switch
((key-history a 1)) S-a break
((key-history b 1)) S-b break
((key-history c 1)) S-c break
((key-history d 8)) (macro d d d) break
() XX break
)
)
----
The `key-timing` compares how long ago recent key typing events occurred.
It accepts, in order,
* the key recency
* a comparison string, which is one of: `less-than|greater-than|lt|gt`
* number of milliseconds to compare against
The key recency must be in the range 1-8,
where 1 is the most recent key that was pressed
and 8 is 8th most recent key pressed.
Most use cases are expected to use a value of 1 for this parameter,
but perhaps you can find a creative use for the other values.
The comparison string determines how the actual key event timing
will be compared to the provided timing.
The number of milliseconds must be 0-65535.
WARNING: The maximum milliseconds value of this configuration item
across your whole configuration
will be a lower bound of how long it takes for kanata to become idle
and stop processing its state machine every approxmately 1ms.
.Example:
[source]
----
(defalias
swh (switch
((key-timing 1 less-than 200)) S-a break
((key-timing 1 greater-than 500)) S-b break
((key-timing 2 lt 1000)) S-c break
((key-timing 8 gt 2000)) (macro d d d) break
() XX break
)
)
----
==== not
The examples presented so far have not included the `not` boolean operator.
This operator will now be discussed.
Syntactically, the `not` operator is used similarly to `or|and`.
Functionally, it means "not **any** of" the list elements.
.Example:
[source]
----
(defalias
swn (switch
((not x y z)) S-a break
;; the above and below cases are equivalent in logic
((not (or x y z))) S-a break
)
)
----
In potentially more familiar notation, both cases have the logic:
!(x || y || z)
==== input
Until now, all `switch` logic has been associated to key code outputs.
It is also possible to operate on inputs.
Inputs can be either real keys or "virtual" (fake) keys.
.Example:
[source]
----
(defalias switch-input-example
(switch
((input real lctl)) $ac1 break
((input virtual vk1)) $ac2 break
() $ac3 break
)
)
----
Similar to `key-history` for regular active keys,
`input-history` also exists.
NOTE:
A perhaps surprising (but hopefully logical) behaviour of input-history
when compared to key-history is that, at the time of switch activation,
the history of `input-history` for recency `1` will be the just-pressed input.
Whereas with `key-history` for example, the key that will be next outputted
is of course still undetermined, so is not in the history.
The consequence of this is that you should use a recency of `2`
when referring to the previously pressed input
because the current input is in the recency `1` slot.
.Example:
[source]
----
(defalias switch-input-history-example
(switch
((input-history real lsft 2)) $var1 break
((input-history virtual vk2 2)) $var1 break
() $ac3 break
)
)
----
[[templates]]
=== Templates
<<table-of-contents,Back to ToC>>
The top-level configuration item `deftemplate`
declares a template that can be expanded multiple times
via the list item `template-expand`.
The parameters to `deftemplate` in order are:
* Template name
* List of template variables
* Template content (any combination of lists / strings)
Within the template content, variable names prefixed with `$`
will be substituted with the expression passed into `template-expand`.
The list item `template-expand` can be placed as a top-level list
or within another list.
Its parameters in order are:
* template name
* parameters to substitute into the template
NOTE: Template expansion happens after file includes and before any other parsing.
One consequence of this early parsing is that variables defined in `defvar`
are **not** substituted when used inside of `template-expand`.
This has consequences for condtional content, e.g. with `if-equal`.
This is discussed further in Example 5.
Example 1:
In a simple example, let's say you wanted to set a large group of keys
to do something different when you're holding alt. Yes, this could also
be handled with remapping alt to a layer shift, but there are cases where
you wouldn't want this. Rather than retyping the code with `fork` and
`unmod` (to release alt) a bunch of times, you could template it like so:
[source]
----
(deftemplate alt-fork (original-action new-action)
(fork $original-action (multi (unmod ralt lalt) $new-action) (lalt ralt))
)
(defsrc 1 2 3)
(defalias fn1 (template-expand alt-fork 1 f1))
;; Templates are a simple text substitution, so the above is exactly equivalent to:
;; (defalias fn1 (fork 1 (multi (unmod ralt lalt) f1) (lalt ralt)))
(defalias fn2 (template-expand alt-fork 2 f2))
(defalias fn3 (template-expand alt-fork 3 f3))
(deflayer default (@fn1 @fn2 @fn3))
----
.Example 2:
[source]
----
(defvar chord-timeout 200)
(defcfg process-unmapped-keys yes)
;; This template defines a chord group and aliases that use the chord group.
;; The purpose is to easily define the same chord position behaviour
;; for multiple layers that have different underlying keys.
(deftemplate left-hand-chords (chordgroupname k1 k2 k3 k4 alias1 alias2 alias3 alias4)
(defalias
$alias1 (chord $chordgroupname $k1)
$alias2 (chord $chordgroupname $k2)
$alias3 (chord $chordgroupname $k3)
$alias4 (chord $chordgroupname $k4)
)
(defchords $chordgroupname $chord-timeout
($k1) $k1
($k2) $k2
($k3) $k3
($k4) $k4
($k1 $k2) lctl
($k3 $k4) lsft
)
)
(template-expand left-hand-chords qwerty a s d f qwa qws qwd qwf)
(template-expand left-hand-chords dvorak a o e u dva dvo dve dvu)
(defsrc a s d f)
(deflayer dvorak @dva @dvo @dve @dvu)
(deflayer qwerty @qwa @qws @qwd @qwf)
----
.Example 3:
[source]
----
;; This template defines a home row that customizes a single key's behaviour
(deftemplate home-row (j-behaviour)
a s d f g h $j-behaviour k l ; '
)
(defsrc
grv 1 2 3 4 5 6 7 8 9 0 - = bspc
tab q w e r t y u i o p [ ] \
;; usable even inside defsrc
caps (template-expand home-row j) ret
lsft z x c v b n m , . / rsft
lctl lmet lalt spc ralt rmet rctl
)
(deflayer base
grv 1 2 3 4 5 6 7 8 9 0 - = bspc
tab q w e r t y u i o p [ ] \
;; lists can be passed in too!
caps (template-expand home-row (tap-hold 200 200 j lctl)) ret
lsft z x c v b n m , . / rsft
lctl lmet lalt spc ralt rmet rctl
)
----
==== if-equal
Within a template you can use the list item `if-equal`
to have condiditionally-used items within a template.
It accepts a minimum of 2 parameters.
The first two parameters must be strings and are compared
against each other.
If they match, the following parameters are inserted into
the template in place of the `if-equal` list.
Otherwise if the strings do not match
then the whole `if-equal` list is removed from the template.
.Example 4:
----
(deftemplate home-row (version)
a s d f g h
(if-equal $version v1 j)
(if-equal $version v2 (tap-hold 200 200 j lctl))
k l ; '
)
(defsrc
grv 1 2 3 4 5 6 7 8 9 0 - = bspc
tab q w e r t y u i o p [ ] \
caps (template-expand home-row v1) ret
lsft z x c v b n m , . / rsft
lctl lmet lalt spc ralt rmet rctl
)
(deflayer base
grv 1 2 3 4 5 6 7 8 9 0 - = bspc
tab q w e r t y u i o p [ ] \
caps (template-expand home-row v2) ret
lsft z x c v b n m , . / rsft
lctl lmet lalt spc ralt rmet rctl
)
----
Similar to `if-equal` are three more conditional operators for templates:
* `if-not-equal`
** the content is used if the first two string parameters are not equal
* `if-in-list`
** the content is used if the first string parameter exists in
the second list-of-strings parameter
* `if-not-in-list`
** the content is used if the first string parameter does not exist in
the second list-of-strings parameter
.Example 5:
----
;; defvar is parsed AFTER template expansion occurs.
(defvar a hello)
(deftemplate template1 (var1)
a (if-equal hello $var1 b) c
)
;; Below will expand to: `a c` because the string
;; $a itself is compared against the string hello
;; and they are not equal.
(expand-template template1 $a)
(deftemplate template2 (var1)
a (if-equal $a $var1 b) c
)
;; Below will expand to: `a b c` because the string
;; $a is compared against the string $a and they are equal.
;; But note that the variable $a is still not substituted
;; with its defvar value of: hello.
(expand-template template2 $a)
----
[[concat-in-deftemplate]]
==== concat in deftemplate
Like <<concat-in-defvar,concat in defvar>>,
a list beginning with `concat` within the content of `deftemplate`
will be replaced with a single string that consists of
all the subsequent items in the list concatenated to each other.
[[custom-tap-hold-behaviour]]
=== Custom tap-hold behaviour
<<table-of-contents,Back to ToC>>
This is not currently configurable without modifying the source code, but if
you're willing and/or capable, there is a tap-hold behaviour that is currently
not exposed. Using this behaviour, one can be very particular about when and how
tap vs. hold will activate by using extra information. The available
information that can be used is exactly which keys have been pressed or
released as well as the timing in milliseconds of those key presses.
The action `+tap-hold-release-keys+` makes use of some of this capability, but
doesn't make full use of the power of this functionality.
For more context, you can read the
https://github.com/jtroo/kanata/issues/128[motivation for custom tap-hold behaviour].
[[fancy-key-symbols]]
=== Fancy key symbols
<<table-of-contents,Back to ToC>>
Instead of using the same `+a-z+` letters for special keys, e.g., `+lsft+` for `+LeftShift+`
you can use much shorter, yet more visible, key symbols like `+‹⇧+`.
For more details see
https://github.com/jtroo/kanata/blob/main/docs/fancy_symbols.md[symbol list] and
https://github.com/jtroo/kanata/blob/main/cfg_samples/fancy_symbols.md[example config], which not only uses these symbols in layer definitions, but also repurposes `+⎇›+` and `+⇧›+` `+⎇›+` keys into "symbol" keys that allow you to insert these fancy symbols by pressing the key, e.g.,
* hold `+⎇›+` and tap `+Delete+` would insert `+␡+`
[[test-your-config]]
=== Test your config
<<table-of-contents,Back to ToC>>
Kanata has a `+kanata_simulated_input+` tool
to help test your configuration in a predictable manner.
You can try it out on https://jtroo.github.io/[GitHub pages].
Code for the CLI tool can be found under link:../simulated_input/[simulated_input].
Instead of physically typing to test something
and wondering whether you didn't get the expected result because your config is wrong or
because you mistyped something,
you can write a sequence of key presses in a `+sim.txt+` file,
run the tool with your config
and get a "timeline" view of input/output events that can help understand how kanata translates
your input into various key/mouse presses.
WARNING: The format of this view may change.
It currently doesn't show timings of output events and emoji output may break vertical alignment.
For more details download the files below and run `kanata_simulated_input -c sim.kbd -s sim.txt` +
- https://github.com/jtroo/kanata/blob/main/docs/simulated_output/sim.kbd[example config] with simple home row mod bindings +
- https://github.com/jtroo/kanata/blob/main/docs/simulated_output/sim.txt[example input sequence] +
- https://github.com/jtroo/kanata/blob/main/docs/simulated_output/sim_out.txt[example output sequence] +
Input sequence file format: whitespace insensitive list of `prefix:key` pairs where prefix is one of: +
- `🕐`, `t`, or `tick` to add time between key events in `ms` +
- `↓`, `d`, `down`, or `press` +
- `↑`, `u`, `up`, or `release` +
- `⟳`, `r`, or `repeat` +
And key names are defined in the https://github.com/jtroo/kanata/blob/main/parser/src/keys/mod.rs[str_to_oscode function],
for example, `1` for the numeric key 1 or `kp1`/`🔢₁` for the keypad numeric key 1
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment