README

Converting ".adoc" to html

To generate html from the these documentation files, use "asciidoctor"
(they are not fully compatible with the separate "asciidoc" project)

---

Simulated Output/Sim Out

🕐Δms│ 1500 100 1500 3500 50 50 50 50 50
In───┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
k↑ │ 1 1 J L
k↓ │ J L 1 1
k⟳ │
Σin │ ↓J 🕐1600 ↓L 🕐5000 ↓1 🕐50 ↑1 🕐50 ↓1 🕐50 ↑1 🕐50 ↑J 🕐50 ↑L 🕐50
Out──┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
k↑ │ ⇧› ⎇›
k↓ │ ⇧› ⎇›
🖰↑ │
🖰↓ │
🖰 │
🔣 │ 🤲 🤲
code│
raw↑│
raw↓│
Σout │ ↓⇧› ↓⎇› 🤲 🤲 ↑⇧› ↑⎇›

---

Config

= 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 _, __, or ___ 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"]
|===
| _
| Map all unmapped keys in this layer that are defined in defsrc.

| __
| Map all unmapped keys in this layer that are not defined in defsrc.

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

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.

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

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.

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

text

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://raw.githubusercontent.com/jtroo/kanata/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://raw.githubusercontent.com/jtroo/kanata/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 likevisible-backspacedon 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.

---

README Copy Section

Converting ".adoc" to html Copy Section

Simulated Output/Sim Out Copy Section

Config Copy Section

powershell

bash

Get all layer names

Get current layer

Switch to nav layer

powershell

bash

Explore Related Technologies & Topics

README

Converting ".adoc" to html

Simulated Output/Sim Out

Config