config.adoc

= Kanata Configuration Guide
:last-update-label!:
ifndef::env-github[]
:toc: left
endif::[]
:stylesheet: config-stylesheet.css

This document describes how to create a kanata configuration file.
The kanata configuration file will determine your keyboard behaviour upon running kanata.

== How to read the guide

ifdef::env-github[]
See the triple bullet-lines at the upper right
to open or close a Table of Contents sidebar.

You may want to view the guide rendered to HTML.
https://jtroo.github.io/config.html[Link to guide].
endif::[]

The **Reference** sections are shorter
and are intended for reviewing how precisely to configure different sections.
The **Description** sections are longer
and contain more details such as advice, motivation, and examples.

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.

ifdef::env-github[]
* https://github.com/jtroo/kanata/blob/v1.12.0/docs/config.adoc[v1.12.0]
* https://github.com/jtroo/kanata/blob/v1.11.0/docs/config.adoc[v1.11.0]
* https://github.com/jtroo/kanata/blob/v1.10.1/docs/config.adoc[v1.10.1]
* https://github.com/jtroo/kanata/blob/v1.10.0/docs/config.adoc[v1.10.0]
* https://github.com/jtroo/kanata/blob/v1.9.0/docs/config.adoc[v1.9.0]
* https://github.com/jtroo/kanata/blob/v1.8.1/docs/config.adoc[v1.8.1]
* https://github.com/jtroo/kanata/blob/v1.8.0/docs/config.adoc[v1.8.0]
endif::[]
ifndef::env-github[]
* link:/config-1.12.0.html[v1.12.0]
* link:/config-1.11.0.html[v1.11.0]
* link:/config-1.10.1.html[v1.10.1]
* link:/config-1.10.0.html[v1.10.0]
* link:/config-1.9.0.html[v1.9.0]
* link:/config-1.8.1.html[v1.8.1]
* link:/config-1.8.0.html[v1.8.0]
endif::[]

== Preamble

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.

Useful terminology to learn early:
[cols="1,5"]
|===
| string
| A sequence of characters.
Optionally surrounded by quotes.
Examples: `backspace`, `"string with spaces and 1 number"`.

| list
| A sequence of strings or nested lists within round brackets.
List items are separated by any amount of whitespace characters,
or by round brackets.
Examples: `(lrld-num 1)`, `(tap-dance 200 (f1(unicode 😀)f2(unicode 🙂)))`.
|===

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.

== Forcefully exit kanata [[force-exit]]

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

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

**Reference**

Your configuration file must have exactly one `defsrc` list.
This defines the order of keys that the `+deflayer+` entries will operate on.

.Syntax:
[source]
----
(defsrc $key1 $key2 ... $keyN)
----

[cols="1,6"]
|===
| `$key`
| The name of a key. This can be a default key name or one defined in <<deflocalkeys>>.
When physically pressing this input key, the action defined
at the same order position on the active layer will activate.
|===

**Description**

The `defsrc` configuration entry defines which of your key inputs
will be processed by kanata and how the keys map to defined layers.
Keys excluded from `defsrc` will not be processed by Kanata
unless you have `process-unmapped-keys yes` in <<introduction-defcfg,defcfg>>.

Keys not processed by Kanata has implications on various actions.
For example:

- Pressing an excluded key will type a letter
while a prior `tap-hold` decision is still pending,
resulting in potentially incorrect results.
- Excluded keys do not trigger early activation
in actions such as `tap-hold-press` or `tap-dance`
- Excluded keys cannot be read by `fork` or `switch` logic.

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:

