Kanata

https://jtroo.github.io/config-1.9.0.html
Admin
Kanata is a project that allows users to customize their keyboard behavior through a configuration...
Tokens:20,458
Snippets:156
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Kanata Switch Example with Boolean Logic

Source: https://jtroo.github.io/config-1.9.0.html/index

Provides a practical example of the Kanata 'switch' action, demonstrating the use of 'and', 'or', and 'break'/'fallthrough' for conditional activation.

```Kanata Config
(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
  )
)
```

--------------------------------

### General defcfg Structure and Example

Source: https://jtroo.github.io/config-1.9.0.html/index

Demonstrates the general structure of the `defcfg` block, which accepts a list of configuration options as key-value pairs. Options not applicable to the current operating system are ignored. This example includes a wide range of settings for different platforms.

```defcfg
(defcfg a 1 b 2)
```

```defcfg
;; 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"
)
```

--------------------------------

### Minimal Kanata Configuration Example

Source: https://jtroo.github.io/config-1.9.0.html/index

A minimal Kanata configuration requires at least `defsrc` to define the source keys and `deflayer` to define the behavior of those keys in a layer. This example demonstrates the simplest valid configuration.

```lisp
(defsrc a b c)

(deflayer start 1 2 3)
```

--------------------------------

### Example Kanata Source Layer Definition

Source: https://jtroo.github.io/config-1.9.0.html/index

An example of defining the source layer in a Kanata configuration file. It includes standard number keys and a custom-defined key ('ì') which might be remapped using `deflocalkeys`.

```lisp
(defsrc
  grv  1    2    3    4    5    6    7    8    9    0    -    ì    bspc
)
```

--------------------------------

### Zippy File Content Example

Source: https://jtroo.github.io/config-1.9.0.html/index

Example content for a zippy file used with Kanata's Zippychord. This file maps short key sequences to longer phrases or commands, demonstrating text expansion capabilities.

```text
dy	day
dy 1	Monday
dy 2	Tuesday
 abc	alphabet
 w  a	Washington
gi	git
gi f p	git fetch -p
```

--------------------------------

### Comprehensive Mouse Actions Example

Source: https://jtroo.github.io/config-1.9.0.html/index

An example demonstrating the configuration of various mouse actions including mouse wheel scrolling, basic and accelerated mouse movements, setting absolute mouse position, and modifying mouse movement speed within a layer definition.

```lisp
(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→
  _    _    _              _              _    _    _
)

```

--------------------------------

### Execute Alias on Startup/Reload with 'alias-to-trigger-on-load'

Source: https://jtroo.github.io/config-1.9.0.html/index

This option allows specifying an alias to be executed automatically when Kanata starts or after a live-reload of the configuration. This is useful for running commands, stacking layers, or initializing specific key behaviors. The provided example shows how to beep on startup and activate a layer that swaps 'i' and 'o' keys.

```kanata
(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 • • _ )
```

--------------------------------

### Macro Action Syntax and Examples

Source: https://jtroo.github.io/config-1.9.0.html/index

Defines the basic macro action for typing sequences of keys, actions, and delays. It supports various inputs and has specific rules for number keys. Examples show typing URLs, capitalized text with special characters, and simulating alt-tab presses.

```lisp
(macro $macro-action1 $macro-action2 ... $macro-actionN)

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

--------------------------------

### Empty Kanata Configuration Definition

Source: https://jtroo.github.io/config-1.9.0.html/index

An example of an empty `defcfg` block in a Kanata configuration file. This allows for Kanata to run with default behavior or with options defined elsewhere.

```lisp
(defcfg)
```

--------------------------------

### Fork Action Syntax Example

Source: https://jtroo.github.io/config-1.9.0.html/index

Demonstrates the basic syntax of the 'fork' action, which takes a default action, an alternate action, and a list of trigger keys. The alternate action is executed if any of the trigger keys are active when 'fork' is invoked.

```configuration
(fork $left-action $right-action $right-trigger-keys)
```

--------------------------------

### Zippychord Output Character Mappings Example (US Layout)

Source: https://jtroo.github.io/config-1.9.0.html/index

Provides an example of configuring output mappings for special characters like closing parenthesis, opening parenthesis, and double quotes within the Zippychord configuration file, tailored for a US keyboard layout.

```scheme
    ")"     S-0
    "("     S-9
    r#"""#  S-'
