| `keymaps` data | 3D array of `uint8_t` holding **keycode** | 3D array of `uint16_t` holding **action code** |
| `fn_actions` data | 1D array of `uint16_t` holding **action code** | 3D array of `uint16_t` holding **action code** |
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.
## 0. Keymap and layers
**Keymap** is comprised of multiple layers of key layout, you can define **32 layers** at most.
**Layer** is an array of **keycodes** to define **actions** for each physical keys.
respective layers can be validated simultaneously. Layers are indexed with 0 to 31 and higher layer has precedence.
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.
Keymap: 32 Layers Layer: Keycode matrix
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**.
Respective layers can be validated simultaneously. Layers are indexed with 0 to 31 and higher layer has precedence.
Keymap: 32 Layers Layer: action code matrix
----------------- ---------------------
stack of layers array_of_keycode[row][column]
stack of layers array_of_action_code[row][column]
____________ precedence _______________________
/ / | high / ESC / F1 / F2 / F3 ....
31 /___________// | /-----/-----/-----/-----
@ -22,11 +37,15 @@ respective layers can be validated simultaneously. Layers are indexed with 0 to
0 /___________/ V low 0 `--------------------------
Sometimes, the action code stored in keymap may be referred as keycode in some documents due to the TMK history.
### 0.1 Keymap layer status
Keymap layer has its state in two 32 bit parameters:
### 0.1 Keymap status
Keymap has its state in two parameters:
**`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.
* **`default_layer_state`** indicates a base keymap layer(0-31) which is always valid and to be referred.
* **`layer_state`** () has current on/off status of the layer on its each bit.
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.
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`.
To change `default_layer` will be useful when you switch key layout completely, say you want Colmak instead of Qwerty.
@ -67,97 +86,132 @@ On the other hand, you shall change `layer_state` to overlay base layer with som
### 0.2 Layer Precedence and Transparency
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.
You can place `KC_TRNS` on overlay layer changes just part of layout to fall back on lower or base layer.
Key with `KC_TRANS` doesn't has its own keycode and refers to lower valid layers for keycode, instead.
You can place `KC_TRANS` on overlay layer changes just part of layout to fall back on lower or base layer.
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.
See example below.
### 0.3 Keymap Example
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.
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).
This is a keymap example for [HHKB](http://en.wikipedia.org/wiki/Happy_Hacking_Keyboard) keyboard.
This example has three layers, 'Qwerty' as base layer, 'Cursor' and 'Mousekey'.
In this example,
> 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).
`Fn0` is a **momentary layer switching** key, you can use keys on Cursor layer while holding the key.
This is a keymap example for [HHKB](http://en.wikipedia.org/wiki/Happy_Hacking_Keyboard) keyboard.
This example has three layers, 'QWERTY' as base layer, 'FN' and 'MOUSE'.
`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.
In this example,
`Fn2` is a **toggle layer switch** key, you can stay switched layer after releasing the key unlike momentary switching.
`MO(layer)` is a **momentary layer switching** key.
You can find other keymap definitions in file `keymap.c` located on project directories.
See [`common/keycode.h`](../common/keycode.h) or keycode table below for the detail. Keycode is internal **8bit code** to indicate 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 control keys, System control keys and Mousekeys.
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.
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.
***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()`.
keymaps[]
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.
The `KEYMAP()` macro defines correspondence between the physical key location to the electrical key connection.
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()`.
### 1.0 Other key
- `KC_NO` for no action
@ -192,7 +246,10 @@ There are 8 modifiers which has discrimination between left and right.
- `KC_WSCH`, `KC_WHOM`, `KC_WBAK`, `KC_WFWD`, `KC_WSTP`, `KC_WREF`, `KC_WFAV` for web browser operation
### 1.5 Fn key
`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. ***32 `Fn` keys can be defined at most.***
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.
`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.***
### 1.6 Keycode Table
See keycode table in [`doc/keycode.txt`](./keycode.txt) for description of keycodes.
@ -581,15 +638,11 @@ Similar to layer tap toggle, this works as a momentary modifier when holding, bu
## 5. Legacy Keymap
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. ***It is not recommended to use Legacy Keymap for new project.***
To enable Legacy Keymap support define this macro in `config.h`.
#define USE_LEGACY_KEYMAP
In QMK, `tmk_core/common/keymap.c` is missing and its replacement `quantum/keymap_common.c` lacks Legacy Keymap support.
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.
In following 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.
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.
static const uint8_t PROGMEM fn_layer[] = {
1, // Fn0
@ -603,6 +656,7 @@ In following setting example, `Fn0`, `Fn1` and `Fn2` switch layer to 1, 2 and 2
KC_SPC, // Fn2
};
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.
Osamu Aoki
8 years ago