.Example:
[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 Menu key instead of a right Meta key.
In this case you can use `menu` instead of `rmet`.

For non-US keyboards, see <<non-us-keyboards,the non-US keyboards section>>.

[[deflayer]]
=== deflayer

**Reference**

Your configuration file must have at least one `+deflayer+` entry. This defines
how each physical key mapped in `+defsrc+` behaves when kanata runs.

.Syntax:
[source]
----
(deflayer $layer-name $action1 $action2 ... $actionN)
----

[cols="1,5"]
|===
| `$layer-name`
| A string representing the layer name.
This name is used to reference this layer in other actions.

| `$action`
| The action that activates while this layer is active
when the corresponding `defsrc` input key is pressed.
|===

**Description**

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:

.Example:
[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
)
----

A <<windows-only-tray-icon,Windows tray menu build>> also allows specifying
layer icons in `+deflayer+` and `+deflayermap+` to show in the tray menu on layer activation,
see https://github.com/jtroo/kanata/blob/main/cfg_samples/tray-icon/tray-icon.kbd[example config]

==== deflayermap

**Reference**

An alternative method for defining a layer exists: `deflayermap`.
This method maps inputs to actions by defining input-output pairs,
ignoring `defsrc` entirely.

You will likely want to either enable <<process-unmapped-keys>>
or define most of your keyboard keys within <<defsrc>> when using `deflayermap`.
Otherwise many actions do not behave as intended.
See one of the links for more context.

.Syntax:
[source]
----
(deflayermap ($layer-name)
 $input1 $action1
 $input2 $action2
 ...
 $inputN $actionN)
----

[cols="1,5"]
|===
| `$layer-name`
| A string representing the layer name.
This name is used to reference this layer in other actions.

| `$input`
| The input key mapped to the corresponding output.

| `$action`
| The action that activates while this layer is active
when the corresponding input key is pressed.
|===

**Description**


The `deflayermap` variant has the advantage of terser configuration
when only a few keys on a layer need to be mapped.
When practicing a new configuration, the standard `deflayer` has an advantage
of looking more like a physical keyboard layout,
which may be helpful to some.

Within `deflayermap`, the very first item must be the layer name.
The layer name must be in parentheses unlike with `deflayer`.
After the layer name, the layer is configured via pairs of items:

* input key
* output action

An example complete configuration that maps Caps Lock to Escape is:

[source]
----
;; defsrc is still necessary
(defsrc)
(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.

As special input names,
you can use one of `&#95;`, `&#95;&#95;`, or `&#95;&#95;&#95;` to map all
the keys that are not explicitly mapped in the layer,
e.g. in the example above, these affect keys other than `caps`.

[cols="1,6"]
|===
| `&#95;`
| Map all unmapped keys in this layer that are defined in `defsrc`.

| `&#95;&#95;`
| Map all unmapped keys in this layer that are not defined in `defsrc`.

| `&#95;&#95;&#95;`
| Map all unmapped keys in this layer.
|===

If a key is not mapped explicitly or through these wildcards, it will be implicitly mapped to a <<transparent-key,transparent key>>.

**Key processing**

The `$input` keys in all `deflayermap` sections will be processed by kanata, even if:

* the layer is inactive
* the key is omitted from `defsrc`
* the `process-unmapped-keys` configuration is omitted, set to `no`, or the key is within `(all-except ...)`

This is particularly relevant for the issue described in <<windows-only-windows-altgr>>.

[[review-of-required-configuration-entries]]
=== Review of required configuration entries

If you're reading in order, you have now seen all of the required entries:

* `+defsrc+`
* `+deflayer+`

[[minimal-config]]
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:https://github.com/jtroo/kanata/blob/main/docs/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.

[[key-names]]
== Key names for defsrc and deflayermap

The source of truth for all default key names are the functions
`str_to_oscode` and `add_default_str_osc_mappings`
in the link:https://github.com/jtroo/kanata/blob/main/parser/src/keys/mod.rs[keys/mod.rs file].

https://www.toptal.com/developers/keycode[This online tool]
will also work for most keys to tell you the key name.
It will be shown as the `event.code` field in the web page
after you press the key.

[[non-us-keyboards]]
== Non-US keyboards

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 online tool]
and press the key.
The `event.code` field tells you the key name to use in Kanata.
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.

IMPORTANT: 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.

NOTE: On macOS, the ISO "#" key to the left of Enter reports
`event.code` as `Backslash` in the browser, but the operating system
delivers it to kanata as a distinct HID usage that the regular
`\`/`Backslash` name does not match. Use the name `non_us_pound`
(aliases: `NonUSPound`, `nuhs`) for that physical key on macOS. If
you want the same config to work on Linux as well, pair this with
`deflocalkeys-linux` to map evdev code 43 to the same name.

[[deflocalkeys]]
=== deflocalkeys

**Reference**

You can use `deflocalkeys` to define additional key names that can be
used in `defsrc`, `deflayer`, and anywhere else in the configuration.

.Syntax:
[source]
----
(deflocalkeys-$variant
  $key-name1 $key-number1
  $key-name2 $key-number2
  ...
  $key-nameN $key-numberN)
----

[cols="1,5"]
|===
| `$variant`
| One of: `win winiov2 wintercept linux macos`

| `$key-name`
| A key name of your choice that can be used in the rest of the configuration.

| `$key-number`
| A key number that varies based on the kanata variant you are using.
|===

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.exe` binary.

**Description**

The `deflocalkeys` configurations are not strictly necessary.
Their purpose is to help you match your physical keyboard's appearance
to your kanata configuration,
in the hopes it will be more readable and less confusing.
In the underlying hardware, all keyboard positions send the same scan codes
according to their position, regardless of what is printed on the key cap.
The scan code names are typically referred to by the corresponding US layout name.
It is the job of the operating system to translate the same scan code
to the correct outputs according to the configured locale and layout.

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!

There are five variants of deflocalkeys:

- `deflocalkeys-win`
- `deflocalkeys-winiov2`
- `deflocalkeys-wintercept`
- `deflocalkeys-linux`
- `deflocalkeys-macos`

.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.

Running kanata with the `--debug` flag lets you read the correct number,
shown in parenthesis of `code` in the `KeyEvent` log lines.

It also possible to use native tools, as described below.

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

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

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.

By default, keys excluded from `defsrc`
and that aren't found in any `deflayermap` input position
will not work in various scenarios.
Some examples:

- The early hold for prior `+tap-hold-press+` actions will not activate early
- Unprocessed keys will be sent
  before a tap-hold key finishes evaluating tap vs. hold
- Prior `+one-shot+` actions will not be released
- `fork` and `switch` logic will not see the key

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.
A known issue being AltGr/ralt/Right Alt; see <<windows-only-windows-altgr>>.

.Example:
[source]
----
(defcfg process-unmapped-keys yes)
(defcfg process-unmapped-keys (all-except lctl ralt))
----

== Aliases and variables[[aliases-and-vars]]

Before learning about actions,
it will be useful to first learn about aliases and variables.

[[aliases]]
=== Aliases

**Reference**

Using the `defalias` configuration entry, you can introduce a shortcut label
for an action.

.Syntax:
[source]
----
(defalias
  $alias-name1 $action1
  $alias-name2 $action2
  ...
  $alias-nameN $actionN)
----

[cols="1,5"]
|===
| `$alias-name`
| The chosen shortcut label for the action.
This shortcut label can be used in the rest of
the configuration by prefixing it with the `@`
character.

| `$action`
| The ouput action used wherever the alias name is referenced.
|===

**Description**

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

**Reference**

Using the `defvar` configuration entry,
you can introduce a shortcut label for an arbitrary string or list.

.Syntax:
[source]
----
(defvar
  $var-name1 $var-value1
  $var-name2 $var-value2
  ...
  $var-nameN $var-valueN)
----

[cols="1,5"]
|===
| `$var-name`
| The chosen shortcut label for the string or list.
This shortcut label can be used in the rest of the
configuration by prefixing it with `$`.

| `$var-value`
| An arbitrary string or list that will be substituted
wherever the variable is used.

|===

**Description**

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 an action name

Variables are referred to by prefixing their name with `$`.

.Example:
[source]
----
(defvar
  tap-repress-timeout   100
  hold-timeout  200
  tt $tap-repress-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

**Reference**

Live reload variants:

[cols="1,5"]
|===
| `lrld`
| String action that live-reloads the currently-used configuration file.

| `lrld-next`
| String action that live-reloads the configuration file specified
consecutively later in the command line order.
Cycles to the first-specified file
if currently using the last file specified.

| `lrld-prev`
| String action that live-reloads the configuration file specified
consecutively earlier in the command line order.
Cycles to the last-specified file
if currently using the first file specified.

| `(lrld-num $n)`
| List action that live-reloads the n'th file
as specified in the command line order.
The first file specified is `n=1`.
|===

Live reload does not read or apply changes to device-related configurations.
Examples of device-related configurations:
`linux-dev`, `macos-dev-names-include`, `linux-use-trackpoint-property`,
`windows-only-windows-interception-keyboard-hwids`.

**Description**

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.

.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

**Reference**

A list action that changes the active base layer.

.Syntax:
[source]
----
(layer-switch $layer-name)
----

[cols="1,5"]
|===
| `$layer-name`
| Layer name to switch to.
|===


**Description**

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

**Reference**

A list action that changes the active layer while the key is held.

.Syntax:
[source]
----
(layer-while-held $layer-name)
----

[cols="1,5"]
|===
| `$layer-name`
| Layer name to activate while key is held.
|===

**Description**

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

**Reference**

[cols="1,5"]
|===
| `+_+`
| String action that activates the action of the layer "underneath" the active one.
|===

**Description**

Kanata maintains a layer stack consisting in order of:

* a stack of temporary layers, where each `layer-while-held` adds one layer on top
* the base layer, manipulated by `layer-switch`
* if `delegate-to-first-layer` is enabled: the first layer defined by `deflayer` or `deflayermap`
* `defsrc`

A single underscore `+_+` acts as a "transparent" key in the current layer.
It will invoke the action assigned to the same key position on the next layer in the stack.

NOTE: If `delegate-to-first-layer` is enabled and the base layer is currently set to the first defined layer, a transparent key on the base layer will fall through directly to `defsrc`.

[[use-defsrc]]
=== use-defsrc

**Reference**

[cols="1,6"]
|===
| `use-defsrc`
| String action that outputs the corresponding `defsrc` input key.
|===

**Description**

A similar concept to transparent key is the `+use-defsrc+` action.
When activated, the underlying `defsrc` key will be the output action.

.Example:
[source]
----
(defsrc a b c d)
(defalias src use-defsrc)
(deflayer remap-only-c-to-d
  _ _ d @src)
----

[[no-op]]
=== No-op

**Reference**

[cols="1,6"]
|===
| `XX`
| String action that will output nothing.
|===

**Description**

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 `+✗+` `+∅+` `+•+` to mean no-op.

.Example:
[source]
----
(deflayer contains-no-ops
  XX ✗ ∅ •)
----

[[unicode]]
=== Unicode

**Reference**

List action that outputs a single unicode codepoint.
The unicode codepoint will not be repeatedly typed if you hold the key down.

.Syntax:
[source]
----
(unicode $unicode-codepoint)
----

[cols="1,4"]
|===
| `$unicode-codepoint`
| One unicode codepoint.
Be warned that many emojis/glyphs/graphemes
are composed of multiple codepoints.
|===

**Description**

NOTE: The <<clipboard-actions>> may output unicode characters more consistently.

The `+unicode+` (or `+🔣+`) action accepts a single unicode character (but not
a composed character, so 🤲, but not 🤲🏿),
or a single unicode number prefixed with `U+`.
For example, both of these actions are the same:
- `(unicode 🚆)`
- `(unicode U+1F686)`

If you want to output a glyph that is composed of multiple codepoints,
you can use <<macro>> with multiple `unicode` actions.

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.
Furthermore, on Wayland the unicode mechanism may be broken entirely.
On Wayland you can install then use the `wtype` program,
using <<cmd, cmd>> to execute it.
For example: `(cmd wtype á)`

.Example:
[source]
----
(defalias
  sml (unicode 😀)
  😀 (🔣 😀)
  🙁 (unicode 🙁)
)
(deflayer has-happy-sad
  @sml @🙁 @😀 🔣😀 d f
)
----

If you want output parentheses `+( )+` via unicode you can quote them.

.Example with parentheses
[source]
----
(defalias
  lp (unicode "(")
  rp (unicode ")")
)
----

If you want to output double quotes via unicode
you need a special quoting syntax.

.Example use of double-quote within a string
[source]
----
(defalias
  dq (unicode r#"""#)
)
----

[[output-chordscombos]]
=== Output chords/combos

**Reference**

Prefixing a known key name with the following strings
will output the key alongside the specified modifier.
Multiple prefixes can be combined to add more modifiers
to the same key output.
Duplicate prefixes are not allowed.

[cols="1,6"]
|===
| `+C-+`
| Left Control

| `+RC-+`
| Right Control

| `+A-+`
| Left Alt

| `+RA-+`
| Right Alt, also known as AltGr

| `+AG-+`
| Also means Right Alt/AltGr

| `+S-+`
| Left Shift

| `+RS-+`
| Right Shift

| `+M-+`
| Left Meta

| `+RM-+`
| Right Meta
|===

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.

**Description**

You may want to remap a key to automatically be pressed in combination with
modifiers such as Control or Shift.
Output chords are a way for you to achieve this.

Output chords are typically used do one-off actions such as:

- type a symbol, e.g. `S-1` to output `!` for the US layout.
- type an accented character,
e.g. `RA-a` to output `á` for the US international layout.
- do a special action like `C-c` to send `SIGTERM` in the terminal

It should be noted that output chords are not usable in all configuration items.
If you get an unknown key error where you expected an output chord to be usable,
you must split the output chord into its component keys.
For example, `+(unmod C-l)+` is an error;
instead you should use `+(unmod lctl l)+`.

The output chord prefix strings are:

* `+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 `+⌘›+` `+❖›+` `+◆›+`)

.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

**Reference**

[cols="1,5"]
|===
| `rpt`
| String action that outputs the single most-recently typed key.

| `rpt-any`
| String action that outputs the most-recently outputted action.
|===

**Description**

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

**Reference**

[cols="1,2"]
|===
| `(release-key $key)`
| List action that releases the defined key from output actions.
Notably this does not act on key inputs.

| `(release-layer $layer-name)`
| List action that releases `layer-while-held` activations
for the given layer name.
|===

**Description**

You can release a held key or layer via these actions:

* `release-key` or `key↑`: release a key, accepts `defsrc` compatible names
* `release-layer` or `layer↑`: release a while-held layer

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.
For example, if the action `(macro-repeat a 50)` were on the `a` key,
activating `(release-key a)` will not stop the repeating macro.

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

**Reference**

Activate multiple actions in sequence.

.Syntax:
[source]
----
(multi $action1 $action2 ... $actionN)
----

[cols="1,3"]
|===
| `$action`
| An output action.
|===

**Description**

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.

==== reverse-release-order

**Reference**

String item that can be used inside of `(multi ...)`
to reverse the release order of any keys that were pressed
as part of `multi`.

.Syntax:
[source]
----
(multi ... reverse-release-order)
----

**Description**

Within `multi` you can use include `reverse-release-order`
to do what the action states: reverse the typical release order from
if you have multiple keys in multi.

For example, pressing then releasing a key with the action:
`(multi a b c)` would press a b c in the stated order
and then release a b c in the stated order.
Changing it to `(multi a b c reverse-release-order)`
would press a b c in the stated order
and then release c b a in the stated order.

.Example:
[source]
----
(defalias
  S-a-reversed (multi lsft a reverse-release-order)
)
----

[[mouse-actions]]
=== Mouse actions

You can click the left, middle, and right buttons using kanata actions, do
vertical/horizontal scrolling, and move the mouse.

[[mouse-buttons]]
==== Mouse buttons

**Reference**

You can activate mouse actions with the string actions below.

[cols="1,5"]
|===
| `mlft`
| Hold left mouse button.

| `mmid`
| Hold middle mouse button.

| `mrgt`
| Hold right mouse button.

| `mfwd`
| Hold forward mouse button.

| `mbck`
| Hold backward mouse button.

| `mltp`
| Tap left mouse button.

| `mmtp`
| Tap middle mouse button.

| `mrtp`
| Tap right mouse button.

| `mftp`
| Tap forward mouse button.

| `mbtp`
| Tap backward mouse button.
|===

In Linux and Windows,
the hold actions can be used within `defsrc` and `deflayermap`
to remap mouse buttons like keyboard keys.

NOTE:
On Windows, the Kanata process must be restarted
for it to begin or to stop handling mouse events;
changing defsrc then live-reloading will not
begin handling mouse events
if defsrc previously did not have any mouse events in defsrc.

**Description**

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.
On Linux, Windows, and macOS,
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

**Reference**

The `mwheel-*` actions allow you to emulate a mouse wheel.
Holding the action will repeatedly scroll
according to the action configuration.

.Syntax:
[source]
----
(mwheel-$variant $interval $distance)
----

[cols="1,4"]
|===
| `$variant`
| One of `up down left right` representing the scroll direction to use.

| `$interval`
| Number of milliseconds between scroll actions.

| `$distance`
| Distance to travel per activation.
The number `120` represents a complete notch on
standard resolution mice and in some environments,
120 or a multiple of it should be what is used.
|===

You may use these key names within `defsrc`
to remap scroll events as if they were keys,
corresponding to up, down, left, right respectively:
`mwu`, `mwd`, `mwl`, `mwr`.

The remapping of mouse button and wheel events is effective on Linux, Windows, and macOS.

NOTE:
On Windows, the Kanata process must be restarted
for it to begin or to stop handling mouse events;
changing defsrc then live-reloading will not
begin handling mouse events
if defsrc previously did not have any mouse events in defsrc.
On macOS, live-reload can install the mouse event tap on the fly
when a new config introduces mouse keys, but stopping the tap
once installed still requires a restart.
Mouse input on macOS requires Accessibility or Input Monitoring
permission in System Settings > Privacy & Security.

**Description**

The mouse wheel actions are:

* `mwheel-up` or `🖱☸↑`: vertical scroll up
* `mwheel-down` or `🖱☸↓`: vertical scroll down
* `mwheel-left` or `🖱☸←`: horizontal scroll left
* `mwheel-right` or `🖱☸→`: 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 Linux and Windows, 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 Windows, 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-wheel-inertial]]
===== Mouse wheel: inertial variants

**Reference**

The `mwheel-accel-*` actions allow you to emulate a mouse wheel,
with "inertial" properties,
meaning scroll speed accelerates while active and decelerates when not.
You can adjust factors of acceleration and deceleration.

.Syntax:
[source]
----
(mwheel-accel-$variant $initial-velocity $maximum-velocity $acceleration-multiplier $deceleration-multiplier)
----

[cols="2,3"]
|===
| `$variant`
| One of `up down left right` representing the scroll direction to use.

| `$initial-velocity`
| Starting scroll speed, in arbitrary units.
Suggested starting point: `3`.

| `$maximum-velocity`
| Starting scroll speed, in arbitrary units.
Suggested starting point: `1200`.

| `$acceleration-multiplier`
| Determines acceleration rate of scroll speed.
Suggested starting point: `1.15`.

| `deceleration-multiplier`
| Determines deceleration rate of scroll speed.
Suggested starting point: `0.93`.
Setting to 0 will make scroll stop abruptly.
|===

**Description**

An alternative scrolling action can be used via `mwheel-accel-*`.
This action has "inertial" behaviour which you may prefer.

The recommended starting point for the parameters are as below:

.Example configuration:
[source]
----
(defvar
  mw-initial-v 3
  mw-maximum-v 1200
  mw-accel 1.15
  mw-decel 0.93)
(defalias
  mwu (mwheel-accel-up   $mw-initial-v $mw-maximum-v $mw-accel $mw-decel)
  mwd (mwheel-accel-down $mw-initial-v $mw-maximum-v $mw-accel $mw-decel))
----

[[mouse-movement]]
==== Mouse movement

**Reference**

The `movemouse-*` actions allow you to move the mouse cursor.
Holding the action will repeatedly move the cursor
according to the configuration.

.Syntax:
[source]
----
(movemouse-$variant $interval $distance)
----

[cols="1,4"]
|===
| `$variant`
| One of `up down left right` representing the direction to move.

| `$interval`
| Number of milliseconds between move activations.

| `$distance`
| Distance to travel per activation in unit of pixels.
|===

There is a move mouse variant that increases distance per activation
at a constant rate until a maximum is reached.

.Syntax:
[source]
----
(movemouse-accel-$variant $interval $acceleration-time $min $max)
----

[cols="1,4"]
|===
| `$variant`
| One of `up down left right` representing the direction to move.

| `$interval`
| Number of milliseconds between move activations.

| `$acceleration-time`
| Number of milliseconds until max distance per activation is reached.

| `$min`
| Initial distance to travel per activation in unit of pixels.

| `$max`
| Maximum distance to travel per activation in unit of pixels.
|===

**Description**

The mouse movement actions are:

* `movemouse-up` or `🖱↑`
* `movemouse-down` or `🖱↓`
* `movemouse-left` or `🖱←`
* `movemouse-right` or `🖱→`

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` or `🖱accel↑`
* `movemouse-accel-down` or `🖱accel↓`
* `movemouse-accel-left` or `🖱accel←`
* `movemouse-accel-right` or `🖱accel→`

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

The action `setmouse` or `set🖱` sets the absolute mouse position.

WARNING: This is not supported on Linux.
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 coordinate system is platform-specific:

* **macOS**: Pixel coordinates. `0,0` is the top-left of the main display,
  maximum values are your screen resolution (e.g., `1920,1080`).
* **Windows**: Normalized coordinates from `0,0` (top-left)
  to `65535,65535` (bottom-right). Multiple monitors are treated as one virtual desktop.

Experimentation will be needed to find the correct values for your setup.

[[mouse-speed]]
==== Modify the speed of mouse movements

The action `movemouse-speed` or `🖱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

[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

**Reference**

The `tap-dance` action allows performing different actions
based on number of consecutive taps of the same key.

.Syntax:
[source]
----
(tap-dance $timeout $action-list)
----

[cols="1,4"]
|===
| `$timeout`
| Number of milliseconds after which the tap-dance ends.

| `$action-list`
| A list of actions that can be selected, ordered by number of taps.
|===

The `tap-dance-eager` variant will eagerly perform actions.
Use of `macro` and `bspc` can help to backtrack for the 2nd tap onwards.

.Syntax:
[source]
----
(tap-dance-eager $timeout $action-list)
----

**Description**

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

**Reference**

Activate keys or layers for a time without keeping the input key held,
for one subsequent key.
Activating other one-shot actions,
while one or more are already active,
will reset the timeout,
and overlap the one-shot actions.


.Syntax:
[source]
----
($one-shot-variant $timeout $action)
----

Values for `$variant`:
[cols="1,3"]
|===
| `one-shot-press`
| End on the first press of another key.
This is also the variant selected by the name `one-shot`.

| `+one-shot-release+`
| End on the first release of a newly pressed key.

| `+one-shot-press-pcancel+`
| End on the first press of another key
  or on re-press of this key, or of another active one-shot key

| `+one-shot-release-pcancel+`
| End on the first release of a newly pressed key
  or on re-press of this key, or of another active one-shot key.
|===

Other items:
[cols="1,3"]
|===
| `$timeout`
| Number of milliseconds after which
if not deactivated due to user input,
one-shot will deactivate on its own.

| `$action`
| Layer action, key, or output chord.
|===

**Description**

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 `+@os2+` 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+` or `+one-shot↓+`:
  end on the first press of another key
- `+one-shot-release+` or `+one-shot↑+`:
  end on the first release of another key
- `+one-shot-press-pcancel+` or `+one-shot↓⤫+`:
  end on the first press of another key
  or on re-press of another active one-shot key
- `+one-shot-release-pcancel+` or `+one-shot↑⤫+`:
  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+`.

NOTE: When using one-shot with keys that will trigger defoverrides,
you will likely want to adjust <<override-release-on-activation>> to yes in `defcfg`.

.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)
)
----

[[one-shot-pause-processing]]
==== one-shot-pause-processing

**Reference**

Pause `one-shot` processing of new input keypresses for a time,
to allow actions that are not intended to consume `one-shot`
to take place.

.Syntax:
[source]
----
(one-shot-pause-processing $time)
----

[cols="1,5"]
|===
| `time`
| Number of milliseconds to ignore processing.
Something notable is that one virtual key press or releas
(tap is a separate press and subsequent release)
will take 1ms to process.
If using virtual keys this number must be larger
than the number of virtual key events that are taking place.
|===

**Description**

The `one-shot-pause-processing` list action allows you to pause the
key press processing of one-shot activations.
An example of when this is useful the following sequence:

- Activate a layer-while-held
- Activate a one-shot action on that layer
- Release the layer-while-held key, which has an `(on-release ...)` action
  associated with it.
- The on-release action is not intended to consume one-shot activations

In the scenario above, by default the on-release activation
would trigger deactivation of one-shot;
thus the pause processing action must be used to stop this from happening.

[[tap-hold]]
=== tap-hold

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 ...))`.
If multiple `tap-hold` actions may be pressed subsequently,
all using the `f24` workaround,
you may need to release the `f24` within the same `multi`
to avoid repeats from one double-tapped `tap-hold` action
followed by another, different `tap-hold` action.
Example:
`(defvirtualkeys relf24 (release-key f24)) ... (multi f24 (tap-hold ...) (macro 5 (on-press tap-vkey relf24)))`

**Reference**

The `tap-hold` action lets you activate different actions
depending if a key is tapped or held.

.Syntax:
[source]
----
(tap-hold $tap-repress-timeout $hold-timeout $tap-action $hold-action)
----

[cols="1,4"]
|===
| `$tap-repress-timeout`
| Number of milliseconds for the window that a tap into re-press with hold
results in the `$tap-action` being held.

| `$hold-timeout`
| Number of milliseconds after which the `$hold-action` activates.
Releasing the key before this elapses
results in `$tap-action` activating.

| `$tap-action`
| Action to activate when the input is determined to be a "tap".

| `$hold-action`
| Action to activate when the input is determined to be a "hold".
|===

.Variants:
----
(tap-hold-press $tap-repress-timeout $hold-timeout $tap-action $hold-action)
(tap-hold-release $tap-repress-timeout $hold-timeout $tap-action $hold-action)
(tap-hold-press-timeout $tap-repress-timeout $hold-timeout $tap-action $hold-action $timeout-action)
(tap-hold-release-timeout $tap-repress-timeout $hold-timeout $tap-action $hold-action $timeout-action [?reset-timeout-on-press])
(tap-hold-release-keys $tap-repress-timeout $hold-timeout $tap-action $hold-action $tap-keys)
(tap-hold-release-tap-keys-release $tap-repress-timeout $hold-timeout $tap-action $hold-action $tap-trigger-keys-on-press $tap-trigger-keys-on-press-then-release)
(tap-hold-except-keys $tap-repress-timeout $hold-timeout $tap-action $hold-action $tap-keys)
(tap-hold-tap-keys $tap-repress-timeout $hold-timeout $tap-action $hold-action $tap-keys)
(tap-hold-keys $tap-repress-timeout $hold-timeout $tap-action $hold-action [options...])
(tap-hold-opposite-hand $timeout $tap-action $hold-action [options...])
(tap-hold-opposite-hand-release $timeout $tap-action $hold-action [options...])
(tap-hold-order $tap-repress-timeout $buffer-ms $tap-action $hold-action [options...])
----

[cols="1,2"]
|===
| `tap-hold-press`
| Activate `$hold-action` early if held and another input key is pressed.

| `tap-hold-release`
| Activate `$hold-action` early if held and another input key is pressed and released.

| `tap-hold-press-timeout`
| Activate `$hold-action` if held and another input key is pressed.
If the defined timeout elapses, `$timeout-action` will activate.

| `tap-hold-release-timeout`
| Activate `$hold-action` early if held and another input key is pressed and released.
If the defined timeout elapses, `$timeout-action` will activate.
Optionally include `reset-timeout-on-press` to reset timeout duration on a new press,
giving more time for a subsequent release to activate hold instead of timeout.

| `tap-hold-release-keys`
| Activate `$hold-action` early if held and another input key is pressed and released.
The `$tap-keys` parameter is a list of key names.
Activates `$tap-action` early if a key within `$tap-keys` is pressed before hold activates.

| `tap-hold-release-tap-keys-release`
| Activate `$hold-action` early if held and another input key is pressed and released.
The `$tap-keys-...` parameters are lists of key names.
Activate `$tap-action` early
if a key within `$tap-trigger-keys-on-press`
is pressed before hold activates
Activate `$tap-action` early
if a key within `$tap-trigger-keys-on-press-then-release`
is pressed then released before hold activates.

| `tap-hold-except-keys`
| The `$tap-keys` parameter is a list of key names.
Activates `$tap-action` if a key within `$tap-keys` is pressed
or if the action key is released before hold timeout.
No key is ever output until the action key is released
or another key is pressed,
which differs from the default `tap-hold` behaviour.

| `tap-hold-tap-keys`
| The `$tap-keys` parameter is a list of key names.
Activates `$tap-action` early if a key within `$tap-keys` is pressed before hold activates.
Unlike `tap-hold-release-keys`, does NOT activate `$hold-action` early
when other keys are pressed and released.
Waits for full `$hold-timeout` before activating `$hold-action`.
This is useful for home row mods where fast typing should not trigger modifiers.

| `tap-hold-keys`
| A flexible tap-hold variant with named key list options.
Options are: `(tap-on-press <keys...>)` activates `$tap-action` early if a listed key is pressed;
`(tap-on-press-release <keys...>)` activates `$tap-action` early if a listed key is pressed then released;
`(hold-on-press <keys...>)` activates `$hold-action` early if a listed key is pressed.
For any other key: if that key is pressed and released while this key is waiting,
`$hold-action` is triggered early (PermissiveHold behavior).
All list options are optional.

| `tap-hold-opposite-hand`
| Resolves to `$hold-action` when a key from the opposite hand (per `defhands`) is pressed.
Requires a `defhands` directive. Supports list-form options for fine-grained control.
See <<defhands and tap-hold-opposite-hand>> below.

| `tap-hold-opposite-hand-release`
| Like `tap-hold-opposite-hand` but waits for the interrupting key to be pressed AND released
before committing. This avoids misfires on fast same-hand rolls where keystrokes briefly overlap.
Requires a `defhands` directive. Supports the same options as `tap-hold-opposite-hand`.

| `tap-hold-order`
| Resolves purely by key release order, with no timeout.
If the tap-hold key is released before the other key, activates `$tap-action`;
if the other key is released first (while the tap-hold key is still held), activates `$hold-action`.
`$buffer-ms` is a grace period after the tap-hold key is pressed during which
release-order logic is ignored so that fast typing resolves as tap.
Optionally, `(require-prior-idle <ms>)` can short-circuit to tap when a different key
was pressed within that many milliseconds before the tap-hold key;
`require-prior-idle` checks prior typing activity before release-order logic begins,
whereas `buffer-ms` creates an unconditional tap-only window after the key is pressed.
This option is available on all tap-hold variants; see <<tap-hold-require-prior-idle>>.
|===

All `tap-hold` variants support an optional trailing `(require-prior-idle <ms>)` option
to override the global <<tap-hold-require-prior-idle>> setting for that specific action.
Use `(require-prior-idle 0)` to disable idle detection for a specific key.

**Description**

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.

NOTE: for more discussion on tap-hold,
you may want to have a look at this GitHub discussion:
https://github.com/jtroo/kanata/discussions/1455[link to discussion].

The action takes 4 parameters in the listed order:

. tap repress timeout (unit: ms)
. hold timeout (unit: ms)
. tap action
. hold action

The tap repress 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 repress timeout in more detail
[%collapsible,indent=4]
====
The way a `tap-hold` action works with respect to the tap repress timeout
is often unclear to newcomers.
To make it concrete, the output event sequence of the `tap-hold` action
`(tap-hold $tap-repress-timeout 200 a lctl)`
for varying values of `$tap-repress-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-repress-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-repress-timeout` values
between and including `0` and `99`.

For a value of `100` or greater for `$tap-repress-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+` or `+tap⬓↓+`
** 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+` or `+tap⬓↑+`
** 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` or `tap⬓↓timeout`
- `tap-hold-release-timeout` or `tap⬓↑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.

The `release` variant also accepts an optional 6th argument,
`reset-timeout-on-press` which if included changes the timeout behaviour.
This flag will make the timeout duration reset if a new key is pressed.
This may result in longer timeouts,
but can help with more consistent hold activations;
because it may be challenging to release a key in time
to activate the hold action instead of the timeout action.

- `tap-hold-release-keys` or `tap⬓↑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: 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-release-tap-keys-release`

This variant behaves nearly the same as `tap-hold-release-keys`,
but has another condition with respect to the eager tap.
It accepts a second list that activates the eager tap
if the any key listed within is pressed then released;
as opposed to only on a press.

The keys in the 5th and 6th parameters 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: u    hold: misc layer      early tap if any of:
  ;;                                 (z x c v) are pressed, OR
  ;;                                 (a s d f) are pressed THEN released
  umk2 (tap-hold-release-tap-keys-release 200 200 u @msc (z x c v) (a s d f))
)
----

- `tap-hold-except-keys` or `tap-hold⤫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: 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))
)
----