```

--------------------------------

### Define Sequences and Virtual Keys (Lisp)

Source: https://jtroo.github.io/config-1.9.0.html/index

Defines a sequence for git status using virtual keys. This example demonstrates how to link a sequence of key presses to a virtual key action, which in turn triggers a macro action.

```common-lisp
(defseq git-status (g s t))
(defvirtualkeys git-status (macro g i t spc s t a t u s))
```

--------------------------------

### Zippychord Git Command Shorthands

Source: https://jtroo.github.io/config-1.9.0.html/index

Illustrates how Zippychord can be used to create shorthands for common Git commands. This example shows a base 'gi' mapping to 'git' and then further sequences to specify different Git operations like fetch, status, or checkout.

```text
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'
```

--------------------------------

### Define Dynamic Macro Alias

Source: https://jtroo.github.io/config-1.9.0.html/index

Defines aliases for dynamic macro actions, including recording, playing, stopping, and truncating recordings. This example showcases common usage patterns for managing keyboard macros.

```scheme
(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)
)
```

--------------------------------

### Context-Dependent Chords with Auto-Space (Lisp)

Source: https://jtroo.github.io/config-1.9.0.html/index

Showcases advanced chord configuration using `defchordsv2`. This example defines chords like '(d a y)' and '(t u e)' that output specific words ('day', 'Tuesday') when used in conjunction with other configurations, including auto-spacing and punctuation handling.

```common-lisp
(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 ;))
```

--------------------------------

### Kanata Zippychord Configuration Example

Source: https://jtroo.github.io/config-1.9.0.html/index

A sample Kanata configuration defining zippychord settings, including output character mappings for special characters and accented letters. This configuration allows for custom keybindings to produce specific characters or sequences.

```hiccup
(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)
  )
)
```

--------------------------------

### Zippychord Configuration File Syntax

Source: https://jtroo.github.io/config-1.9.0.html/index

Illustrates the syntax for defining chords and their corresponding outputs in a Zippychord configuration file. It explains the use of comments, the tab-separated format for input and output columns, and the concept of follow chords.

```text
// 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
```

--------------------------------

### Macro Release Cancel and Cancel On Press Variant

Source: https://jtroo.github.io/config-1.9.0.html/index

Explains the macro-release-cancel-and-cancel-on-press variant, combining the cancellation logic of both release and press triggers. The example demonstrates this combined behavior for the '1!@' macro.

```lisp
(macro-release-cancel-and-cancel-on-press @1 500 bspc S-1 500 bspc S-2)

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

--------------------------------

### Kanata Switch Logic Check Syntax

Source: https://jtroo.github.io/config-1.9.0.html/index

Illustrates the syntax for constructing logic checks within the Kanata 'switch' action, including basic key names and compound logic.

```Kanata Config
($item1 $item2 ... $itemN)
```

--------------------------------

### Kanata Switch Action Syntax

Source: https://jtroo.github.io/config-1.9.0.html/index

Defines the basic syntax for the 'switch' action in Kanata, including logic checks, actions, and post-activation behavior.

```Kanata Config
(switch
  $logic-check1 $action1 $post-activate1
  $logic-check2 $action2 $post-activate2
  ...
  $logic-checkN $actionN $post-activateN)
```

--------------------------------

### Building Kanata with Windows Manifest Support

Source: https://jtroo.github.io/config-1.9.0.html/index

