6.5 KiB

Raw Blame History

Common Keymap Shortcuts

Your keymap can include shortcuts to common operations, for example shifted keys. This page documents the functions that are available to you.

People often define custom names using #define. For example:

#define FN_CAPS LT(_FL, KC_CAPSLOCK)
#define ALT_TAB LALT(KC_TAB)

This will allow you to use FN_CAPS and ALT_TAB in your KEYMAP(), keeping it more readable.

Limits of these aliases

Currently, the keycodes able to used with these functions are limited to the Basic Keycodes, meaning you can't use keycodes like KC_TILD, or anything greater than 0xFF. For a full list of the keycodes able to be used see Keycodes.

Switching and toggling layers

These functions allow you to activate layers in various ways.

Care must be taken when switching layers, it's possible to lock yourself in a layer with no way to deactivate that layer (without unplugging your keyboard.) Always make sure that the layer you're switching into has the same key set to KC_TRNS.

Layers stack on top of each other in numerical order, and as a result you can only activate a layer that is "above" your current layer. For example, on layer 2 you can't use MO(1), the behavior will be undefined.

MO(layer) - momentary switch to layer. As soon as you let go of the key, the layer is deactivated and you pop back out to the previous layer.
LT(layer, kc) - momentary switch to layer when held, and kc when tapped.
TG(layer) - toggles a layer on or off.
TO(layer) - Goes to a layer. This code is special, because it lets you go either up or down the stack -- just goes directly to the layer you want. So while other codes only let you go up the stack (from layer 0 to layer 3, for example), TO(2) is going to get you to layer 2, no matter where you activate it from -- even if you're currently on layer 5. This gets activated on keydown (as soon as the key is pressed).
TT(layer) - Layer Tap-Toggle. If you hold the key down, the layer becomes active, and then deactivates when you let go. And if you tap it, the layer simply becomes active (toggles on). It needs 5 taps by default, but you can set it by defining TAPPING_TOGGLE, for example, #define TAPPING_TOGGLE 2 for just two taps.

Modifier keys

These functions allow you to combine a mod with a keycode. When pressed the keydown for the mod will be sent first, and then kc will be sent. When released the keyup for kc will be sent and then the mod will be sent.

LSFT(kc) or S(kc) - applies left Shift to kc (keycode)
RSFT(kc) - applies right Shift to kc
LCTL(kc) - applies left Control to kc
RCTL(kc) - applies right Control to kc
LALT(kc) - applies left Alt to kc
RALT(kc) - applies right Alt to kc
LGUI(kc) - applies left GUI (command/win) to kc
RGUI(kc) - applies right GUI (command/win) to kc
HYPR(kc) - applies Hyper (all modifiers) to kc
MEH(kc) - applies Meh (all modifiers except Win/Cmd) to kc
LCAG(kc) - applies CtrlAltGui to kc

You can also chain these, like this:

LALT(LCTL(KC_DEL)) -- this makes a key that sends Alt, Control, and Delete in a single keypress.

Shifted Keycodes

The following shortcuts automatically add LSFT() to keycodes to get commonly used symbols.

Name	Description
KC_TILD	~
KC_EXLM	!
KC_QUES	?
KC_AT	@
KC_HASH	#
KC_DLR	$
KC_PERC	%
KC_CIRC	^
KC_AMPR	&
KC_ASTR	*
KC_LPRN	(
KC_RPRN	)
KC_UNDS	_
KC_PLUS	+
KC_DQUO	"
KC_LCBR	{
KC_RCBR	}
KC_LABK	<
KC_RABK	>
KC_PIPE
KC_COLN	:

Mod Tap

MT(mod, kc) - is mod (modifier key - MOD_LCTL, MOD_LSFT) when held, and kc when tapped. In other words, you can have a key that sends Esc (or the letter O or whatever) when you tap it, but works as a Control key or a Shift key when you hold it down.

These are the values you can use for the mod in MT() and OSM():

MOD_LCTL
MOD_LSFT
MOD_LALT
MOD_LGUI
MOD_RCTL
MOD_RSFT
MOD_RALT
MOD_RGUI
MOD_HYPR
MOD_MEH

These can also be combined like MOD_LCTL | MOD_LSFT e.g. MT(MOD_LCTL | MOD_LSFT, KC_ESC) which would activate Control and Shift when held, and send Escape when tapped. Note however, that you cannot mix right and left side modifiers.

We've added shortcuts to make common modifier/tap (mod-tap) mappings more compact:

CTL_T(kc) - is LCTL when held and kc when tapped
SFT_T(kc) - is LSFT when held and kc when tapped
ALT_T(kc) - is LALT when held and kc when tapped
ALGR_T(kc) - is AltGr when held and kc when tapped
GUI_T(kc) - is LGUI when held and kc when tapped
ALL_T(kc) - is Hyper (all mods) when held and kc when tapped. To read more about what you can do with a Hyper key, see this blog post by Brett Terpstra
LCAG_T(kc) - is CtrlAltGui when held and kc when tapped
MEH_T(kc) - is like Hyper, but not as cool -- does not include the Cmd/Win key, so just sends Alt+Ctrl+Shift.

One Shot Keys

One shot keys are keys that remain active until the next key is pressed, and then are releasd. This allows you to type keyboard combinations without pressing more than one key at a time.

For example, if you define a key as OSM(MOD_LSFT), you can type a capital A character by first pressing and releasing shift, and then pressing and releasing A. Your computer will see the shift key being held the moment shift is pressed, and it will see the shift key being released immediately after A is released.

One shot keys also work as normal modifiers. If you hold down a one shot key and type other keys, your one shot will be released immediately after you let go of the key.

OSM(mod) - Momentarily hold down mod. You must use the MOD_* keycodes as shown in Mod Tap, not the KC_* codes.
OSL(layer) - momentary switch to layer.

Permissive Hold

As of PR#1359, there is a new config.h option:

#define PERMISSIVE_HOLD

This makes it easier for fast typists to use dual-function keys. Without this, if you let go of a held key inside the tapping term, it won't register.

Example: (Tapping Term = 200ms)

SHFT_T(KC_A) Down
KC_X Down
KC_X Up
SHFT_T(KC_A) Up

With defaults, if above is typed within tapping term, this will emit ax. With permissive hold, if above is typed within tapping term, this will emit X (so, Shift+X).

6.5 KiB Raw Blame History