aboutsummaryrefslogtreecommitdiff
path: root/docs/Keymap.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/Keymap.md')
-rw-r--r--docs/Keymap.md222
1 files changed, 222 insertions, 0 deletions
diff --git a/docs/Keymap.md b/docs/Keymap.md
new file mode 100644
index 000000000..53b17f401
--- /dev/null
+++ b/docs/Keymap.md
@@ -0,0 +1,222 @@
1# Keymap Overview
2
3QMK 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.
4
5
6## Keymap and layers
7In 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.
8
9For 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**.
10
11Respective layers can be validated simultaneously. Layers are indexed with 0 to 31 and higher layer has precedence.
12
13 Keymap: 32 Layers Layer: action code matrix
14 ----------------- ---------------------
15 stack of layers array_of_action_code[row][column]
16 ____________ precedence _______________________
17 / / | high / ESC / F1 / F2 / F3 ....
18 31 /___________// | /-----/-----/-----/-----
19 30 /___________// | / TAB / Q / W / E ....
20 29 /___________/ | /-----/-----/-----/-----
21 : _:_:_:_:_:__ | : /LCtrl/ A / S / D ....
22 : / : : : : : / | : / : : : :
23 2 /___________// | 2 `--------------------------
24 1 /___________// | 1 `--------------------------
25 0 /___________/ V low 0 `--------------------------
26
27
28Sometimes, the action code stored in keymap may be referred as keycode in some documents due to the TMK history.
29
30### Keymap layer status
31Keymap layer has its state in two 32 bit parameters:
32
33* **`default_layer_state`** indicates a base keymap layer(0-31) which is always valid and to be referred.
34* **`layer_state`** () has current on/off status of the layer on its each bit.
35
36Keymap 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.
37Keymap 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`.
38To change `default_layer` will be useful when you switch key layout completely, say you want Colmak instead of Qwerty.
39
40 Initial state of Keymap Change base layout
41 ----------------------- ------------------
42
43 31 31
44 30 30
45 29 29
46 : :
47 : : ____________
48 2 ____________ 2 / /
49 1 / / ,->1 /___________/
50 ,->0 /___________/ | 0
51 | |
52 `--- default_layer = 0 `--- default_layer = 1
53 layer_state = 0x00000001 layer_state = 0x00000002
54
55On 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.
56
57 Overlay feature layer
58 --------------------- bit|status
59 ____________ ---+------
60 31 / / 31 | 0
61 30 /___________// -----> 30 | 1
62 29 /___________/ -----> 29 | 1
63 : : | :
64 : ____________ : | :
65 2 / / 2 | 0
66 ,->1 /___________/ -----> 1 | 1
67 | 0 0 | 0
68 | +
69 `--- default_layer = 1 |
70 layer_state = 0x60000002 <-'
71
72
73
74### Layer Precedence and Transparency
75Note 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.
76
77You can place `KC_TRANS` on overlay layer changes just part of layout to fall back on lower or base layer.
78Key with `KC_TRANS` (`KC_TRNS` and `_______` are the alias) doesn't has its own keycode and refers to lower valid layers for keycode, instead.
79
80## Anatomy Of A `keymap.c`
81
82For 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.
83
84There are 3 main sections of a `keymap.c` file you'll want to concern yourself with:
85
86* [The Definitions](#definitions)
87* [The Layer/Keymap Datastructure](#layers-and-keymaps)
88* [Custom Functions](#custom-functions), if any
89
90### Definitions
91
92At the top of the file you'll find this:
93
94 #include "clueboard.h"
95
96 // Helpful defines
97 #define GRAVE_MODS (MOD_BIT(KC_LSHIFT)|MOD_BIT(KC_RSHIFT)|MOD_BIT(KC_LGUI)|MOD_BIT(KC_RGUI)|MOD_BIT(KC_LALT)|MOD_BIT(KC_RALT))
98 #define _______ KC_TRNS
99
100 // Each layer gets a name for readability.
101 // The underscores don't mean anything - you can
102 // have a layer called STUFF or any other name.
103 // Layer names don't all need to be of the same
104 // length, and you can also skip them entirely
105 // and just use numbers.
106 #define _BL 0
107 #define _FL 1
108 #define _CL 2
109
110These are some handy definitions we can use when building our keymap and our custom function. The `GRAVE_MODS` definition will be used later in our custom function. The `_______` define makes it easier to see what keys a layer is overriding, while the `_BL`, `_FL`, and `_CL` defines make it easier to refer to each of our layers.
111
112### Layers and Keymaps
113
114The main part of this file is the `keymaps[]` definition. This is where you list your layers and the contents of those layers. This part of the file begins with this definition:
115
116 const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
117
118After this you'll find a list of KEYMAP() macros. A KEYMAP() is simply a list of keys to define a single layer. Typically you'll have one or more "base layers" (such as QWERTY, Dvorak, or Colemak) and then you'll layer on top of that one or more "function" layers. Due to the way layers are processed you can't overlay a "lower" layer on top of a "higher" layer.
119
120`keymaps[][MATRIX_ROWS][MATRIX_COLS]` in QMK holds the 16 bit action code (sometimes referred as the quantum keycode) in it. For the keycode representing typical keys, its high byte is 0 and its low byte is the USB HID usage ID for keyboard.
121
122> TMK from which QMK was forked uses `const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS]` instead and holds the 8 bit keycode. Some keycode values are reserved to induce execution of certain action codes via the `fn_actions[]` array.
123
124#### Base Layer
125
126Here is an example of the Clueboard's base layer:
127
128 /* Keymap _BL: Base Layer (Default Layer)
129 */
130 [_BL] = KEYMAP(
131 F(0), 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_GRV, KC_BSPC, KC_PGUP, \
132 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_BSLS, KC_PGDN, \
133 KC_CAPS, KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L, KC_SCLN, KC_QUOT, KC_NUHS, KC_ENT, \
134 KC_LSFT, KC_NUBS, KC_Z, KC_X, KC_C, KC_V, KC_B, KC_N, KC_M, KC_COMM, KC_DOT, KC_SLSH, KC_RO, KC_RSFT, KC_UP, \
135 KC_LCTL, KC_LGUI, KC_LALT, KC_MHEN, KC_SPC,KC_SPC, KC_HENK, KC_RALT, KC_RCTL, MO(_FL), KC_LEFT, KC_DOWN, KC_RGHT),
136
137Some interesting things to note about this:
138
139* From a C source point of view it's only a single array, but we have embedded whitespace to more easily visualize where each key is on the physical device.
140* Plain keyboard scancodes are prefixed with KC_, while "special" keys are not.
141* The upper left key activates custom function 0 (`F(0)`)
142* The "Fn" key is defined with `MO(_FL)`, which moves to the `_FL` layer while that key is being held down.
143
144#### Function Overlay Layer
145
146Our function layer is, from a code point of view, no different from the base layer. Conceptually, however, you will build that layer as an overlay, not a replacement. For many people this distinction does not matter, but as you build more complicated layering setups it matters more and more.
147
148 [_FL] = KEYMAP(
149 KC_GRV, 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_DEL, BL_STEP, \
150 _______, _______, _______,_______,_______,_______,_______,_______,KC_PSCR,KC_SLCK, KC_PAUS, _______, _______, _______, _______, \
151 _______, _______, MO(_CL),_______,_______,_______,_______,_______,_______,_______, _______, _______, _______, _______, \
152 _______, _______, _______,_______,_______,_______,_______,_______,_______,_______, _______, _______, _______, _______, KC_PGUP, \
153 _______, _______, _______, _______, _______,_______, _______, _______, _______, MO(_FL), KC_HOME, KC_PGDN, KC_END),
154
155Some interesting things to note:
156
157* We have used our `_______` definition to turn `KC_TRNS` into `_______`. This makes it easier to spot the keys that have changed on this layer.
158* While in this layer if you press one of the `_______` keys it will activate the key in the next lowest active layer.
159
160### Custom Functions
161
162At the bottom of the file we've defined a single custom function. This function defines a key that sends `KC_ESC` when pressed without modifiers and `KC_GRAVE` when modifiers are held. There are a couple pieces that need to be in place for this to work, and we will go over both of them.
163
164#### `fn_actions[]`
165
166We define the `fn_actions[]` array to point to custom functions. `F(N)` in a keymap will call element N of that array. For the Clueboard's that looks like this:
167
168 const uint16_t PROGMEM fn_actions[] = {
169 [0] = ACTION_FUNCTION(0), // Calls action_function()
170 };
171
172In this case we've instructed QMK to call the `ACTION_FUNCTION` callback, which we will define in the next section.
173
174> This `fn_actions[]` interface is mostly for backward compatibility. In QMK, you don't need to use `fn_actions[]`. You can directly use `ACTION_FUNCTION(N)` or any other action code value itself normally generated by the macro in `keymaps[][MATRIX_ROWS][MATRIX_COLS]`. N in `F(N)` can only be 0 to 31. Use of the action code directly in `keymaps` unlocks this limitation.
175
176#### `action_function()`
177
178To actually handle the keypress event we define an `action_function()`. This function will be called when the key is pressed, and then again when the key is released. We have to handle both situations within our code, as well as determining whether to send/release `KC_ESC` or `KC_GRAVE`.
179
180 void action_function(keyrecord_t *record, uint8_t id, uint8_t opt) {
181 static uint8_t mods_pressed;
182
183 switch (id) {
184 case 0:
185 /* Handle the combined Grave/Esc key
186 */
187 mods_pressed = get_mods()&GRAVE_MODS; // Check to see what mods are pressed
188
189 if (record->event.pressed) {
190 /* The key is being pressed.
191 */
192 if (mods_pressed) {
193 add_key(KC_GRV);
194 send_keyboard_report();
195 } else {
196 add_key(KC_ESC);
197 send_keyboard_report();
198 }
199 } else {
200 /* The key is being released.
201 */
202 if (mods_pressed) {
203 del_key(KC_GRV);
204 send_keyboard_report();
205 } else {
206 del_key(KC_ESC);
207 send_keyboard_report();
208 }
209 }
210 break;
211 }
212 }
213
214# Nitty Gritty Details
215
216This should have given you a basic overview for creating your own keymap. For more details see the following resources:
217
218* https://github.com/qmk/qmk_firmware/wiki/Keycodes
219* https://github.com/qmk/qmk_firmware/wiki/FAQ-Keymap
220* https://github.com/qmk/qmk_firmware/wiki/Keymap-examples
221
222We are actively working to improve these docs. If you have suggestions for how they could be made better please [file an issue](https://github.com/qmk/qmk_firmware/issues/new)! \ No newline at end of file
generated by cgit v1.2.3 (git 2.25.1) at 2025-07-05 22:29:14 +0000