[jackhill/qmk/firmware.git] / docs / keymap.md

# Keymap Overview

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 `LAYOUT()` 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
The state of the Keymap layer is determined by two 32 bit parameters:

* **`default_layer_state`** indicates a base keymap layer (0-31) which is always valid and to be referred (the default layer).
* **`layer_state`** has current on/off status of each layer in its bits.

Keymap layer '0' is usually the `default_layer`, with other layers initially off after booting up the firmware, although this can configured differently in `config.h`. It is useful to change `default_layer` when you completely switch a key layout, for example, if you want to switch to Colemak 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 can change `layer_state` to overlay the base layer with other layers for features such as navigation keys, function keys (F1-F12), media keys, and/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 an [older version of the default Clueboard 66% keymap](https://github.com/qmk/qmk_firmware/blob/ca01d94005f67ec4fa9528353481faa622d949ae/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.

There are 3 main sections of a `keymap.c` file you'll want to concern yourself with:

* [The Definitions](#definitions)
* [The Layer/Keymap Datastructure](#layers-and-keymaps)
* [Custom Functions](#custom-functions), if any

### Definitions

At the top of the file you'll find this:

    #include QMK_KEYBOARD_H

    // Helpful defines
    #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))

    /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 
     *  You can use _______ in place for KC_TRNS (transparent)   *
     *  Or you can use XXXXXXX for KC_NO (NOOP)                  *
     * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

    // Each layer gets a name for readability.
    // The underscores don't mean anything - you can
    // have a layer called STUFF or any other name.
    // Layer names don't all need to be of the same
    // length, and you can also skip them entirely
    // and just use numbers.
    #define _BL 0
    #define _FL 1
    #define _CL 2

These 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, and the following `_BL`, `_FL`, and `_CL` defines make it easier to refer to each of our layers.

Note: You may also find some older keymap files may also have a define(s) for `_______` and/or `XXXXXXX`. These can be used in place for `KC_TRNS` and `KC_NO` respectively, making it easier to see what keys a layer is overriding. These definitions are now unecessary, as they are included by default.

### Layers and Keymaps

The 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:

    const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {

After this you'll find a list of LAYOUT() macros. A LAYOUT() 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.

`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.

> 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.

#### Base Layer

Here is an example of the Clueboard's base layer:

      /* Keymap _BL: Base Layer (Default Layer)
       */
    [_BL] = LAYOUT(
      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, \
      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, \
      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,                             \
      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,            \
      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),

Some interesting things to note about this:

* 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.
* Plain keyboard scancodes are prefixed with KC_, while "special" keys are not.
* The upper left key activates custom function 0 (`F(0)`)
* The "Fn" key is defined with `MO(_FL)`, which moves to the `_FL` layer while that key is being held down.

#### Function Overlay Layer

Our 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.

    [_FL] = LAYOUT(
      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, \
      _______, _______, _______,_______,_______,_______,_______,_______,KC_PSCR,KC_SLCK, KC_PAUS,  _______,  _______,  _______,                   _______, \
      _______, _______, MO(_CL),_______,_______,_______,_______,_______,_______,_______, _______,  _______,  _______,  _______,                           \
      _______, _______, _______,_______,_______,_______,_______,_______,_______,_______, _______,  _______,  _______,  _______,          KC_PGUP,         \
      _______, _______, _______, _______,        _______,_______,                        _______,  _______,  _______,  MO(_FL), KC_HOME, KC_PGDN, KC_END),

Some interesting things to note:

* We have used our `_______` definition to turn `KC_TRNS` into `_______`. This makes it easier to spot the keys that have changed on this layer.
* While in this layer if you press one of the `_______` keys it will activate the key in the next lowest active layer.

# Nitty Gritty Details

This should have given you a basic overview for creating your own keymap. For more details see the following resources:

* [Keycodes](keycodes.md)
* [Keymap FAQ](faq_keymap.md)

We 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)!
Commit	Line	Data
ca01d940 JH	1	# Keymap Overview
ca01d940 JH	2
384fef72	3	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 `LAYOUT()` macro to help you create this array of arrays.
ca01d940 JH	4
ca01d940 JH	5
7b0356d1	6	## Keymap and Layers
ca01d940 JH	7	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.
	8
	9	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.
	10
	11	Respective 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
	28	Sometimes, the action code stored in keymap may be referred as keycode in some documents due to the TMK history.
	29
7b0356d1	30	### Keymap Layer Status
e236f1eb	31	The state of the Keymap layer is determined by two 32 bit parameters:
ca01d940	32
e236f1eb ZB	33	* `default_layer_state` indicates a base keymap layer (0-31) which is always valid and to be referred (the default layer).
e236f1eb ZB	34	* `layer_state` has current on/off status of each layer in its bits.
ca01d940	35
8df2ee4e	36	Keymap layer '0' is usually the `default_layer`, with other layers initially off after booting up the firmware, although this can configured differently in `config.h`. It is useful to change `default_layer` when you completely switch a key layout, for example, if you want to switch to Colemak instead of Qwerty.
ca01d940	37
bb53635f	38	Initial state of Keymap Change base layout
bb53635f	39	----------------------- ------------------
ca01d940 JH	40
	41	31 31
	42	30 30
	43	29 29
	44	: :
	45	: : ____________
	46	2 ____________ 2 / /
	47	1 / / ,->1 /___________/
	48	,->0 /___________/ \| 0
	49	\| \|
	50	`--- default_layer = 0 `--- default_layer = 1
	51	layer_state = 0x00000001 layer_state = 0x00000002
	52
e236f1eb	53	On the other hand, you can change `layer_state` to overlay the base layer with other layers for features such as navigation keys, function keys (F1-F12), media keys, and/or special actions.
ca01d940 JH	54
	55	Overlay feature layer
	56	--------------------- bit\|status
	57	____________ ---+------
	58	31 / / 31 \| 0
	59	30 /___________// -----> 30 \| 1
	60	29 /___________/ -----> 29 \| 1
	61	: : \| :
	62	: ____________ : \| :
	63	2 / / 2 \| 0
	64	,->1 /___________/ -----> 1 \| 1
	65	\| 0 0 \| 0
	66	\| +
	67	`--- default_layer = 1 \|
	68	layer_state = 0x60000002 <-'
	69
	70
	71
	72	### Layer Precedence and Transparency
	73	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.
	74
	75	You can place `KC_TRANS` on overlay layer changes just part of layout to fall back on lower or base layer.
	76	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.
	77
7b0356d1	78	## Anatomy of a `keymap.c`
ca01d940	79
b9f426ae	80	For this example we will walk through an [older version of the default Clueboard 66% keymap](https://github.com/qmk/qmk_firmware/blob/ca01d94005f67ec4fa9528353481faa622d949ae/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.
ca01d940 JH	81
	82	There are 3 main sections of a `keymap.c` file you'll want to concern yourself with:
	83
	84	* [The Definitions](#definitions)
	85	* [The Layer/Keymap Datastructure](#layers-and-keymaps)
	86	* [Custom Functions](#custom-functions), if any
	87
	88	### Definitions
	89
	90	At the top of the file you'll find this:
	91
334e2629	92	#include QMK_KEYBOARD_H
ca01d940 JH	93
	94	// Helpful defines
	95	#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))
334e2629 AW	96
	97	/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
	98	* You can use _______ in place for KC_TRNS (transparent) *
	99	* Or you can use XXXXXXX for KC_NO (NOOP) *
	100	* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
ca01d940 JH	101
	102	// Each layer gets a name for readability.
	103	// The underscores don't mean anything - you can
	104	// have a layer called STUFF or any other name.
bb53635f	105	// Layer names don't all need to be of the same
ca01d940 JH	106	// length, and you can also skip them entirely
	107	// and just use numbers.
	108	#define _BL 0
	109	#define _FL 1
	110	#define _CL 2
	111
334e2629 AW	112	These 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, and the following `_BL`, `_FL`, and `_CL` defines make it easier to refer to each of our layers.
	113
	114	Note: You may also find some older keymap files may also have a define(s) for `_______` and/or `XXXXXXX`. These can be used in place for `KC_TRNS` and `KC_NO` respectively, making it easier to see what keys a layer is overriding. These definitions are now unecessary, as they are included by default.
ca01d940 JH	115
	116	### Layers and Keymaps
	117
	118	The 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:
	119
	120	const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
	121
384fef72	122	After this you'll find a list of LAYOUT() macros. A LAYOUT() 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.
ca01d940	123
bb53635f	124	`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.
ca01d940 JH	125
	126	> 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.
	127
	128	#### Base Layer
	129
	130	Here is an example of the Clueboard's base layer:
	131
	132	/* Keymap _BL: Base Layer (Default Layer)
	133	*/
384fef72	134	[_BL] = LAYOUT(
ca01d940 JH	135	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, \
	136	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, \
	137	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, \
	138	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, \
	139	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),
	140
	141	Some interesting things to note about this:
	142
	143	* 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.
	144	* Plain keyboard scancodes are prefixed with KC_, while "special" keys are not.
	145	* The upper left key activates custom function 0 (`F(0)`)
	146	* The "Fn" key is defined with `MO(_FL)`, which moves to the `_FL` layer while that key is being held down.
	147
	148	#### Function Overlay Layer
	149
	150	Our 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.
	151
384fef72	152	[_FL] = LAYOUT(
ca01d940 JH	153	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, \
	154	_______, _______, _______,_______,_______,_______,_______,_______,KC_PSCR,KC_SLCK, KC_PAUS, _______, _______, _______, _______, \
	155	_______, _______, MO(_CL),_______,_______,_______,_______,_______,_______,_______, _______, _______, _______, _______, \
	156	_______, _______, _______,_______,_______,_______,_______,_______,_______,_______, _______, _______, _______, _______, KC_PGUP, \
	157	_______, _______, _______, _______, _______,_______, _______, _______, _______, MO(_FL), KC_HOME, KC_PGDN, KC_END),
	158
	159	Some interesting things to note:
	160
	161	* We have used our `_______` definition to turn `KC_TRNS` into `_______`. This makes it easier to spot the keys that have changed on this layer.
bb53635f	162	* While in this layer if you press one of the `_______` keys it will activate the key in the next lowest active layer.
ca01d940	163
ca01d940 JH	164	# Nitty Gritty Details
	165
	166	This should have given you a basic overview for creating your own keymap. For more details see the following resources:
	167
9d1a08e3	168	* [Keycodes](keycodes.md)
9d1a08e3	169	* [Keymap FAQ](faq_keymap.md)
ca01d940	170
9d1a08e3	171	We 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)!