Demonstrates the command to build the Kanata binary with Windows manifest support, enabling its use in elevated windows. This requires the `win_manifest` feature flag to be set during the build process.

```bash
cargo build --win_manifest
```

--------------------------------

### Tap Repress Timeout Example

Source: https://jtroo.github.io/config-1.9.0.html/index

Illustrates the behavior of the tap-hold action with different `$tap-repress-timeout` values. It shows how this parameter influences whether a rapid press-release-press sequence results in a tap action or contributes to a hold action.

```Emacs Lisp
(tap-hold $tap-repress-timeout 200 a lctl)
```

--------------------------------

### Kanata Configuration Comments

Source: https://jtroo.github.io/config-1.9.0.html/index

Demonstrates how to add single-line and multi-line comments to Kanata configuration files. Comments are ignored by Kanata and are used for human readability.

```kanata-config
;; 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.

#|
This is
a multi-line comment block
|#
```

--------------------------------

### Setting Environment Variables for Kanata

Source: https://jtroo.github.io/config-1.9.0.html/index

Examples of how to set environment variables in the current terminal session, which can then be used by Kanata's `environment` directive. This applies to different shells like PowerShell and Bash.

```powershell
# powershell
$env:VAR_NAME = "var_value"
```

```bash
# bash
VAR_NAME=var_value
```

--------------------------------

### Tap-Hold Variants

Source: https://jtroo.github.io/config-1.9.0.html/index

Provides details on various tap-hold variants, including tap-hold-press, tap-hold-release, and others, each with specific trigger conditions.

```APIDOC
## Tap-Hold Variants

### Description
These variants extend the basic `tap-hold` functionality with additional conditions for activating hold or tap actions.

### Method
N/A (Configuration directive)

### Endpoint
N/A (Configuration directive)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Variants:

1.  **tap-hold-press** (`tap⬓↓`)
    *   **Description**: Activates `$hold-action` early if the key is held and another input key is pressed.
    *   **Syntax**: `(tap-hold-press $tap-repress-timeout $hold-timeout $tap-action $hold-action)`

2.  **tap-hold-release** (`tap⬓↑`)
    *   **Description**: Activates `$hold-action` early if the key is held and another input key is pressed and then released.
    *   **Syntax**: `(tap-hold-release $tap-repress-timeout $hold-timeout $tap-action $hold-action)`

3.  **tap-hold-press-timeout**
    *   **Description**: Activates `$hold-action` if the key is held and another input key is pressed. If the defined timeout elapses, `$timeout-action` will activate.
    *   **Syntax**: `(tap-hold-press-timeout $tap-repress-timeout $hold-timeout $tap-action $hold-action $timeout-action)`

4.  **tap-hold-release-timeout**
    *   **Description**: Activates `$hold-action` early if the key is held and another input key is pressed and released. If the defined timeout elapses, `$timeout-action` will activate.
    *   **Syntax**: `(tap-hold-release-timeout $tap-repress-timeout $hold-timeout $tap-action $hold-action $timeout-action)`

5.  **tap-hold-release-keys**
    *   **Description**: Activates `$hold-action` early if the key is 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.
    *   **Syntax**: `(tap-hold-release-keys $tap-repress-timeout $hold-timeout $tap-action $hold-action $tap-keys)`

6.  **tap-hold-except-keys**
    *   **Description**: 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.
    *   **Syntax**: `(tap-hold-except-keys $tap-repress-timeout $hold-timeout $tap-action $hold-action $tap-keys)`

### Request Example
```
(tap-hold-press 50 200 a lctl)
(tap-hold-release 50 200 a lctl)
(tap-hold-release-keys 50 200 a lctl (key "b"))
```

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Define and Expand Basic Template for Key Remapping

Source: https://jtroo.github.io/config-1.9.0.html/index

Demonstrates defining a template `alt-fork` for modifying key behavior with the Alt modifier. It shows how to expand this template using `template-expand` and its shorthand `t!`, substituting specific keys and actions.

```lisp
(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)
```

--------------------------------

### Conceptual Equivalence of Kanata Logic to C-style Boolean Logic

Source: https://jtroo.github.io/config-1.9.0.html/index

Translates a complex Kanata logic check used in a 'switch' case to its equivalent representation in C-style boolean logic for comparison.

```Conceptual Equivalence
(a && b && (c || d) && (e || f))
```

--------------------------------

### Define Aliases and Sequences with Shifted Keys (Lisp)

Source: https://jtroo.github.io/config-1.9.0.html/index

Demonstrates defining aliases for key combinations and sequences for domain names. It specifically shows how to handle shifted keys within sequences, distinguishing between holding a modifier and releasing/repressing it.

```common-lisp
(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))
)
```

--------------------------------

### Layer and Base Layer Checks in Switch Statements

Source: https://jtroo.github.io/config-1.9.0.html/index

Shows how to use `layer` and `base-layer` conditions in `switch` statements to check the currently active layer or the designated base layer.

```lisp
(defalias switch-layer-example
  (switch
     ((layer base)) x break
    ((layer other)) y break
                 () z break
  )
)
```

```lisp
(defalias switch-layer-example
  (switch
     ((base-layer base)) x break
    ((base-layer other)) y break
                 () z break
  )
)
```

--------------------------------

### Macro Release Cancel Variant

Source: https://jtroo.github.io/config-1.9.0.html/index

Implements the macro-release-cancel variant, which cancels all active macros when the triggering key is released. This allows for sequential output changes based on hold duration, with an example demonstrating typing '1', then '!', then '@' with delays.

```lisp
(macro-release-cancel @1 500 bspc S-1 500 bspc S-2)

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