- `tap-hold-tap-keys` or `tap⬓tapkeys`

This variant takes a 5th parameter which is a list of keys
that trigger an early tap when they are pressed.
Unlike `tap-hold-release-keys`, pressing and releasing other keys
does NOT activate hold early - the full hold timeout is always waited.
This is useful for home row mods where fast typing should not trigger modifiers.

The keys in the 5th parameter correspond to the physical input keys,
or in other words the key that corresponds to `defsrc`.

.Example:
[source]
----
(defalias
  ;; tap: a    hold: lsft    early tap if any of: (s d f) are pressed
  ;; other keys do NOT trigger early hold
  ath (tap-hold-tap-keys 200 200 a lsft (s d f))
)
----

==== defhands and tap-hold-opposite-hand

`defhands` assigns physical keys to `left` / `right` hand groups.
`tap-hold-opposite-hand` uses this to resolve hold when the next key
is on the opposite hand — reducing misfires compared to manual key lists.

[source]
----
(defhands
  (left  q w e r t a s d f g z x c v b)
  (right y u i o p h j k l ; n m , . /))

(defalias
  fctl (tap-hold-opposite-hand 180 f lctl))
----

`defhands` rules: at most one block; each group (`(left ...)`/`(right ...)`) at most once;
a key cannot appear in both groups; partial definitions (only one hand) are allowed;
unlisted keys have no hand assignment.

`tap-hold-opposite-hand` takes `$timeout $tap-action $hold-action` followed by
optional option lists. Most use `(name value)`, while `neutral-keys` uses
followup key atoms: `(neutral-keys spc tab ...)`.
It requires `defhands` to be defined.
Internally it uses the same `HoldTapConfig::Custom` machinery as `tap-hold-release-keys`.

[cols="1,1,1,2"]
|===
| Option | Values | Default | Description

| `(timeout <value>)` | `tap`, `hold` | `tap` | Action when hold timeout elapses (optimized for home-row-mod behavior).
| `(same-hand <value>)` | `tap`, `hold`, `ignore` | `tap` | Action when a same-hand key is pressed.
| `(neutral-keys key ...)` | one or more key names | (empty) | Keys treated as neutral, overriding their `defhands` assignment.
| `(neutral <value>)` | `tap`, `hold`, `ignore` | `ignore` | Action when a `neutral-keys` key is pressed.
| `(unknown-hand <value>)` | `tap`, `hold`, `ignore` | `ignore` | Action when a key not in `defhands` is pressed.
| `(require-prior-idle <ms>)` | `0`–`65535` | (disabled) | If a key was pressed within this many ms before the tap-hold key, resolve as tap immediately. Useful for avoiding accidental holds during fast typing.
| `(tap-repress-timeout <ms>)` | `0`–`65535` | `0` | If the same key is re-pressed within this many ms after a tap, immediately tap again instead of entering the hold decision. `0` disables (every press enters the hold decision). See <<tap-hold,tap repress timeout>> for details.
|===

When a value is `ignore`, that key press is skipped and the action
waits for the next key or timeout.

Example with options:
[source]
----
(defalias
  fctl (tap-hold-opposite-hand 180 f lctl
    (same-hand ignore)
    (timeout hold)
    (neutral-keys spc tab)
    (neutral tap)))
----

See `cfg_samples/opposite-hand-hrm.kbd` for a full working example.

[[macro]]
=== macro

**Reference**

The macro action taps the configured sequence of keys or actions.
Numbers can be used to delay the sequence by the defined number of milliseconds.

.Syntax:
[source]
----
(macro $macro-action1 $macro-action2 ... $macro-actionN)
----

[cols="1,4"]
|===
| `$macro-action`
| A delay, key, action within the subset allowed within macros,
or an output-chord-prefixed list of more macro-actions.
|===

.Variants:
----
(macro-release-cancel ...)
(macro-cancel-on-press ...)
(macro-release-cancel-and-cancel-on-press ...)
(macro-repeat ...)
(macro-repeat-$cancel-variant ...)
----
[cols="1,2"]
|===
| `macro-release-cancel`
| Cancel all active macros if the key is released.

| `macro-cancel-on-press`
| Cancel all active macros if a different key is pressed.

| `macro-release-cancel-and-cancel-on-press`
| Cancel all active macros if either the key is released or a different key is pressed.

| `macro-repeat`
| Repeat the macro while held.

| `macro-repeat-$cancel-variant`
| Repeat the macro while held.
Cancels the final repeat according the behaviour of one of the variants:
`release-cancel`, `cancel-on-press`, `release-cancel-and-cancel-on-press`.
|===

**Description**

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.

IMPORTANT: The number keys `0-9` will be parsed as millisecond delays
whereas in other contexts they would be parsed as key names.
To use the numbered keys they must be aliased
or otherwise use the key names `Digit0-Digit9`.

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>>
* <<virtual-keys,virtual key actions>>
* <<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))
)
----

[[macro-release-cancel]]
==== macro-release-cancel

The `macro-release-cancel` variant of the `+macro+` action
will cancel all active macros
upon releasing the key.
Shorter unicode variant: `+macro↑⤫+`.
This variant 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)
)
----

[[macro-cancel-on-press]]
==== macro-cancel-on-press

The `macro-cancel-on-press` variant of the `macro action`
enables a cancellation trigger for all active macros including itself,
which is activated when a physical press of any other key happens.
The trigger is enabled while the macro is in progress.

[source]
----
(defalias
  1 1
  1!@ (macro-cancel-on-press @1 500 bspc S-1 500 bspc S-2)
)
----

[[macro-release-cancel-and-cancel-on-press]]
==== macro-release-cancel-and-cancel-on-press

The `macro-release-cancel-and-cancel-on-press` variant
combines the cancel behaviours
of both the release-cancel and cancel-on-press.

[source]
----
(defalias
  1 1
  1!@ (macro-release-cancel-and-cancel-on-press @1 500 bspc S-1 500 bspc S-2)
)
----


[[macro-repeat]]
==== macro-repeat

There are further `macro-repeat` variants of the three `macro` actions described previously.
These variants 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)
  mr3 (macro-repeat-cancel-on-press mltp)
  mr4 (macro-repeat-release-cancel-and-cancel-on-press mltp)
)
----

[[dynamic-macro]]
=== dynamic-macro

**Reference**

Record and replay key inputs.

.Syntax:
[source]
----
(dynamic-macro-record $id)
(dynamic-macro-play   $id)
(dynamic-macro-record-stop)
(dynamic-macro-record-stop-truncate $count)
----

[cols="1,3"]
|===
| `dynamic-macro-record`
| Record a dynamicro macro which will be saved with the defined `$id`.

| `dynamic-macro-play`
| Play back a macro saved with the defined `$id`.

| `dynamic-macro-record-stop`
| Stop and save a macro recording.
This can also be achieved by recording a new macro
or re-pressing record with the same `$id`.

