docs/keymap_old.md

   1 Keymap framework - how to define your keymap
   2 ============================================
   3 ***NOTE: This is updated for QMK but this is still work in progress.  This may still be inconsistent with the source code.***
   4
   5 QMK is based on TMK.   Understanding the essential changes made should help you understand variable names etc.
   6
   7 ## TMK vs. QMK
   8
   9 | Firmware                  |TMK                    |QMK                      |
  10 |---------------------------|-----------------------|-------------------------|
  11 | Maintainer                |hasu                   |Jack Humbert et al.      |
  12 | Build path customization  | `TMK_DIR = ...`       | `include .../Makefile`  |
  13 | `keymaps` data            | 3D array of `uint8_t` holding **keycode**      | 3D array of `uint16_t` holding **action code**  |
  14 | `fn_actions` data         | 1D array of `uint16_t` holding **action code** | 1D array of `uint16_t` holding **action code**  |
  15
  16 Since QMK is based on TMK and uses major portion of TMK code as is, understanding the essential changes made should help you understand the code.
  17
  18 ## 0. Keymap and layers
  19 In QMK,  **`const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS]`** holds multiple **layers** of keymap information in **16 bit** data holding the **action code**. You can define **32 layers** at most.
  20
  21 For trivial key definitions, the higher 8 bits of the **action code** are all 0 and the lower 8 bits holds the USB HID usage code generated by the key as **keycode**.
  22
  23 Respective layers can be validated simultaneously. Layers are indexed with 0 to 31 and higher layer has precedence.
  24
  25     Keymap: 32 Layers                   Layer: action code matrix
  26     -----------------                   ---------------------
  27     stack of layers                     array_of_action_code[row][column]
  28            ____________ precedence               _______________________
  29           /           / | high                  / ESC / F1  / F2  / F3   ....
  30       31 /___________// |                      /-----/-----/-----/-----
  31       30 /___________// |                     / TAB /  Q  /  W  /  E   ....
  32       29 /___________/  |                    /-----/-----/-----/-----
  33        :   _:_:_:_:_:__ |               :   /LCtrl/  A  /  S  /  D   ....
  34        :  / : : : : : / |               :  /  :     :     :     :
  35        2 /___________// |               2 `--------------------------
  36        1 /___________// |               1 `--------------------------
  37        0 /___________/  V low           0 `--------------------------
  38
  39
  40 Sometimes, the action code stored in keymap may be referred as keycode in some documents due to the TMK history.
  41
  42 ### 0.1 Keymap layer status
  43 Keymap layer has its state in two 32 bit parameters:
  44
  45 * **`default_layer_state`** indicates a base keymap layer(0-31) which is always valid and to be referred.
  46 * **`layer_state`** () has current on/off status of the layer on its each bit.
  47
  48 Keymap has its state in two parameter **`default_layer`** indicates a base keymap layer(0-31) which is always valid and to be referred, **`keymap_stat`** is 16bit variable which has current on/off status of layers on its each bit.
  49 Keymap layer '0' is usually `default_layer` and which is the only valid layer and other layers is initially off after boot up firmware, though, you can configured them in `config.h`.
  50 To change `default_layer` will be useful when you switch key layout completely, say you want Colmak instead of Qwerty.
  51
  52     Initial state of Keymap          Change base layout
  53     -----------------------          ------------------
  54
  55       31                               31
  56       30                               30
  57       29                               29
  58        :                                :
  59        :                                :   ____________
  60        2   ____________                 2  /           /
  61        1  /           /              ,->1 /___________/
  62     ,->0 /___________/               |  0
  63     |                                |
  64     `--- default_layer = 0           `--- default_layer = 1
  65          layer_state   = 0x00000001       layer_state   = 0x00000002
  66
  67 On the other hand, you shall change `layer_state` to overlay base layer with some layers for feature such as navigation keys, function key(F1-F12), media keys or special actions.
  68
  69     Overlay feature layer
  70     ---------------------      bit|status
  71            ____________        ---+------
  72       31  /           /        31 |   0
  73       30 /___________// -----> 30 |   1
  74       29 /___________/  -----> 29 |   1
  75        :                        : |   :
  76        :   ____________         : |   :
  77        2  /           /         2 |   0
  78     ,->1 /___________/  ----->  1 |   1
  79     |  0                        0 |   0
  80     |                                 +
  81     `--- default_layer = 1            |
  82          layer_state   = 0x60000002 <-'
  83
  84
  85
  86 ### 0.2 Layer Precedence and Transparency
  87 Note that ***higher layer has higher priority on stack of layers***, namely firmware falls down from top layer to bottom to look up keycode. Once it spots keycode other than **`KC_TRNS`**(transparent) on a layer it stops searching and lower layers aren't referred.
  88
  89 You can place `KC_TRANS` on overlay layer changes just part of layout to fall back on lower or base layer.
  90 Key with `KC_TRANS` (`KC_TRNS` and `_______` are the alias) doesn't has its own keycode and refers to lower valid layers for keycode, instead.
  91 See example below.
  92
  93
  94 ### 0.3 Keymap Example
  95 Keymap in this QMK is **`static const uint16_t PROGMEM keymaps[]`** C array in fact and you can define layers in it with **`KEYMAP()`** C macro and keycodes. To use complex actions you need to define `Fn` keycode in **`fn_actions[]`** array.  It holds the 16 bit quantum keycode (action code).
  96
  97 > Please note that keymap in the TMK, which QMK was forked from, is **`static const uint8_t PROGMEM keymaps[]`** C array which holds the 8 bit keycode (~USB HID usage code).
  98
  99 This is a keymap example for [HHKB](http://en.wikipedia.org/wiki/Happy_Hacking_Keyboard) keyboard.
 100 This example has three layers, 'QWERTY' as base layer, 'FN' and  'MOUSE'.
 101
 102 In this example,
 103
 104  `MO(layer)` is a **momentary layer switching** key.
 105
 106 You can find other keymap definitions in file `keymap.c` located on project directories.
 107 ```
 108 /*
 109  * dbroqua HHKB Layout
 110  */
 111 #include "hhkb.h"
 112
 113 #define BASE 0
 114 #define FN 1
 115 #define MOUSE 2
 116
 117 const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
 118     /* BASE Level: Default Layer
 119      * ,-----------------------------------------------------------------------------------------.
 120      * | Esc |  1  |  2  |  3  |  4  |  5  |  6  |  7  |  8  |  9  |  0  |  -  |  =  |  \  |  `  |
 121      * |-----------------------------------------------------------------------------------------+
 122      * | Tab    |  Q  |  W  |  E  |  R  |  T  |  Y  |  U  |  I  |  O  |  P  |  [  |  ]  |  Bksp  |
 123      * |-----------------------------------------------------------------------------------------+
 124      * | Ctrl    |  A  |  S  |  D  |  F  |  G  |  H  |  J  |  K  |  L  |  ;  |  '  |    Enter    |
 125      * |-----------------------------------------------------------------------------------------+
 126      * | Shift     |  Z  |  X  |  C  |  V  |  B  |  N  |  M  |  ,  |  .  |  /  | Shift     | fn  |
 127      * +-----------------------------------------------------------------------------------------+
 128      *         | Gui |  Alt   |               Space               | AltGr |Mouse|
 129      *         `----------------------------------------------------------------´
 130      */
 131     [BASE] = KEYMAP(
 132         KC_ESC,   KC_1,  KC_2,  KC_3,  KC_4,  KC_5,  KC_6,  KC_7,  KC_8,     KC_9,    KC_0,     KC_MINS,  KC_EQL,    KC_BSLS,  KC_GRV, \
 133         KC_TAB,   KC_Q,  KC_W,  KC_E,  KC_R,  KC_T,  KC_Y,  KC_U,  KC_I,     KC_O,    KC_P,     KC_LBRC,  KC_RBRC,   KC_BSPC,          \
 134         KC_LCTL,  KC_A,  KC_S,  KC_D,  KC_F,  KC_G,  KC_H,  KC_J,  KC_K,     KC_L,    KC_SCLN,  KC_QUOT,  KC_ENT,                      \
 135         KC_LSFT,  KC_Z,  KC_X,  KC_C,  KC_V,  KC_B,  KC_N,  KC_M,  KC_COMM,  KC_DOT,  KC_SLSH,  KC_RSFT,  MO(FN),                    \
 136                         KC_LGUI, KC_LALT,  /*        */ KC_SPC, KC_RALT, MO(MOUSE)
 137     ),
 138
 139     /* FN Layer
 140      * ,-----------------------------------------------------------------------------------------.
 141      * | Pwr |  F1  | F2  | F3  | F4  | F5  | F6  | F7  | F8  | F9  | F0  | F11 | F12 | Ins | Del|
 142      * |-----------------------------------------------------------------------------------------+
 143      * | Caps   |     |     |     |     |     |     |     |PrtSc| Slck| Paus|  Up |     |        |
 144      * |-----------------------------------------------------------------------------------------+
 145      * |         | Vol-| Vol+| Mute|     |     | *   | /   | Home| PgUp| Left |Right|            |
 146      * |-----------------------------------------------------------------------------------------+
 147      * |           | Prev| Play| Next|     |     | +   | -   | End |PgDwn| Down|           |     |
 148      * +-----------------------------------------------------------------------------------------+
 149      *         |     |        |                                   | Stop  |     |
 150      *         `----------------------------------------------------------------´
 151      */
 152     [FN] = KEYMAP(
 153         KC_PWR,   KC_F1,    KC_F2,    KC_F3,    KC_F4,    KC_F5,    KC_F6,    KC_F7,    KC_F8,    KC_F9,    KC_F10,   KC_F11,   KC_F12,   KC_INS,   KC_DEL, \
 154         KC_CAPS,  KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_PSCR,  KC_SLCK,  KC_PAUS,  KC_UP,    KC_TRNS,  KC_TRNS,          \
 155         KC_TRNS,  KC_VOLD,  KC_VOLU,  KC_MUTE,  KC_TRNS,  KC_TRNS,  KC_PAST,  KC_PSLS,  KC_HOME,  KC_PGUP,  KC_LEFT,  KC_RGHT,  KC_TRNS,                    \
 156         KC_TRNS,  KC_MPRV,  KC_MPLY,  KC_MNXT,  KC_TRNS,  KC_TRNS,  KC_PPLS,  KC_PMNS,  KC_END,   KC_PGDN,  KC_DOWN,  KC_TRNS,  KC_TRNS,                    \
 157                         KC_TRNS, KC_TRNS,           KC_TRNS,                KC_MSTP, KC_TRNS
 158     ),
 159
 160     /* MOUSE Layer
 161      * ,-----------------------------------------------------------------------------------------.
 162      * |     |      |     |     |     |     |     |     |     |     |     |     |     |     |    |
 163      * |-----------------------------------------------------------------------------------------+
 164      * |        |     | WUp |     |     |     |     |     |     |     | Btn1|  Up | Btn2|        |
 165      * |-----------------------------------------------------------------------------------------+
 166      * |         | WLt | WDn | WRt |     |     |     |     |     |     | Left |Right|            |
 167      * |-----------------------------------------------------------------------------------------+
 168      * |           |     |     |     |     |     |     |     |     | Btn3| Down|           |     |
 169      * +-----------------------------------------------------------------------------------------+
 170      *         |     |        |                                   |       |     |
 171      *         `----------------------------------------------------------------´
 172      */
 173     [MOUSE] = KEYMAP(
 174         KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_TRNS,   KC_TRNS, \
 175         KC_TRNS,  KC_TRNS,  KC_WH_U,  KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_BTN1,  KC_MS_U,  KC_BTN2,  KC_TRNS,          \
 176         KC_TRNS,  KC_WH_L,  KC_WH_D,  KC_WH_R,  KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_MS_L,  KC_MS_R,  KC_TRNS,                    \
 177         KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_TRNS,  KC_BTN3,  KC_MS_D,  KC_TRNS,  KC_TRNS,                    \
 178                         KC_TRNS, KC_TRNS,           KC_TRNS,                KC_TRNS, KC_TRNS
 179     )
 180 };
 181
 182 const uint16_t PROGMEM fn_actions[] = {
 183
 184 };
 185
 186 const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt)
 187 {
 188   // MACRODOWN only works in this function
 189       switch(id) {
 190         case 0:
 191           if (record->event.pressed) {
 192             register_code(KC_RSFT);
 193           } else {
 194             unregister_code(KC_RSFT);
 195           }
 196         break;
 197       }
 198     return MACRO_NONE;
 199 };
 200 ```
 201
 202
 203 ## 1. Keycode
 204 See [`tmk_core/common/keycode.h`](../tmk_core/common/keycode.h) or keycode table below for the detail. Keycode is internal **8bit code** to indicate action performed on key in keymap.  Keycodes are based on [HID Usage Keyboard/Keypad Page(0x07)](http://www.usb.org/developers/hidpage/Hut1_12v2.pdf) plus special codes in the `0xA5-DF` range.
 205
 206 Keycode has `KC_` prefixed symbol respectively. Most of keycodes like `KC_A` have simple action registers key to host on press and unregister on release, while some of other keycodes has some special actions like `Fn` keys, Media control keys, System control keys and Mousekeys.
 207
 208 keymaps[]
 209
 210 In `KEYMAP()` macro, TMK recommends you to keep prefix part `KC_` of keycode to keep keymap compact. For example, just use `A` instead you place `KC_A` in `KEYMAP()`.  But this doesn't apply for QMK.
 211
 212 The `KEYMAP()` macro defines correspondence between the physical key location to the electrical key connection.
 213
 214 Some keycodes has 7-letter **short name** such as `KC_COMM` in addition to descriptive name `KC_COMMA`, you'll prefer short one in `KEYMAP()`.
 215
 216 ### 1.0 Other key
 217 - `KC_NO` for no action
 218 - `KC_TRNS` for layer transparency (See above)
 219
 220 ### 1.1 Normal key
 221 - `KC_A` to `KC_Z`, `KC_1` to `KC_0` for alpha numeric key
 222 - `KC_MINS`, `KC_EQL`, `KC_GRV`, `KC_RBRC`, `KC_LBRC`, `KC_COMM`, `KC_DOT`, `KC_BSLS`, `KC_SLSH`, `KC_SCLN`, `KC_QUOT`
 223 - `KC_ESC`, `KC_TAB`, `KC_SPC`, `KC_BSPC`, `KC_ENT`, `KC_DEL`, `KC_INS`
 224 - `KC_UP`, `KC_DOWN`, `KC_RGHT`, `KC_LEFT`, `KC_PGUP`, `KC_PGDN`, `KC_HOME`, `KC_END`
 225 - `KC_CAPS`, `KC_NLCK`, `KC_SLCK`, `KC_PSCR`, `KC_PAUS`, `KC_APP`, `KC_F1` to `KC_F24`
 226 - `KC_P1` to `KC_P0`, `KC_PDOT`, `KC_PCMM`, `KC_PSLS`, `KC_PAST`, `KC_PMNS`, `KC_PPLS`, `KC_PEQL`, `KC_PENT` for keypad.
 227
 228 ### 1.2 Modifier
 229 There are 8 modifiers which has discrimination between left and right.
 230
 231 - `KC_LCTL` and `KC_RCTL` for Control
 232 - `KC_LSFT` and `KC_RSFT` for Shift
 233 - `KC_LALT` and `KC_RALT` for Alt
 234 - `KC_LGUI` and `KC_RGUI` for Windows key or Command key in Mac
 235
 236 ### 1.3 Mousekey
 237 - `KC_MS_U`, `KC_MS_D`, `KC_MS_L`, `KC_MS_R` for mouse cursor
 238 - `KC_WH_U`, `KC_WH_D`, `KC_WH_L`, `KC_WH_R` for mouse wheel
 239 - `KC_BTN1`, `KC_BTN2`, `KC_BTN3`, `KC_BTN4`, `KC_BTN5` for mouse buttons
 240
 241 ### 1.4 System & Media key
 242 - `KC_PWR`, `KC_SLEP`, `KC_WAKE` for Power, Sleep, Wake
 243 - `KC_MUTE`, `KC_VOLU`, `KC_VOLD` for audio volume control
 244 - `KC_MNXT`, `KC_MPRV`, `KC_MSTP`, `KC_MPLY`, `KC_MSEL` for media control
 245 - `KC_MAIL`, `KC_CALC`, `KC_MYCM` for application launch
 246 - `KC_WSCH`, `KC_WHOM`, `KC_WBAK`, `KC_WFWD`, `KC_WSTP`, `KC_WREF`, `KC_WFAV` for web browser operation
 247
 248 ### 1.5 Fn key
 249 You don't need to use this functionality under QMK since this is a backward compatibility functionality.  Unlike TMK, you can write action code itself directly in  **`static const uint16_t PROGMEM keymaps[]`** C array using `MO(layer)`, etc.
 250
 251 `KC_FNnn` are keycodes for `Fn` key which not given any actions at the beginning unlike most of keycodes has its own inborn action. To use these keycodes in `KEYMAP()` you need to assign action you want at first. Action of `Fn` key is defined in `fn_actions[]` and its index of the array is identical with number part of `KC_FNnn`. Thus `KC_FN0` keycode indicates the action defined in first element of the array. ***Only 32 `Fn` keys can be defined at most.***
 252
 253
 254 ### 1.6 Keycode Table
 255  See keycode table in [`doc/keycode.txt`](./keycode.txt) for description of keycodes.
 256
 257  In regard to implementation side most of keycodes are identical with [HID usage][HID_usage](pdf) sent to host for real and some virtual keycodes are defined to support special actions.
 258 [HID_usage]: http://www.usb.org/developers/hidpage/Hut1_12v2.pdf
 259
 260
 261
 262 ## 2. Action
 263 See [`common/action_code.h`](../common/action_code.h). Action is a **16bit code** and defines function to perform on events of a key like press, release, holding and tapping.
 264
 265 Most of keys just register 8bit scancode to host, but to support other complex features needs 16bit extended action codes internally. However, using 16bit action codes in keymap results in double size in memory compared to using just keycodes. To avoid this waste 8bit keycodes are used in `KEYMAP()` instead of action codes.
 266
 267 ***You can just use keycodes of `Normal key`, `Modifier`, `Mousekey` and `System & Media key` in keymap*** to indicate corresponding actions instead of using action codes. While ***to use other special actions you should use keycode of `Fn` key defined in `fn_actions[]`.***
 268
 269
 270 ### 2.1 Key Action
 271 This is a simple action that registers scancodes(HID usage in fact) to host on press event of key and unregister on release.
 272
 273 #### Parameters
 274 + **mods**: { ` MOD_LCTL`, ` MOD_LSFT`, ` MOD_LALT`, ` MOD_LGUI`,
 275               ` MOD_RCTL`, ` MOD_RSFT`, ` MOD_RALT`, ` MOD_RGUI` }
 276 + **key**: keycode
 277
 278
 279 #### 2.1.1 Normal key and Modifier
 280 ***This action usually won't be used expressly in keymap*** because you can just use keycodes in `KEYMAP()` instead.
 281
 282 You can define these actions on *'A'* key and *'left shift'* modifier with:
 283
 284     ACTION_KEY(KC_A)
 285     ACTION_KEY(KC_LSFT)
 286
 287 #### 2.1.2 Modified key
 288 This action is comprised of strokes of modifiers and a key. `Macro` action is needed if you want more complex key strokes.
 289
 290 Say you want to assign a key to `Shift + 1` to get character *'!'* or `Alt + Tab` to switch application windows.
 291
 292     ACTION_MODS_KEY(MOD_LSFT, KC_1)
 293     ACTION_MODS_KEY(MOD_LALT, KC_TAB)
 294
 295 Or `Alt,Shift + Tab` can be defined. `ACTION_MODS_KEY(mods, key)` requires **4-bit modifier state** and a **keycode** as arguments. See `keycode.h` for `MOD_BIT()` macro.
 296
 297     ACTION_MODS_KEY(MOD_LALT | MOD_LSFT, KC_TAB)
 298
 299 #### 2.1.3 Multiple Modifiers
 300 Registers multiple modifiers with pressing a key. To specify multiple modifiers use `|`.
 301
 302     ACTION_MODS(MOD_ALT | MOD_LSFT)
 303
 304 #### 2.1.3 Modifier with Tap key([Dual role][dual_role])
 305 Works as a modifier key while holding, but registers a key on tap(press and release quickly).
 306
 307
 308     ACTION_MODS_TAP_KEY(MOD_RCTL, KC_ENT)
 309
 310
 311
 312 ### 2.2 Layer Action
 313 These actions operate layers of keymap.
 314
 315 #### Parameters
 316 You can specify a **target layer** of action and **when the action is executed**. Some actions take a **bit value** for bitwise operation.
 317
 318
 319 + **layer**: `0`-`31`
 320 + **on**: { `ON_PRESS` | `ON_RELEASE` | `ON_BOTH` }
 321 + **bits**: 4-bit value and 1-bit mask bit
 322
 323
 324 #### 2.2.1 Default Layer
 325 Default Layer is a layer which always is valid and referred to when actions is not defined on other overlay layers.
 326
 327 This sets Default Layer to given parameter `layer` and activate it.
 328
 329     ACTION_DEFAULT_LAYER_SET(layer)
 330
 331
 332 #### 2.2.2 Momentary
 333 Turns on `layer` momentarily while holding, in other words it activates when key is pressed and deactivate when released.
 334
 335     ACTION_LAYER_MOMENTARY(layer)
 336
 337
 338 #### 2.2.3 Toggle Switch
 339 Turns on `layer` with first type(press and release) and turns off with next.
 340
 341     ACTION_LAYER_TOGGLE(layer)
 342
 343
 344 #### 2.2.4 Momentary Switch with tap key
 345 Turns on `layer` momentary while holding, but registers key on tap(press and release quickly).
 346
 347     ACTION_LAYER_TAP_KEY(layer, key)
 348
 349
 350 #### 2.2.5 Momentary Switch with tap toggle
 351 Turns on `layer` momentary while holding and toggles it with serial taps.
 352
 353     ACTION_LAYER_TAP_TOGGLE(layer)
 354
 355
 356 #### 2.2.6 Invert state of layer
 357 Inverts current state of `layer`. If the layer is on it becomes off with this action.
 358
 359     ACTION_LAYER_INVERT(layer, on)
 360
 361
 362 #### 2.2.7 Turn On layer
 363 Turns on layer state.
 364
 365     ACTION_LAYER_ON(layer, on)
 366
 367 Turns on layer state on press and turns off on release.
 368
 369     ACTION_LAYER_ON_OFF(layer)
 370
 371
 372 #### 2.2.8 Turn Off layer
 373 Turns off layer state.
 374
 375     ACTION_LAYER_OFF(layer, on)
 376
 377 Turns off layer state on press and activates on release.
 378
 379     ACTION_LAYER_OFF_ON(layer)
 380
 381
 382 #### 2.2.9 Set layer
 383 Turn on layer only.
 384 `layer_state = (1<<layer) [layer: 0-31]`
 385
 386     ACTION_LAYER_SET(layer, on)
 387
 388 Turns on layer only and clear all layer on release..
 389
 390     ACTION_LAYER_SET_CLEAR(layer)
 391
 392
 393 #### 2.2.10 Bitwise operation
 394
 395 **part** indicates which part of 32bit layer state(0-7). **bits** is 5-bit value. **on** indicates when the action is executed.
 396
 397     ACTION_LAYER_BIT_AND(part, bits, on)
 398     ACTION_LAYER_BIT_OR(part, bits, on)
 399     ACTION_LAYER_BIT_XOR(part, bits, on)
 400     ACTION_LAYER_BIT_SET(part, bits, on)
 401
 402 These actions works with parameters as following code.
 403
 404     uint8_t shift = part*4;
 405     uint32_t mask = (bits&0x10) ? ~(0xf<<shift) : 0;
 406     uint32_t layer_state = layer_state <bitop> ((bits<<shift)|mask);
 407
 408
 409 Default Layer also has bitwise operations, they are executed when key is released.
 410
 411     ACTION_DEFAULT_LAYER_BIT_AND(part, bits)
 412     ACTION_DEFAULT_LAYER_BIT_OR(part, bits)
 413     ACTION_DEFAULT_LAYER_BIT_XOR(part, bits)
 414     ACTION_DEFAULT_LAYER_BIT_SET(part, bits)
 415
 416
 417
 418 ### 2.3 Macro action
 419 ***TBD***
 420
 421 `Macro` action indicates complex key strokes.
 422
 423     MACRO( D(LSHIFT), D(D), END )
 424     MACRO( U(D), U(LSHIFT), END )
 425     MACRO( I(255), T(H), T(E), T(L), T(L), W(255), T(O), END )
 426
 427 #### 2.3.1 Macro Commands
 428 - **I()**   change interval of stroke.
 429 - **D()**   press key
 430 - **U()**   release key
 431 - **T()**   type key(press and release)
 432 - **W()**   wait
 433 - **END**   end mark
 434
 435 #### 2.3.2 Examples
 436
 437 ***TODO: sample implementation***
 438 See `keyboards/hhkb/keymap.c` for sample.
 439
 440
 441
 442 ### 2.4 Function action
 443 ***TBD***
 444
 445 There are two type of action, normal `Function` and tappable `Function`.
 446 These actions call user defined function with `id`, `opt`, and key event information as arguments.
 447
 448 #### 2.4.1 Function
 449 To define normal `Function` action in keymap use this.
 450
 451     ACTION_FUNCTION(id, opt)
 452
 453 #### 2.4.2 Function with tap
 454 To define tappable `Function` action in keymap use this.
 455
 456     ACTION_FUNCTION_TAP(id, opt)
 457
 458 #### 2.4.3 Implement user function
 459 `Function` actions can be defined freely with C by user in callback function:
 460
 461     void keymap_call_function(keyrecord_t *event, uint8_t id, uint8_t opt)
 462
 463 This C function is called every time key is operated, argument `id` selects action to be performed and `opt` can be used for option. Function `id` can be 0-255 and `opt` can be 0-15.
 464
 465  `keyrecord_t` is comprised of key event and tap count. `keyevent_t` indicates which and when key is pressed or released. From `tap_count` you can know tap state, 0 means no tap. These information will be used in user function to decide how action of key is performed.
 466
 467     typedef struct {
 468         keyevent_t  event;
 469         uint8_t     tap_count;
 470     } keyrecord_t;
 471
 472     typedef struct {
 473         key_t    key;
 474         bool     pressed;
 475         uint16_t time;
 476     } keyevent_t;
 477
 478     typedef struct {
 479         uint8_t col;
 480         uint8_t row;
 481     } key_t;
 482
 483 ***TODO: sample implementation***
 484 See `keyboards/hhkb/keymap.c` for sample.
 485
 486
 487
 488 ### 2.5 Backlight Action
 489 These actions control the backlight.
 490
 491 #### 2.5.1 Change backlight level
 492 Increase backlight level.
 493
 494     ACTION_BACKLIGHT_INCREASE()
 495
 496 Decrease backlight level.
 497
 498     ACTION_BACKLIGHT_DECREASE()
 499
 500 Step through backlight levels.
 501
 502     ACTION_BACKLIGHT_STEP()
 503
 504 Turn a specific backlight level on or off.
 505
 506     ACTION_BACKLIGHT_LEVEL(1)
 507
 508 #### 2.5.2 Turn on / off backlight
 509 Turn the backlight on and off without changing level.
 510
 511     ACTION_BACKLIGHT_TOGGLE()
 512
 513
 514
 515 ### 2.6 Swap-Hands Action
 516 The swap-hands action allows support for one-handed keyboards without requiring a separate layer. Set `ONEHAND_ENABLE` in the Makefile and define a `hand_swap_config` entry in your keymap. Now whenever the `ACTION_SWAP_HANDS` command key is pressed the keyboard is mirrored. For instance, to type "Hello, World" on QWERTY you would type `^Ge^s^s^w^c W^wr^sd`
 517
 518 ### 2.6.1 Configuration
 519 The configuration table is a simple 2-dimensional array to map from column/row to new column/row. Example `hand_swap_config` for Planck:
 520
 521 ```
 522 const keypos_t hand_swap_config[MATRIX_ROWS][MATRIX_COLS] = {
 523   {{11, 0}, {10, 0}, {9, 0}, {8, 0}, {7, 0}, {6, 0}, {5, 0}, {4, 0}, {3, 0}, {2, 0}, {1, 0}, {0, 0}},
 524   {{11, 1}, {10, 1}, {9, 1}, {8, 1}, {7, 1}, {6, 1}, {5, 1}, {4, 1}, {3, 1}, {2, 1}, {1, 1}, {0, 1}},
 525   {{11, 2}, {10, 2}, {9, 2}, {8, 2}, {7, 2}, {6, 2}, {5, 2}, {4, 2}, {3, 2}, {2, 2}, {1, 2}, {0, 2}},
 526   {{11, 3}, {10, 3}, {9, 3}, {8, 3}, {7, 3}, {6, 3}, {5, 3}, {4, 3}, {3, 3}, {2, 3}, {1, 3}, {0, 3}},
 527 };
 528 ```
 529
 530 Note that the array indices are reversed same as the matrix and the values are of type `keypos_t` which is `{col, row}` and all values are zero-based. In the example above, `hand_swap_config[2][4]` (third row, fifth column) would return {7, 2} (third row, eighth column).
 531
 532 ### 2.6.2 Advanced Swap Commands
 533 - **`ACTION_SWAP_HANDS()`** Swaps hands when pressed, returns to normal when released (momentary).
 534 - **`ACTION_SWAP_HANDS_TOGGLE()`** Toggles swap on and off with every keypress.
 535 - **`ACTION_SWAP_HANDS_TAP_TOGGLE()`** Toggles with a tap; momentary when held.
 536 - **`ACTION_SWAP_HANDS_TAP_KEY(key)`** Sends `key` with a tap; momentary swap when held.
 537 - **`ACTION_SWAP_HANDS_ON_OFF()`** Alias for `ACTION_SWAP_HANDS()`
 538 - **`ACTION_SWAP_HANDS_OFF_ON()`** Momentarily turns off swap.
 539 - **`ACTION_SWAP_HANDS_ON()`** Turns on swapping and leaves it on.
 540 - **`ACTION_SWAP_HANDS_OFF()`** Turn off swapping and leaves it off. Good for returning to a known state.
 541
 542
 543
 544 ## 3. Layer switching Example
 545 There are some ways to switch layer with 'Layer' actions.
 546
 547 ### 3.1 Momentary switching
 548 Momentary switching changes layer only while holding Fn key.
 549
 550 This action makes 'Layer 1' active(valid) on key press event and inactive on release event. Namely you can overlay a layer on lower layers or default layer temporarily with this action.
 551
 552     ACTION_LAYER_MOMENTARY(1)
 553
 554
 555 Note that after switching on press the actions on destination layer(Layer 1) are performed.
 556 ***Thus you shall need to place an action to go back on destination layer***, or you will be stuck in destination layer without way to get back. Usually you need to place same action or 'KC_TRNS` on destination layer to get back.
 557
 558
 559 ### 3.2 Toggle switching
 560 Toggle switching performed after releasing a key. With this action you can keep staying on the destination layer until you type the key again to return.
 561
 562 This performs toggle switching action of 'Layer 2'.
 563
 564     ACTION_LAYER_TOGGLE(2)
 565
 566
 567
 568 ### 3.3 Momentary switching with Tap key
 569 These actions switch a layer only while holding a key but register the key on tap. **Tap** means to press and release a key quickly.
 570
 571     ACTION_LAYER_TAP_KEY(2, KC_SCLN)
 572
 573 With this you can place a layer switching action on normal key like ';' without losing its original key register function. This action allows you to have layer switching action without necessity of a dedicated key. It means you can have it even on home row of keyboard.
 574
 575
 576
 577 ### 3.4 Momentary switching with Tap Toggle
 578 This switches layer only while holding a key but toggle layer with several taps. **Tap** means to press and release key quickly.
 579
 580     ACTION_LAYER_TAP_TOGGLE(1)
 581
 582 Number of taps can be configured with `TAPPING_TOGGLE` in `config.h`, `5` by default.
 583
 584
 585
 586 ### 3.5 Momentary switching with Modifiers
 587 This registers modifier key(s) simultaneously with layer switching.
 588
 589     ACTION_LAYER_MODS(2, MOD_LSFT | MOD_LALT)
 590
 591
 592
 593 ## 4. Tapping
 594 Tapping is to press and release a key quickly. Tapping speed is determined with setting of `TAPPING_TERM`, which can be defined in `config.h`, 200ms by default.
 595
 596 ### 4.1 Tap Key
 597 This is a feature to assign normal key action and modifier including layer switching to just same one physical key. This is a kind of [Dual role key][dual_role]. It works as modifier when holding the key but registers normal key when tapping.
 598
 599 Modifier with tap key:
 600
 601     ACTION_MODS_TAP_KEY(MOD_RSFT, KC_GRV)
 602
 603 Layer switching with tap key:
 604
 605     ACTION_LAYER_TAP_KEY(2, KC_SCLN)
 606
 607 [dual_role]: http://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys
 608
 609 When user hold a key after tap, it repeat the tapped key rather to hold a modifier key.
 610 If you prefer to hold a modifier instead, define `TAPPING_FORCE_HOLD` in `config.h`.
 611 See https://github.com/qmk/qmk_firmware/issues/889 for the detail.
 612
 613 ### 4.2 Tap Toggle
 614 This is a feature to assign both toggle layer and momentary switch layer action to just same one physical key. It works as momentary layer switch when holding a key but toggle switch with several taps.
 615
 616     ACTION_LAYER_TAP_TOGGLE(1)
 617
 618
 619 ### 4.3 Oneshot Modifier
 620 This runs onetime effects which modify only on just one following key. It works as normal modifier key when holding down while oneshot modifier when tapping. The behavior of oneshot modifiers is similar to the [sticky keys](https://en.wikipedia.org/wiki/StickyKeys) functionality found in most operating systems.
 621
 622     ACTION_MODS_ONESHOT(MOD_LSFT)
 623
 624 Oneshot layer key:
 625
 626     ACTION_LAYER_ONESHOT(MY_LAYER)
 627
 628 Say you want to type 'The', you have to push and hold Shift key before type 't' then release it before type 'h' and 'e', otherwise you'll get 'THe' or 'the' unintentionally. With Oneshot Modifier you can tap Shift then type 't', 'h' and 'e' normally, you don't need to holding Shift key properly here. This mean you can release Shift before 't' is pressed down.
 629
 630 Oneshot effect is cancel unless following key is pressed down within `ONESHOT_TIMEOUT` of `config.h`. No timeout when it is `0` or not defined.
 631
 632 Most implementations of sticky keys allow you to lock a modifier by double tapping the modifier. The layer then remains locked untill the modifier is tapped again. To enable this behaviour for oneshot modifiers set `ONESHOT_TAP_TOGGLE` to the number taps required. The feature is disabled if `ONESHOT_TAP_TOGGLE<2` or not defined.
 633
 634
 635 ### 4.4 Tap Toggle Mods
 636 Similar to layer tap toggle, this works as a momentary modifier when holding, but toggles on with several taps. A single tap will 'unstick' the modifier again.
 637
 638     ACTION_MODS_TAP_TOGGLE(MOD_LSFT)
 639
 640
 641
 642
 643 ## 5. Legacy Keymap
 644 In QMK, `tmk_core/common/keymap.c` is missing and its replacement `quantum/keymap_common.c` lacks Legacy Keymap support.
 645
 646 Legacy Keymap uses two arrays `fn_layer[]` and `fn_keycode[]` to define Fn key. The index of arrays corresponds with postfix number of `Fn` key. Array `fn_layer[]` indicates destination layer to switch and `fn_keycode[]` has keycodes to send when tapping `Fn` key.
 647
 648 In the following legacy keymap setting example, `Fn0`, `Fn1` and `Fn2` switch layer to 1, 2 and 2 respectively. `Fn2` registers `Space` key when tapping while `Fn0` and `Fn1` doesn't send any key.
 649
 650     static const uint8_t PROGMEM fn_layer[] = {
 651         1,              // Fn0
 652         2,              // Fn1
 653         2,              // Fn2
 654     };
 655
 656     static const uint8_t PROGMEM fn_keycode[] = {
 657         KC_NO,          // Fn0
 658         KC_NO,          // Fn1
 659         KC_SPC,         // Fn2
 660     };
 661
 662 Under QMK, these can be realized using action code ACTION_LAYER_TAP_KEY(1, KC_NO), ACTION_LAYER_TAP_KEY(2, KC_NO), and ACTION_LAYER_TAP_KEY(2, KC_SPC) in the `keymaps` directly.
 663
 664 ## 6. Terminology
 665 ***TBD***
 666 ### keymap
 667 is comprised of multiple layers.
 668 ### layer
 669 is matrix of keycodes.
 670 ### key
 671 is physical button on keyboard or logical switch on software.
 672 ### keycode
 673 is codes used on firmware.
 674 ### action
 675 is a function assigned on a key.
 676 ### layer transparency
 677 Using transparent keycode one layer can refer key definition on other lower layer.
 678 ### layer precedence
 679 Top layer has higher precedence than lower layers.
 680 ### tapping
 681 is to press and release a key quickly.
 682 ### Fn key
 683 is key which executes a special action like layer switching, mouse key, macro or etc.
 684 ### dual role key
 685 <http://en.wikipedia.org/wiki/Modifier_key#Dual-role_keys>