--------------------------------

### Define Virtual Keys for Sequences (Lisp)

Source: https://jtroo.github.io/config-1.9.0.html/index

Defines virtual keys for domain names, including 'https'. This shows how to map typed sequences to specific macro actions, with 'https' demonstrating a more complex sequence involving modifier keys.

```common-lisp
(defvirtualkeys
    dotcom (macro . c o m)
    dotorg (macro . o r g)
    https (macro h t t p s S-; / /)
)
```

--------------------------------

### Template for Defining Sequences and Virtual Keys (Lisp)

Source: https://jtroo.github.io/config-1.9.0.html/index

A template used to define virtual keys and sequences simultaneously. This simplifies the creation of common patterns where a sequence of inputs maps to a specific output action via a virtual key.

```common-lisp
(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))
```

--------------------------------

### Basic Mouse Movement Configuration

Source: https://jtroo.github.io/config-1.9.0.html/index

Configures basic mouse cursor movement in specified directions. It takes an interval between movements and a distance for each movement. Supports up, down, left, and right directions.

```lisp
(movemouse-$variant $interval $distance)
```

--------------------------------

### Kanata defsrc Key Definition

Source: https://jtroo.github.io/config-1.9.0.html/index

Defines the source keys for Kanata, specifying the order and names of physical keys that will be processed. This is a required entry, and exactly one `defsrc` list must be present in the configuration.

```kanata-config
(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
)
```

--------------------------------

### Enable System Notification on Config Reload

Source: https://jtroo.github.io/config-1.9.0.html/index

Enables system notifications to appear when Kanata's configuration is reloaded. This feature requires a Kanata build with `win-tray` and `gui-enabled` and defaults to true.

```defcfg
(defcfg
  notify-cfg-reload true
)
```

--------------------------------

### Enable Command Execution with danger-enable-cmd

Source: https://jtroo.github.io/config-1.9.0.html/index

Enables the `cmd` action in Kanata, allowing the execution of programs with arguments. This is a security-sensitive option and requires the Kanata program to be compiled with the `cmd` action enabled. Disabled by default.

```lisp
(defcfg
  danger-enable-cmd yes
)
```

--------------------------------