| `dynamic-macro-record-stop-truncate`
| Stop and save a macro recording while truncating `$count` events
from the end of the recording.
This can be useful if the record/stop button is on a different layer.
|===

**Description**

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)
)
----

[[caps-word]]
=== caps-word

**Reference**

The `caps-word` action puts Kanata into a state where
typed keys are automatically shifted by `lsft`.
The state persists until terminated by timeout
or by typing a key that ends the state.
Typing a non-terminating key refreshes the timeout duration.

The `-toggle` variants will end the caps-word state
if pressed while caps-word is active,
whereas the re-pressing the standard variants
will keep the state active and refresh the timeout duration.

.Syntax:
[source]
----
(caps-word $timeout)
(caps-word-toggle $timeout)
(caps-word-custom $timeout $shifted-list $non-terminal-list)
(caps-word-custom-toggle $timeout $shifted-list $non-terminal-list)
----

[cols="1,4"]
|===
| `$timeout`
| Number of milliseconds after which the caps-word state ends.
The duration is refreshed upon typing a non-terminating character.

| `$shifted-list`
| List of keys that will be automatically shifted.

| `$non-terminal-list`
| List of keys that are not shifted
but which do not terminate the caps-word state.
|===

**Description**

The `caps-word` or `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` or `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).

.Example:
[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)
  )
)
----

==== caps-word-toggle[[caps-word-toggle]]

There are `-toggle` variants of the `caps-word` actions.
By default re-pressing `caps-word` will keep `caps-word` active.
The `-toggle` variants will end `caps-word` if it is currently active,
otherwise `caps-word` will be activate as normal.

.Example:
[source]
----
(defalias
  cwt (caps-word-toggle 2000)
  cct (caps-word-custom-toggle
    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]]

**Reference**

The `unmod` action will deactivate modifier keys while outputting
one or more defined keys.

.Syntax:
[source]
----
(unmod $key1 $key2 ... $keyN)
(unmod ($mod1 $mod2 ... $modN) $key1 $key2 ... $keyN)
----

[cols="1,5"]
|===
| `$key`
| A key name to output while unmodded.

| `$mod`
| By default `unmod` will deactivate all modifier keys.
An optional list as the first parameter
allows specfying a subset of modifiers to deactivate during the action.
|===

**Description**

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 affected modifiers are: `lsft,rsft,lctl,rctl,lmet,rmet,lalt,ralt`.

A variant of `unmod` is `unshift` or `un⇧`.
This action only releases the `lsft,rsft` keys.
This can be useful for forcing unshifted keys while AltGr is still held.

NOTE: In case the modifiers to be undone are not part of `defsrc`,
<<process-unmapped-keys>> needs to be enabled in `defcfg` in order for their
states to be tracked correctly.

.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)
)
----

A list may optionally be used as the first parameter of `unmod`.
The list must be non-empty and must contain only modifier keys,
which are the keys in the affected modifiers list from earlier in this document section.

When this list exists, the action will temporarily release only the keys listed
rather than all modifiers.

.Example:
[source]
----
(defalias
	;; only unshift the alt keys
	unalt-a (unmod (lalt ralt) a)
)
----

[[fork]]
=== fork

**Reference**

The `fork` action allows choosing between a default and an alternate action
based on whether specific keys are active. `fork` is the equivalent of the
basic key checks in `switch`, using none of the list logic items, i.e. virtual
keys are not supported.

.Syntax:
[source]
----
(fork $left-action $right-action $right-trigger-keys)
----

[cols="1,3"]
|===
| `$left-action`
| Action to activate by default.

| `$right-action`
| Action to activate if any of `$right-trigger-keys` are active.

| `$right-trigger-keys`
| List of keys that, if active when fork activates,
causes `$right-action` to happen in place of `$left-action`.
|===

TIP: The keys `nop0-nop9` can be used as no-op outputs that
can still be checked within `fork`, unlike what `XX` does.

[[switch]]
=== switch

**Reference**

The `switch` action allows conditionally activating 0 or more actions,
depending on conditional checks.

.Syntax:
[source]
----
(switch
  $logic-check1 $action1 $post-activate1
  $logic-check2 $action2 $post-activate2
  ...
  $logic-checkN $actionN $post-activateN)
----

[cols="1,4"]
|===
| `$logic-check`
| The condition, which if it evaluates to true,
will trigger the corresponding action.

| `$action`
| Action to activate when logic evaluates to true.

| `$post-activate`
| Valid values are `fallthrough` and `break`.
With `fallthrough`, when an action activates
switch will continue evaluating further logic checks
and potentially trigger more actions.
With `break`, further actions will not activate.
|===

The logic check is a list.
The items within the list can either be key names or a special list check.
A key name item evaluates to true if that key name
is a currently active key output of Kanata upon activating `switch`.
The outer-most list evaluates to true
if any of the items evaluates to true.

.Syntax of logic check:
[source]
----
($item1 $item2 ... $itemN)
----

.Syntax of special checks:
[source]
----
(or  $item1 $item2 ... $itemN)
(and $item1 $item2 ... $itemN)
(not $item1 $item2 ... $itemN)
(key-history $key-name $key-recency)
(key-timing  $key-recency $comparator $time)
(input         $input-type $key-name)
(input-history $input-type $key-name $input-recency)
(layer      $layer-name)
(base-layer $layer-name)
(device-history $device-id $device-recency)
(cmd-exit   $exit-code)
----

[cols="1,4"]
|===
| `or`
| Evaluates to true if any `$item` is true.

| `and`
| Evaluates to true if all of `$item` are true.

| `not`
| Evaluates to true if all of `$item` are false.

| `key-history`
| Evaluates to true if the key in the recency slot matches `$key-name`.
A `$key-recency` of 1 is the most recent key pressed according to Kanata processing.
The max recency is 8.

| `key-timing`
| The valid values for `$comparator` are `less-than` and `greater-than`,
with `lt` and `gt` as shorthand if desired.
This item evaluates to true if the key with the corresponding recency
was pressed — for `lt` more recently than, or for `gt` later than —
the defined `$time` with unit milliseconds.

| `input`
| Evaluates to true if the `$key-name` is currently pressed.
The `$input-type` must be either `real` or `virtual`.
If using `real`, this will check against the defsrc inputs.
If using `virtual`, this will check against virtual key activations.

| `input-history`
| Evaluates to true if the input in the `$input-recency` slot matches `$key-name`.
Two input types use the same history with respect to recency slots.
A recency of 1 is the most recent input i.e. the input activating `switch` itself.
The max recency is 8.

| `layer`
| Evaluates to true if the active layer matches `$layer-name`.

| `base-layer`
| Evaluates to true if the most-recently-switched-to layer
from a `layer-switch` action matches `$layer-name`.

| `device-history`
| Evaluates to true if the device in the `$device-recency` slot
matches `$device-id`. A recency of 1 is the most recent device
that sent an event. The max recency is 8.
Device IDs are defined via <<definputdevices,`definputdevices`>>.
Currently supported on macOS only.

| `cmd-exit`
| Requires a binary compiled with `cmd` enabled.
| Evaluates to true if the process exit code of the most recent `init-cmd` matches `$exit-code`.
  The `$exit-code` parameter must be a 32 bit signed integer.
|===

.Syntax of optional `switch` argument `init-cmd`:
[source]
----
(switch
  (init-cmd $binary $arg1 $arg2 ... $argN)
  $logic-check1 $action1 $post-activate1 ...)
----

**Description**

Conceptually, the `switch` action is similar to <<fork>>
but has more capabilities as well as more complexity.
The `switch` action accepts multiple cases.
One case is a triple of:

- logic check
- action: to activate if logic check evaluates to true
- `fallthrough|break`: choose to continue vs. stop evaluating cases

The default use of the logic check behaves similarly to fork.

For example, the logic check `(a b c)` will activate the corresponding action
if any of a, b, or c are currently pressed.

TIP: the keys `nop0-nop9` can be used as no-op outputs that
can still be checked within `switch`, unlike what `XX` does.

The logic 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 logic check to some other common languages
might look like:

----
(a && b && (c || d) && (e || f))
----

If the logic 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 logic check passes and the case 1 does not pass,
the action `@ac2` will activate first.
Since the logic check of case 3 always passes, `@ac3` will activate next.

If neither case 1 or case 2 pass their logic 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 logic 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 approximately 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.
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.
In other words recency `1` is the input activating the `switch` action itself.
Whereas with `key-history` for example, the key that will be next outputted
may be determined by the switch logic itself, 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
  )
)
----

==== layer

The `layer` list item can be used in `switch` logic to operate on the active layer.
It accepts a single layer name
and evaluates to true if the configured layer name is the active layer,
otherwise it evaluates to false.

.Example:
[source]
----
(defalias switch-layer-example
  (switch
     ((layer base)) x break
    ((layer other)) y break
                 () z break
  )
)
----

==== base-layer

The `base-layer` list item evaluates to true
if the configured layer name is the base layer.
The base layer is the most recently switched-to layer
from a `layer-switch` action,
or the first layer defined in your configuration
if `layer-switch` has never been activated.

.Example:
[source]
----
(defalias switch-layer-example
  (switch
     ((base-layer base)) x break
    ((base-layer other)) y break
                 () z break
  )
)
----

==== `init-cmd` and `cmd-exit`

With a <<cmd,cmd-enabled>> Kanata variant
you have access to the `init-cmd` optional switch parameter
which goes before the normal switch syntax.
This will execute a program synchronously,
blocking the rest of Kanata's execution until it completes.
What this enables is later use of `cmd-exit` logic item
which can output different actions based on which exit code is returned by the command.

.Example:
[source]
----
(defalias
  my-switch-with-cmd (switch
    (init-cmd powershell.exe -c "if (-not (Test-Path 'myfile')) { exit 1 }")
    ((cmd-exit 0)) a break
    ((cmd-exit 1)) b break
    () c break
  ))
----


[[cmd]]
=== cmd

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.

**Reference**

The `cmd` action allows you to execute arbitrary binaries with arbitrary arguments.
The `cmd-log` variant behaves similarly but allows customization
of the stdout and stderr log levels within Kanata's output logging.
The `cmd-output-keys` is like `cmd`, but stdout of the command
will be parsed as a list of keys, output chords, and delays similar to <<macro>>
and be typed as kanata outputs.

.Syntax:
[source]
----
(cmd $binary $arg1 $arg2 ... $argN)
(cmd-log $stdout-log-level $stderr-log-level)
(cmd-output-keys $binary $arg1 $arg2 ... $argN)
----

[cols="1,3"]
|===
| `$binary`
| Executable binary to run.

| `$arg`
| Argument passed into the binary.

| `$stdout-log-level`
| Log level for stdout of the command. Must be `+debug+`, `+info+`, `+warn+`, `+error+`, or `+none+`.

| `$stderr-log-level`
| Log level for stderr of the command. Must be `+debug+`, `+info+`, `+warn+`, `+error+`, or `+none+`.
|===

**Description**

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).

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`.

The user executing the command
is the user that kanata was started with.
For example, if kanata was started by root,
the command will be run by the root user.
If you need to execute as a different user,
on Unix platforms you can use `sudo -u USER`
before the rest of your command to achieve this.

.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")

  ;; You can prefix commands with sudo -u USER
  ;; to execute commands as a different user.
  cm3 (cmd sudo -u other_user bash -c "echo goodbye")
)
----

By default, `+cmd+` logs start of command, completion of command, stdout, and stderr.
Using the variant `+cmd-log+`, these log levels can be changed, and even disabled.
It takes two arguments, `+<log_level>+` and `+<error_log_level>+`. `+<log_level>+`
will be the level where the command to run, stdout, and stderr are logged.
The error channel is logged only if there is a failure with running the
command (typically if the command can't be found, or there is trouble spawning it).

The valid levels are `+debug+`, `+info+`, `+warn+`, `+error+`, and `+none+`.

.Example:
[source]
----
(defalias
  ;; The first two arguments are the log levels, then just the normal command
  ;; This will only error if `bash` is not found or something else goes
  ;; wrong with the initial execution. Any logs produced by bash will not
  ;; be shown.
  noisy-cmd (cmd-log none error bash -c "echo hello this produces a log")

  ;; This will only log the output of the command, but it won't start
  ;; because the command doesn't exist.
  ignore-failure-cmd (cmd-log info none thiscmddoesnotexist)

  verbose-only-log (cmd-log verbose verbose bash -c "echo yo")
)
----

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 delays, keys, chords, and
chorded lists are supported. 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-;') ')'")
)
----

[[push-msg]]
=== push-msg

NOTE: This action requires the TCP server to be enabled via the
<<args-port,`-p` / `--port`>> command line argument.
If used without the TCP server enabled, a warning will be logged
and the action will have no effect.

**Reference**

The `push-msg` action sends an arbitrary message to all connected TCP clients.
This enables communication between your keyboard configuration and external tools
without the security risks or performance overhead of executing shell commands.

.Syntax:
[source]
----
(push-msg $message)
----

[cols="1,3"]
|===
| `$message`
| A string or S-expression to send to TCP clients.
  Strings are sent as-is; S-expressions are converted to JSON arrays.
|===

**Description**

The `push-msg` action broadcasts a message to all TCP clients connected to Kanata's
TCP server. This is useful for:

- Triggering external tool actions from keyboard shortcuts
- Layer change notifications to status bars or tray applications
- Integration with automation tools like Raycast, Alfred, or Hammerspoon
- Controlling other applications without spawning shell processes

Messages are sent as newline-terminated JSON in the format:

[source,json]
----
{"MessagePush":{"message":"your-message-here"}}
----

Compared to the <<cmd>> action, `push-msg` offers:

- **Better security**: No shell execution, no privilege escalation risks
- **Better performance**: Sub-millisecond latency vs ~100ms for command execution
- **No special flags**: Does not require `danger-enable-cmd` in defcfg

.Example - Basic messages:
[source]
----
(defalias
  ;; Send a simple string message
  notify (push-msg "key-pressed")

  ;; Send layer change notification
  nav-on (push-msg "layer:nav:activated")
  nav-off (push-msg "layer:nav:deactivated")
)
----

.Example - Integration with external tools:
[source]
----
(defalias
  ;; Trigger a Raycast extension
  raycast-clip (push-msg "raycast:clipboard-history")

  ;; Control media playback via external script
  play-pause (push-msg "media:toggle")
  next-track (push-msg "media:next")

  ;; Switch keyboard layouts via external tool
  layout-next (push-msg "xkb:next-layout")
)
----

.Example - Using with defvirtualkeys for external triggering:
[source]
----
;; Define virtual keys that can be triggered via TCP's ActOnFakeKey command
;; External tools can trigger these using: {"ActOnFakeKey":{"name":"email-sig","action":"Tap"}}
(defvirtualkeys
  email-sig (macro S-b e s t spc r e g a r d s , ret ret S-j o h n)
  nav-mode (layer-switch nav)
)

