KMonad

KEYBOARD

/dev/input/by-id/usb-Logitech_USB_Receiver-if02-event-kbd

STARSHIP_RUNNER_CONFIG

I want the runner to have a different configuration than my normal shell, so this points to the other config

~/.config/starship_runner.toml

Let’s define buttons for increasing/decreasing the keyboard backlight. These will be used in other layers so that I can easily see when I’m in the base layer and when I’m in a custom layer, like Volume. This will be done by turning on the backlight when in the layers, and turning it back off when leaving the layers.

[aliases]
kbd-set-backlight-command = "dbus-send --system --print-reply --dest=\"org.freedesktop.UPower\" /org/freedesktop/UPower/KbdBacklight org.freedesktop.UPower.KbdBacklight.SetBrightness"
kbd-set-backlight-on-command = "$kbd-set-backlight-command int32:1"
kbd-set-backlight-off-command = "$kbd-set-backlight-command int32:0"

kbd-set-backlight-on = (cmd-button "$kbd-set-backlight-command int32:1")
kbd-set-backlight-off = (cmd-button "$kbd-set-backlight-command int32:0")
kbd-toggle-backlight = (cmd-button "$kbd-set-backlight-on-command" "$kbd-set-backlight-off-command")

Optional: as many layers as you please

We had already defined `num` as referring to a `(layer-toggle numbers)`. We will get into layer-manipulation soon, but first, let’s just create a second layer that overlays a numpad under our right-hand.

To easily specify layers it is highly recommended to create an empty `deflayer` statement as a comment at the top of your config, so you can simply copy-paste this template. There are also various empty layer templates available in the ’./keymap/template’ directory.

Enable the “leader” layer for the next keypress. If we release @leader_key before the next key, we treat the keypress as a tap, even if for a short period of time both keys were down. If we release @leader_key after the next key, we treat it as holding.

Also, if we hold the key for more than 250 milliseconds, treat it like we are holding the key. When we are trying to use the super key in a tap melody, we have the key down for a very short time, so having the hold timeout on 250ms lets us use it for chords more conveniently

[base]
[[private]]
leader-key = (tap-hold-next-release 250 (around-next (layer-toggle leader)) lmet)
[[keys]]
lmet = leader-key
grave = (tap-hold $tap-hold-delay-min grave @simple-datetime-overlay) # (simple-datetime-overlay)
lalt = (tap-hold-next-release $tap-hold-delay XX (around-next (layer-toggle leader-no-block)))

[qwerty]
# we inherit from source before base so that we can add the `qwerty` on top of
# other layers and overwrite other mappings
parent = { source, base }
[[private]]
enable-homerow-mods = (layer-switch qwerty-homerow-mods)
[[keys]]
ScrollLock = enable-homerow-mods
caps = 'lctrl'

[qwerty-homerow-mods]
parent = base
[[private]]
disable-homerow-mods = (layer-switch qwerty)

We want this key to act as escape when tapped, and lctrl when held. However, while holding the key, we want to disable home row modifiers. We do this by adding the stock qwerty layer on top of the stack and holding lctl while holding the key. To do this,

lctrl-or-escape = (tap-hold-next-release 125 esc (around (layer-toggle qwerty) lctl))
lshift-or-caps-lock = (tap-hold-next-release 125 caps (around (layer-toggle qwerty) lshift))
rshift-or-caps-lock = (tap-hold-next-release 125 caps (around (layer-toggle qwerty) rshift))

This is a GACS home-row-mods configuration detailed on this page. k is bound to lctl rather than rctl because rctl is the compose key on my system.

a_homerow_chords = (tap-hold $hmod-delay a (layer-toggle home-row-chord))
q_homerow_movement = (tap-hold $hmod-delay q (layer-toggle home-row-movement))
backslash_layer = (tap-hold-next-release $hmod-delay \ (layer-toggle backslash))
s_lalt = (tap-hold-next-release $hmod-delay s lalt)
d_lctrl = (tap-hold-next-release $hmod-delay d lctl)
f_lshift = (tap-hold-next-release $hmod-delay f lshift)

k_lctrl = (tap-hold-next-release $hmod-delay k lctl)
j_rshift = (tap-hold-next-release $hmod-delay j rshift)
l_ralt = (tap-hold-next-release $hmod-delay l ralt)

[[keys]]
ScrollLock = disable-homerow-mods
caps = lctrl-or-escape

a = a_homerow_chords
q = q_homerow_movement
backslash = backslash_layer
s = s_lalt
d = d_lctrl
f = f_lshift
k = k_lctrl
j = j_rshift
l = l_ralt

We want to disable the homerow mods whenever we explicitly hit a modifier key.

lshift = (around (layer-toggle qwerty) @lshift-or-caps-lock)
rshift = (around (layer-toggle qwerty) @rshift-or-caps-lock)
lctrl = (around (layer-toggle qwerty) lctrl)

This is a layer where the numeric keys are mapped to buttons that switch to that numbered desktop.

SWAP_MONITOR_WINDOWS_SCRIPT

~/.config/kmonad/windows/swap_monitor_windows.sh

MONITOR_MOVE_RELATIVE_SCRIPT

~/.config/kmonad/windows/monitor_move_relative.sh

