doc/keymap.md

   1 Keymap framework - how to define your keymap
   2 ============================================
   3 ***NOTE: This is not final version, may be inconsistent with source code and changed occasionally for a while.***
   4
   5 ## Keymap
   6 **Keymap** is comprised of multiple layers of key layout, you can define **16** layers at most.
   7 **Layer** is an array of **keycodes** to define **actions** on each physical keys.
   8 respective layers can be validated simultaneously. Layers are indexed with 0 to 15 and higher layer has precedence.
   9
  10     Keymap with 16 Layers               Layer: array of Keycodes
  11     ---------------------               ------------------------
  12           stack of layers               content of layer
  13            ____________ precedence               _______________________
  14           /           / | high                  / ESC / F1  / F2  / F3   ....
  15       15 /___________// |                      /-----/-----/-----/-----
  16       14 /___________// |                     / TAB /     /     /      ....
  17       13 /___________/_ |                    /-----/-----/-----/-----
  18        :  / : : : : : / |                   /LCtrl/     /     /      ....
  19        3 /___________// |               :  /  :     :     :     :
  20        2 /___________// |               2 `--------------------------
  21        1 /___________// |               1 `--------------------------
  22        0 /___________/  V low           0 `--------------------------
  23
  24
  25 ### Keymap status
  26 Keymap has its state in two parameters:
  27 **`default_layer`** indicates a base keymap layer(0-15) 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.
  28
  29 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`.
  30 To change `default_layer` will be useful when you want to switch key layout completely, say you use Colmak instead of Qwerty.
  31
  32     Initial state of Keymap         Change base layout
  33     -----------------------         ------------------
  34
  35       15                              15
  36       14                              14
  37       13                              13
  38        :                               :
  39        3                               3   ____________
  40        2   ____________                2  /           /
  41        1  /           /             ,->1 /___________/
  42     ,->0 /___________/              |  0
  43     |                               |
  44     `--- default_layer = 0          `--- default_layer = 1
  45          keymap_stat   = 0x0001          keymap_stat   = 0x0002
  46
  47
  48 On the other hand, you shall change `keymap_state` to overlay base layer with some layers for feature such as navigation keys, function key(F1-F12), media keys or special actions.
  49
  50     Overlay feature layer
  51     ---------------------      bit|status
  52            ____________        ---+------
  53       15  /           /        15 |   0
  54       14 /___________// -----> 14 |   1
  55       13 /___________/  -----> 13 |   1
  56        :                        : |
  57        3   ____________         3 |   0
  58        2  /           /         2 |   0
  59     ,->1 /___________/  ----->  1 |   1
  60     |  0                        0 |   0
  61     |                                 |
  62     `--- default_layer = 1            |
  63          keymap_stat   = 0x6002 <-----'
  64
  65
  66 ### Layer Precedence and Transparency
  67 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.
  68
  69 You can place `KC_TRNS` on overlay layer changes just part of layout to fall back on lower or base layer.
  70 Key with `KC_TRANS` doen't has its own keycode and refers to its lower layers for keycode, instead.
  71 See layer 1 or 2 below for example.
  72
  73
  74 ### Keymap Example
  75 Keymap is **`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.
  76
  77 This is a keymap example for [HHKB](http://en.wikipedia.org/wiki/Happy_Hacking_Keyboard) keyboard.
  78 This example has three layers, 'Qwerty' as base layer, 'Cursor' and  'Mousekey'.
  79 In this example,
  80
  81  `Fn0` is a **momentary layer switching** key, you can use keys on Cursor layer while holding the key.
  82
  83  `Fn1` is a momentary layer switching key with tapping feature, you can get semicolon **';'** with taping the key and switch layers while holding the key. The word **'tap'** or **'tapping'** mean to press and release a key quickly.
  84
  85  `Fn2` is a **toggle layer switch** key, you can stay switched layer after releasing the key unlike momentary switching.
  86
  87 You can find other keymap definitions in file `keymap.c` located on project directories.
  88
  89     static const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
  90         /* 0: Qwerty
  91          * ,-----------------------------------------------------------.
  92          * |Esc|  1|  2|  3|  4|  5|  6|  7|  8|  9|  0|  -|  =|  \|  `|
  93          * |-----------------------------------------------------------|
  94          * |Tab  |  Q|  W|  E|  R|  T|  Y|  U|  I|  O|  P|  [|  ]|Backs|
  95          * |-----------------------------------------------------------|
  96          * |Contro|  A|  S|  D|  F|  G|  H|  J|  K|  L|Fn1|  '|Enter   |
  97          * |-----------------------------------------------------------|
  98          * |Shift   |  Z|  X|  C|  V|  B|  N|  M|  ,|  .|  /|Shift |Fn0|
  99          * `-----------------------------------------------------------'
 100          *       |Gui|Alt  |Space                  |Alt  |Fn2|
 101          *       `-------------------------------------------'
 102          */
 103         KEYMAP(ESC, 1,   2,   3,   4,   5,   6,   7,   8,   9,   0,   MINS,EQL, BSLS,GRV, \
 104                TAB, Q,   W,   E,   R,   T,   Y,   U,   I,   O,   P,   LBRC,RBRC,BSPC, \
 105                LCTL,A,   S,   D,   F,   G,   H,   J,   K,   L,   FN1, QUOT,ENT, \
 106                LSFT,Z,   X,   C,   V,   B,   N,   M,   COMM,DOT, SLSH,RSFT,FN0, \
 107                     LGUI,LALT,          SPC,                RALT,FN2),
 108         /* 1: Cursor(HHKB mode)
 109          * ,-----------------------------------------------------------.
 110          * |Pwr| F1| F2| F3| F4| F5| F6| F7| F8| F9|F10|F11|F12|Ins|Del|
 111          * |-----------------------------------------------------------|
 112          * |Caps |   |   |   |   |   |   |   |Psc|Slk|Pus|Up |   |Backs|
 113          * |-----------------------------------------------------------|
 114          * |Contro|VoD|VoU|Mut|   |   |  *|  /|Hom|PgU|Lef|Rig|Enter   |
 115          * |-----------------------------------------------------------|
 116          * |Shift   |   |   |   |   |   |  +|  -|End|PgD|Dow|Shift |   |
 117          * `-----------------------------------------------------------'
 118          *      |Gui |Alt  |Space                  |Alt  |Gui|
 119          *      `--------------------------------------------'
 120          */
 121         KEYMAP(PWR, F1,  F2,  F3,  F4,  F5,  F6,  F7,  F8,  F9,  F10, F11, F12, INS, DEL, \
 122                CAPS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,TRNS,PSCR,SLCK,PAUS,UP,  TRNS,BSPC, \
 123                LCTL,VOLD,VOLU,MUTE,TRNS,TRNS,PAST,PSLS,HOME,PGUP,LEFT,RGHT,ENT, \
 124                LSFT,TRNS,TRNS,TRNS,TRNS,TRNS,PPLS,PMNS,END, PGDN,DOWN,RSFT,TRNS, \
 125                     LGUI,LALT,          SPC,                RALT,RGUI),
 126         /* 2: Mousekey
 127          * ,-----------------------------------------------------------.
 128          * |Esc| F1| F2| F3| F4| F5| F6| F7| F8| F9|F10|F11|F12|Ins|Del|
 129          * |-----------------------------------------------------------|
 130          * |Tab  |   |   |   |   |   |MwL|MwD|MwU|MwR|   |   |   |Backs|
 131          * |-----------------------------------------------------------|
 132          * |Contro|   |   |   |   |   |McL|McD|McU|McR|   |   |Return  |
 133          * |-----------------------------------------------------------|
 134          * |Shift   |   |   |   |   |Mb3|Mb2|Mb1|Mb4|Mb5|   |Shift |   |
 135          * `-----------------------------------------------------------'
 136          *      |Gui |Alt  |Mb1                    |Alt  |   |
 137          *      `--------------------------------------------'
 138          * Mc: Mouse Cursor / Mb: Mouse Button / Mw: Mouse Wheel
 139          */
 140         KEYMAP(ESC, F1,  F2,  F3,  F4,  F5,  F6,  F7,  F8,  F9,  F10, F11, F12, INS, DEL, \
 141                TAB, TRNS,TRNS,TRNS,TRNS,TRNS,WH_L,WH_D,WH_U,WH_R,TRNS,TRNS,TRNS,BSPC, \
 142                LCTL,TRNS,ACL0,ACL1,ACL2,TRNS,MS_L,MS_D,MS_U,MS_R,TRNS,QUOT,ENT, \
 143                LSFT,TRNS,TRNS,TRNS,TRNS,BTN3,BTN2,BTN1,BTN4,BTN5,SLSH,RSFT,TRNS, \
 144                     LGUI,LALT,          BTN1,               RALT,TRNS),
 145     };
 146
 147     static const uint16_t PROGMEM fn_actions[] = {
 148         ACTION_KEYMAP(1),                            // FN0
 149         ACTION_KEYMAP_TAP_KEY(2, KC_SCLN),           // FN1
 150         ACTION_KEYMAP_TOGGLE(2),                     // FN2
 151     };
 152
 153
 154
 155
 156 ## 1. Keycode
 157 See [`common/keycode.h`](common/keycode.h) or keycode table below. Keycode is internal **8bit code** to inidicate action performed on key in keymap. 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 contorl keys, System control keys and Mousekeys.
 158
 159  ***In `KEYMAP()` macro you should omit prefix part `KC_` of keycode to keep keymap compact.*** For example, just use `A` instead you place `KC_A` in `KEYMAP()`. Some keycodes has 4-letter **short name** in addition to descriptive name, you'll prefer short one in `KEYMAP()`.
 160
 161 ### 1.0 Other key
 162 - `KC_NO` for no aciton
 163 - `KC_TRNS` for layer transparency (See above)
 164
 165 ### 1.1 Normal key
 166 - `KC_A` to `KC_Z`, `KC_1` to `KC_0` for alpha numeric key
 167 - `KC_MINS`, `KC_EQL`, `KC_GRV`, `KC_RBRC`, `KC_LBRC`, `KC_COMM`, `KC_DOT`, `KC_BSLS`, `KC_SLSH`, `KC_SCLN`, `KC_QUOT`
 168 - `KC_ESC`, `KC_TAB`, `KC_SPC`, `KC_BSPC`, `KC_ENT`, `KC_DEL`, `KC_INS`
 169 - `KC_UP`, `KC_DOWN`, `KC_RGHT`, `KC_LEFT`, `KC_PGUP`, `KC_PGDN`, `KC_HOME`, `KC_END`
 170 - `KC_CAPS`, `KC_NLCK`, `KC_SLCK`, `KC_PSCR`, `KC_PAUS`, `KC_APP`, `KC_F1` to `KC_F24`
 171 - `KC_P1` to `KC_P0`, `KC_PDOT`, `KC_PCMM`, `KC_PSLS`, `KC_PAST`, `KC_PMNS`, `KC_PPLS`, `KC_PEQL`, `KC_PENT` for keypad.
 172
 173 ### 1.2 Modifier
 174 There are 8 modifiers which has discrimination between left and right.
 175
 176 - `KC_LCTL` and `KC_RCTL` for Control
 177 - `KC_LSFT` and `KC_RSFT` for Shift
 178 - `KC_LALT` and `KC_RALT` for Alt
 179 - `KC_LGUI` and `KC_RGUI` for Windows key or Command key in Mac
 180
 181 ### 1.3 Mousekey
 182 - `KC_MS_U`, `KC_MS_D`, `KC_MS_L`, `KC_MS_R` for mouse cursor
 183 - `KC_WH_U`, `KC_WH_D`, `KC_WH_L`, `KC_WH_R` for mouse wheel
 184 - `KC_BTN1`, `KC_BTN2`, `KC_BTN3`, `KC_BTN4`, `KC_BTN5` for mouse buttons
 185
 186 ### 1.4 System & Media key
 187 - `KC_PWR`, `KC_SLEP`, `KC_WAKE` for Power, Sleep, Wake
 188 - `KC_MUTE`, `KC_VOLU`, `KC_VOLD` for audio volume control
 189 - `KC_MNXT`, `KC_MPRV`, `KC_MSTP`, `KC_MPLY`, `KC_MSEL` for media control
 190 - `KC_MAIL`, `KC_CALC`, `KC_MYCM` for application launch
 191 - `KC_WSCH`, `KC_WHOM`, `KC_WBAK`, `KC_WFWD`, `KC_WSTP`, `KC_WREF`, `KC_WFAV` for web browser operation
 192
 193 ### 1.5 Fn key
 194 `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` keyocde indicates the action defined in first element of the array. ***32 `Fn` keys can be defined at most.***
 195
 196 ### 1.6 Keycode Table
 197  See keycode table in [`doc/keycode.txt`](doc/keycode.txt) for description of keycodes.
 198
 199  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.
 200 [HID_usage]: http://www.usb.org/developers/devclass_docs/Hut1_11.pdf
 201
 202
 203
 204 ## 2. Action
 205 See [`common/action.h`](common/action.h). Action is a **16bit code** and defines function to perform on events of a key like press, release, holding and tapping.
 206
 207 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 against using jsut keycodes. To avoid this waste 8bit keycodes are used in `KEYMAP` instead of action codes.
 208
 209 ***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[]`.***
 210
 211 Usually action codes are needed only when you want to use layer switching, or
 212
 213 ### 2.1 Key action
 214 This is a simple action that registers scancodes(HID usage in fact) to host on press event of key and unregister on release.
 215
 216 #### 2.1.1 Normal key and Modifier
 217 This action usually won't be used expressly because you can use keycodes in `KEYMAP()` instead.
 218 You can define `Key` action on *'A'* key and *'left shift'* modifier with:
 219
 220     ACTION_KEY(KC_A)
 221     ACTION_KEY(KC_LSHIFT)
 222
 223 #### 2.1.2 Key with modifiers
 224 This action is comprised of strokes of modifiers and a key. `Macro` action is needed if you want more complex key strokes.
 225 Say you want to assign a key to `Shift + 1` to get charactor *'!'* or `Alt + Tab` to switch application windows.
 226
 227     ACTION_LMOD_KEY(KC_LSHIFT, KC_1)
 228     ACTION_LMOD_KEY(KC_LALT, KC_TAB)
 229
 230 Or `Alt,Shift + Tab` can be defined. `ACTION_LMODS_KEY()` requires **4-bit modifier state** and a **keycode** as arguments. See `keycode.h` for `MOD_BIT()` macro.
 231
 232     ACTION_LMODS_KEY((MOD_BIT(KC_LALT) | MOD_BIT(KC_LSHIFT)), KC_TAB)
 233
 234
 235
 236 ### 2.2 Layer Actions
 237
 238 #### 2.2.0 Default Layer
 239 `default_layer` is layer which always is on and refered to when actions is not defined on other layers.
 240
 241 ##### Return to Default Layer
 242 Turns on `default layer` only with clearing other all layers.
 243
 244     ACTION_DEFAULT_LAYER
 245
 246 ##### Set Default Layer
 247 Sets 'default layer' to layer and turn it on without clear any other layers.
 248
 249     ACTION_DEFAULT_LAYER_SET(layer)
 250
 251 This does it on { press | release | both }.
 252
 253     ACTION_DEFAULT_LAYER_SET(layer, on)
 254
 255
 256 #### 2.2.1 Keymap
 257 These actions operate given layer argument which ranges from 0 to 15.
 258
 259 ##### Switch to layer
 260 Turns on layer momentary while holding, in other words turn on when key is pressed and off when released.
 261
 262     ACTION_KEYMAP_MOMENTARY(layer)
 263
 264
 265 ##### Toggle layer
 266 Turns on layer on first type and turns off on next.
 267
 268     ACTION_KEYMAP_TOGGLE(layer)
 269
 270
 271 ##### Switch to layer with tap key
 272 Turns on layer momentary while holding but registers key on tap.
 273
 274     ACTION_KEYMAP_TAP_KEY(layer, key)
 275
 276
 277 ##### Switch to layer with tap toggle
 278 Turns on layer momentary while holding but toggles it with serial taps.
 279
 280     ACTION_KEYMAP_TAP_TOGGLE(layer)
 281
 282
 283 ##### Invert layer
 284 Inverts current layer state. If the layer is on it becomes off with this action.
 285
 286     ACTION_KEYMAP_INV(layer, on)
 287
 288
 289 ##### Turn On layer
 290 Turns on layer state.
 291
 292     ACTION_KEYMAP_ON(layer, on)
 293
 294 Turns on layer state on press and turn off on release. This is identical to **'Switch to layer'** action.
 295
 296     ACTION_KEYMAP_ON_OFF(layer)
 297
 298
 299 ##### Turn Off layer
 300 Turns off layer state.
 301
 302     ACTION_KEYMAP_OFF(layer, on)
 303
 304
 305 ##### Set layer
 306 Turn on layer only.
 307 `keymap_stat = (1<<layer) [layer: 0-15]`
 308
 309     ACTION_KEYMAP_SET(layer, on)
 310
 311 Turns on layer only and clear all layer on release..
 312
 313     ACTION_KEYMAP_SET_CLEAR(layer)
 314
 315
 316 #### 2.2.2 Overlay
 317 ***TBD***
 318
 319 In addition to actions of `Keymap` above these actions are also available.
 320
 321 ##### Invert 4bit layer states
 322 Invert 4bits out of 16bits of overlay status on both press and release.
 323 `overlay_stat = (overlay_stat ^ bits<<(shift*4)) [bits: 0-15, shift: 0-3]`
 324
 325     ACTION_OVERLAY_INV4(bits, shift)
 326
 327
 328 ### 2.3 Macro action
 329 ***TBD***
 330
 331 `Macro` action indicates complex key strokes.
 332
 333     MACRO( MD(LSHIFT), D(D), END )
 334     MACRO( U(D), MU(LSHIFT), END )
 335     MACRO( I(255), T(H), T(E), T(L), T(L), W(255), T(O), END )
 336
 337 #### 2.3.1 Normal mode
 338 - **I()**   change interavl of stroke.
 339 - **D()**   press key
 340 - **U()**   release key
 341 - **T()**   type key(press and release)
 342 - **W()**   wait
 343 - **MD()**  modifier down
 344 - **MU()**  modifier up
 345 - **END**   end mark
 346
 347 #### 2.3.2 Extended mode
 348
 349 ***TODO: sample impl***
 350 See `keyboard/hhkb/keymap.c` for sample.
 351
 352
 353 ### 2.4 Function action
 354 ***TBD***
 355
 356 There are two type of action, normal `Function` and tappable `Function`.
 357 These actions call user defined function with `id`, `opt`, and key event information as arguments.
 358
 359 #### 2.4.1 Function
 360 To define normal `Function` action in keymap use this.
 361
 362     ACTION_FUNCTION(id, opt)
 363
 364 #### 2.4.2 Function with tap
 365 To define tappable `Function` action in keymap use this.
 366
 367     ACTION_FUNCTION_TAP(id, opt)
 368
 369 #### 2.4.3 Implement user function
 370 `Function` actions can be defined freely with C by user in callback function:
 371
 372     void keymap_call_function(keyrecord_t *event, uint8_t id, uint8_t opt)
 373
 374 This C function is called every time key is operated, argument `id` selects action to be performed and `opt` can be used for option. Functon `id` can be 0-255 and `opt` can be 0-15.
 375
 376  `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.
 377
 378     typedef struct {
 379         keyevent_t  event;
 380         uint8_t     tap_count;
 381     } keyrecord_t;
 382
 383     typedef struct {
 384         key_t    key;
 385         bool     pressed;
 386         uint16_t time;
 387     } keyevent_t;
 388
 389     typedef struct {
 390         uint8_t col;
 391         uint8_t row;
 392     } key_t;
 393
 394 ***TODO: sample impl***
 395 See `keyboard/hhkb/keymap.c` for sample.
 396
 397
 398
 399
 400
 401 ## 3. Layer
 402  Layer is key-action map to assign action to every physical key. You can define multiple layers in keymap and make layers active out of keymap during operation at will.
 403
 404  First layer is indexed by `0` which usually become `default layer` and active in initial state.
 405
 406 You can define **16 layers** at most in each keymaps and overlays.
 407
 408             ____________
 409            /           /
 410           /           //
 411       15 /___________///
 412       14 /___________//_
 413       13 /___________/ /
 414           /: : : : :  //
 415        3 /___________///
 416        2 /___________///
 417        1 /___________//
 418     .->0 /___________/
 419     `--- default_layer = 0
 420
 421  you can define a layer with placing keycode symbols separated with `comma` in `KEYMAP`, which is formed with resemblance to physical keyboard layout so as you can easily put keycode on place you want to map. ***You can define most of keys with just using keycodes*** except for `Fn` key serving special actions.
 422
 423 ### 3.0 Transparency
 424 With KC_TRNS you can define transparent key which itself doesn't have action but refer to lower valid layer. Transparent key is useful when you want to change part of layout not over all.
 425
 426
 427
 428 ## 4. Layer switching
 429 You can have some ways to switch layer with these actions.
 430 There are two kind of layer switch action `Layer Set` and `Layer Bit` and two type of switching behaviour **Momentary** and **Toggle**.
 431
 432 ### 4.1 Momentary switching
 433 Momentary switching changes layer only while holding Fn key.
 434
 435 #### 4.1.1 Momentary Set
 436 This action makes `Layer 1` active on key press event and inactive on release event..
 437
 438     ACTION_KEYMAP_MOMENTARY(1)
 439
 440
 441 It switches to destination layer immediately when key is pressed, after that actions on keymap of destination layer is perfomed. ***Thus you shall need to place action to come back on destination layer***, or you will be stuck in destination layer without way to get back. To get back to `default layer` you can use this action.
 442
 443     ACTION_LAYER_DEFAULT
 444
 445 #### 4.1.2 Momentary Bit
 446 This `Layer Bit` action performs XOR `1` with `current layer` on both press and release event. If you are on `Layer 0` now next layer to switch will be `Layer 1`. To come back to previous layer you need to place same action on destination layer.
 447
 448     ACTION_LAYER_BIT(1)
 449
 450 ### 4.2 Toggle switching
 451 Toggle switching changes layer after press then release. You keep being on the layer until you press key to return.
 452
 453 #### 4.2.1 Toggle Set
 454 This `Layer Set Toggle` action is to set `Layer 1` to `current layer` on release and do none on press.
 455
 456     ACTION_LAYER_SET_TOGGLE(1)
 457
 458 To get back to `default layer` you can use this action.
 459
 460     ACTION_LAYER_DEFAULT
 461
 462 #### 4.2.2 Toggle Bit
 463 This `Layer Bit Toggle` action is to XOR `1` with `current layer` on release and do none on press. If you are on `Layer 2` you'll switch to `Layer 3` on press. To come back to previous layer you need to place same action on destination layer.
 464
 465     ACTION_LAYER_BIT_TOGGLE(1)
 466
 467
 468 ### 4.3 Momentary switching with Tap key
 469 These actions switch to layer only while holding `Fn` key and register key on tap. **Tap** means to press and release key quickly.
 470
 471     ACTION_LAYER_SET_TAP_KEY(2, KC_SCLN)
 472     ACTION_LAYER_SET_BIT_KEY(2, KC_SCLN)
 473
 474 With these you can place layer switching function on normal alphabet key like `;` without losing its original register function.
 475
 476 ### 4.4 Momentary switching with Tap Toggle
 477 This changes layer only while holding `Fn` key and toggle layer after several taps. **Tap** means to press and release key quickly.
 478
 479     ACTION_LAYER_SET_TAP_TOGGLE(layer)
 480     ACTION_LAYER_BIT_TAP_TOGGLE(layer)
 481
 482 Number of taps can be defined with `TAPPING_TOGGLE` in `config.h`, `5` by default.
 483
 484
 485 ## Tapping
 486 ### Tap Key
 487 ### One Shot Modifier
 488
 489
 490 ## Legacy Keymap
 491 This was used in prior version and still works due to legacy support code in `common/keymap.c`. Legacy keymap doesn't support many of features that new keymap offers.
 492
 493 In comparison with new keymap how to define Fn key is different. It uses two arrays `fn_layer[]` and `fn_keycode[]`. 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.
 494
 495 In following setting example, `Fn0`, `Fn1` and `Fn2` switch layer to 1, 2 and 2 respectively. `Fn2` registers `Space` key when tap while `Fn0` and `Fn1` doesn't send any key.
 496
 497     static const uint8_t PROGMEM fn_layer[] = {
 498         1,              // Fn0
 499         2,              // Fn1
 500         2,              // Fn2
 501     };
 502
 503     static const uint8_t PROGMEM fn_keycode[] = {
 504         KC_NO,          // Fn0
 505         KC_NO,          // Fn1
 506         KC_SPC,         // Fn2
 507     };
 508
 509
 510 ## Terminology
 511 - keymap
 512 - layer
 513 - layout
 514 - key
 515 - keycode
 516 - scancode
 517 - action
 518 - layer transparency
 519 - layer precedence
 520 - register
 521 - tap
 522 - Fn key