;; Combine push-msg with other actions
(defalias
  launch-term (multi
    (push-msg "app:launch:terminal")
    (layer-switch base)
  )
)
----

To receive these messages, connect a TCP client to Kanata's server port.
See the https://github.com/jtroo/kanata/blob/main/example_tcp_client/src/main.rs[example TCP client]
for implementation guidance.

[[clipboard-actions]]
=== clipboard actions

**Reference**

Clipboard actions can manipulate the operating system clipboard
alongside "save ids".
To paste, you would use an action such as `C-v`;
Kanata has no builtin paste action.

.Syntax:
[source]
----
(clipboard-set   $clipboard-string)
(clipboard-save  $save-id)
(clipboard-restore    $save-id)
(clipboard-save-swap  $save-id $save-id)
(clipboard-cmd-set  $binary $arg1 $arg2 ... $argN)
(clipboard-save-cmd-set  $save-id $binary $arg1 $arg2 ... $argN)
----

[cols="1,3"]
|===
| `clipboard-set`
| Sets the clipboard to the specified string.

| `clipboard-save`
| Saves the current clipboard content with the specified ID.

| `clipboard-restore`
| Sets the clipboard to content saved with the specified ID.
If the save ID content is blank, this will do nothing.

| `clipboard-save-swap`
| Swaps the content of two save IDs.

| `clipboard-cmd-set`
| Sets the clipboard to the output of the command.
The current content of the clipboard is passed to stdin of the command
if the current content is text.
If the content is an image, nothing is passed to stdin.

| `clipboard-save-cmd-set`
| Sets the save ID content to the output of the command.
The current content of the save ID is passed to stdin of the command
if the current content is text.
If the content is an image, nothing is passed to stdin.

| `$clipboard-string`
| Fixed string to set the operating system clipboard to.

| `$save-id`
| A number `0-65535` representing an ID of saved clipboard content.

| `$binary`
| Executable binary to run.

| `$arg`
| Argument passed into the binary.
|===

**Description**

You can use clipboard actions to save clipboard content,
paste arbitrary content,
and then restore the original clipboard content.
This functionality is similar to what some text expanders do.
You can additionally use shell commands to manipulate
clipboard content in arbitrary ways.
This can all be done in a single command via <<macro>>.

Note that you will likely want to add delays in between components,
because clipboard systems take some time to propagate updates.

The example below is a macro that pastes the content of the clipboard
twice with a space in between,
while restoring the original clipboard content at the end.
Notable is that the example uses `C-v` but this may not work for you.
If you have OS-level remapping, the `v` may be different
to effectively paste.
Something that may also work is `S-ins`

.Example:
[source]
----
(macro
 (clipboard-save 0)
 20
 (clipboard-cmd-set powershell.exe -c r#"$v = ($Input | Select-Object -First 1); Write-Host -NoNewLine "$v $v""#)
 300
 C-v
 (clipboard-restore 0)
)
----

As another example you can use templates
with clipboard actions to have a convenient clipboard-based
text output while preserving the old clipboard content.
This can fit the use case of "text expansion".

.Example:
[source]
----
(deftemplate text-paste (text)
 (macro
  (clipboard-save 0)
  20
  (clipboard-set $text)
  300
  C-v
  (clipboard-restore 0)
 ))

(defalias
 myalias1 (t! text-paste "Hello world")
 myalias2 (t! text-paste "Goodbye my old friend")
)
----

[[arbitrary-code]]
=== arbitrary-code

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

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.

NOTE: Depending on your use case
you may want to adjust <<override-release-on-activation>> in `defcfg`.

.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
)
----

[[defoverridesv2]]
=== defoverridesv2

There is a more recent version of defoverrides that offers more customizability.
Instead of 2 list items per override entry,
`defoverridesv2` mandates 4, though the extra 2 can be empty.

You cannot have both a v1 and v2 of `defoverrides` at the same time.

The 3rd item is an "exclude modifiers list" which is composed of modifier key names
(such as `lctl`, `lalt`) that, if held, will disable the override from activating.

NOTE: if all excluded list modifiers are released while the
override input is still active, the override will activate.
You can avoid this by ensuring to always release the non-modifier key
before releasing any modifiers.

The 4th item is an "exclude layers" list which is composed of layer names
that while active as the most recent `layer-switch` or `layer-while-held`,
will disable the override from activating.

NOTE: if the layer changes while the override input is still active,
the override will activate.

.Example:
[source]
----
(defoverridesv2
  ;; lctl+a will become lalt+9
  ;; except when lsft is held or other-layer is active.
  (lctl a) (lalt 9) (lsft) (other-layer))

  ;; lctl+b will always become lalt+0
  (lctl b) (lalt 0) () ()
)
----

[[templates]]
== Templates

