jlj-qmk/docs/keycodes.md
Konstantin Đorđević bdc8d89e6b New keycode macro (XP) for shifted character pairs using UNICODEMAP + bug fixes and improvements (#4803)
* Expose unicode_saved_mods

* Add UNICODEMAP shift pair functionality and XS keycode

* Add XS to keycode reference documentation

* Pick pair index based on both Shift and Caps Lock state

* Add XS to Unicode feature docs

* Clean up process_unicode* headers

* Extract unicode_map index calculation into function

* Pick pair index as XOR rather than OR of Shift and Caps states

* unicode_input_start() has to be called before the unicode_map index is calculated

* Replace unicodemap_input_error() with more generic unicode_input_cancel()

* Replace register+tap+unregister with tap_code16(LCTL(LSFT(KC_U)))

* UNICODE_OSX_KEY → UNICODE_KEY_OSX, UNICODE_WINC_KEY → UNICODE_KEY_WINC

* Make keycode range checks more robust

* Fix keycode range checks for different input modes

* Add UNICODE_KEY_LNX, update docs

* QK_UNICODEMAP_SHIFT → QK_UNICODEMAP_PAIR

* XS → XP, update docs

* Tweak Unicode docs

* Use recently added MOD_MASK_SHIFT and IS_HOST_LED_ON helpers

* Update Unicode table in docs/keycodes.md

* Update Unicode docs per review comments

* Replace references to Mac OS X with macOS in Unicode docs

* As of v0.9.0, WinCompose supports all possible code points

* Expand descriptions in XP docs

* Update keycode table and cycling docs

* Further expand cycling docs
2019-05-03 09:33:00 -07:00

40 KiB

Keycodes Overview

When defining a keymap each key needs a valid key definition. This page documents the symbols that correspond to keycodes that are available to you in QMK.

This is a reference only. Each group of keys links to the page documenting their functionality in more detail.

Basic Keycodes

Key Aliases Description
KC_NO XXXXXXX Ignore this key (NOOP)
KC_TRANSPARENT KC_TRNS, _______ Use the next lowest non-transparent key
KC_A a and A
KC_B b and B
KC_C c and C
KC_D d and D
KC_E e and E
KC_F f and F
KC_G g and G
KC_H h and H
KC_I i and I
KC_J j and J
KC_K k and K
KC_L l and L
KC_M m and M
KC_N n and N
KC_O o and O
KC_P p and P
KC_Q q and Q
KC_R r and R
KC_S s and S
KC_T t and T
KC_U u and U
KC_V v and V
KC_W w and W
KC_X x and X
KC_Y y and Y
KC_Z z and Z
KC_1 1 and !
KC_2 2 and @
KC_3 3 and #
KC_4 4 and $
KC_5 5 and %
KC_6 6 and ^
KC_7 7 and &
KC_8 8 and *
KC_9 9 and (
KC_0 0 and )
KC_ENTER KC_ENT Return (Enter)
KC_ESCAPE KC_ESC Escape
KC_BSPACE KC_BSPC Delete (Backspace)
KC_TAB Tab
KC_SPACE KC_SPC Spacebar
KC_MINUS KC_MINS - and _
KC_EQUAL KC_EQL = and +
KC_LBRACKET KC_LBRC [ and {
KC_RBRACKET KC_RBRC ] and }
KC_BSLASH KC_BSLS \ and |
KC_NONUS_HASH KC_NUHS Non-US # and ~
KC_SCOLON KC_SCLN ; and :
KC_QUOTE KC_QUOT ' and "
KC_GRAVE KC_GRV, KC_ZKHK ` and ~, JIS Zenkaku/Hankaku
KC_COMMA KC_COMM , and <
KC_DOT . and >
KC_SLASH KC_SLSH / and ?
KC_CAPSLOCK KC_CLCK, KC_CAPS Caps Lock
KC_F1 F1
KC_F2 F2
KC_F3 F3
KC_F4 F4
KC_F5 F5
KC_F6 F6
KC_F7 F7
KC_F8 F8
KC_F9 F9
KC_F10 F10
KC_F11 F11
KC_F12 F12
KC_PSCREEN KC_PSCR Print Screen
KC_SCROLLLOCK KC_SLCK, KC_BRMD Scroll Lock, Brightness Down (macOS)
KC_PAUSE KC_PAUS, KC_BRK, KC_BRMU Pause, Brightness Up (macOS)
KC_INSERT KC_INS Insert
KC_HOME Home
KC_PGUP Page Up
KC_DELETE KC_DEL Forward Delete
KC_END End
KC_PGDOWN KC_PGDN Page Down
KC_RIGHT KC_RGHT Right Arrow
KC_LEFT Left Arrow
KC_DOWN Down Arrow
KC_UP Up Arrow
KC_NUMLOCK KC_NLCK Keypad Num Lock and Clear
KC_KP_SLASH KC_PSLS Keypad /
KC_KP_ASTERISK KC_PAST Keypad *
KC_KP_MINUS KC_PMNS Keypad -
KC_KP_PLUS KC_PPLS Keypad +
KC_KP_ENTER KC_PENT Keypad Enter
KC_KP_1 KC_P1 Keypad 1 and End
KC_KP_2 KC_P2 Keypad 2 and Down Arrow
KC_KP_3 KC_P3 Keypad 3 and Page Down
KC_KP_4 KC_P4 Keypad 4 and Left Arrow
KC_KP_5 KC_P5 Keypad 5
KC_KP_6 KC_P6 Keypad 6 and Right Arrow
KC_KP_7 KC_P7 Keypad 7 and Home
KC_KP_8 KC_P8 Keypad 8 and Up Arrow
KC_KP_9 KC_P9 Keypad 9 and Page Up
KC_KP_0 KC_P0 Keypad 0 and Insert
KC_KP_DOT KC_PDOT Keypad . and Delete
KC_NONUS_BSLASH KC_NUBS Non-US \ and |
KC_APPLICATION KC_APP Application (Windows Menu Key)
KC_POWER System Power (macOS)
KC_KP_EQUAL KC_PEQL Keypad =
KC_F13 F13
KC_F14 F14
KC_F15 F15
KC_F16 F16
KC_F17 F17
KC_F18 F18
KC_F19 F19
KC_F20 F20
KC_F21 F21
KC_F22 F22
KC_F23 F23
KC_F24 F24
KC_EXECUTE KC_EXEC Execute
KC_HELP Help
KC_MENU Menu
KC_SELECT KC_SLCT Select
KC_STOP Stop
KC_AGAIN KC_AGIN Again
KC_UNDO Undo
KC_CUT Cut
KC_COPY Copy
KC_PASTE KC_PSTE Paste
KC_FIND Find
KC__MUTE Mute (macOS)
KC__VOLUP Volume Up (macOS)
KC__VOLDOWN Volume Down (macOS)
KC_LOCKING_CAPS KC_LCAP Locking Caps Lock
KC_LOCKING_NUM KC_LNUM Locking Num Lock
KC_LOCKING_SCROLL KC_LSCR Locking Scroll Lock
KC_KP_COMMA KC_PCMM Keypad ,
KC_KP_EQUAL_AS400 Keypad = on AS/400 keyboards
KC_INT1 KC_RO JIS \ and _
KC_INT2 KC_KANA JIS Katakana/Hiragana
KC_INT3 KC_JYEN JIS ¥ and |
KC_INT4 KC_HENK JIS Henkan
KC_INT5 KC_MHEN JIS Muhenkan
KC_INT6 JIS Numpad ,
KC_INT7 International 7
KC_INT8 International 8
KC_INT9 International 9
KC_LANG1 KC_HAEN Hangul/English
KC_LANG2 KC_HANJ Hanja
KC_LANG3 JIS Katakana
KC_LANG4 JIS Hiragana
KC_LANG5 JIS Zenkaku/Hankaku
KC_LANG6 Language 6
KC_LANG7 Language 7
KC_LANG8 Language 8
KC_LANG9 Language 9
KC_ALT_ERASE KC_ERAS Alternate Erase
KC_SYSREQ SysReq/Attention
KC_CANCEL Cancel
KC_CLEAR KC_CLR Clear
KC_PRIOR Prior
KC_RETURN Return
KC_SEPARATOR Separator
KC_OUT Out
KC_OPER Oper
KC_CLEAR_AGAIN Clear/Again
KC_CRSEL CrSel/Props
KC_EXSEL ExSel
KC_LCTRL KC_LCTL Left Control
KC_LSHIFT KC_LSFT Left Shift
KC_LALT Left Alt
KC_LGUI KC_LCMD, KC_LWIN Left GUI (Windows/Command/Meta key)
KC_RCTRL KC_RCTL Right Control
KC_RSHIFT KC_RSFT Right Shift
KC_RALT KC_ALGR Right Alt (AltGr)
KC_RGUI KC_RCMD, KC_RWIN Right GUI (Windows/Command/Meta key)
KC_SYSTEM_POWER KC_PWR System Power Down
KC_SYSTEM_SLEEP KC_SLEP System Sleep
KC_SYSTEM_WAKE KC_WAKE System Wake
KC_AUDIO_MUTE KC_MUTE Mute
KC_AUDIO_VOL_UP KC_VOLU Volume Up
KC_AUDIO_VOL_DOWN KC_VOLD Volume Down
KC_MEDIA_NEXT_TRACK KC_MNXT Next Track (Windows)
KC_MEDIA_PREV_TRACK KC_MPRV Previous Track (Windows)
KC_MEDIA_STOP KC_MSTP Stop Track (Windows)
KC_MEDIA_PLAY_PAUSE KC_MPLY Play/Pause Track
KC_MEDIA_SELECT KC_MSEL Launch Media Player (Windows)
KC_MEDIA_EJECT KC_EJCT Eject (macOS)
KC_MAIL Launch Mail (Windows)
KC_CALCULATOR KC_CALC Launch Calculator (Windows)
KC_MY_COMPUTER KC_MYCM Launch My Computer (Windows)
KC_WWW_SEARCH KC_WSCH Browser Search (Windows)
KC_WWW_HOME KC_WHOM Browser Home (Windows)
KC_WWW_BACK KC_WBAK Browser Back (Windows)
KC_WWW_FORWARD KC_WFWD Browser Forward (Windows)
KC_WWW_STOP KC_WSTP Browser Stop (Windows)
KC_WWW_REFRESH KC_WREF Browser Refresh (Windows)
KC_WWW_FAVORITES KC_WFAV Browser Favorites (Windows)
KC_MEDIA_FAST_FORWARD KC_MFFD Next Track (macOS)
KC_MEDIA_REWIND KC_MRWD Previous Track (macOS)
KC_BRIGHTNESS_UP KC_BRIU Brightness Up
KC_BRIGHTNESS_DOWN KC_BRID Brightness Down

Quantum Keycodes

Key Aliases Description
RESET Put the keyboard into DFU mode for flashing
DEBUG Toggle debug mode
EEPROM_RESET EEP_RST Resets EEPROM state by reinitializing it
KC_GESC GRAVE_ESC Escape when tapped, ` when pressed with Shift or GUI
KC_LSPO Left Shift when held, ( when tapped
KC_RSPC Right Shift when held, ) when tapped
KC_LEAD The Leader key
KC_LOCK The Lock key
FUNC(n) F(n) Call fn_action(n) (deprecated)
M(n) Call macro n
MACROTAP(n) Macro-tap n idk FIXME

Audio Keys

Key Aliases Description
AU_ON Turns on Audio Feature
AU_OFF Turns off Audio Feature
AU_TOG Toggles Audio state
CLICKY_TOGGLE CK_TOGG Toggles Audio clicky mode
CLICKY_UP CK_UP Increases frequency of the clicks
CLICKY_DOWN CK_DOWN Decreases frequency of the clicks
CLICKY_RESET CK_RST Resets frequency to default
MU_ON Turns on Music Mode
MU_OFF Turns off Music Mode
MU_TOG Toggles Music Mode
MU_MOD Cycles through the music modes

Backlighting

Key Description
BL_TOGG Turn the backlight on or off
BL_STEP Cycle through backlight levels
BL_ON Set the backlight to max brightness
BL_OFF Turn the backlight off
BL_INC Increase the backlight level
BL_DEC Decrease the backlight level
BL_BRTG Toggle backlight breathing

Bootmagic

Key Aliases Description
MAGIC_SWAP_CONTROL_CAPSLOCK Swap Caps Lock and Left Control
MAGIC_CAPSLOCK_TO_CONTROL Treat Caps Lock as Control
MAGIC_SWAP_LALT_LGUI Swap Left Alt and GUI
MAGIC_SWAP_RALT_RGUI Swap Right Alt and GUI
MAGIC_NO_GUI Disable the GUI key
MAGIC_SWAP_GRAVE_ESC Swap ` and Escape
MAGIC_SWAP_BACKSLASH_BACKSPACE Swap \ and Backspace
MAGIC_HOST_NKRO Force NKRO on
MAGIC_SWAP_ALT_GUI AG_SWAP Swap Alt and GUI on both sides
MAGIC_UNSWAP_CONTROL_CAPSLOCK Unswap Caps Lock and Left Control
MAGIC_UNCAPSLOCK_TO_CONTROL Stop treating Caps Lock as Control
MAGIC_UNSWAP_LALT_LGUI Unswap Left Alt and GUI
MAGIC_UNSWAP_RALT_RGUI Unswap Right Alt and GUI
MAGIC_UNNO_GUI Enable the GUI key
MAGIC_UNSWAP_GRAVE_ESC Unswap ` and Escape
MAGIC_UNSWAP_BACKSLASH_BACKSPACE Unswap \ and Backspace
MAGIC_UNHOST_NKRO Force NKRO off
MAGIC_UNSWAP_ALT_GUI AG_NORM Unswap Alt and GUI on both sides
MAGIC_TOGGLE_ALT_GUI AG_TOGG Toggle Alt and GUI swap on both sides
MAGIC_TOGGLE_NKRO Turn NKRO on or off

Bluetooth

Key Description
OUT_AUTO Automatically switch between USB and Bluetooth
OUT_USB USB only
OUT_BT Bluetooth only

Layer Switching

Key Description
DF(layer) Set the base (default) layer
MO(layer) Momentarily turn on layer when pressed (requires KC_TRNS on destination layer)
OSL(layer) Momentarily activates layer until a key is pressed. See One Shot Keys for details.
LM(layer, mod) Momentarily turn on layer (like MO) with mod active as well. Where mod is a mods_bit. Mods can be viewed here. Example Implementation: LM(LAYER_1, MOD_LALT)
LT(layer, kc) Turn on layer when held, kc when tapped
TG(layer) Toggle layer on or off
TO(layer) Turn on layer when pressed
TT(layer) Normally acts like MO unless it's tapped multiple times, which toggles layer on

Mouse Keys

Key Aliases Description
KC_MS_UP KC_MS_U Mouse Cursor Up
KC_MS_DOWN KC_MS_D Mouse Cursor Down
KC_MS_LEFT KC_MS_L Mouse Cursor Left
KC_MS_RIGHT KC_MS_R Mouse Cursor Right
KC_MS_BTN1 KC_BTN1 Mouse Button 1
KC_MS_BTN2 KC_BTN2 Mouse Button 2
KC_MS_BTN3 KC_BTN3 Mouse Button 3
KC_MS_BTN4 KC_BTN4 Mouse Button 4
KC_MS_BTN5 KC_BTN5 Mouse Button 5
KC_MS_WH_UP KC_WH_U Mouse Wheel Up
KC_MS_WH_DOWN KC_WH_D Mouse Wheel Down
KC_MS_WH_LEFT KC_WH_L Mouse Wheel Left
KC_MS_WH_RIGHT KC_WH_R Mouse Wheel Right
KC_MS_ACCEL0 KC_ACL0 Set mouse acceleration to 0
KC_MS_ACCEL1 KC_ACL1 Set mouse acceleration to 1
KC_MS_ACCEL2 KC_ACL2 Set mouse acceleration to 2

Modifiers

Key Aliases Description
LCTL(kc) C(kc) Hold Left Control and press kc
LSFT(kc) S(kc) Hold Left Shift and press kc
LALT(kc) A(kc) Hold Left Alt and press kc
LGUI(kc) G(kc), LCMD(kc), LWIN(kc) Hold Left GUI and press kc
RCTL(kc) Hold Right Control and press kc
RSFT(kc) Hold Right Shift and press kc
RALT(kc) ALGR(kc) Hold Right Alt and press kc
RGUI(kc) RCMD(kc), LWIN(kc) Hold Right GUI and press kc
SGUI(kc) SCMD(kc), SWIN(kc) Hold Left Shift and GUI and press kc
LCA(kc) Hold Left Control and Alt and press kc
LCAG(kc) Hold Left Control, Alt and GUI and press kc
MEH(kc) Hold Left Control, Shift and Alt and press kc
HYPR(kc) Hold Left Control, Shift, Alt and GUI and press kc
KC_MEH Left Control, Shift and Alt
KC_HYPR Left Control, Shift, Alt and GUI

Mod-Tap Keys

Key Aliases Description
LCTL_T(kc) CTL_T(kc) Left Control when held, kc when tapped
LSFT_T(kc) SFT_T(kc) Left Shift when held, kc when tapped
LALT_T(kc) ALT_T(kc) Left Alt when held, kc when tapped
LGUI_T(kc) LCMD_T(kc), LWIN_T(kc), GUI_T(kc), CMD_T(kc), WIN_T(kc) Left GUI when held, kc when tapped
RCTL_T(kc) Right Control when held, kc when tapped
RSFT_T(kc) Right Shift when held, kc when tapped
RALT_T(kc) ALGR_T(kc) Right Alt when held, kc when tapped
RGUI_T(kc) RCMD_T(kc), RWIN_T(kc) Right GUI when held, kc when tapped
SGUI_T(kc) SCMD_T(kc), SWIN_T(kc) Left Shift and GUI when held, kc when tapped
LCA_T(kc) Left Control and Alt when held, kc when tapped
LCAG_T(kc) Left Control, Alt and GUI when held, kc when tapped
RCAG_T(kc) Right Control, Alt and GUI when held, kc when tapped
C_S_T(kc) Left Control and Shift when held, kc when tapped
MEH_T(kc) Left Control, Shift and Alt when held, kc when tapped
HYPR_T(kc) ALL_T(kc) Left Control, Shift, Alt and GUI when held, kc when tapped - more info here

RGB Lighting

Key Aliases Description
RGB_TOG Toggle RGB lighting on or off
RGB_MODE_FORWARD RGB_MOD Cycle through modes, reverse direction when Shift is held
RGB_MODE_REVERSE RGB_RMOD Cycle through modes in reverse, forward direction when Shift is held
RGB_HUI Increase hue
RGB_HUD Decrease hue
RGB_SAI Increase saturation
RGB_SAD Decrease saturation
RGB_VAI Increase value (brightness)
RGB_VAD Decrease value (brightness)
RGB_MODE_PLAIN RGB_M_P Static (no animation) mode
RGB_MODE_BREATHE RGB_M_B Breathing animation mode
RGB_MODE_RAINBOW RGB_M_R Rainbow animation mode
RGB_MODE_SWIRL RGB_M_SW Swirl animation mode
RGB_MODE_SNAKE RGB_M_SN Snake animation mode
RGB_MODE_KNIGHT RGB_M_K "Knight Rider" animation mode
RGB_MODE_XMAS RGB_M_X Christmas animation mode
RGB_MODE_GRADIENT RGB_M_G Static gradient animation mode
RGB_MODE_RGBTEST RGB_M_T Red,Green,Blue test animation mode

RGB Matrix Lighting

Key Aliases Description
RGB_TOG Toggle RGB lighting on or off
RGB_MODE_FORWARD RGB_MOD Cycle through modes, reverse direction when Shift is held
RGB_MODE_REVERSE RGB_RMOD Cycle through modes in reverse, forward direction when Shift is held
RGB_HUI Increase hue
RGB_HUD Decrease hue
RGB_SAI Increase saturation
RGB_SAD Decrease saturation
RGB_VAI Increase value (brightness)
RGB_VAD Decrease value (brightness)
RGB_SPI Increase effect speed (does no support eeprom yet)
RGB_SPD Decrease effect speed (does no support eeprom yet)

Thermal Printer

Key Description
PRINT_ON Start printing everything the user types
PRINT_OFF Stop printing everything the user types

US ANSI Shifted Symbols

Key Aliases Description
KC_TILDE KC_TILD ~
KC_EXCLAIM KC_EXLM !
KC_AT @
KC_HASH #
KC_DOLLAR KC_DLR $
KC_PERCENT KC_PERC %
KC_CIRCUMFLEX KC_CIRC ^
KC_AMPERSAND KC_AMPR &
KC_ASTERISK KC_ASTR *
KC_LEFT_PAREN KC_LPRN (
KC_RIGHT_PAREN KC_RPRN )
KC_UNDERSCORE KC_UNDS _
KC_PLUS +
KC_LEFT_CURLY_BRACE KC_LCBR {
KC_RIGHT_CURLY_BRACE KC_RCBR }
KC_PIPE |
KC_COLON KC_COLN :
KC_DOUBLE_QUOTE KC_DQUO, KC_DQT "
KC_LEFT_ANGLE_BRACKET KC_LABK, KC_LT <
KC_RIGHT_ANGLE_BRACKET KC_RABK, KC_GT >
KC_QUESTION KC_QUES ?

One Shot Keys

Key Description
OSM(mod) Hold mod for one keypress
OSL(layer) Switch to layer for one keypress

Swap Hands

Key Description
SH_T(key) Sends key with a tap; momentary swap when held.
SW_ON Turns on swapping and leaves it on.
SW_OFF Turn off swapping and leaves it off. Good for returning to a known state.
SH_MON Swaps hands when pressed, returns to normal when released (momentary).
SH_MOFF Momentarily turns off swap.
SH_TG Toggles swap on and off with every key press.
SH_TT Toggles with a tap; momentary when held.

Unicode Support

Key Aliases Description
UC(c) Send Unicode code point c
X(i) Send Unicode code point at index i in unicode_map
XP(i, j) Send Unicode code point at index i, or j if Shift/Caps is on
UNICODE_MODE_FORWARD UC_MOD Cycle through selected input modes
UNICODE_MODE_REVERSE UC_RMOD Cycle through selected input modes in reverse
UNICODE_MODE_OSX UC_M_OS Switch to macOS input
UNICODE_MODE_LNX UC_M_LN Switch to Linux input
UNICODE_MODE_WIN UC_M_WI Switch to Windows input
UNICODE_MODE_BSD UC_M_BS Switch to BSD input (not implemented)
UNICODE_MODE_WINC UC_M_WC Switch to Windows input using WinCompose