[numeric-desktop-switching]
[[private]]
SWAP_MONITOR_WINDOWS_SCRIPT = "|>SWAP_MONITOR_WINDOWS_SCRIPT<|"
MONITOR_MOVE_RELATIVE_SCRIPT = "|>MONITOR_MOVE_RELATIVE_SCRIPT<|"

window_to_next_screen = (cmd-button "$kwin_shortcut_cmd \"Window to Next Screen\"")
[[keys]]

Let’s generate this repetitive code with Python.

return '\n'.join(
    map(lambda n: f'{n} = (tap-hold $tap-hold-delay-min (cmd-button "$kwin_shortcut_cmd \\"Switch to Desktop {n}\\"") (cmd-button "$kwin_shortcut_cmd \\"Window to Desktop {n}\\""))',
        range(1, 10)))

1 = (tap-hold $tap-hold-delay-min (cmd-button "$kwin_shortcut_cmd \"Switch to Desktop 1\"") (cmd-button "$kwin_shortcut_cmd \"Window to Desktop 1\""))
2 = (tap-hold $tap-hold-delay-min (cmd-button "$kwin_shortcut_cmd \"Switch to Desktop 2\"") (cmd-button "$kwin_shortcut_cmd \"Window to Desktop 2\""))
3 = (tap-hold $tap-hold-delay-min (cmd-button "$kwin_shortcut_cmd \"Switch to Desktop 3\"") (cmd-button "$kwin_shortcut_cmd \"Window to Desktop 3\""))
4 = (tap-hold $tap-hold-delay-min (cmd-button "$kwin_shortcut_cmd \"Switch to Desktop 4\"") (cmd-button "$kwin_shortcut_cmd \"Window to Desktop 4\""))
5 = (tap-hold $tap-hold-delay-min (cmd-button "$kwin_shortcut_cmd \"Switch to Desktop 5\"") (cmd-button "$kwin_shortcut_cmd \"Window to Desktop 5\""))
6 = (tap-hold $tap-hold-delay-min (cmd-button "$kwin_shortcut_cmd \"Switch to Desktop 6\"") (cmd-button "$kwin_shortcut_cmd \"Window to Desktop 6\""))
7 = (tap-hold $tap-hold-delay-min (cmd-button "$kwin_shortcut_cmd \"Switch to Desktop 7\"") (cmd-button "$kwin_shortcut_cmd \"Window to Desktop 7\""))
8 = (tap-hold $tap-hold-delay-min (cmd-button "$kwin_shortcut_cmd \"Switch to Desktop 8\"") (cmd-button "$kwin_shortcut_cmd \"Window to Desktop 8\""))
9 = (tap-hold $tap-hold-delay-min (cmd-button "$kwin_shortcut_cmd \"Switch to Desktop 9\"") (cmd-button "$kwin_shortcut_cmd \"Window to Desktop 9\""))

# go to previous desktop
semicolon = (tap-hold $tap-hold-delay-min (cmd-button "$kwin_shortcut_cmd \"Switch to Previous Desktop\"") (cmd-button "$MONITOR_MOVE_RELATIVE_SCRIPT -1"))
# go to next desktop
apostrophe = (tap-hold $tap-hold-delay-min (cmd-button "$kwin_shortcut_cmd \"Switch to Next Desktop\"") (cmd-button "$MONITOR_MOVE_RELATIVE_SCRIPT 1"))