### Define Localized Keyboard Keys (Linux)

Source: https://jtroo.github.io/config-1.9.0.html/index

Defines custom key names for Kanata configurations on Linux systems. It maps a physical key ('ì') to a numerical code specific to the Linux input system.

```lisp
(deflocalkeys-linux
  ì 13
)
```

--------------------------------

### Define and Use Fake Keys with Actions (Older Style)

Source: https://jtroo.github.io/config-1.9.0.html/index

Demonstrates the older configuration style for fake keys, including defining modifier fake keys and actions like press, release, tap, and toggle. It also shows aliasing these fake keys and integrating them into a layer.

```lisp
(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
)
```

--------------------------------

### Continue Kanata if No Linux Devices Found

Source: https://jtroo.github.io/config-1.9.0.html/index

Configures Kanata to continue running even if no input devices are detected. By default, Kanata will exit if no devices are found. Setting this to `yes` prevents a crash in such scenarios.

```lisp
(defcfg
  linux-continue-if-no-devs-found yes
)
```

--------------------------------

### Tap-Hold with Key Exceptions

Source: https://jtroo.github.io/config-1.9.0.html/index

Details the `tap-hold-except-keys` variant, designed to always trigger a tap action when specific keys are pressed during the hold period. This differs from standard tap-hold behavior by prioritizing tap actions under certain conditions, useful for complex modifier or layer switching setups.

```emacs-lisp
(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))
)
```

--------------------------------

### Define Localized Keyboard Keys (macOS)

Source: https://jtroo.github.io/config-1.9.0.html/index

Defines custom key names for Kanata configurations on macOS. This maps a physical key ('ì') to a numerical code recognized by the macOS input system.

```lisp
(deflocalkeys-macos
  ì 13
)
```

--------------------------------

### Basic Tap-Hold Key Configurations

Source: https://jtroo.github.io/config-1.9.0.html/index

Demonstrates the fundamental tap-hold, tap-hold-press, and tap-hold-release actions. These actions allow a single key to perform one function when tapped and another when held, with defined timings. They are useful for creating more responsive custom keymaps.

```emacs-lisp
(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
)
```

--------------------------------

### Control Display of Blank Tooltip Icons

Source: https://jtroo.github.io/config-1.9.0.html/index

Determines whether a blank square is shown instead of an icon when a layer does not have a configured icon. This option requires a Kanata build with `win-tray` and `gui-enabled` and defaults to false.

```defcfg
(defcfg
  tooltip-show-blank true
)
```

--------------------------------

### Define and Expand Template for Chord Groups and Aliases

Source: https://jtroo.github.io/config-1.9.0.html/index

Illustrates defining a template `left-hand-chords` to manage chord groups and their associated aliases across different layers. The template takes parameters for the chord group name, keys, and alias names, facilitating consistent chord behavior.

```lisp
(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)
```

--------------------------------

### Enable System Notifications for Kanata Errors

Source: https://jtroo.github.io/config-1.9.0.html/index

Enables system notifications to be displayed when Kanata encounters errors. This feature requires a Kanata build with `win-tray` and `gui-enabled` and defaults to true.

```defcfg
(defcfg
  notify-error true
)
```

--------------------------------

### Define Localized Keyboard Keys (Windows IOv2)

Source: https://jtroo.github.io/config-1.9.0.html/index

Defines custom key names for Kanata configurations using the winIOv2 input method on Windows. It maps a physical key ('ì') to a numerical code compatible with the winIOv2 variant.

```lisp
(deflocalkeys-winiov2
  ì 187
)
```

--------------------------------

### Configure Minimum Idle Time for v2 Chords (Kanata Lisp)

Source: https://jtroo.github.io/config-1.9.0.html/index

Sets the minimum idle time in milliseconds during which chord processing is disabled. The default and minimum value for `chords-v2-min-idle` is 5ms.

```lisp
(defcfg
  chords-v2-min-idle 200
)
```

