Updated Keymap (markdown)
This commit is contained in:
Osamu Aoki
parent
5fb058eb34
commit
97d6184ed0
76
Keymap.md
76
Keymap.md
|
|
@ -2,6 +2,81 @@
|
|||
|
||||
QMK keymaps are defined inside a C source file. The data structure is an array of arrays. The outer array is a list of layer arrays while the inner layer array is a list of keys. Most keyboards define a `KEYMAP()` macro to help you create this array of arrays.
|
||||
|
||||
|
||||
## Keymap and layers
|
||||
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.
|
||||
|
||||
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_action_code[row][column]
|
||||
____________ precedence _______________________
|
||||
/ / | high / ESC / F1 / F2 / F3 ....
|
||||
31 /___________// | /-----/-----/-----/-----
|
||||
30 /___________// | / TAB / Q / W / E ....
|
||||
29 /___________/ | /-----/-----/-----/-----
|
||||
: _:_:_:_:_:__ | : /LCtrl/ A / S / D ....
|
||||
: / : : : : : / | : / : : : :
|
||||
2 /___________// | 2 `--------------------------
|
||||
1 /___________// | 1 `--------------------------
|
||||
0 /___________/ V low 0 `--------------------------
|
||||
|
||||
|
||||
Sometimes, the action code stored in keymap may be referred as keycode in some documents due to the TMK history.
|
||||
|
||||
### Keymap layer status
|
||||
Keymap layer has its state in two 32 bit parameters:
|
||||
|
||||
* **`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.
|
||||
|
||||
Initial state of Keymap Change base layout
|
||||
----------------------- ------------------
|
||||
|
||||
31 31
|
||||
30 30
|
||||
29 29
|
||||
: :
|
||||
: : ____________
|
||||
2 ____________ 2 / /
|
||||
1 / / ,->1 /___________/
|
||||
,->0 /___________/ | 0
|
||||
| |
|
||||
`--- default_layer = 0 `--- default_layer = 1
|
||||
layer_state = 0x00000001 layer_state = 0x00000002
|
||||
|
||||
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.
|
||||
|
||||
Overlay feature layer
|
||||
--------------------- bit|status
|
||||
____________ ---+------
|
||||
31 / / 31 | 0
|
||||
30 /___________// -----> 30 | 1
|
||||
29 /___________/ -----> 29 | 1
|
||||
: : | :
|
||||
: ____________ : | :
|
||||
2 / / 2 | 0
|
||||
,->1 /___________/ -----> 1 | 1
|
||||
| 0 0 | 0
|
||||
| +
|
||||
`--- default_layer = 1 |
|
||||
layer_state = 0x60000002 <-'
|
||||
|
||||
|
||||
|
||||
### 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_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.
|
||||
|
||||
## Anatomy Of A `keymap.c`
|
||||
|
||||
For this example we will walk through the [default Clueboard keymap](https://github.com/qmk/qmk_firmware/blob/master/keyboards/clueboard/keymaps/default/keymap.c). You'll find it helpful to open that file in another browser window so you can look at everything in context.
|
||||
|
|
@ -140,7 +215,6 @@ To actually handle the keypress event we define an `action_function()`. This fun
|
|||
|
||||
This should have given you a basic overview for creating your own keymap. For more details see the following resources:
|
||||
|
||||
* https://github.com/qmk/qmk_firmware/blob/master/doc/keymap.md (If you see `static const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS]`, it is still the TMK code example code.)
|
||||
* https://github.com/qmk/qmk_firmware/wiki/Keycodes
|
||||
* https://github.com/qmk/qmk_firmware/wiki/FAQ-Keymap
|
||||
* https://github.com/qmk/qmk_firmware/wiki/Keymap-examples
|
||||
|
|
|
|||
Loading…
Reference in New Issue