docs/quantum_keycodes.md

   1 # Quantum Keycodes
   2
   3 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.
   4
   5 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.
   6
   7 * `SAFE_RANGE` is always the last keycode in the quantum list, and where custom lists can begin
   8 * `RESET` puts the keyboard into DFU mode for flashing
   9 * `DEBUG` toggles debug mode
  10 * Shortcuts for bootmagic options (work when bootmagic is off)
  11     * `MAGIC_SWAP_CONTROL_CAPSLOCK`
  12     * `MAGIC_CAPSLOCK_TO_CONTROL`
  13     * `MAGIC_SWAP_LALT_LGUI`
  14     * `MAGIC_SWAP_RALT_RGUI`
  15     * `MAGIC_NO_GUI`
  16     * `MAGIC_SWAP_GRAVE_ESC`
  17     * `MAGIC_SWAP_BACKSLASH_BACKSPACE`
  18     * `MAGIC_HOST_NKRO`
  19     * `MAGIC_SWAP_ALT_GUI`/`AG_SWAP`
  20     * `MAGIC_UNSWAP_CONTROL_CAPSLOCK`
  21     * `MAGIC_UNCAPSLOCK_TO_CONTROL`
  22     * `MAGIC_UNSWAP_LALT_LGUI`
  23     * `MAGIC_UNSWAP_RALT_RGUI`
  24     * `MAGIC_UNNO_GUI`
  25     * `MAGIC_UNSWAP_GRAVE_ESC`
  26     * `MAGIC_UNSWAP_BACKSLASH_BACKSPACE`
  27     * `MAGIC_UNHOST_NKRO`
  28     * `MAGIC_UNSWAP_ALT_GUI`/`AG_NORM`
  29     * `MAGIC_TOGGLE_NKRO`
  30 * `KC_GESC`/`GRAVE_ESC` acts as escape when pressed normally but when pressed with a mod will send a `~`
  31 * `KC_LSPO` left shift when held, open paranthesis when tapped
  32 * `KC_RSPC` right shift when held, close paranthesis when tapped
  33 * `KC_LEAD` the leader key
  34
  35 * `FUNC(n)`/`F(n)` to call `fn_action` n
  36 * `M(n)` to call macro n
  37 * `MACROTAP(n)` to macro-tap n idk FIXME
  38
  39 ## Audio
  40
  41 ```c
  42 #ifdef AUDIO_ENABLE
  43     AU_ON,
  44     AU_OFF,
  45     AU_TOG,
  46
  47     #ifdef FAUXCLICKY_ENABLE
  48         FC_ON,
  49         FC_OFF,
  50         FC_TOG,
  51     #endif
  52
  53     // Music mode on/off/toggle
  54     MU_ON,
  55     MU_OFF,
  56     MU_TOG,
  57
  58     // Music voice iterate
  59     MUV_IN,
  60     MUV_DE,
  61 #endif
  62 ```
  63
  64 ## Midi
  65
  66 #if !MIDI_ENABLE_STRICT || (defined(MIDI_ENABLE) && defined(MIDI_BASIC))
  67     MI_ON,  // send midi notes when music mode is enabled
  68     MI_OFF, // don't send midi notes when music mode is enabled
  69 #endif
  70
  71 MIDI_TONE_MIN,
  72 MIDI_TONE_MAX
  73
  74 MI_C = MIDI_TONE_MIN,
  75 MI_Cs,
  76 MI_Db = MI_Cs,
  77 MI_D,
  78 MI_Ds,
  79 MI_Eb = MI_Ds,
  80 MI_E,
  81 MI_F,
  82 MI_Fs,
  83 MI_Gb = MI_Fs,
  84 MI_G,
  85 MI_Gs,
  86 MI_Ab = MI_Gs,
  87 MI_A,
  88 MI_As,
  89 MI_Bb = MI_As,
  90 MI_B,
  91
  92 MIDI_TONE_KEYCODE_OCTAVES > 1
  93
  94 where x = 1-5:
  95 MI_C_x,
  96 MI_Cs_x,
  97 MI_Db_x = MI_Cs_x,
  98 MI_D_x,
  99 MI_Ds_x,
 100 MI_Eb_x = MI_Ds_x,
 101 MI_E_x,
 102 MI_F_x,
 103 MI_Fs_x,
 104 MI_Gb_x = MI_Fs_x,
 105 MI_G_x,
 106 MI_Gs_x,
 107 MI_Ab_x = MI_Gs_x,
 108 MI_A_x,
 109 MI_As_x,
 110 MI_Bb_x = MI_As_x,
 111 MI_B_x,
 112
 113 MI_OCT_Nx 1-2
 114 MI_OCT_x 0-7
 115 MIDI_OCTAVE_MIN = MI_OCT_N2,
 116 MIDI_OCTAVE_MAX = MI_OCT_7,
 117 MI_OCTD, // octave down
 118 MI_OCTU, // octave up
 119
 120 MI_TRNS_Nx 1-6
 121 MI_TRNS_x 0-6
 122 MIDI_TRANSPOSE_MIN = MI_TRNS_N6,
 123 MIDI_TRANSPOSE_MAX = MI_TRNS_6,
 124 MI_TRNSD, // transpose down
 125 MI_TRNSU, // transpose up
 126
 127 MI_VEL_x 1-10
 128 MIDI_VELOCITY_MIN = MI_VEL_1,
 129 MIDI_VELOCITY_MAX = MI_VEL_10,
 130 MI_VELD, // velocity down
 131 MI_VELU, // velocity up
 132
 133 MI_CHx 1-16
 134 MIDI_CHANNEL_MIN = MI_CH1
 135 MIDI_CHANNEL_MAX = MI_CH16,
 136 MI_CHD, // previous channel
 137 MI_CHU, // next channel
 138
 139 MI_ALLOFF, // all notes off
 140
 141 MI_SUS, // sustain
 142 MI_PORT, // portamento
 143 MI_SOST, // sostenuto
 144 MI_SOFT, // soft pedal
 145 MI_LEG,  // legato
 146
 147 MI_MOD, // modulation
 148 MI_MODSD, // decrease modulation speed
 149 MI_MODSU, // increase modulation speed
 150 #endif // MIDI_ADVANCED
 151
 152 ## Backlight
 153
 154 * `BL_x` where x = 0-15
 155 * `BL_ON = BL_9`
 156 * `BL_OFF = BL_0`
 157 * `BL_DEC`
 158 * `BL_INC`
 159 * `BL_TOGG`
 160 * `BL_STEP`
 161
 162 ## RGB WS2818 LEDs
 163
 164 * `RGB_TOG` toggle on/off
 165 * `RGB_MOD` cycle between modes
 166 * `RGB_HUI` hue increase
 167 * `RGB_HUD` hue decrease
 168 * `RGB_SAI` saturation increase
 169 * `RGB_SAD` saturation decrease
 170 * `RGB_VAI` value increase
 171 * `RGB_VAD` value decrease
 172
 173 ## Thermal Printer (experimental)
 174
 175 * `PRINT_ON`
 176 * `PRINT_OFF`
 177
 178 ## Keyboard output selection
 179
 180 * `OUT_AUTO` auto mode
 181 * `OUT_USB` usb only
 182 * `OUT_BT` bluetooth (when `BLUETOOTH_ENABLE`)
 183
 184 ## Modifiers
 185
 186 * `KC_HYPR` LCTL + LSFT + LALT + LGUI - `MOD_HYPR` is the bit version
 187 * `KC_MEH` LCTL + LSFT + LALT - `MOD_MEH` is the bit version
 188
 189 ### Modifiers with keys
 190
 191 * `LCTL(kc)` LCTL + kc
 192 * `LSFT(kc)`/`S(kc)` LSFT + kc
 193 * `LALT(kc)` LALT + kc
 194 * `LGUI(kc)` LGUI + kc
 195 * `RCTL(kc)` RCTL + kc
 196 * `RSFT(kc)` RSFT + kc
 197 * `RALT(kc)` RALT + kc
 198 * `RGUI(kc)` RGUI + kc
 199
 200 * `HYPR(kc)` LCTL + LSFT + LALT + LGUI + kc
 201 * `MEH(kc)`  LCTL + LSFT + LALT + kc
 202 * `LCAG(kc)` LCTL + LALT + LGUI + kc
 203 * `ALTG(kc)` RCTL + RALT + kc
 204 * `SCMD(kc)`/`SWIN(kc)` LGUI + LSFT + kc
 205 * `LCA(kc)` LCTL + LALT + kc
 206
 207 * `OSM(mod)` use mod for one keypress - use mod bits with this
 208
 209 > Mod bits are the 4-letter part of the keycode prefixed with `MOD_`, e.g. `MOD_LCTL`
 210
 211 ### Mod-tap keys
 212
 213 These keycodes will press the mod(s) when held, and the key when tapped. They only work with [basic keycodes](basic_keycodes.md).
 214
 215 * `CTL_T(kc)`/`LCTL_T(kc)` LCTL when held, kc when tapped
 216 * `RCTL_T(kc)` RCTL when held, kc when tapped
 217
 218 * `SFT_T(kc)`/`LSFT_T(kc)` LSFT when held, kc when tapped
 219 * `RSFT_T(kc)` RSFT when held, kc when tapped
 220
 221 * `ALT_T(kc)`/`LALT_T(kc)` LALT when held, kc when tapped
 222 * `RALT_T(kc)`/`ALGR_T(kc)` RALT when held, kc when tapped
 223
 224 * `GUI_T(kc)`/`LGUI_T(kc)` LGUI when held, kc when tapped
 225 * `RGUI_T(kc)` RGUI when held, kc when tapped
 226
 227 * `C_S_T(kc)` LCTL + LSFT when held, kc when tapped
 228 * `MEH_T(kc)` LCTL + LSFT + LALT when held, kc when tapped
 229 * `LCAG_T(kc)` LCTL + LALT + LGUI when held, kc when tapped
 230 * `RCAG_T(kc)` RCTL + RALT + RGUI when held, kc when tapped
 231 * `ALL_T(kc)` LCTL + LSFT + LALT + LGUI when held, kc tapped [more info](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)
 232 * `SCMD_T(kc)`/`SWIN_T(kc)` LGUI + LSFT when held, kc when tapped
 233 * `LCA_T(kc)` LCTL + LALT when held, kc when tapped
 234
 235 ## Shifted symbols
 236
 237 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.
 238
 239 * `KC_TILD`/`KC_TILDE` tilde `~`
 240 * `KC_EXLM`/`KC_EXCLAIM` exclamation mark `!`
 241 * `KC_AT` at sign `@`
 242 * `KC_HASH` hash sign `#`
 243 * `KC_DLR`/`KC_DOLLAR` dollar sign `$`
 244 * `KC_PERC`/`KC_PERCENT` percent sign `%`
 245 * `KC_CIRC`/`KC_CIRCUMFLEX` circumflex `^`
 246 * `KC_AMPR`/`KC_AMPERSAND` ampersand `&`
 247 * `KC_ASTR`/`KC_ASTERISK` asterisk `*`
 248 * `KC_LPRN`/`KC_LEFT_PAREN` left parenthesis `(`
 249 * `KC_RPRN`/`KC_RIGHT_PAREN` right parenthesis `)`
 250 * `KC_UNDS`/`KC_UNDERSCORE` underscore `_`
 251 * `KC_PLUS` plus sign `+`
 252 * `KC_LCBR`/`KC_LEFT_CURLY_BRACE` left curly brace `{`
 253 * `KC_RCBR`/`KC_RIGHT_CURLY_BRACE` right curly brace `}`
 254 * `KC_LT`/`KC_LABK`/`KC_LEFT_ANGLE_BRACKET` left angle bracket `<`
 255 * `KC_GT`/`KC_RABK`/`KC_RIGHT_ANGLE_BRACKET` right angle bracket `>`
 256 * `KC_COLN`/`KC_COLON` colon `:`
 257 * `KC_PIPE` pipe `|`
 258 * `KC_QUES`/`KC_QUESTION` question mark `?`
 259 * `KC_DQT`/`KC_DOUBLE_QUOTE`/`KC_DQUO` double quote `"`
 260
 261 ## Layer adjustments
 262
 263 * `LT(layer, kc)` turn on layer (0-15) when held, kc ([basic keycodes](basic_keycodes.md)) when tapped
 264 * `TO(layer)` turn on layer when depressed
 265 * `MO(layer)` momentarily turn on layer when depressed (requires `KC_TRNS` on destination layer)
 266 * `DF(layer)` sets the base (default) layer
 267 * `TG(layer)` toggle layer on/off
 268 * `OSL(layer)` switch to layer for one keycode
 269 * `TT(layer)` tap toggle? idk FIXME
 270
 271 ## Unicode
 272
 273 * `UNICODE(n)`/`UC(n)` if `UNICODE_ENABLE`, this will send characters up to `0x7FFF`
 274 * `X(n)` if `UNICODEMAP_ENABLE`, also sends unicode via a different method