--------------------------------

### Live Reload Configuration Actions in Kanata

Source: https://jtroo.github.io/config-1.9.0.html/index

These actions reload the current configuration file without restarting Kanata. They support cycling through multiple configuration files specified at startup. Live reload does not apply to device-related configurations.

```Kanata Lisp
(deflayer has-live-reload
  lrld a s d f
)
```

```Kanata Lisp
(deflayer has-live-reloads
  lrld lrpv lrnx (lrld-num 3)
)
```

--------------------------------

### Kanata Zippychord Configuration Syntax

Source: https://jtroo.github.io/config-1.9.0.html/index

Defines the `defzippy` configuration item within Kanata for enabling chorded text expansion. It specifies required and optional parameters like the zippy filename, deadlines, idle reactivate time, smart space behavior, and output character mappings.

```scheme
(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 (
    $punc1 $punc2 ... $puncN) ;; optional
  output-character-mappings (
    $character1 $output-mapping1
    $character2 $output-mapping2
    ;; ...
    $characterN $output-mappingN
  )
)
```

--------------------------------

### Include Specific Linux Input Device Names

Source: https://jtroo.github.io/config-1.9.0.html/index

Defines a list of device names to be included when `linux-dev` is omitted. Device names not present in this list will be ignored. Only exact matches are supported; device paths are not valid. This is useful for precise control over which devices Kanata processes.

```lisp
(defcfg
  linux-dev-names-include (
    "Device name 1"
    "Device name 2"
  )
)
```

--------------------------------

### Platform-Specific Kanata Configuration

Source: https://jtroo.github.io/config-1.9.0.html/index

Define configurations that are only active on specific operating systems using the `platform` directive. This directive takes a list of applicable platforms and a configuration block. Supported platforms include `win`, `winiov2`, `wintercept`, `linux`, and `macos`.

```kanata-config
(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 |#))
)
```

--------------------------------

### Key History Logic in Switch Statements

Source: https://jtroo.github.io/config-1.9.0.html/index

Shows how to use `key-history` within a `switch` statement to check the recency and order of typed keys. The recency parameter ranges from 1 (most recent) to 8.

```lisp
(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
  )
)
```

--------------------------------

### Parse Command Output as S-expression Keys (Kanata)

Source: https://jtroo.github.io/config-1.9.0.html/index

The `cmd-output-keys` variant executes a command and parses its stdout as an S-expression. It specifically supports delays, keys, and chords. This is useful for commands that output structured data that Kanata can interpret as input events.

```scheme
(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-;') ')'")
)
```

--------------------------------

### Kanata Global Key Overrides with defoverrides

Source: https://jtroo.github.io/config-1.9.0.html/index

The `defoverrides` configuration item allows defining global key mappings that override existing ones, regardless of how keys are generated. It accepts pairs of input and output key lists, each containing modifiers and a single non-modifier key.

```lisp
;; 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
)
```

--------------------------------

### Accelerated Mouse Movement Configuration

Source: https://jtroo.github.io/config-1.9.0.html/index

Configures mouse cursor movement with acceleration, gradually increasing the distance per movement until a maximum is reached. Requires interval, acceleration time, minimum distance, and maximum distance parameters.

```lisp
(movemouse-accel-$variant $interval $acceleration-time $min $max)
```

--------------------------------

### Block Unmapped Keys (Kanata Lisp)

Source: https://jtroo.github.io/config-1.9.0.html/index

This option makes keys not present in `defsrc` act as no-ops, useful for using only a subset of the keyboard. It requires `process-unmapped-keys` to be set to `yes` for correct functionality.

```lisp
(defcfg
  block-unmapped-keys yes
)
```

--------------------------------

### Logical OR and Fallthrough in Switch Cases

Source: https://jtroo.github.io/config-1.9.0.html/index