The top-level configuration item `deftemplate`
declares a template that can be expanded multiple times
via the list item `template-expand`.
The short form of `template-expand` is `t!`.

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) nop0) $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) nop0) f1) (lalt ralt)))
(defalias fn2 (template-expand alt-fork 2 f2))
;; You can use t! as a short form of template-expand
(defalias fn3 (t! 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)
;; t! is short for template-expand
(t! 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 (t! 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 (t! 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 conditionally-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.
(template-expand 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.
(template-expand 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.

== Include other files[[include]]

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.

Non-existing files will be ignored.

.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
  ;; ...
)
----

[[platform]]
== Platform-specific configuration

If you put any top-level configuration item
within a list beginning with `platform`,
it will become a platform-specific configuration
that is only active for the specified platforms.

.Syntax:
[source]
----
(platform (applicable-platforms) ...)
----

The valid values for applicable platforms are:

- `win`
- `winiov2`
- `wintercept`
- `linux`
- `macos`

.Example:
[source]
----
(platform (macos)
  ;; Only on macos, use command arrows to jump/delete words
  ;; because command is used for so many other things
  ;; and it's weird that these cases use alt.
  (defoverrides
    (lmet bspc) (lalt bspc)
    (lmet left) (lalt left)
    (lmet right) (lalt right)
  )
)

(platform (win winiov2 wintercept)
  (defalias run-my-script (cmd #| something involving powershell |#))
)

(platform (macos linux)
  (defalias run-my-script (cmd #| something involving bash |#))
)
----

[[environment]]
== Environment-conditional configuration

.Syntax:
[source]
----
(environment (env-var-name env-var-value) ...)
----

The items `env-var-name` and `env-var-value` can be arbitrary strings.
The name is the environment variable that is read
for determining if the configuration is used or not.
If the value of the environment variable (set only on kanata startup)
matches `env-var-value`, the configuration is used; otherwise it is ignored.
An empty string for `env-var-value` — `""` — will use the configuration
if the environment variable is an empty string
and also if the environment variable is not defined.

.Example:
[source]
----
(environment (LAPTOP lp1)
  (defalias met @lp1met)
)

(environment (LAPTOP lp2)
  (defalias met @lp2met)
)
----

.Set environment variables in the current terminal process:
[source]
----
# powershell
$env:VAR_NAME = "var_value"

# bash
VAR_NAME=var_value
----


[[input-chords-v2]]
== Input chords / combos (v2)

You may define a single `+defchordsv2+` configuration item.
This enables you to define global input chord behaviour.
One might also find this functionality called another name of "combos"
in other projects.

Input chords enables you to press two or more keys in quick succession
to activate a different action
than would normally be associated with those keys.
When activating a chord, the order of presses is not important;
when all keys belonging to a chord are pressed,
the action activates regardless of press order.

The `+defchordsv2+` feature is configured as shown below:

.Syntax example
[source]
----
(defchordsv2
  (participating-keys1) action1 timeout1 release-behaviour1 (disabled-layers1)
    ...
  (participating-keysN) actionN timeoutN release-behaviourN (disabled-layersN)
)
----

The configuration is made up of 5-tuples of:

[cols="1,3"]
|===
| `$participating-keys`
| These are key names you would use in `defsrc`.
A minimum of two keys must be defined per chord.
The list must be unique per chord.

| `$action`
| These are actions as you would configure in `deflayer` or `defalias`.
The action activates if all participating keys are activated
within the timeout.

| `$timeout`
| The time (unit: milliseconds) within which,
if all participating keys are pressed,
the chord action will activate;
otherwise the key presses are handled by the active layer.
The time begins when the first participant is pressed.

| `$release-behaviour`
| This must be either `first-release` or `all-released`;
`first-release` means the chord action will be released
when the first participant is released,
while `all-released` means the chord action will be released
only when all of the participants have been released.

| `$disabled-layers`
| A list of layer names on which this chord is disabled.
|===

Input chords have a related `defcfg` item: <<chords-v2-min-idle>>.
When any non-chord activation happens,
a timeout begins with duration configured by
`chords-v2-min-idle` (unit: milliseconds).
Until this timeout expires, all inputs will immediately skip
chords processing and be processed by the active layer.

IMPORTANT: When opting into input chords v2,
you must enable `concurrent-tap-hold`.
This is enforced for a more responsive `tap-hold` experience when
activated by a chord.

.Example:
[source]
----
(defcfg concurrent-tap-hold yes)
(defchordsv2
  (a s)    c                200 all-released  (non-chord-layer)
  (a s d) (macro h e l l o) 250 first-release (non-chord-layer)
  (s d f) (macro b y e)     400 first-release (non-chord-layer)
)
----

NOTE: Also see <<input-chords,v1 chords>>,
which are configured differently and can be defined per-layer.

[[chordsv2-processing-order]]
=== Action processing order

The chordsv2 system handles keys before any layer action handling.
This has a consequence of not entering the delay and interruption flow
of actions such as `tap-hold-release`.

If you want a chordsv2 action activation to be processed
by the aforementioned category of actions
you can move the action into a virtual key
(see <<virtual-keys>>) and have the chordsv2 action
press and release the virtual key.

See a sample below that showcases a reusable template.

.Example:
[source]
----
(defcfg concurrent-tap-hold yes)
(defsrc)
(deflayermap (base)
  caps (tap-hold-release 0 200 esc lctl))

;; defines a vkey named v-$key, example v-bspc
;; and an alias @v-bspc that press and and releases the v-key
;; within on-press and on-release respectively.
(deftemplate v- (key)
  (defvirtualkeys (concat v- $key) $key)
  (defalias (concat v- $key)
    (multi (on-press press-vkey (concat v- $key)) (on-release release-vkey (concat v- $key))))
)

(t! v- bspc)
(t! v- del)
(defchordsv2
  (j k) @v-bspc 75 first-release ()
  (s d) @v-del 75 first-release ()
)
----

[[definputdevices]]
== definputdevices

**Reference**

The optional `definputdevices` block maps user-chosen numeric device IDs
to physical input devices, enabling per-device key mappings via the
<<switch,`switch`>> action's `(device-history $id $recency)` condition.

.Syntax:
[source]
----
(definputdevices
  $id1 ($matcher1a $matcher1b ...)
  $id2 ($matcher2a ...)
  ...
)
----

[cols="1,4"]
|===
| `$id`
| An integer from 1-255 used to reference this device in `(device-history $id $recency)` conditions. The value is arbitrary; use `defvar` to give IDs meaningful names.

| `($matcher ...)`
| A list of matcher expressions. All matchers within an entry must match for a device to be assigned that ID (AND semantics).
|===

.Available matchers:
[cols="1,4"]
|===
| `(name "...")`
| Matches devices whose product name contains the given string.

| `(hash "...")`
| Matches devices whose hex hash equals the given string.
Use `kanata --list` to see device hashes.

| `(vendor_id N)`
| Matches devices with the given USB vendor ID. Valid values: decimal 0-65535, or hex `0x0-0xFFFF`.

| `(product_id N)`
| Matches devices with the given USB product ID. Valid values: decimal 0-65535, or hex `0x0-0xFFFF`.
|===

**Description**

`definputdevices` is useful when you have multiple keyboards with different
physical layouts and want to unify their behavior — for example, to remap
swapped modifier key positions between Ctrl, Meta, and Alt across devices.

The kanata-defined IDs are arbitrary numbers whose only purpose is referencing
within the `switch` action's `(device-history $id $recency)` condition.
Using `defvar` to name them is recommended for readability.

Device history only records press events (not release or repeat).
If a key is pressed on a device not listed in `definputdevices`, the history
slot will be recorded as "unknown" and will not match any device ID.

.Example:
[source]
----
(defvar
  id-AppleInternal 1
  id-Go60          2
)

(definputdevices
  $id-AppleInternal ((name "Apple Internal Keyboard"))
  $id-Go60 ((name "Go60") (vendor_id 0x1D50) (product_id 0x615E))
)

(defsrc a)
(deflayer base
  (switch
    ((device-history $id-AppleInternal  1)) x break
    ((device-history $id-Go60           1)) y break
    () a break))
----

In this example, pressing `a` on the internal keyboard outputs `x`,
pressing `a` on the Go60 outputs `y`, and pressing `a` on any other
device outputs `a`.

NOTE: Device IDs are matched at startup. Devices plugged in after kanata
starts will not be recognized. Live reload does not re-read device mappings.

NOTE: Currently supported on macOS only. Linux support is planned.

[[optional-defcfg-options]]
== defcfg options

[[danger-enable-cmd]]
=== danger-enable-cmd

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

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

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

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

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
)
----

If `+--log-layer-changes+` is passed as a command line argument,
a `no` in the configuration file will be overridden
and layer changes will again be logged.
This flag can be helpful when testing new configuration changes
while keeping the default behaviour as "no logging" to save on processing,
so that the `defcfg` item does not need to be adjusted back and forth
when experimenting vs. stable usage.

[[delegate-to-first-layer]]
=== delegate-to-first-layer


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

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

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]]

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

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

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
* a non-eager tap-dance activation from interruption by another key
* input chord activations, both v1 and v2

Key event processing is paused the defined number of milliseconds (approximate).
The default value is 5.

There will be a minor input latency impact in the mentioned scenarios.
Since 5ms is 1 frame at 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 key events.
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 reduce the value to a number between 0 and 4.

.Example:
[source]
----
(defcfg
  ;; If your environment is particularly buggy, might need to delay even more
  rapid-event-delay 20
)
----

[[chords-v2-min-idle]]
=== chords-v2-min-idle

This configuration affects the timer during which chords processing is disabled.
NOTE: For more info, see <<input-chords-v2>>.

The default (and minimum) value is `5` and the unit is milliseconds.

.Example:
[source]
----
(defcfg
  chords-v2-min-idle 200
)
----

[[tap-hold-require-prior-idle]]
=== tap-hold-require-prior-idle

This configuration applies to all `tap-hold` variants.
When a different physical key was pressed within the configured number of
milliseconds before a `tap-hold` key is pressed, the `tap-hold` key will
immediately resolve as its tap action without entering the waiting state.
This prevents accidental modifier activations during fast typing.
The concept is equivalent to ZMK's `require-prior-idle-ms`.

NOTE: For more info, see <<tap-hold>>.

The default value is `0` (disabled) and the unit is milliseconds.

.Example:
[source]
----
(defcfg
  tap-hold-require-prior-idle 150
)
----

- If you type a normal key and then press a `tap-hold` key within the threshold,
  the `tap-hold` key immediately outputs its tap action.
- If the keyboard is idle for longer than the threshold before pressing a `tap-hold` key,
  normal `tap-hold` behavior applies (waiting state, hold on timeout, etc.).
- When `tap-hold-require-prior-idle` triggers, the tap action is chosen before any other
  `tap-hold` configuration (e.g., `tap-hold-opposite-hand`, `concurrent-tap-hold`)
  is consulted.

==== Per-action override

The global `tap-hold-require-prior-idle` value can be overridden on individual
`tap-hold` actions using the `(require-prior-idle <ms>)` option.
This is useful when most keys benefit from idle detection (e.g., home-row mods)
but specific keys (e.g., a layer-tap key) need immediate activation even during
fast typing.

The option can be appended to any `tap-hold` variant as a trailing
`(keyword value)` list:

.Example: disable for a specific key
[source]
----
(defcfg tap-hold-require-prior-idle 150)
(defalias
  ;; HRMs use the global 150ms threshold
  a (tap-hold 200 200 a lmet)
  s (tap-hold 200 200 s lalt)
  ;; Layer key disables idle detection for immediate activation
  nav (tap-hold 200 200 tab (layer-toggle nav) (require-prior-idle 0))
)
----

.Example: enable for a specific key without a global setting
[source]
----
(defalias
  a (tap-hold 200 200 a lmet (require-prior-idle 150))
)
----

- `(require-prior-idle 0)` disables the feature for that action,
  even when a global threshold is set.
- A non-zero value enables or changes the threshold for that action only.
- When no per-action override is specified, the global `defcfg` value is used.
- Works with all `tap-hold` variants: `tap-hold`, `tap-hold-press`,
  `tap-hold-release`, `tap-hold-press-timeout`, `tap-hold-release-timeout`,
  `tap-hold-release-keys`, `tap-hold-except-keys`, `tap-hold-tap-keys`,
  and `tap-hold-opposite-hand`.

[[override-release-on-activation]]
=== override-release-on-activation

This configuration item changes activation behaviour from `defoverrides`.

Take this example override:

[source]
----
(defoverrides (lsft a) (lsft 9))
----

The default behaviour is that if `lsft` is released **before** releasing `a`,
kanata's behaviour would be to send `a`.

A future improvement could be to make the `9` continue to be the key held,
but that is not implemented today.

The workaround in case the above behaviour negatively impacts your workflow
is to enable this configuration.
This configuration will press and then immediately release the `9` output
as soon as the override activates, meaning you are unlikely as a human to ever
release `lsft` first.

The effect of this configuration is that the `9` key cannot remain held
when activated by the override which is important to consider for your use cases.

.Example:
[source]
----
(defcfg
  override-release-on-activation yes
)
----

[[allow-hardware-repeat]]
=== allow-hardware-repeat

By default, any repeat-key events generated by the physical keyboard (or operating system)
will be passed through to the application.  On Linux, under Wayland, this is wasted effort
since the DE handles key-repeat on its own.  Such events can also be distracting when
debugging your configuration with evtest, etc.

Setting this option to "false" will cause such events to be dropped, and not passed through.
This is primarily meant for Linux, but may find some use on Mac.  It is not implemented on
Windows, and will be silently ignored.

.Example:
[source]
----
(defcfg
   allow-hardware-repeat false
)
----

[[alias-to-trigger-on-load]]
=== alias-to-trigger-on-load

Select an alias to execute when first starting, and after each
live-reload of the config. You can use this to run external
commands, or to stack layers (with layer-while-held).

The name of an alias, without a leading "@", is expected as a
parameter.  The example below will beep at startup (assuming
your system has a beep command), and will already be blocking
the swapped "i" and "o" keys.

.Example:
[source]
----
(defcfg
  alias-to-trigger-on-load S
  danger-enable-cmd yes
)

(deffakekeys B (layer-while-held block))

(defalias
  P (on-press toggle-vkey B)
  S (macro @P (cmd beep))
)

(defsrc i o p )
(deflayer base o i @P )
(deflayer block • • _ )
----

[[mouse-movement-key]]
=== Linux, macOS, or Windows-interception only: mouse-movement-key

Accepts a single key name.
When configured, whenever a mouse cursor movement is received,
the configured key name will be "tapped" by Kanata,
activating the key's action.

This enables reporting of every relative mouse movement, which
corresponds to standard mice, trackballs, trackpads and
trackpoints. Absolute movements, which can be generated by
touchscreens, drawing tablets and some mouse replacement or
accessibility software, are ignored. Scrolling events and mouse
buttons are also ignored.

The intended use of these events is to provide a way to automatically
enable a mouse keys layer while mousing, which can be disabled by a
timeout or typing on other keys, rather than explicit toggling. see
cfg_examples/automousekeys-*.kbd for more.

The `mvmt` key name is specially intended for this purpose.  It has no
output key mapping and cannot be supplied as an action; however, any
key may be used.

Supports live reload on Linux and macOS. With Windows-interception, this
option must be present on startup to enable mouse movement event
collection, so restart is required to enable it. Changing the key name
is always supported, however.

On macOS, this feature uses the same CGEventTap as the existing mouse
button input support, and so requires the same Accessibility or Input
Monitoring permission in System Settings > Privacy & Security.

.Example:
[source]
----
(defcfg
  process-unmapped-keys yes
  mouse-movement-key mvmt
)

(defsrc
  k     l     ;
  mvmt
)

(defvirtualkeys
  mouse (layer-while-held mouse-layer)
)

(defalias
  mhld (hold-for-duration 750 mouse)
)

(deflayer qwerty
  k     l     ;
  @mhld
)

(deflayer mouse-layer
  mlft  mmid  mrgt
  @mhld
)
----

[[linux-only-linux-dev]]
=== Linux only: linux-dev

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"
  )
)
----

For devices that do not have an easily identifiable device path like Bluetooth
keyboards using the `linux-dev-names-include` option below is recommended.

[[linux-only-linux-dev-names-include]]
=== Linux only: linux-dev-names-include

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.

Device paths are not supported by this option; instead use the device names
as output by Kanata during startup.  Launch Kanata with a
<<minimal-configuration,minimal configuration>> (any use of a `linux-dev*`
option may hide devices) and look for lines beginning with "registering":

----
registering /dev/input/eventX: "Device name 1"
registering /dev/input/eventY: "Device name 2"
----

The entire name within quotes must be used, partial matches and regex's are not supported.

.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

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-names-include`.

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

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-device-detect-mode]]
=== Linux only: linux-device-detect-mode

Kanata on Linux automatically detects and grabs input devices
when none of the explicit device configurations are in use.
In case kanata is undesirably grabbing mouse-like devices,
you can use a configuration item to change detection behaviour.

The configuration is `linux-device-detect-mode` and it has the options:

[cols="1,4"]
|===
| `keyboard-only`
| Grab devices that seem to be a keyboard only.

| `keyboard-mice`
| Grab devices that seem to be a keyboard only
and devices that declare **both** keyboard and mouse functionality.

| `any`
| Grab all keyboard-like and mouse-like devices.
|===

The default behaviour is:

[cols="1,4"]
|===
| `keyboard-mice`
| When no mouse events are in `defsrc`.

| `any`
| When any mouse buttons or mouse scroll events are in `defsrc`.
|===

[[linux-only-linux-unicode-u-code]]
=== Linux only: linux-unicode-u-code

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

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]]

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
)
----

[[linux-only-linux-use-trackpoint-property]]
=== Linux only: linux-use-trackpoint-property

On linux, you can ask kanata to label itself as a trackpoint. This has several
effects on libinput including enabling middle mouse button scrolling and using a
different acceleration curve. Otherwise, a trackpoint intercepted by kanata may
not behave as expected.

If using this feature, it is recommended to filter out any non-trackpoint
pointing devices using <<linux-only-linux-dev-names-include>>,
<<linux-only-linux-dev-names-exclude>> or <<linux-only-linux-dev>> to avoid
changing their behavior as well.

.Example:
[source]
----
(defcfg
  linux-use-trackpoint-property yes
)
----

[[linux-only-linux-output-device-name]]
=== Linux only: linux-output-device-name

This option defines the name of the evdev output device.
The default value is kanata.

.Example:
[source]
----
(defcfg
   linux-output-device-name "kanata output"
)
----

[[linux-only-linux-output-device-bus-type]]
=== Linux only: linux-output-device-bus-type

Kanata on Linux needs to declare a "bus type" for its evdev output device.
The options are `USB`, `I8042`, and `virtual`, with the default as `I8042`.
Using USB can https://github.com/jtroo/kanata/pull/661[break disable-touchpad-while-typing on Wayland].
But using I8042 appears to break https://github.com/jtroo/kanata/issues/1131[some other scenarios].
Thus the output bus type is configurable.

.Example:
[source]
----
(defcfg
   linux-output-device-bus-type USB
)
----

[[macos-only-macos-dev-names-include]]
=== macOS only: macos-dev-names-include

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"
  )
)
----

[[macos-only-macos-dev-names-exclude]]
=== macOS only: macos-dev-names-exclude

This option defines a list of device names that should be excluded.
By default, kanata will try to detect which input devices are keyboards and try
to intercept them all. However, you may specify certain keyboard devices to be ignored
using the `macos-dev-names-exclude` configuration.
Device names that do not exist in the list will be included.
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-exclude (
    "Device name 1"
    "Device name 2"
  )
)
----

[[macos-only-macos-continue-if-no-devs-found]]
=== macOS only: macos-continue-if-no-devs-found

By default, kanata will exit with an error if no input devices matching
the configured include list are found at startup. Setting
`macos-continue-if-no-devs-found` changes this: kanata keeps running and
waits for matching devices to connect, then grabs them automatically.

This is useful for Bluetooth or USB keyboards that may not be connected
at boot time. When the device later appears (e.g. Bluetooth pairs, USB
plugged in), kanata captures it and begins remapping.

Works with `macos-dev-names-include` and `definputdevices`.
This has no effect with macOS laptops when no device filter is configured
because the default enumeration always finds the built-in keyboard.

.Example:
[source]
----
(defcfg
  macos-dev-names-include ("My BT Keyboard")
  macos-continue-if-no-devs-found yes
)
----

[[windows-only-windows-altgr]]
=== Windows only: windows-altgr

There is an option for Windows to mitigate the strange behaviour of AltGr
(key names: `ralt | altgr`) if you're using `process-unmapped-keys yes`
or have the AltGr key or the Left Control key
in your `defsrc` or in any `deflayermap` `$input` position.
This is applicable for many non-US layouts
that use AltGr for adding modifier accents to characters.
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

Without these workarounds,
within <<process-unmapped-keys,`defcfg`>> you should use
`process-unmapped-keys (all-except lctl ralt))` or `process-unmapped-keys no`
**and** also omit both `ralt` and `lctl` from `defsrc`
and any <<deflayermap,`deflayermap`>> `$input` position.

.Example:
[source]
----
(defcfg
  windows-altgr add-lctl-release
)
----

[[windows-only-windows-sync-keystates]]
=== Windows only: windows-sync-keystates

By default Kanata on Windows without Interception
has behaviour to check against the Windows operating system
and try to synchronize known keys where they differ
between the OS and Kanata.
This is because of limitations in the Windows keyboard APIs
where Kanata is not guaranteed to see all events.
However, likewise due to limitations in the APIs,
even this sync mechanism is not perfect.
If the sync behaviour is causing issues, set it to `none`.
The default is `clear-kanata-states`.

Options:

* `none`
* `clear-kanata-states`
* `clear-kanata-and-os-states`

.Example:
[source]
----
(defcfg
  windows-sync-keystates none
)
----

For more context, see: https://github.com/jtroo/kanata/issues/55.

NOTE: Even with these workarounds, putting `+lctl+` and `+ralt+` in your defsrc may not
work properly with other applications that also use keyboard interception.
Known application with issues: GWSL/VcXsrv.
In this case it is recommended to ensure the keys are omitted from processing.

NOTE: Even if a workaround is applied in Kanata,
if you use other LLHOOK-using programs such as
PowerToys Keyboard Manager or AutoHotKey (AHK),
you can still experience issues.
PowerToys has no workaround while with AHK
you may be able to script your own workaround.

=== Windows only: windows-interception-mouse-hwid[[windows-only-windows-interception-mouse-hwid]]

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]]

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]]

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"
  )
)
----

=== Windows only: windows-interception-keyboard-hwids-exclude[[windows-only-windows-interception-keyboard-hwids-exclude]]

This defcfg item allows you to exclude certain keyboards from being intercepted.
You cannot define this alongside the inclusive keyboard configuration.

It is parsed identically to the inclusive configuration.

.Example:
[source]
----
(defcfg
  windows-interception-keyboard-hwids-exclude (
    "70, 0, 60, 0"
    "71, 72, 73, 74"
  )
)
----

=== Windows only: windows-interception-mouse-hwids-exclude[[windows-only-windows-interception-mouse-hwids-exclude]]

This defcfg item allows you to exclude certain mice from being intercepted.
You cannot define this alongside the inclusive mouse configuration.

It is parsed identically to the inclusive configuration.

.Example:
[source]
----
(defcfg
  windows-interception-mouse-hwids-exclude (
    "70, 0, 60, 0"
    "71, 0, 62, 0"
  )
)
----

[[windows-only-tray-icon]]
=== Windows only: tray-icon

Show a custom tray icon file for a <<windows-only-win-tray>> gui-enabled build of kanata on Windows.
Accepts either the full path (including the file name with an extension) to the icon file
or just the file name, which is then searched in the following locations:

* Default parent folders:
** config file's, executable's
** env vars: `XDG_CONFIG_HOME`, `APPDATA` (`C:\Users\<Name>\AppData\Roaming`), `USERPROFILE` `/.config` (`C:\Users\<Name>\.config`)
* Default config subfolders: `kanata` `kanata-tray`
* Default image subfolders (optional): `icon` `img` `icons`
* Supported image file formats: `ico` `jpg` `jpeg` `png` `bmp` `dds` `tiff`

If not specified, tries to load any icon file from the same locations with the name matching
config name with extension replaced by one of the supported ones.
See https://github.com/jtroo/kanata/blob/main/cfg_samples/tray-icon/tray-icon.kbd[example config] for more details.

.Example:
[source]
----
;; in a config file C:\Users\<U>\AppData\Roaming\kanata\kanata.kbd
(defcfg
  tray-icon base.png ;; will load C:\Users\<U>\AppData\Roaming\kanata\base.png
)
----

[[windows-only-icon-match-layer-name]]
=== Windows only: icon-match-layer-name

When enabled, attempt to switch to a custom tray icon that matches the name of the active layer
if the layer doesn't specify an explicit icon. If no icon file is found, the default icon will be used (see <<windows-only-tray-icon>>).
File search rules are the same as in <<windows-only-tray-icon>>. Defaults to true.
See https://github.com/jtroo/kanata/blob/main/cfg_samples/tray-icon/tray-icon.kbd[example config] for more details.

[[windows-only-tooltip-layer-changes]]
=== Windows only: tooltip-layer-changes

Show a custom layer icon near the mouse pointer position. Defaults to false. Requires <<windows-only-win-tray>> gui-enabled build.

[[windows-only-tooltip-show-blank]]
=== Windows only: tooltip-show-blank

Show a blank square when instead of an icon if a layer isn't configured to have one. Defaults to false. Requires <<windows-only-win-tray>> gui-enabled build.

[[windows-only-tooltip-no-base]]
=== Windows only: tooltip-no-base

Don't show a tooltip layer icon for the base layer (1st deflayer). Defaults to true. Requires <<windows-only-win-tray>> gui-enabled build.

[[windows-only-tooltip-duration]]
=== Windows only: tooltip-duration

Set duration (in ms) for showing a custom layer icon near the mouse pointer position. 0 to never hide. Defaults to 500. Requires <<windows-only-win-tray>> gui-enabled build.

[[windows-only-tooltip-size]]
=== Windows only: tooltip-size

Set the size (comma-separated Width,Height without spaces) for a custom layer icon near the mouse pointer position. Defaults to 24,24. Requires <<windows-only-win-tray>> gui-enabled build.

[[windows-only-notify-cfg-reload]]
=== Windows only: notify-cfg-reload

Show system notification message on config reload. Defaults to true. Requires <<windows-only-win-tray>> gui-enabled build.

[[windows-only-notify-cfg-reload-silent]]
=== Windows only: notify-cfg-reload-silent

Disable sound for the system notification message on config reload. Defaults to false. Requires <<windows-only-win-tray>> gui-enabled build.

[[windows-only-notify-error]]
=== Windows only: notify-error

Show system notification message on kanata errors. Defaults to true. Requires <<windows-only-win-tray>> gui-enabled build.

[[using-multiple-defcfg-options]]
=== Using multiple defcfg options

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"
)
----

== Command line arguments[[cli-args]]

When executing Kanata, you can pass a variety of arguments to the program
to change Kanata's behaviour.
This section describes the purpose and usage of these arguments.

[[args-help]]
=== Show help text: `-h`, `--help`

Only show help text that describes these arguments,
then exit the program.

[[args-config-file]]
=== Configuration file(s): `-c`, `--cfg`

Configuration file(s) to use with Kanata.
When not specified, default file locations are checked.
The default files checked depend on your operating system
and are described by `--help`.

This argument can be used more than once;
see <<live-reload>> to understand the behaviour of this.
The startup configuration will be the first file listed.

[[args-tcp]]
=== TCP server address: `-p`, `--port`

Enable the TCP server capability and listen on either:
- a specified port, on all IP addresses
- a specific `IP:PORT`

This enables use cases such as
https://github.com/jtroo/kanata?tab=readme-ov-file#community-projects-related-to-kanata[application aware switching].

The protocol is plaintext newline-terminated JSON.
The source of truth is the
https://github.com/jtroo/kanata/blob/main/tcp_protocol/src/lib.rs[TCP protocol code].

You may also be interested in the
https://github.com/jtroo/kanata/blob/main/example_tcp_client/src/main.rs[example client].

==== TCP Protocol Overview

The TCP server uses a simple request/response model with JSON messages.
Each message is a single line of JSON terminated by a newline (`\n`).

- **Client → Server**: Commands to control Kanata (reload config, switch layers, etc.)
- **Server → Client**: Responses to commands and event notifications (layer changes, config reloads, etc.)

==== Client Commands

These JSON messages can be sent from a TCP client to control Kanata:

===== Layer Control

[cols="1,2"]
|===
| Command | Description

| `{"ChangeLayer":{"new":"layer-name"}}`
| Switch to the specified layer. Equivalent to the `layer-switch` keyboard action.

| `{"RequestLayerNames":{}}`
| Request a list of all defined layer names. Server responds with `LayerNames`.

| `{"RequestCurrentLayerName":{}}`
| Request the name of the currently active layer. Server responds with `CurrentLayerName`.

| `{"RequestCurrentLayerInfo":{}}`
| Request the current layer's name and full configuration text. Server responds with `CurrentLayerInfo`.
|===

.Example - Query and switch layers:
[source,bash]
----
# Get all layer names
echo '{"RequestLayerNames":{}}' | nc localhost 7070

# Get current layer
echo '{"RequestCurrentLayerName":{}}' | nc localhost 7070

# Switch to nav layer
echo '{"ChangeLayer":{"new":"nav"}}' | nc localhost 7070
----

===== Virtual Key Actions

[cols="1,2"]
|===
| Command | Description

| `{"RequestFakeKeyNames":{}}`
| Request a list of all defined virtual key names. Server responds with `FakeKeyNames`.

| `{"ActOnFakeKey":{"name":"key-name","action":"Tap"}}`
| Trigger a virtual key defined in `defvirtualkeys`. Actions: `Press`, `Release`, `Tap`, `Toggle`.
|===

Virtual keys must be defined in your configuration using `defvirtualkeys`.
See the <<virtual-keys>> section for details.

.Example - Trigger a text expansion macro:
[source]
----
;; In your config:
(defvirtualkeys
  email-sig (macro S-b e s t spc r e g a r d s)
)

;; From TCP client:
echo '{"ActOnFakeKey":{"name":"email-sig","action":"Tap"}}' | nc localhost 7070
----

===== Mouse Control

[cols="1,2"]
|===
| Command | Description

| `{"SetMouse":{"x":100,"y":200}}`
| Set the mouse cursor position to absolute screen coordinates.
|===

This is the TCP equivalent of the <<set-mouse>> keyboard action.

===== Configuration Reload

[cols="1,2"]
|===
| Command | Description

| `{"Reload":{}}`
| Reload the current configuration file. Equivalent to `lrld` keyboard action.

| `{"ReloadNext":{}}`
| Load the next configuration file in the list. Equivalent to `lrnx` keyboard action.

| `{"ReloadPrev":{}}`
| Load the previous configuration file in the list. Equivalent to `lrpv` keyboard action.

| `{"ReloadNum":{"index":0}}`
| Load configuration file at the specified index (0-based).

| `{"ReloadFile":{"path":"/path/to/config.kbd"}}`
| Load a specific configuration file by path.
|===

All reload commands support optional `wait` and `timeout_ms` fields for synchronous confirmation:

[source,json]
----
{"Reload":{"wait":true,"timeout_ms":5000}}
----

When `wait` is `true`, the server blocks until the reload completes or times out, then sends a `ReloadResult` message. The `timeout_ms` field specifies the maximum wait time in milliseconds (default: 5000).

===== Server Information

[cols="1,2"]
|===
| Command | Description

| `{"Hello":{}}`
| Request server version and capabilities. Server responds with `HelloOk`.
|===

==== Server Messages

These JSON messages are sent from Kanata to connected TCP clients:

===== Event Notifications

These are sent automatically when events occur:

[cols="1,2"]
|===
| Message | Description

| `{"LayerChange":{"new":"layer-name"}}`
| Sent when the active layer changes.

| `{"ConfigFileReload":{"new":"/path/to/config.kbd"}}`
| Sent when a configuration file is reloaded.

| `{"MessagePush":{"message":"your-message"}}`
| Sent when a `push-msg` action is triggered from the keyboard configuration.

| `{"Error":{"msg":"error description"}}`
| Sent when an error occurs processing a command.

| `{"HoldActivated":{"key":"caps"}}`
| Sent when a tap-hold key transitions to hold state. The `key` field is the physical key name.

| `{"TapActivated":{"key":"a"}}`
| Sent when a tap-hold key triggers its tap action. The `key` field is the physical key name.
|===

===== Query Responses

These are sent in response to client queries:

[cols="1,2"]
|===
| Message | Description

| `{"LayerNames":{"names":["base","nav","num"]}}`
| Response to `RequestLayerNames`. Contains all defined layer names.

| `{"FakeKeyNames":{"names":["email-sig","nav-mode"]}}`
| Response to `RequestFakeKeyNames`. Contains all defined virtual key names.

| `{"CurrentLayerName":{"name":"base"}}`
| Response to `RequestCurrentLayerName`. Contains the active layer name.

| `{"CurrentLayerInfo":{"name":"base","cfg_text":"..."}}`
| Response to `RequestCurrentLayerInfo`. Contains the layer name and its full configuration text.

| `{"HelloOk":{"version":"1.11.0","protocol":1,"capabilities":[...]}}`
| Response to `Hello`. Contains server version, protocol version, and supported capabilities. Includes `hold-activated` and `tap-activated`.

| `{"ReloadResult":{"ok":true}}`
| Response to reload commands when `wait` was `true`. Indicates whether the config reload succeeded. If timed out, includes `timeout_ms`.
|===

For a complete implementation example, see the
https://github.com/jtroo/kanata/blob/main/example_tcp_client/src/main.rs[example TCP client].

[[args-quiet]]
=== Disable logs other than errors: `-q`, `--quiet`

Silence info and warning logs so that only errors are logged.
This might be desirable when running in the background as a system service.

[[args-debug]]
=== Enable debug logs: `-d`, `--debug`

Add extra debug logging.
This is helpful when diagnosing an issue
or discovering key names.

[[args-trace]]
=== Enable trace logs: `-t`, `--trace`

Add extra trace logging.
Also includes debug logging.
This is sometimes helpful when diagnosing an issue,
but is very verbose.

[[args-nodelay]]
=== Remove startup delay: `-n`, `--nodelay`

By default, Kanata adds a delay before reading keyboard inputs.
This helps protect against stale states
when started from a terminal.

Without this delay, Kanata may interpret any keys you're still holding down when it starts
as being stuck.

However, this may be undesirable
when running as a background service.

[[args-check]]
=== Only check configuration: `--check`

Check the configuration file validity and then exit.

[[args-log-layer-changes]]
=== Force log changes: `--log-layer-changes`

Your final desired `defcfg` could be to have logging of layer changes as false.
However, for testing purposes you may want to temporarily log the layers.
This configuration forces logging to happen for this use case.

[[args-no-wait]]
=== Skip exit prompt: `--no-wait`

By default, kanata displays "Press enter to exit" and waits for user input
before exiting. This flag skips that prompt and exits immediately.

This is useful when running kanata as a background service (e.g., systemd)
where you want automatic restart on failure. Without this flag,
the service would hang waiting for stdin input that never comes.

[[args-linux-dev-symlink]]
=== Linux only - Device symlink path: `-s`, `--symlink-path`

If you want another program to consume the Kanata device output,
you can use this flag to have a consistent device filesystem path.

[[args-wait-device]]
=== Linux only - Wait before device grab attempt: `-w`, `--wait-device-ms`

Some devices take a while to become ready and can fail to be grabbed.
This configuration adds a delay before trying to grab devices
in case this is an issue impacting you.

[[args-macos-list-devices]]
=== macOS only - Only list keyboards: `-l`, `--list`

List keyboard names that can be used
within defcfg and then exit.

[[args-macos-release-grab-on-lock]]
=== macOS only - Release grab on lock / user switch: `--release-grab-on-lock`

By default, kanata's keyboard grab on macOS stays active even when
the screen is locked or another user takes the console via fast user
switching. This means anyone else at the keyboard (including you on
the lock-screen prompt) types through your remap.

Pass `--release-grab-on-lock` to make kanata poll its CGSession state
and release the grab whenever the screen is locked
(`CGSSessionScreenIsLocked`) or kanata's session loses the console
(`kCGSSessionOnConsoleKey == false`). The grab is re-acquired once
kanata's session is back on the console with the screen unlocked.

This is useful on shared Macs where another user's lock-screen
password or session should not be remapped. Off by default to
preserve the historical always-grab behavior for single-user setups.

== Advanced features[[advanced-features]]
[[virtual-keys]]
=== Virtual keys

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>)` or `on↓`:
Activate a virtual key action when pressing the associated input key.
* `(on-release  <action> <virtual key name>)` or `on↑`:
Activate a virtual key action when releasing the associated input key.
* `(on-idle <idle time> <action> <virtual key name>)`:
Activate a virtual key action when kanata has been idle
for at least `idle time` milliseconds.
* `(on-physical-idle <idle time> <action> <virtual key name>)`:
Activate a virtual key action when the physical keyboard has
had all keys released
for at least `idle time` milliseconds.
* `(hold-for-duration <hold time> <virtual key name>`):
Press a virtual key for `hold time` milliseconds.
If `hold-for-duration` retriggered on a virtual key before release,
the time will be reset with no additional press/release events.

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.
The variant `on-physical-idle` may be more desirable if you want the timer
to only start based on having all keyboard keys be released.

.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)
  hfd (hold-for-duration 1000 met)
)