Minus = (cmd-button "$SWAP_MONITOR_WINDOWS_SCRIPT")
# NOTE: this approach only works with 2 monitors
Equal = (tap-hold $tap-hold-delay-min @window_to_next_screen #(@window_to_next_screen @switch_focus_screen))

This used to be the “Desktop/Window” layer, but after adding leader key functionality, the backslash key now constitutes its own dedicated layer name.

[backslash]
parent = { numeric-desktop-switching, alphabetic-window-tiling, leader }
[[keys]]
RightBrace = window-focusing:focus-right
LeftBrace = window-focusing:focus-left

The idea of the Jump List is to emulate Vim behavior and allow for switching between different positions. In a windowing system context, each entry in the Jump List is an active window (+ Desktop). Vim has a ton of operations which modify the Jump List, but for our purposes, we will have two main modes of modification:

1. Window Switcher
   • using the window switcher will automatically add entries to the Jump List
2. Manual Marks
   • to fill in for the Vim operations, we will provide an easy way to mark an entry in the Jump List through a direct keybinding

3. /home/sridaran/.config/kmonad/jump-list/jump_list.pl
   

We move the command to the global scope so we can use it within other layers.

[aliases]
jump-list-mark = "|>JUMP_LIST_SCRIPT<| add-shift"

[jump-list]
[[private]]
script = "|>JUMP_LIST_SCRIPT<|"
[[public]]
# adds current window as entry to the jump list
add = (cmd-button "$script add-replace")

# jumps to the next entry in the jump list
next = (cmd-button "$script next")
# jumps to the previous entry in the jump list
prev = (cmd-button "$script prev")

Opens the Window Switcher

[window-switcher]
[[private]]
rofi-args = "-noplugins -lines 5 --normal-window -sort -sorting-method fzf -monitor -4 -matching fuzzy -modi window -show window"

# note that in Posix SH, & acts as a separator between commands, and a semicolon
# after it is invalid syntax.
mark-and-jump-command = "$jump-list-mark & sleep 0.15; wmctrl -ia {window}"
jump-to-window = (cmd-button "$ROFI $rofi-args -window-command \"/bin/dash -c '$mark-and-jump-command'\" -kb-accept-entry '' -kb-accept-alt 'Return'")
pull-window = (cmd-button "$ROFI $rofi-args -window-command 'wmctrl -iR {window}' -kb-accept-entry '' -kb-accept-alt 'Return'")
[[public]]
activate = (tap-hold $tap-hold-delay-min @jump-to-window @pull-window)

I made this into a layer purely for organizational purposes. When tapped, activate will yield a Rofi window switcher which will switch to the selected window. When held, activate will yield a Rofi window switcher which will move the selected window to the current desktop before selecting it.

I compiled rofi from source and put it in ~/.local/bin because the RPM version was too slow for my taste. Some of the flags are also there for optimization reasons: -modi, -noplugins and --normal-window. I noticed that the startup animation was faster with --normal-window, and the other 2 flags stop rofi from doing unnecessary work. -matching fuzzy makes it use fuzzy matching instead of only matching the raw string. -sort and -sorting-method fzf make the selections a lot more intelligent. -monitor -4 makes it open rofi on the monitor of the currently focused window.

This command uses wmctrl to switch to a currently-existing Discord window, and if it fails opens a new instance of Discord.

[aliases]
DISCORD_SCRIPT = "~/.config/kmonad/discord/discord.sh"
discord = (cmd-button "$DISCORD_SCRIPT")

Opens Emacs: emacsclient on tap, emacs process on hold.

[aliases]
emacs = (tap-hold $tap-hold-delay-min (cmd-button "$EMACSCLIENT --create-frame") (cmd-button "$EMACS"))

Opens a new Firefox window

FIREFOX_TAB_SWITCHER_SCRIPT

~/.config/kmonad/firefox/firefox_tab_switcher.sh

[aliases]
FIREFOX_TAB_SWITCHER_SCRIPT = "|>FIREFOX_TAB_SWITCHER_SCRIPT<|"

open_firefox = (cmd-button "firefox")
select_firefox_tab = (cmd-button "$FIREFOX_TAB_SWITCHER_SCRIPT")

firefox_composite = (tap-hold 135 @open_firefox @select_firefox_tab)

CHANGE_BRIGHTNESS_SCRIPT

~/.config/kmonad/brightness/change_brightness.sh

CHANGE_BACKLIGHT_SCRIPT

~/.config/kmonad/brightness/change_backlight.sh

QUEUE_DIGIT_SCRIPT

~/.config/kmonad/brightness/queue_digit.sh

DIGIT_QUEUE_FILE

/tmp/kmonad_digit_queue

LAST_BRIGHTNESS_CHANGE_FILE

/tmp/kmonad_last_brightness_change

[brightness]
[[private]]
QUEUE_DIGIT_SCRIPT = "|>QUEUE_DIGIT_SCRIPT<|"
CHANGE_BRIGHTNESS_SCRIPT = "|>CHANGE_BRIGHTNESS_SCRIPT<|"
CHANGE_BACKLIGHT_SCRIPT = "|>CHANGE_BACKLIGHT_SCRIPT<|"

exit_internal = (layer-rem brightness)
# the definition for `exit` is generated by our preprocessing script
[[public]]
enter = (tap-hold-next-release $tap-hold-delay #((layer-add brightness) @kbd-set-backlight-on) (layer-toggle brightness))

up = (tap-hold-next-release $tap-hold-delay-min (cmd-button "$CHANGE_BRIGHTNESS_SCRIPT +") (cmd-button "$CHANGE_BACKLIGHT_SCRIPT +"))
down = (tap-hold-next-release $tap-hold-delay-min (cmd-button "$CHANGE_BRIGHTNESS_SCRIPT -") (cmd-button "$CHANGE_BACKLIGHT_SCRIPT -"))

toggle_nightlight = (cmd-button "$CHANGE_BRIGHTNESS_SCRIPT '*'")
[[keys]]

This is repetitive, so let’s abstract it away by generating the code with Python.

return '\n'.join(map(lambda n: f'{n} = (cmd-button "$QUEUE_DIGIT_SCRIPT {n}")', range(0, 10)))

0 = (cmd-button "$QUEUE_DIGIT_SCRIPT 0")
1 = (cmd-button "$QUEUE_DIGIT_SCRIPT 1")
2 = (cmd-button "$QUEUE_DIGIT_SCRIPT 2")
3 = (cmd-button "$QUEUE_DIGIT_SCRIPT 3")
4 = (cmd-button "$QUEUE_DIGIT_SCRIPT 4")
5 = (cmd-button "$QUEUE_DIGIT_SCRIPT 5")
6 = (cmd-button "$QUEUE_DIGIT_SCRIPT 6")
7 = (cmd-button "$QUEUE_DIGIT_SCRIPT 7")
8 = (cmd-button "$QUEUE_DIGIT_SCRIPT 8")
9 = (cmd-button "$QUEUE_DIGIT_SCRIPT 9")

k = up
j = down

h = toggle_nightlight

# q displays brightness on each monitor

tab = switch_focus_composite

lmet = exit

OPEN_PRESET_SCRIPT

~/Development/Scripts/DE/presets/rofi_menu.sh

[aliases]
OPEN_PRESET_SCRIPT = "~/Development/Scripts/DE/presets/rofi_menu.sh"
open-preset = (cmd-button "$OPEN_PRESET_SCRIPT")

We set the scroll buttons to invoke the scroll.sh script once on press and once on release. On release, the script will kill the instance created on press

SCROLL_SCRIPT

~/.config/kmonad/scroll/scroll.sh

SCROLL_SPEED_SCRIPT

~/.config/kmonad/scroll/scroll_speed.sh

[scroll]
[[private]]
scroll_script = "|>SCROLL_SCRIPT<|"
speed_script = "|>SCROLL_SPEED_SCRIPT<|"

left  = (cmd-button "$scroll_script h -"
                    "$scroll_script h 0")
up    = (cmd-button "$scroll_script v -"
                    "$scroll_script v 0")
down  = (cmd-button "$scroll_script v +"
                    "$scroll_script v 0")
right = (cmd-button "$scroll_script h +"
                    "$scroll_script h 0")

speed-up   = (cmd-button "$speed_script 50"
                         "$speed_script 0")
speed-down = (cmd-button "$speed_script 200"
                         "$speed_script 0")

exit_internal = (layer-rem scroll)
[[public]]
enter = (tap-hold-next-release $tap-hold-delay #((layer-add scroll) @kbd-set-backlight-on) (layer-toggle scroll))
[[keys]]
h = left
l = right
k = up
j = down

caps = speed-down
lctrl = speed-down
lshift = speed-up

lmet = exit

VOLUME_SCRIPT

~/.config/kmonad/volume/volume.sh

VOLUME_TOGGLE_OSD_SCRIPT

~/.config/kmonad/volume/volume_popup_toggle.sh

VOLUME_SCRIPT_OSD_FILE

Stores whether to show/hide volume osd popups

/tmp/kmonad_volume_script_display_osd

[volume]
[[private]]
volume_script = "|>VOLUME_SCRIPT<|"
toggle_osd_script = "|>VOLUME_TOGGLE_OSD_SCRIPT<|"

up   = (cmd-button "$volume_script +"
                   "$volume_script 0")
down = (cmd-button "$volume_script -"
                   "$volume_script 0")

toggle-osd = (cmd-button "$toggle_osd_script")
mute = (cmd-button "qdbus org.kde.kglobalaccel /component/kmix invokeShortcut mute")

play-pause = 'PlayPause'

exit_internal = (layer-rem volume)
[[public]]
enter = (tap-hold-next-release $tap-hold-delay #((layer-add volume) @kbd-set-backlight-on) (layer-toggle volume))
[[keys]]
k = up
j = down

m = mute
q = toggle-osd

p = play-pause

lmet = exit

Yank Script

~/.config/kmonad/yank/yank_active_window.sh

Copies the actively focused window title to the clipboard.

[aliases]
yank_script = "|>YANK_SCRIPT<|"
yank = (cmd-button "$yank_script")

SWITCH_MOUSE_SCREEN_SCRIPT

/home/sridaran/Development/Scripts/DE/mouseToNextDesktop.sh

[aliases]
SWITCH_MOUSE_SCREEN_SCRIPT = "|>SWITCH_MOUSE_SCREEN_SCRIPT<|"

switch_mouse_screen = (cmd-button "$SWITCH_MOUSE_SCREEN_SCRIPT")
switch_focus_screen = (cmd-button "qdbus org.kde.kglobalaccel /component/kwin invokeShortcut \"Switch to Next Screen\"")

switch_focus_composite = (tap-hold $tap-hold-delay-min @switch_focus_screen @switch_mouse_screen)

NVIM

/home/sridaran/Packages/neovim/nvim0-6-0.appimage

NVIM_SCRIPT

/home/sridaran/.config/kmonad/vim/run_neovim.sh

[aliases]
NVIM_SCRIPT = "|>NVIM_SCRIPT<|"
vim = (cmd-button "kitty fish -C \"$NVIM_SCRIPT\"")

Simple Datetime Overlay Path

/home/sridaran/.local/bin/simple-datetime-overlay

This is a simple button that spawns my program and then kills all instances of it.

[aliases]
SIMPLE_DATETIME_OVERLAY = "|>SDO_SCRIPT_PATH<|"
simple-datetime-overlay = (cmd-button "/bin/dash -c '$SIMPLE_DATETIME_OVERLAY'" "sleep 0.15; kill \$(pgrep -f simple-datetime-overlay)")

Here are my issues with simple-datetime-overlay:

1. Setting it to show up on all monitors is ideal, but it feels too slow unless I have my CPU profile on high or max
2. Setting it to show up on the active monitor is nice, but sometimes I don’t know which monitor is active so I don’t know where to look
3. Setting it to show up on monitor 0 makes it consistently fast, but I don’t want to have to turn my head to look at it

Ideally, show up on all monitors when we are on max performance, active monitor otherwise.

KMonad’s configuration language is styled on various lisps, like scheme or Common Lisp. In a lisp, every statement is entered between ’(’ and ’)’s. If you are more used to Fortan style languages (python, ruby, C, Java, etc.), the change is quite straightforward: the function name moves into the parentheses, and you don’t use commas to separate arguments. I.e.

This: my_function(a, 3, “Alakazam”) Becomes: (my_function a 3 “Alakazam”)

The reason for this is because Lisp-style languages are very easy to parse and write syntax-highlighters for.

We also provide standard Lisp syntax for comments:

• block comments between: #| and its reverse

• line comments following: ;;

  Unlike standard lisp, a single ; does not denote a command, but instead the keycode for semicolon.

  Also, as you might have noticed, whitespace is possible anywhere.

  To check for syntax errors while editing, invoke kmonad with the -d option.

Necessary: the `defcfg` block

There are a few bits of information that are required to be present in a KMonad configuration file. One of these is the existence of exactly 1 `defcfg` statement. This statement is used to customize various configuration settings. Many of these settings have default values, but a minimal definition must include at least an ’input’ field and an ’output’ field. These describe how KMonad captures its inputs and how it emits its outputs.

First, let’s go over the optional, non-OS specific settings. Currently there is only 2:

• fallthrough: `true` or `false`, defaults to `false`

  KMonad catches input events and tries to match them to various handlers. If it cannot match an event to any handler (for example, if it isn’t included in the `defsrc` block, or if it is, but the current keymap does not map any buttons to it), then the event gets quietly ignored. If `fallthrough` is set to `true`, any unhandled events simply get reemitted.

• allow-cmd: `true` or `false`, defaults to `false`

  If this is set to `false`, any action that runs a shell-command will simply log to `stdout` without ever running (log-level info). Don’t ever enable this on a configuration that you do not trust, because:

  (cmd-button “rm -rf ~/*”)

  is a thing. For more information on the `cmd-button’ function, see the section on Command buttons below.

  There are also some optional OS specific settings that we support:

  • `cmp-seq’: KEY, defaults to `RightAlt’ (Linux X11 specific)

    This sets your compose key for Unicode input. For more information, as well as a workaround to also make this work on windows, see the section on Compose-key sequences below.

  • `cmp-seq-delay’: NUMBER (in milliseconds)

    This sets a delay between each pressed key in a compose-key sequence. Some environments may have troubles recognizing the key sequence if it’s pressed too rapidly; if you experience any problems in this direction, you can try setting this value to `5’ or `10’ and see if that helps.

  Secondly, let’s go over how to specify the `input` and `output` fields of a `defcfg` block. This differs between OS’es, and so do the capabilities of these interfaces.

Necessary: the `defsrc` block

It is difficult to explain the `defsrc` block without immediately going into `deflayer` blocks as well. Essentially, KMonad maps input-events to various internal actions, many of which generate output events. The `defsrc` block explains the layout on which we specify our `deflayer`s down the line.

It is important to realize that the `defsrc` block doesn’t necessarily have to coincide with your actual input keyboard. You can specify a full 100% `defsrc` block, but only use a 40% keyboard. This will mean that every `deflayer` you specify will also have to match your 100% `defsrc`, and that your actual keyboard would be physically unable to trigger about 60% of your keymap, but it would be perfectly valid syntax.

The dual of this (and more useful) is that it is also perfectly valid to only specify that part of your keyboard in `defsrc` that you want to remap. If you use a 100% keyboard, but don’t want to remap the numpad at all you can simply leave the numpad out of your `defsrc`, and it should work just fine. In that particular case you probably want to set `fallthrough` to `true` in your `defcfg` block though.

In the future we would like to provide support for multiple, named `defsrc` blocks, so that it becomes easier to specify various layers for just the numpad, for example, but at the moment any more or less than 1 `defsrc` block will result in an error.

The layouting in the `defsrc` block is completely free, whitespace simply gets ignored. We strive to provide a name for every keycode that is no longer than 4 characters, so we find that laying out your keymap in columns of 5 works out quite nicely (although wider columns will allow for more informative aliases, see below).

Most keycodes should be obvious. If you are unsure, check ’./src/KMonad/Keyboard/Keycode.hs’. Every Keycode has a name corresponding to its Keycode name, but all lower-case and with the ’Key’ prefix removed. There are also various aliases for Keycodes starting around line 350. If you are trying to bind a key and there is not a 4-letter alias, please file an issue, or better yet, a pull-request, and it will be added promptly.

Also, you can consult ’./keymap/template/’ for various input templates to use directly or to look up keycodes by position. Here we use the input-template for ’us_ansi_60.kbd’

Optional : `defalias` statements

KMonad will let you specify some very specific, crazy buttons. These definitions can get pretty long, though, and would make `deflayer` blocks nearly impossible to read. Therefore we provide the ability to alias names to these buttons, to keep the actual `deflayer` statements orderly.

A `defalias` can contain any number of aliases, and it can refer backwards or forwards to layers without issue. The only sequencing that needs to be kept in mind is that a `defalias` cannot refer forward to another `defalias` that is not yet defined.

Here we define a few aliases, but we will define more later. Notice that we try to only use 3 letter names for aliases. If that is not enough to be clear, consider widening all columns to 6 or 7 characters (or be content with a messy config).

Necessary: at least 1 `deflayer` block

As explained in the `defsrc` section, a `deflayer` will define a button for each corresponding entry in the `defsrc` definition. A `deflayer` statement consists of the `deflayer` keyword, followed by the name used to identify this layer, followed by N ’statements-that-evaluate-to-a-button’, where N is exactly how many entries are defined in the `defsrc` statement.

It is also important to mention that the ’keymap’ in KMonad is modelled as a stack of layers (just like in QMK). When an event is registered we look in the top-most layer for a handler. If we don’t find one we try the next layer, and then the next.

Exactly what ’evaluates-to-a-button’ will be expanded on in more detail below. There are very many different specialist buttons in KMonad that we will touch upon. However, for now, these 4 are a good place to begin:

1. Any keycode evaluates to a button that, on press, emits the press of that keycode, and on release, emits the release of that keycode. Just a ’normal’ button. The exception is ’\’, which gets used as an escape character. Use ’\\’ instead. Other characters that need to be escaped to match the literal character are ’(’, ’)’, and ’_’.
2. An @-prefixed name evaluates to an alias lookup. We named two buttons in the `defalias` block above, we could now refer to these buttons using `@num` and `@kil`. This is also why we only use alias-names no longer than 3 characters in this tutorial. Also, note that we are already referencing some aliases that have not yet been defined, this is not an issue.
3. The ’_’ character evaluates to transparent. I.e. no handler for that key-event in this layer, causing this event to be handed down the layer stack to perhaps be handled by the next layer.

4. The ’XX’ character evaluates to blocked. I.e. no action bound to that key-event in this layer, but do actually catch event, preventing any underlying layer from handling it.

   Finally, it is important to note that the first `deflayer` statement in a KMonad config will be the layer that is active when KMonad starts up.

Optional: modded buttons

Let’s start by exploring the various special buttons that are supported by KMonad by looking at ’modded’ buttons, that is to say, buttons that activate some kind of ’mod’, then perform some button, and finally release that ’mod’ again.

We have already seen an example of this style of button, our `kil` button is one such button. Let’s look at it in more detail: C-A-del

This looks like a simple declarative statement, but it’s helpful to realize that is simply syntactic sugar around 2 function calls. This statement is equivalent to: (around ctl (around alt del))

This highlights a core design principle in KMonad: we try to provide very simple buttons, and then we provide rules and functions for combining them into new buttons. Although note: still very much a work in progress.

So, looking at this statement: (around foo bar)

Here, `around` is a function that takes two buttons and creates a new button. This new button will, on a press, first press foo, then press bar, and on a release first release bar, and then foo. Once created, this new button can be passed to anything in KMonad that expects a button.

We have already seen other examples of modded buttons, \(, \), *, and +. There are no Keycodes for these buttons in KMonad, but they are buttons. They simply evaluate to `(around lsft x)`. All shifted numbers have their corresponding characters, the same is true for all capitals, and < > : ~ “ | { }  + and ?.

To wrap up ’modded-buttons’, let’s look back at C-A-del. We have 8 variants: C- : (around lctl X) A- : (around lalt X) M- : (around lmet X) S- : (around lsft X)

Then RC-, RA-, RM-, and RS- behave exactly the same, except using the right-modifier.

These can be combined however you please: C-A-M-S-x ;; Perfectly valid C-% ;; Perfectly valid: same as C-S-5 C-RC-RA-A-M-S-RS-m ;; Sure, but why would you?

Also, note that although we provide special syntax for certain modifiers, these buttons are in no way ’special’ in KMonad. There is no concept of ’modifier’. (around a (around b c)) ;; Perfectly valid

Optional: sticky keys

KMonad also support so called “sticky keys”. These are keys that will behave as if they were pressed after just tapping them. This behaviour wears off after the next button is pressed, which makes them ideal for things like a quick control or shift. For example, tapping a sticky and then pressing `abc’ will result in `Abc’.

You can create these keys with the `sticky-key’ keyword:

(defalias slc (sticky-key 500 lctl))

The number after `sticky-key’ is the timeout you want, in milliseconds. If a key is tapped and that time has passed, it won’t act like it’s pressed down when we receive the next keypress.

It is also possible to combine sticky keys. For example, to get a sticky shift+control you can do

(defalias ssc (around (sticky-key 500 lsft) (sticky-key 500 lctl)))

Optional: tap-macros

Let’s look at a button we haven’t seen yet, tap-macros.

`tap-macro` is a function that takes an arbitrary number of buttons and returns a new button. When this new button is pressed it rapidly taps all its stored buttons in quick succesion except for its last button, which it only presses. This last button gets released when the `tap-macro` gets released.

There are two ways to define a `tap-macro`, using the `tap-macro` function directly, or through the #() syntactic sugar. Both evaluate to exactly the same button.

(tap-macro K M o n a d) #(K M o n a d)

If you are going to use a `tap-macro` to perform a sequence of actions inside some program you probably want to include short pauses between inputs to give the program time to register all the key-presses. Therefore we also provide the ’pause’ function, which simply pauses processing for a certain amount of milliseconds. Pauses can be created like this:

(pause 20) P20

You an also pause between each key stroke by specifying the `:delay’ keyword, as well as a time in ms, at the end of a `tap-macro’:

(tap-macro K M o n a d :delay 5) #(K M o n a d :delay 5)

The above would be equivalent to e.g.

(tap-macro K P5 M P5 o P5 n P5 a P5 d)

WARNING: DO NOT STORE YOUR PASSWORDS IN PLAIN TEXT OR IN YOUR KEYBOARD

I know it might be tempting to store your password as a macro, but there are 2 huge risks:

1. You accidentally leak your config and expose your password

2. Anyone who knows about the button can get clear-text representation of your password with any text editor, shell, or text-input field.

   Support for triggering shell commands directly from KMonad is described in the command buttons section below.

   This concludes this public service announcement.

Optional: layer manipulation

You have already seen the basics of layer-manipulation. The `layer-toggle` button. This button adds a layer to the top of KMonad’s layer stack when pressed, and removes it again when released. There are a number of other ways to manipulate the layer stack, some safer than others. Let’s go through all of them from safest to least safe:

`layer-toggle` works as described before, 2 things to note:

1. If you are confused or worried about pressing a key, changing layers, and then releasing a key and this causing issues: don’t be. KMonad handles presses and releases in very different ways. Presses get passed directly to the stacked keymap as previously described. When a KMonad button has its press-action triggered, it then registers a callback that will catch its own release before we ever touch the keymap. This guarantees that the button triggered by the press of X will be the button whose release is triggered by the release of X (the release of X might trigger other things as well, but that is besides the point.)

2. If `layer-toggle` can only ever add and then necessarily remove 1 layer from the stack, then it will never cause a permanent change, and is perfectly safe.

   `layer-delay`, once pressed, temporarily switches to some layer for some milliseconds. Just like `layer-toggle` this will never permanently mess-up the layer stack. This button was initially implemented to provide some ’leader-key’ style behavior. Although I think in the future better solutions will be available. For now this will temporarily add a layer to the top of the stack: (layer-delay 500 my-layer)

   `layer-next`, once pressed, primes KMonad to handle the next press from some arbitrary layer. This aims to fill the same usecase as `layer-delay`: the beginnings of ’leader-key’ style behavior. I think this whole button will get deleted soon, because the more general `around-next` now exists (see below) and this is nothing more than: (around-next (layer-toggle layer-name) some-button) Until then though, use `layer-next` like this: (layer-next layer-name)

   `layer-switch`: change the base-layer of KMonad. As described at the top of this document, the first `deflayer` statement is the layer that is active when KMonad starts. Since `layer-toggle` can only ever add on and remove from the top of that, it can never change the base-layer. The following button will unregister the bottom-most layer of the keymap, and replace it with another layer. (layer-switch my-layer)

   This is where things start getting potentially dangerous (i.e. get KMonad into an unusuable state until a restart has occured). It is perfectly possible to switch into a layer that you can never get out of. Or worse, you could theoretically have a layer full of only `XX`s and switch into that, rendering your keyboard unuseable until you somehow manage to kill KMonad (without using your keyboard).

   However, when handled well, `layer-switch` is very useful, letting you switch between ’modes’ for your keyboard. I have a tiny keyboard with a weird keymap, but I switch into a simple ’qwerty’ keymap shifted 1 button to the right for gaming. Just make sure that any ’mode’ you switch into has a button that allows you to switch back out of the ’mode’ (or content yourself restarting KMonad somehow).

   `layer-add` and `layer-rem`. This is where you can very quickly cause yourself a big headache. Originally I didn’t expose these operations, but someone wanted to use them, and I am not one to deny someone else a chainsaw. As the names might give away: (layer-add name) ;; Add a layer to the top of the stack (layer-rem name) ;; Remove a layer by name (noop if no such layer)

   To use `layer-add` and `layer-rem` well, you should take a moment to think about how to create a layout that will prevent you from getting into situations where you enter a key-configuration you cannot get out of again. These two operations together, however, are very useful for activating a permanent overlay for a while. This technique is illustrated in the tap-hold overlay a bit further down.

Optional: Multi-use buttons

Perhaps one of the most useful features of KMonad, where a lot of work has gone into, but also an area with many buttons that are ever so slightly different. The naming and structuring of these buttons might change sometime soon, but for now, this is what there is.

For the next section being able to talk about examples is going to be handy, so consider the following scenario and mini-language that will be the same between scenarios.

• We have some button `foo` that will be different between scenarios
• `foo` is bound to ’Esc’ on the input keyboard
• the letters a s d f are bound to themselves
• Px signifies the press of button x on the keyboard
• Rx signifies the release of said button
• Tx signifies the sequential and near instantaneous press and release of x

• 100 signifies 100ms pass

  So for example: Tesc Ta: tap of ’Esc’ (triggering `foo`), tap of ’a’ triggering `a` Pesc 100 Ta Tb Resc: press of ’Esc’, 100ms pause, tap of ’a’, tap of ’b’, release of ’Esc’

  The `tap-next` button takes 2 buttons, one for tapping, one for holding, and combines them into a single button. When pressed, if the next event is its own release, we tap the ’tapping’ button. In all other cases we first press the ’holding’ button then we handle the event. Then when the `tap-next` gets released, we release the ’holding’ button.

  So, using our mini-language, we set foo to: (tap-next x lsft) Then: Tesc -> x Tesc Ta -> xa Pesc Ta Resc -> A Pesc Ta Tr Resc -> AR

  The `tap-hold` button is very similar to `tap-next` (a theme, trust me). The difference lies in how the decision is made whether to tap or hold. A `tap-hold` waits for a particular timeout, if the `tap-hold` is released anywhere before that moment we execute a tap immediately. If the timeout occurs and the `tap-hold` is still held, we switch to holding mode.

  The additional feature of a `tap-hold` is that it pauses event-processing until it makes its decision and then rolls back processing when the decision has been made.

  So, again with the mini-language, we set foo to: (tap-hold 200 x lsft) ;; Like tap-next, but with a 200ms timeout Then: Tesc -> x Tesc Ta -> xa Pesc 300 a -> A (the moment you press a) Pesc a 300 -> A (after 200 ms) Pesc a 100 Resc -> xa (both happening immediately on Resc)

  The `tap-hold-next` button is a combination of the previous 2. Essentially, think of it as a `tap-next` button, but it also switches to held after a period of time. This is useful, because if you have a (tap-next ret ctl) for example, and you press it thinking you want to press C-v, but then you change your mind, you now cannot release the button without triggering a ’ret’, that you then have to backspace. With the `tap-hold-next` button, you simply outwait the delay, and you’re good. I see no benefit of `tap-next` over `tap-hold-next` with a decent timeout value.

  The `tap-next-release` is like `tap-next`, except it decides whether to tap or hold based on the next release of a key that was not pressed before us. This also performs rollback like `tap-hold`.So, using the minilanguage and foo as: (tap-next-release x lsft) Then: Tesc Ta -> xa Pa Pesc Ra Resc -> ax (because ’a’ was already pressed when we started, so foo decides it is tapping) Pesc Ta Resc -> A (because a was pressed and released after we started, so foo decides it is holding)

  These increasingly stranger buttons are, I think, coming from the stubborn drive of some of my more eccentric (and I mean that in the most positive way) users to make typing with modifiers on the home-row more comfortable. Especially layouts that encourage a lot of rolling motions are nicer to use with the `release` style buttons.

  The `tap-hold-next-release` (notice a trend?) is just like `tap-next-release`, but it comes with an additional timeout that, just like `tap-hold-next` will jump into holding-mode after a timeout.

  I honestly think that `tap-hold-next-release`, although it seems the most complicated, probably is the most comfortable to use. But I’ve put all of them in a testing layer down below, so give them a go and see what is nice.

Optional: Multi-tap

Besides the tap-hold style buttons there is another multi-use button (with. only 1 variant, at the moment). The `multi-tap`.

A `multi-tap` codes for different buttons depending on how often it is tapped. It is defined by a series of delays and buttons, followed by a last button without delay. As long as you tap the `multi-tap` within the delay specified, it will jump to the next button. Once the delay is exceeded the selected button is pressed. If the last button in the list is reached, it is immediately pressed.

Note that you can actually hold the button, so in the below example, going: tap-tap-hold (wait 300ms) will get you a pressed c, until you release again.

Optional: Around-next

The `around-next` function creates a button that primes KMonad to perform the next button-press inside some context. This could be the context of ’having Shift pressed’ or ’being inside some layer’ or, less usefully, ’having d pressed’. It is a more general and powerful version of `layer-next`.

I think expansion of this button-style is probably the future of leader-key, hydra-style functionality support in KMonad.

Optional: Compose-key sequences

Compose-key sequences are series of button-presses that your operating system will interpret as the insertion of a special character, like accented characters, or various special-languages. In that sense, they are just syntactic sugar for keyboard macros.

To get this to work on Linux you will need to set your compose-key with a tool like `setxkbmap’, as well as tell kmonad that information. See the `defcfg’ block at the top of this file for a working example. Note that you need to wait ever so slightly for the keyboard to register with linux before the command gets executed, that’s why the `sleep 1`. Also, note that all the `/run/current-system’ stuff is because the author uses NixOS. Just find a shell-command that will:

1. Sleep a moment

2. Set the compose-key to your desired key

   Please be aware that what `setxkbmap’ calls the `menu’ key is not actually the `menu’ key! If you want to use the often suggested

   setxkbmap -option compose:menu

   you will have to set your compose key within kmonad to `compose’ and not `menu’.

   After this, this should work out of the box under Linux. Windows does not recognize the same compose-key sequences, but WinCompose will make most of the sequences line up with KMonad: http://wincompose.info/ This has not in any way been tested on Mac.

   In addition to hard-coded symbols, we also provide ’uncompleted’ macros. Since a compose-key sequence is literally just a series of keystrokes, we can omit the last one, and enter the sequence for ’add an umlaut’ and let the user then press some letter to add this umlaut to. These are created using the `+“` syntax.

Optional: Command buttons

Currently we also provide the ability to launch arbitrary shell-commands from inside kmonad. These commands are simply handed off to the command-shell without any further checking or waiting.

NOTE: currently only tested on Linux, but should work on any platform, as long as the command is valid for that platform.

The `cmd-button’ function takes two arguments, the second one of which is optional. These represent the commands to be executed on pressing and releasing the button respectively.

BEWARE: never run anyone’s configuration without looking at it. You wouldn’t want to push:

(cmd-button “rm -rf ~/*”) ;; Delete all this user’s data

(defalias
  dat (cmd-button "date >> /tmp/kmonad_example.txt")   ;; Append date to tmpfile
  pth (cmd-button "echo $PATH > /tmp/kmonad_path.txt") ;; Write out PATH
  ;; `dat' on press and `pth' on release
  bth (cmd-button "date >> /tmp/kmonad_example.txt"
                   "echo $PATH > /tmp/kmonad_path.txt")
  )

(deflayer command-test
  _    _    _    _    _    _    _    _    _    _    _    _    _    _
  _    _    _    _    _    _    _    _    _    _    _    _    _    _
  _    _    _    _    _    _    _    _    _    _    _    _    _
  _    _    _    _    _    _    _    _    _    @dat @pth _
  _    _    _              _              _    _    _    _
  )