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