(deflayer use-virtual-keys
  @psf @rsf @tal @mac a s d f @isf @hfd
)
----

.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>)+` or `on↓fakekey`: Activate a fake key
  action when pressing the key mapped to this action.
* `+(on-release-fakekey <fake key name> <action>)+` or `on↑fakekey`: 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-virtual-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 virtual
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

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 `+defvirtualkeys+`. 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 tap-vkey <virtual key name>)+`

.Example:
[source]
----
(defseq git-status (g s t))
(defvirtualkeys 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)

    ;;     The shifted letters in parentheses means a single press of lsft
    ;;     must remain held while both h and then s are pressed.
    ;;     This is not the same as S-h S-s, which means that the lsft key
    ;;     must be released and repressed between the h and s presses.
    https (S-(h s))
)
(defvirtualkeys
    dotcom (macro . c o m)
    dotorg (macro . o r g)
    https (macro h t t p s S-; / /)
)
----

There are 10 special keys with names `nop0-nop9` which kanata treats specially.
Kanata will never send OS events for these keys
but they can still participate in sequences.
See an example of using the nop keys below.

Additionally useful to note in this example is the use of a template
to define a sequence and its virtual key in one template expansion,
with template parameters:

- virtual key name
- activating key sequence
- action triggered by sequence activation

