docs/quantum_keycodes.md

   1 # Quantum Keycodes
   2
   3 All keycodes within quantum are numbers between `0x0000` and `0xFFFF`. Within your `keymap.c` it may look like you have functions and other special cases, but ultimately the C preprocessor will translate those into a single 4 byte integer. QMK has reserved `0x0000` through `0x00FF` for standard keycodes. These are keycodes such as `KC_A`, `KC_1`, and `KC_LCTL`, which are basic keys defined in the USB HID specification.
   4
   5 On this page we have documented keycodes between `0x00FF` and `0xFFFF` which are used to implement advanced quantum features. If you define your own custom keycodes they will be put into this range as well. Keycodes above `0x00FF` may not be used with any of the mod/layer-tap keys listed
   6
   7 ## QMK keycodes
   8
   9 |Name|Description|
  10 |----|-----------|
  11 |`RESET`|Put the keyboard into DFU mode for flashing|
  12 |`DEBUG`|Toggles debug mode|
  13 |`KC_GESC`/`GRAVE_ESC`|Acts as escape when pressed normally but when pressed with Shift or GUI will send a `~`|
  14 |`KC_LSPO`|Left shift when held, open paranthesis when tapped|
  15 |`KC_RSPC`|Right shift when held, close paranthesis when tapped|
  16 |`KC_LEAD`|The [leader key](leader_key.md)|
  17 |`FUNC(n)`/`F(n)`|Call `fn_action(n)`|
  18 |`M(n)`|to call macro n|
  19 |`MACROTAP(n)`|to macro-tap n idk FIXME|
  20 |`KC_LOCK`|The [lock key](key_lock.md)|
  21
  22 ## Bootmagic Keycodes
  23
  24 Shortcuts for bootmagic options (these work even when bootmagic is off.)
  25
  26 |Name|Description|
  27 |----|-----------|
  28 |`MAGIC_SWAP_CONTROL_CAPSLOCK`|Swap Capslock and Left Control|
  29 |`MAGIC_CAPSLOCK_TO_CONTROL`|Treat Capslock like a Control Key|
  30 |`MAGIC_SWAP_LALT_LGUI`|Swap the left Alt and GUI keys|
  31 |`MAGIC_SWAP_RALT_RGUI`|Swap the right Alt and GUI keys|
  32 |`MAGIC_NO_GUI`|Disable the GUI key|
  33 |`MAGIC_SWAP_GRAVE_ESC`|Swap the Grave and Esc key.|
  34 |`MAGIC_SWAP_BACKSLASH_BACKSPACE`|Swap backslack and backspace|
  35 |`MAGIC_HOST_NKRO`|Force NKRO on|
  36 |`MAGIC_SWAP_ALT_GUI`/`AG_SWAP`|Swap Alt and Gui on both sides|
  37 |`MAGIC_UNSWAP_CONTROL_CAPSLOCK`|Disable the Control/Capslock swap|
  38 |`MAGIC_UNCAPSLOCK_TO_CONTROL`|Disable treating Capslock like Control |
  39 |`MAGIC_UNSWAP_LALT_LGUI`|Disable Left Alt and GUI switching|
  40 |`MAGIC_UNSWAP_RALT_RGUI`|Disable Right Alt and GUI switching|
  41 |`MAGIC_UNNO_GUI`|Enable the GUI key |
  42 |`MAGIC_UNSWAP_GRAVE_ESC`|Disable the Grave/Esc swap |
  43 |`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|Disable the backslash/backspace swap|
  44 |`MAGIC_UNHOST_NKRO`|Force NKRO off|
  45 |`MAGIC_UNSWAP_ALT_GUI`/`AG_NORM`|Disable the Alt/GUI switching|
  46 |`MAGIC_TOGGLE_NKRO`|Turn NKRO on or off|
  47
  48 <!-- FIXME: this formatting needs work
  49
  50 ## Audio
  51
  52 ```c
  53 #ifdef AUDIO_ENABLE
  54     AU_ON,
  55     AU_OFF,
  56     AU_TOG,
  57
  58     #ifdef FAUXCLICKY_ENABLE
  59         FC_ON,
  60         FC_OFF,
  61         FC_TOG,
  62     #endif
  63
  64     // Music mode on/off/toggle
  65     MU_ON,
  66     MU_OFF,
  67     MU_TOG,
  68
  69     // Music voice iterate
  70     MUV_IN,
  71     MUV_DE,
  72 #endif
  73 ```
  74
  75 ### Midi
  76
  77 #if !MIDI_ENABLE_STRICT || (defined(MIDI_ENABLE) && defined(MIDI_BASIC))
  78     MI_ON,  // send midi notes when music mode is enabled
  79     MI_OFF, // don't send midi notes when music mode is enabled
  80 #endif
  81
  82 MIDI_TONE_MIN,
  83 MIDI_TONE_MAX
  84
  85 MI_C = MIDI_TONE_MIN,
  86 MI_Cs,
  87 MI_Db = MI_Cs,
  88 MI_D,
  89 MI_Ds,
  90 MI_Eb = MI_Ds,
  91 MI_E,
  92 MI_F,
  93 MI_Fs,
  94 MI_Gb = MI_Fs,
  95 MI_G,
  96 MI_Gs,
  97 MI_Ab = MI_Gs,
  98 MI_A,
  99 MI_As,
 100 MI_Bb = MI_As,
 101 MI_B,
 102
 103 MIDI_TONE_KEYCODE_OCTAVES > 1
 104
 105 where x = 1-5:
 106 MI_C_x,
 107 MI_Cs_x,
 108 MI_Db_x = MI_Cs_x,
 109 MI_D_x,
 110 MI_Ds_x,
 111 MI_Eb_x = MI_Ds_x,
 112 MI_E_x,
 113 MI_F_x,
 114 MI_Fs_x,
 115 MI_Gb_x = MI_Fs_x,
 116 MI_G_x,
 117 MI_Gs_x,
 118 MI_Ab_x = MI_Gs_x,
 119 MI_A_x,
 120 MI_As_x,
 121 MI_Bb_x = MI_As_x,
 122 MI_B_x,
 123
 124 MI_OCT_Nx 1-2
 125 MI_OCT_x 0-7
 126 MIDI_OCTAVE_MIN = MI_OCT_N2,
 127 MIDI_OCTAVE_MAX = MI_OCT_7,
 128 MI_OCTD, // octave down
 129 MI_OCTU, // octave up
 130
 131 MI_TRNS_Nx 1-6
 132 MI_TRNS_x 0-6
 133 MIDI_TRANSPOSE_MIN = MI_TRNS_N6,
 134 MIDI_TRANSPOSE_MAX = MI_TRNS_6,
 135 MI_TRNSD, // transpose down
 136 MI_TRNSU, // transpose up
 137
 138 MI_VEL_x 1-10
 139 MIDI_VELOCITY_MIN = MI_VEL_1,
 140 MIDI_VELOCITY_MAX = MI_VEL_9,
 141 MI_VELD, // velocity down
 142 MI_VELU, // velocity up
 143
 144 MI_CHx 1-16
 145 MIDI_CHANNEL_MIN = MI_CH1
 146 MIDI_CHANNEL_MAX = MI_CH16,
 147 MI_CHD, // previous channel
 148 MI_CHU, // next channel
 149
 150 MI_ALLOFF, // all notes off
 151
 152 MI_SUS, // sustain
 153 MI_PORT, // portamento
 154 MI_SOST, // sostenuto
 155 MI_SOFT, // soft pedal
 156 MI_LEG,  // legato
 157
 158 MI_MOD, // modulation
 159 MI_MODSD, // decrease modulation speed
 160 MI_MODSU, // increase modulation speed
 161 #endif // MIDI_ADVANCED
 162
 163 -->
 164
 165 ## Backlight
 166
 167 These keycodes control the backlight. Most keyboards use this for single color in-switch lighting.
 168
 169 |Name|Description|
 170 |----|-----------|
 171 |`BL_x`|Set a specific backlight level between 0-9|
 172 |`BL_ON`|An alias for `BL_9`|
 173 |`BL_OFF`|An alias for `BL_0`|
 174 |`BL_DEC`|Turn the backlight level down by 1|
 175 |`BL_INC`|Turn the backlight level up by 1|
 176 |`BL_TOGG`|Toggle the backlight on or off|
 177 |`BL_STEP`|Step through backlight levels, wrapping around to 0 when you reach the top.|
 178
 179 ## RGBLIGHT WS2818 LEDs
 180
 181 This controls the `RGBLIGHT` functionality. Most keyboards use WS2812 (and compatible) LEDs for underlight or case lighting.
 182
 183 |Name|Description|
 184 |----|-----------|
 185 |`RGB_TOG`|toggle on/off|
 186 |`RGB_MOD`|cycle through modes|
 187 |`RGB_HUI`|hue increase|
 188 |`RGB_HUD`|hue decrease|
 189 |`RGB_SAI`|saturation increase|
 190 |`RGB_SAD`|saturation decrease|
 191 |`RGB_VAI`|value increase|
 192 |`RGB_VAD`|value decrease|
 193
 194 ## Thermal Printer (experimental)
 195
 196 |Name|Description|
 197 |----|-----------|
 198 |`PRINT_ON`|Start printing everything the user types|
 199 |`PRINT_OFF`|Stop printing everything the user types|
 200
 201 ## Keyboard output selection
 202
 203 This is used when multiple keyboard outputs can be selected. Currently this only allows for switching between USB and Bluetooth on keyboards that support both.
 204
 205 |Name|Description|
 206 |----|-----------|
 207 |`OUT_AUTO`|auto mode|
 208 |`OUT_USB`|usb only|
 209 |`OUT_BT`|bluetooth (when `BLUETOOTH_ENABLE`)|
 210
 211 ## Modifiers
 212
 213 These are special keycodes that simulate pressing several modifiers at once.
 214
 215 |Name|Description|
 216 |----|-----------|
 217 |`KC_HYPR`|Hold down LCTL + LSFT + LALT + LGUI|
 218 |`KC_MEH`|Hold down LCTL + LSFT + LALT|
 219
 220 /* FIXME: Should we have these in QMK too?
 221  * |`KC_LCAG`|`LCTL` + `LALT` + `LGUI`|
 222  * |`KC_ALTG`|`RCTL` + `RALT`|
 223  * |`KC_SCMD`/`KC_SWIN`|`LGUI` + `LSFT`|
 224  * |`KC_LCA`|`LCTL` + `LALT`|
 225  */
 226
 227 ### Modifiers with keys
 228
 229 |Name|Description|
 230 |----|-----------|
 231 |`LCTL(kc)`|`LCTL` + `kc`|
 232 |`LSFT(kc)`/`S(kc)`|`LSFT` + `kc`|
 233 |`LALT(kc)`|`LALT` + `kc`|
 234 |`LGUI(kc)`|`LGUI` + `kc`|
 235 |`RCTL(kc)`|`RCTL` + `kc`|
 236 |`RSFT(kc)`|`RSFT` + `kc`|
 237 |`RALT(kc)`|`RALT` + `kc`|
 238 |`RGUI(kc)`|`RGUI` + `kc`|
 239 |`HYPR(kc)`|`LCTL` + `LSFT` + `LALT` + `LGUI` + `kc`|
 240 |`MEH(kc)`|`LCTL` + `LSFT` + `LALT` + `kc`|
 241 |`LCAG(kc)`|`LCTL` + `LALT` + `LGUI` + `kc`|
 242 |`ALTG(kc)`|`RCTL` + `RALT` + `kc`|
 243 |`SCMD(kc)`/`SWIN(kc)`|`LGUI` + `LSFT` + `kc`|
 244 |`LCA(kc)`|`LCTL` + `LALT` + `kc`|
 245
 246 ### One Shot Keys
 247
 248 Most modifiers work by being held down while you push another key. You can use `OSM()` to setup a "One Shot" modifier. When you tap a one shot mod it will remain is a pressed state until you press another key.
 249
 250 To specify a your modifier you need to pass the `MOD` form of the key. For example, if you want to setup a One Shot Control you would use `OSM(MOD_LCTL)`.
 251
 252 |Name|Description|
 253 |----|-----------|
 254 |`OSM(mod)`|use mod for one keypress|
 255 |`OSL(layer)`|switch to layer for one keypress|
 256
 257 ### Mod-tap keys
 258
 259 These keycodes will press the mod(s) when held, and the key when tapped. They only work with [basic keycodes](basic_keycodes.md).
 260
 261 |Name|Description|
 262 |----|-----------|
 263 |`CTL_T(kc)`/`LCTL_T(kc)`|`LCTL` when held, `kc` when tapped|
 264 |`RCTL_T(kc)`|`RCTL` when held, `kc` when tapped|
 265 |`SFT_T(kc)`/`LSFT_T(kc)`|`LSFT` when held, `kc` when tapped|
 266 |`RSFT_T(kc)`|`RSFT` when held, `kc` when tapped|
 267 |`ALT_T(kc)`/`LALT_T(kc)`|`LALT` when held, `kc` when tapped|
 268 |`RALT_T(kc)`/`ALGR_T(kc)`|`RALT` when held, `kc` when tapped|
 269 |`GUI_T(kc)`/`LGUI_T(kc)`|`LGUI` when held, `kc` when tapped|
 270 |`RGUI_T(kc)`|`RGUI` when held, `kc` when tapped|
 271 |`C_S_T(kc)`|`LCTL` + `LSFT` when held, `kc` when tapped|
 272 |`MEH_T(kc)`|`LCTL` + `LSFT` + `LALT` when held, `kc` when tapped|
 273 |`LCAG_T(kc)`|`LCTL` + `LALT` + `LGUI` when held, `kc` when tapped|
 274 |`RCAG_T(kc)`|`RCTL` + `RALT` + `RGUI` when held, `kc` when tapped|
 275 |`ALL_T(kc)`|`LCTL` + `LSFT` + `LALT` + `LGUI` when held, `kc` when tapped [more info](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)|
 276 |`SCMD_T(kc)`/`SWIN_T(kc)`|`LGUI` + `LSFT` when held, `kc` when tapped|
 277 |`LCA_T(kc)`|`LCTL` + `LALT` when held, `kc` when tapped|
 278
 279 ## US ANSI Shifted symbols
 280
 281 These keycodes correspond to characters that are "shifted" on a standard US ANSI keyboards. They do not have dedicated keycodes but are instead typed by holding down shift and then sending a keycode.
 282
 283 It's important to remember that all of these keycodes send a left shift - this may cause unintended actions if unaccounted for. The short code is preferred in most situations.
 284
 285 |Short Name|Long Name|Description|
 286 |----------|---------|-----------|
 287 |`KC_TILD`|`KC_TILDE`|tilde `~`|
 288 |`KC_EXLM`|`KC_EXCLAIM`|exclamation mark `!`|
 289 |`KC_AT`||at sign `@`|
 290 |`KC_HASH`||hash sign `#`|
 291 |`KC_DLR`|`KC_DOLLAR`|dollar sign `$`|
 292 |`KC_PERC`|`KC_PERCENT`|percent sign `%`|
 293 |`KC_CIRC`|`KC_CIRCUMFLEX`|circumflex `^`|
 294 |`KC_AMPR`|`KC_AMPERSAND`|ampersand `&`|
 295 |`KC_ASTR`|`KC_ASTERISK`|asterisk `*`|
 296 |`KC_LPRN`|`KC_LEFT_PAREN`|left parenthesis `(`|
 297 |`KC_RPRN`|`KC_RIGHT_PAREN`|right parenthesis `)`|
 298 |`KC_UNDS`|`KC_UNDERSCORE`|underscore `_`|
 299 |`KC_PLUS`||plus sign `+`|
 300 |`KC_LCBR`|`KC_LEFT_CURLY_BRACE`|left curly brace `{`|
 301 |`KC_RCBR`|`KC_RIGHT_CURLY_BRACE`|right curly brace `}`|
 302 |`KC_LT`/`KC_LABK`|`KC_LEFT_ANGLE_BRACKET`|left angle bracket `<`|
 303 |`KC_GT`/`KC_RABK`|`KC_RIGHT_ANGLE_BRACKET`|right angle bracket `>`|
 304 |`KC_COLN`|`KC_COLON`|colon `:`|
 305 |`KC_PIPE`||pipe `\|`|
 306 |`KC_QUES`|`KC_QUESTION`|question mark `?`|
 307 |`KC_DQT`/`KC_DQUO`|`KC_DOUBLE_QUOTE`|double quote `"`|
 308
 309 ## Layer Changes
 310
 311 These are keycodes that can be used to change the current layer.
 312
 313 |Name|Description|
 314 |----|-----------|
 315 |`LT(layer, kc)`|turn on layer (0-15) when held, kc ([basic keycodes](basic_keycodes.md)) when tapped|
 316 |`TO(layer)`|turn on layer when depressed|
 317 |`MO(layer)`|momentarily turn on layer when depressed (requires `KC_TRNS` on destination layer)|
 318 |`DF(layer)`|sets the base (default) layer|
 319 |`TG(layer)`|toggle layer on/off|
 320 |`TT(layer)`|tap toggle? idk FIXME|
 321 |`OSL(layer)`|switch to layer for one keycode|
 322
 323 ## Unicode
 324
 325 These keycodes can be used in conjuction with the [Unicode](unicode_and_additional_language_support.md) support.
 326
 327 |`UNICODE(n)`/`UC(n)`|if `UNICODE_ENABLE`, this will send characters up to `0x7FFF`|
 328 |`X(n)`|if `UNICODEMAP_ENABLE`, also sends unicode via a different method|
 329
 330 # `SAFE_RANGE`, or safely defining custom keycodes
 331
 332 Sometimes you want to define your own custom keycodes to make your keymap easier to read. QMK provides `SAFE_RANGE` to help you do that. `SAFE_RANGE` is the first available keycode in the `0x0000`-`0xFFFF` range and you can use it when creating your own custom keycode enum:
 333
 334 ```
 335 enum my_keycodes {
 336   FOO = SAFE_RANGE,
 337   BAR
 338 };
 339 ```
 340
 341 You can then use `process_record_user()` to do something with your keycode:
 342
 343 ```
 344 bool process_record_user(uint16_t keycode, keyrecord_t *record) {
 345   switch (keycode) {
 346     case FOO:
 347       // Do something here
 348       break;
 349     case BAR:
 350       // Do something here
 351       break;
 352   }
 353 }
 354 ```