Demonstrates logical OR operations and fallthrough behavior in switch cases. Case 2 uses a logic check similar to `fork`, while Case 3 always passes, ensuring activation if previous cases fail.

```lisp
(a b c) c fallthrough
() b break
```

```lisp
(or a b c)
```

```plaintext
a || b || c
```

--------------------------------

### Configure Tooltip Behavior for Layer Changes

Source: https://jtroo.github.io/config-1.9.0.html/index

Enables the display of a custom layer icon near the mouse pointer to indicate layer changes. This feature requires a Kanata build with `win-tray` and `gui-enabled`. It defaults to false.

```defcfg
(defcfg
  tooltip-layer-changes true
)
```

--------------------------------

### Tap-Hold Action

Source: https://jtroo.github.io/config-1.9.0.html/index

The tap-hold action allows one action/key for a 'tap' and a different action/key for a 'hold'. It takes four parameters: tap repress timeout, hold timeout, tap action, and hold action.

```APIDOC
## (tap-hold $tap-repress-timeout $hold-timeout $tap-action $hold-action)

### Description
Activates different actions based on whether a key is tapped or held. A tap is a rapid press and release, while a hold is a long press.

### Method
N/A (Configuration directive)

### Endpoint
N/A (Configuration directive)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```
(tap-hold 100 200 a lctl)
```

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Key Timing Logic in Switch Statements

Source: https://jtroo.github.io/config-1.9.0.html/index

Illustrates the use of `key-timing` in `switch` statements to compare the time elapsed since key presses. It supports comparisons like 'less-than' or 'greater-than' against a specified millisecond value, with recency from 1 to 8.

```lisp
(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
  )
)
```

--------------------------------

### Define Localized Keyboard Keys (Windows Interception)

Source: https://jtroo.github.io/config-1.9.0.html/index

Defines custom key names for Kanata configurations when using the Interception driver on Windows. This maps a physical key ('ì') to a numerical code recognized by the Interception variant.

```lisp
(deflocalkeys-wintercept
  ì 187
)
```

--------------------------------

### Overlapping Keys in Sequences (Lisp)

Source: https://jtroo.github.io/config-1.9.0.html/index

Demonstrates using the 'O-' prefix in `defseq` to define a set of keys that must all be pressed before any are released. This is useful for multi-key inputs where the order of secondary keys doesn't matter, but it has memory limitations.

```common-lisp
(defvirtualkey hello (macro h (unshift e l) 5 (unshift l o)))
(defseq hello (O-(h l o)))
```

--------------------------------

### Transparent and Use-Defsrc Actions in Kanata

Source: https://jtroo.github.io/config-1.9.0.html/index

The transparent key action `_` activates the behavior of the layer underneath the current one. `use-defsrc` outputs the corresponding input key from the `defsrc` definition. These are useful for layered keymaps.

```Kanata Lisp
(defsrc a b c d)
(defalias src use-defsrc)
(deflayer remap-only-c-to-d
  _ _ d @src)
```

--------------------------------

### Define Unmod with Specific Modifier Release

Source: https://jtroo.github.io/config-1.9.0.html/index

Demonstrates using `unmod` with a specified list of modifiers to deactivate. This allows for selective release of modifiers (e.g., only Alt keys) before outputting a key, offering finer control than releasing all modifiers.

```lisp
(defalias
	;; only unshift the alt keys
	unalt-a (unmod (lalt ralt) a)
)
```

--------------------------------

### Input Handling in Switch Statements

Source: https://jtroo.github.io/config-1.9.0.html/index

Explains how to use the `input` condition in `switch` statements to check for real or virtual keys. It also introduces `input-history`, which requires a recency of 2 to refer to the previously pressed input because recency 1 is the activating input.

```lisp
(defalias switch-input-example
  (switch
    ((input real lctl)) $ac1 break
    ((input virtual vk1)) $ac2 break
    () $ac3 break
  )
)
```

```lisp
(defalias switch-input-history-example
  (switch
    ((input-history real lsft 2)) $var1 break
    ((input-history virtual vk2 2)) $var1 break
    () $ac3 break
  )
)
```

--------------------------------

### Macro Repeat Variants

Source: https://jtroo.github.io/config-1.9.0.html/index

Introduces the macro-repeat variants, which allow macros to repeat while a key is held down. It specifies that repetition occurs after all macros complete and notes that only the most recently pressed repeating macro will repeat if multiple are held.

```lisp
(macro-repeat mltp)
(macro-repeat-release-cancel mltp)
(macro-repeat-cancel-on-press mltp)
(macro-repeat-release-cancel-and-cancel-on-press mltp)

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