This template may be useful to you within your own configuration.

.Example:
[source]
----
(defsrc f7   f8   f9   f10)
(deflayer base
        sldr nop0 nop1 nop2)
(deftemplate seq (vk-name input-keys output-action)
    (defvirtualkeys $vk-name $output-action)
    (defseq $vk-name $input-keys)
)
;; template-expand has a shortened form: t!
(t! seq dotcom (nop0 nop1) (macro . c o m))
(t! seq dotorg (nop0 nop2) (macro . o r g))
----

If 10 special nop keys do not seem sufficient,
you can get creative with your sequences and treat some as a prefix modifier.
For example, you can get 24 "keys" by treating `nop0-nop5` as normal
while treating `nop6-nop9` as prefixes that are always followed by a second nop key.

.Example:
[source]
----
(defalias
  nop0 nop0
  ;; ...
  nop5 nop5
  nop6 (macro nop6 nop0)
  ;; ...
  nop11 (macro nop6 nop5)
  ;; ...
  nop18 (macro nop9 nop0)
  ;; ...
  nop23 (macro nop9 nop5)
)
----

==== Overlapping keys in any order

Within the key list of `defseq` configuration items,
the special `O-` list prefix can be used to denote a set of keys that must
all be pressed before any are released in order to match the sequence.

For an example, `O-(a b c)` is equivalent to `O-(c b a)`.

.Example:
[source]
----
(defvirtualkey hello (macro h (unshift e l) 5 (unshift l o)))
(defseq hello (O-(h l o)))
----

WARNING: The way that sequences implements this functionality behind the scenes
is by generating a sequence for every permutation of the overlapping keys.
This can make kanata use up a lot of memory.
Due to this, the maximum keys allowed in a given `O-(...)` list is 6,
but you are still permitted to add more to the sequence,
including more `O-(...)` lists.
Doing the above can balloon kanata's memory consumption.

.Sample of more advanced usage
[%collapsible]
====

The configuration below showcases context-dependent chording
with auto-space and auto-deleted spaces from typing punctuation.

For example, chording `(d a y)` and then `(t u e)` will output
`Tuesday`, while chording `(t u e)` by itself does nothing.

.Example configuration:
[source]
----
(defsrc f1)
(deflayer base lrld)
(defcfg process-unmapped-keys yes
	sequence-input-mode visible-backspaced
	concurrent-tap-hold true)
(deftemplate seq (vk-name in out)
	(defvirtualkeys $vk-name $out)
	(defseq $vk-name $in))

(defvirtualkeys rls-sft (multi (release-key lsft)(release-key rsft)))
(defvar rls-sft (on-press tap-vkey rls-sft))
(deftemplate rls-sft () $rls-sft 5)

(defchordsv2
	(d a y) (macro sldr d (t! rls-sft) a y spc nop0) 200 first-release ()
	(h l o) (macro h (t! rls-sft) e l l o sldr spc nop0) 200 first-release ()
)
(t! seq Monday (d a y spc nop0 O-(m o n)) (macro S-m $rls-sft o n d a y nop9 sldr spc nop0))
(t! seq Tuesday (d a y spc nop0 O-(t u e)) (macro S-t $rls-sft u e s d a y nop9 sldr spc nop0))
(t! seq DelSpace_. (spc nop0 .) (macro .))
(t! seq DelSpace_; (spc nop0 ;) (macro ;))
----

.Try using the above configuration to type the text:
[source]
----
day;
Day;
Tuesday.
day hello
hello day
Hello day.
hello Tuesday
Hello Monday;
----

====

==== 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 .))
----

==== sequence-noerase

When you have a keyboard locale that uses dead keys,
you may be pressing two keys that only actually output one symbol.
By default, when the `visible-backspaced` input mode does the backtracking backspaces,
it backspaces according to input count.
With dead keys, this may result in too many backspaces.

The `sequence-noerase` action is a no-output action
that tells the sequences action to have one fewer backspace
when backtracking with visible-backspaced.

.Example:
[source]
----
(deflayermap (base)
  0 sldr
  u (t! maybe-noerase u)
)
(deftemplate maybe-noerase (char)
  (multi
    (switch
      ((key-history ' 1)) (sequence-noerase 1) fallthrough
      () $char break
   ))
)
(defvirtualkeys seq-output-1 (macro a b c d e f g))
(defseq seq-output-1 (' u))

----

==== More about sequences

For more context about sequences, 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.

[[input-chords]]
=== Input chords

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

NOTE: this configuration item is older and instead you may want to use
the newer and more generalized <<environment>> configuration.

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
----

[[custom-tap-hold-behaviour]]
=== Custom tap-hold behaviour

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

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.kbd[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 `+␡+`

[[windows-only-work-elevated]]
=== Windows only: enable in elevated windows

The default `kanata.exe` binary doesn't work in elevated windows (run with administrative privileges),
e.g., `Control Panel`. However, you can use AutoHotkey's "EnableUIAccess" script to self-sign the binary,
move it to "Program Files", then launching kanata from there will also work in these elevated windows.
See https://github.com/jtroo/kanata/blob/main/EnableUIAccess[EnableUIAccess] folder with the script
and its required libraries (needs https://www.autohotkey.com/download/[AutoHotkey v2] installed)

If compiling yourself, you should add the feature flag `win_manifest`
to enable the use of the `EnableUIAccess` script:

```
cargo build --win_manifest
```

[[windows-only-win-tray]]
=== Windows only: win-tray

Kanata can be compiled as a Windows GUI tray app with the feature flag `gui`.
This can simplify launching the app on user login by placing a `.lnk`
at `%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup`, show custom icon indicator per config


image:https://github.com/jtroo/kanata/blob/main/docs/win-tray/win-tray-screen.png[icon indicator per config,477,129]

as well as dynamic icon indicator per layer (might need to click on the gif below to play)

image:https://github.com/jtroo/kanata/blob/main/docs/win-tray/win-tray-layer-change.gif[icon indicator per layer,33,35,opts=autoplay]

(see <<windows-only-win-tray>>). It also supports (re)loading configs.

Currently the only configuration supported is tray icon per profile, all other configuration should
be done by passing cli flags in the `Target` field of `.lnk`, e.g., `"C:\Program Files\kanata\kanata.exe" -d -n`
to launch kanata without a delay in a debug mode

When launched from a command line, the app outputs log to the console, but otherwise the logs are currently
only available via an app capable of viewing `OutputDebugString` debugs, e.g., https://github.com/smourier/TraceSpy[TraceSpy].

[[test-your-config]]
=== Test your config

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:https://github.com/jtroo/kanata/blob/main/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. 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` +
  - `🎭`, `fakekey`, `vk`, or `virtualkey` to activate virtual keys +
  - `🔀`, `ls`, or `layer-switch` to switch layers +

Virtual key format is `vk:name[:action]`, `fakekey:name[:action]`, or `virtualkey:name[:action]`. +
When using the emoji prefix, the format is `🎭name[:action]`. Action is one of: +
  - `press` or `p` (default if omitted) +
  - `release` +
  - `tap` or `t` +
  - `toggle` or `g` +
Example: `vk:vk_bear:tap` or `🎭vk_bear:tap`. +

Layer switch format is `ls:name` or `layer-switch:name`. +
When using the emoji prefix, the format is `🔀name`. +
This switches to the specified layer as the new default layer. +
Example: `ls:nav` or `🔀nav`. +

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

Using unicode symbols `🕐`,`↓`,`↑`,`⟳`,`🎭`,`🔀` allows skipping the `:` separator, e.g., `↓k` ≝ `↓:k` ≝ `d:k`

[[zippychord]]
=== Zippychord

**Reference**

You may define a single `+defzippy+` configuration item.
This configuration enables chorded text expansion.

.Configuration syntax within the kanata configuration
[source]
----
(defzippy
  $zippy-filename ;; required
  on-first-press-chord-deadline $deadline-millis  ;; optional
  idle-reactivate-time          $idle-time-millis ;; optional
  smart-space                   $smart-space-cfg  ;; optional
  smart-space-punctuation (                       ;; optional
    $punc1 $punc2 ... $puncN)
  output-character-mappings (    ;; optional
    $character1 $output-mapping1
    $character2 $output-mapping2
    ;; ...
    $characterN $output-mappingN
  )
)
----

[cols="1,4"]
|===
| `$zippy-filename`
| Relative or absolute file path.
If relative, its path is relative to
the directory containing the kanata configuration file.
This must be the first item following `defzippy`.

| `$deadline-millis`
| Number of milliseconds.
After the first press while zippy is enabled,
if no chord activates within this configured time,
zippy is temporarily disabled.

| `$idle-time-millis`
| Number of milliseconds.
After typing ends and this configured number of milliseconds elapses,
zippy will be re-enabled from being temporarily disabled.

| `$smart-space-cfg`
| Determines the smart space behaviour.
The options are `none`, `add-space-only`, and `full`.
With `none`, outputs are typed as-is.
With `add-space-only`, spaces are automatically added after outputs
which end with neither a space or a backspace ⌫.
With `full`, the `add-space-only` behaviour applies
alongside additional behaviour:
typing punctuation (default characters: `, . ;`)
after a zippy activation will delete a prior automatically-added space.

| `$punc`
| A character defined in `output-character-mappings`
or a known key name, which shall be considered as punctuation.
The `smart-space-punctuation` configuration
will overwrite the default punctuation list
considered by smart-space;
if you want to include the default characters,
you must include them in this configuration.

| `$character`
| A single unicode codepoint for use
in the output column of the zippy configuration file.

| `$output-mapping`
| Key or output chord to tell kanata how to type `$character`
when seen in the zippy file output column.
Must be a single key or output chord.
The output chord may contain `AG-` to tell kanata to press with AltGr
and may contain `S-` to tell kanata to press with Shift.

The list items `no-erase` and `single-output` are also usable in this position.

| `no-erase`
| Accepts a single key or output chord as a parameter.
The zippy system will not backspace this character
in case of auto-erasure by a superset chord or followup chord.
Use for dead keys or compose keys.

| `single-output`
| Accepts one or more keys or output chords as a parameter.
The zippy system send only one backspace
in case of auto-erasure by a superset chord or followup chord.
Use for a dead key or compose key sequence with one output symbol.
|===

Regarding output mappings,
you can configure the output of the special-lisp-syntax characters
`+) ( "+` via these lines:

[source]
----
    ")"    $right-paren-output
    "("    $left-paren-output
    r#"""# $double-quote-output
----

As an example, for the US layout these should be the correct lines:

[source]
----
    ")"     S-0
    "("     S-9
    r#"""#  S-'
----

.Configuration syntax within the zippy configuration file
[source]
----
// This is a comment.
//          inputs            ↹  outputs
$chord1 $follow-chord1.1...1.M	$output1
$chord2 $follow-chord2.1...2.M	$output2
// ...
$chordN $follow-chordN.1...N.M	$outputN
----

The format is two columns separated by a single Tab character.
The first column is input and the second is output.

[cols="1,4"]
|===
|`$chord`
| A set of characters.
You can use space by including it as the first character in the chord;
for an example see `Alphabet` in the sample below.
With 0 optional follow chords,
the corresponding output on the same line (`$output`)
will activate when zippy is enabled
and all the defined chord keys are pressed simultaneously.
The order of presses is not important.

| `$follow-chord`
| 0 or more chords, used the same way as `$chord`.
Having follow chords means the `$output` on the same line
will activate upon first activating the earlier chord(s) in the same line,
releasing all keys, and pressing the keys in `$follow-chordN.M`.
Follow chords are separated from the previous chord by a space.
If using a space in the follow chord, use two spaces;
for an example see `Washington` in the sample below.

| `$output`
| The characters to type when the chord and optional follow chord(s)
are all pressed by the user.
This is separated from the input chord column
by a single Tab character.
The characters are typed in sequence
and must all be singular-name key names
as one would configure in `defsrc`.
A capitalized single-character key name
will be parsed successfully
and these will be outputted alongside Shift to output the capitalized key.
Additionally, `output-character-mappings` configuration can be used
to inform kanata of additional mappings that may use Shift or AltGr.
|===

**Examples**

.Sample kanata configuration
[source]
----
(defzippy
  zippy.txt
  on-first-press-chord-deadline 500
  idle-reactivate-time          500
  smart-space-punctuation (? ! . , ; :)
  output-character-mappings (
    ;; This should work for US international.
    ! S-1
    ? S-/
    % S-5
    "(" S-9
    ")" S-0
    : S-;
    < S-,
    > S-.
    r#"""# S-'
    | S-\
    _ S--
    ® AG-r
    ’ (no-erase `)
    é (single-output ' e)
  )
)
----

.Sample zippy file content

[source]
----
dy	day
dy 1	Monday
dy 2	Tuesday
 abc	alphabet
 w  a	Washington
gi	git
gi f p	git fetch -p
----

**Description**

Zippychord is yet another chording mechanism in Kanata.
The inspiration behind it is primarily the
https://github.com/psoukie/zipchord[zipchord project].
The name is similar; it is named "zippy" instead of "zip" because
Kanata's implementation is not a port and does not aim for 100%
behavioural compatibility.

The intended use case is shorthands, or accelerating character output.
Within zippychord, inputs are keycode chords or sequences,
and the outputs are also purely keycodes.
In other words, all other actions are unsupported;
e.g. layers, switch, one-shot.

Zippychord behaves on outputted keycodes, i.e. the key outputs
after kanata has finished processing your
inputs, layers, switch logic and other configurations.
This is similar to how sequences operate
and is unlike chords(v1) and chordsv2.
Furthermore, outputs are all eager like `visible-backspaced` on sequences.
If a zippychord activation occurs, typed keys are backspaced.

To give an example, if one configures zippychord with a line like:

[source]
----
gi	git
----

then either of the following typing event sequences
will erase the input characters
and then proceed to type the output "git"
like if it was `(macro bspc bspc g i t)`.

[source]
----
(press g) (press i)
(press i) (press g)
----

Note that there aren't any release events listed.
To contrast, the following event sequence would not result in an activation:

[source]
----
(press g) (release g) (press i)
----

Zippychord supports fully overlapping chords and sequences.
For example, this configuration is allowed:

[source]
----
gi	git␣
gi s	git␣status
gi c	git checkout␣
gi c b	git checkout -b␣
gi c a	git commit --amend␣
gi c n	git commit --amend --no-edit
gi c a m	git commit --amend -m 'FIX_THIS_COMMIT_MESSAGE'
----

When you begin with the `(g i)` chord, you can follow up
with various character sequences to output different git commands.
This use case is quite similar to git aliases.
One advantage of zippychord is that it eagerly shows you
the true underlying command as you type.