@ -4,225 +4,14 @@ When defining a [keymap](keymap.md) each key needs a valid key definition.
This page documents the symbols that correspond to keycodes that are available to you in QMK.
To customize your board, they can be used by themselves or as **action codes** in combination with one of the [many C macros](https://github.com/qmk/qmk_firmware/wiki#c-macros-for-action-code).
## Basic keycodes (`0x00` - `0xFF`)
The source of truth for these codes is [tmk_core/common/keycode.h](https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/keycode.h) file in the qmk source code.
# The Keycodes
Keycodes in QMK are based on [HID Usage Keyboard/Keypad Page(0x07)](http://www.usb.org/developers/hidpage/Hut1_12v2.pdf) with following exceptions:
[Basic keycodes](basic_keycodes.md) in QMK are based on [HID Usage Keyboard/Keypad Page(0x07)](http://www.usb.org/developers/hidpage/Hut1_12v2.pdf) with following exceptions:
* `KC_NO` = 0 for no action
* `KC_TRNS` = 1 for layer transparency
* internal special keycodes in the `0xA5-DF` range (tmk heritage).
The following keys can be used to turn on and off various "Magic" features. These include Boot Magic (holding certain keys down while plugging the keyboard in) and the Magic Key.
## Quantum keycodes (`0x0100` - `0xFFFF`)
|Long Name|Short Name|Description|
|---------|----------|-----------|
|MAGIC_SWAP_CONTROL_CAPSLOCK||Swap Capslock and Control|
|MAGIC_CAPSLOCK_TO_CONTROL||Change Capslock to Control|
|MAGIC_SWAP_ALT_GUI||Swap ALT and GUI|
|MAGIC_SWAP_LALT_LGUI||Swap LALT and LGUI|
|MAGIC_SWAP_RALT_RGUI||Swap RALT and RGUI|
|MAGIC_NO_GUI||Disable off the GUI key|
|MAGIC_SWAP_GRAVE_ESC||Swap the GRAVE (~ `) and Esc keys|
|MAGIC_SWAP_BACKSLASH_BACKSPACE||Swap Backslash and Backspace|
|MAGIC_UNSWAP_CONTROL_CAPSLOCK||Disable the Control/Caps Swap|
|MAGIC_UNCAPSLOCK_TO_CONTROL||Turn Capslock back into Capslock|
|MAGIC_UNSWAP_ALT_GUI||Turn the ALT/GUI swap off|
|MAGIC_UNSWAP_LALT_LGUI||Turn the LALT/LGUI swap off|
|MAGIC_UNSWAP_RALT_RGUI||Turn the RALT/RGUI swap off|
|MAGIC_UNNO_GUI||Enable the GUI key|
|MAGIC_UNSWAP_GRAVE_ESC||Turn the GRAVE/ESC swap off|
|MAGIC_UNSWAP_BACKSLASH_BACKSPACE||Turn the Backslash/Backspace swap off|
|MAGIC_HOST_NKRO||Turn NKRO on|
|MAGIC_UNHOST_NKRO||Turn NKRO off|
|MAGIC_TOGGLE_NKRO||Toggle NKRO on or off|
[Quantum keycodes](quantum_keycodes.md) allow for easier customisation of your keymap than the basic ones provide, without having to define custom actions.
Something important to realise with keycodes is that they are all numbers between `0x0` and `0xFFFF` - even though they may look like functions, words, or phrases, they are all shortcuts to some number. This allows us to define all of what they do in different places, and store keymaps in a relatively small place (arrays). If you try to "call" a keycode by placing it somewhere besides a keymap, it may compile, but it won't do anything useful.
All keycodes on this page have a value above `0xFF` (values less are considered the [basic keycodes](basic_keycodes.md)) and won't work with any of the mod/layer-tap keys listed at the bottom.
* `SAFE_RANGE` is always the last keycode in the quantum list, and where custom lists can begin
* `RESET` puts the keyboard into DFU mode for flashing
* `DEBUG` toggles debug mode
* Shortcuts for bootmagic options (work when bootmagic is off)
* `MAGIC_SWAP_CONTROL_CAPSLOCK`
* `MAGIC_CAPSLOCK_TO_CONTROL`
* `MAGIC_SWAP_LALT_LGUI`
* `MAGIC_SWAP_RALT_RGUI`
* `MAGIC_NO_GUI`
* `MAGIC_SWAP_GRAVE_ESC`
* `MAGIC_SWAP_BACKSLASH_BACKSPACE`
* `MAGIC_HOST_NKRO`
* `MAGIC_SWAP_ALT_GUI`/`AG_SWAP`
* `MAGIC_UNSWAP_CONTROL_CAPSLOCK`
* `MAGIC_UNCAPSLOCK_TO_CONTROL`
* `MAGIC_UNSWAP_LALT_LGUI`
* `MAGIC_UNSWAP_RALT_RGUI`
* `MAGIC_UNNO_GUI`
* `MAGIC_UNSWAP_GRAVE_ESC`
* `MAGIC_UNSWAP_BACKSLASH_BACKSPACE`
* `MAGIC_UNHOST_NKRO`
* `MAGIC_UNSWAP_ALT_GUI`/`AG_NORM`
* `MAGIC_TOGGLE_NKRO`
* `KC_GESC`/`GRAVE_ESC` acts as escape when pressed normally but when pressed with a mod will send a `~`
* `KC_LSPO` left shift when held, open paranthesis when tapped
* `KC_RSPC` right shift when held, close paranthesis when tapped
* `SCMD_T(kc)`/`SWIN_T(kc)` LGUI + LSFT when held, kc when tapped
* `LCA_T(kc)` LCTL + LALT when held, kc when tapped
## Shifted symbols
It's important to remember that all of the keycodes also send a left shift - this may cause unintended actions if unaccounted for. The 4-letter code is preferred in most situations.
* `KC_TILD`/`KC_TILDE` tilde `~`
* `KC_EXLM`/`KC_EXCLAIM` exclamation mark `!`
* `KC_AT` at sign `@`
* `KC_HASH` hash sign `#`
* `KC_DLR`/`KC_DOLLAR` dollar sign `$`
* `KC_PERC`/`KC_PERCENT` percent sign `%`
* `KC_CIRC`/`KC_CIRCUMFLEX` circumflex `^`
* `KC_AMPR`/`KC_AMPERSAND` ampersand `&`
* `KC_ASTR`/`KC_ASTERISK` asterisk `*`
* `KC_LPRN`/`KC_LEFT_PAREN` left parenthesis `(`
* `KC_RPRN`/`KC_RIGHT_PAREN` right parenthesis `)`
* `KC_UNDS`/`KC_UNDERSCORE` underscore `_`
* `KC_PLUS` plus sign `+`
* `KC_LCBR`/`KC_LEFT_CURLY_BRACE` left curly brace `{`
* `KC_RCBR`/`KC_RIGHT_CURLY_BRACE` right curly brace `}`
* `KC_LT`/`KC_LABK`/`KC_LEFT_ANGLE_BRACKET` left angle bracket `<`
* `KC_GT`/`KC_RABK`/`KC_RIGHT_ANGLE_BRACKET` right angle bracket `>`