--------------------------------

### Kanata Arbitrary Code Action for Key Testing

Source: https://jtroo.github.io/config-1.9.0.html/index

The `arbitrary-code` action sends a specified numerical key code to Kanata's output mechanism, useful for testing keys not yet mapped or named. This action is not cross-platform and still uses SendInput with the Interception driver.

```lisp
(defalias ab1 (arbitrary-code 700))
```

--------------------------------

### Configure Linux Unicode Input Termination

Source: https://jtroo.github.io/config-1.9.0.html/index

Sets the key or key combination used to terminate Unicode input on Linux. The default is 'enter', but this can be changed to 'space', 'enter-space', or 'space-enter' to accommodate different application behaviors.

```lisp
(defcfg
  linux-unicode-termination space
)
```

--------------------------------

### Exclude Specific Linux Input Device Names

Source: https://jtroo.github.io/config-1.9.0.html/index

Defines a list of device names to be excluded when `linux-dev` is omitted. This option functions identically to `linux-dev-names-include` but for exclusion. It is generally recommended to use either `linux-dev-names-include` or `linux-dev-names-exclude`, but not both.

```lisp
(defcfg
  linux-dev-names-exclude (
    "Device Name 1"
    "Device Name 2"
  )
)
```

--------------------------------

### Tap-Hold with Early Tap Keys

Source: https://jtroo.github.io/config-1.9.0.html/index

Explains the `tap-hold-release-keys` variant, which allows specific keys to trigger an early tap while the main tap-hold action is active. This enables immediate activation of a tap action based on secondary key presses, enhancing macro or shortcut functionality.

```emacs-lisp
(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-Dance Action Configuration

Source: https://jtroo.github.io/config-1.9.0.html/index

The `tap-dance` action allows different behaviors based on the number of consecutive taps of the same key within a specified timeout. The `tap-dance-eager` variant activates actions sequentially as taps progress. These are often used with macros to prevent key auto-repeat.

```lisp
(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))
)

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

--------------------------------

### Configure Rapid Event Delay (Kanata Lisp)

Source: https://jtroo.github.io/config-1.9.0.html/index

Applies a delay in milliseconds to specific key events, such as the release of one-shot presses or tap-holds, and chord activations. The default is 5ms, but can be adjusted to mitigate environment-specific issues with rapid event processing.

```lisp
;; If your environment is particularly buggy, might need to delay even more
(defcfg
  rapid-event-delay 20
)
```

--------------------------------

### Kanata Switch Special Logic Checks

Source: https://jtroo.github.io/config-1.9.0.html/index

Details the syntax for special logic checks available in Kanata's 'switch' action, such as 'or', 'and', 'not', 'key-history', 'key-timing', 'input', 'input-history', 'layer', and 'base-layer'.

```Kanata Config
(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)
```

--------------------------------

### Execute Arbitrary Binaries with Arguments (Kanata)

Source: https://jtroo.github.io/config-1.9.0.html/index

The `cmd` action executes a specified binary with a list of arguments. It's useful for running external programs directly from the configuration. Lists can be used for arguments and are flattened depth-first. Commands are not executed via a shell, so shell features like environment variable substitution are not available.

```scheme
(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")
)
```
Tokens:
Raw