X-Git-Url: https://git.friedersdorff.com/?a=blobdiff_plain;f=tmk_core%2Fdoc%2Fkeymap.md;h=3a196a2dd5bb17e3ff8c0af8b29c156024fe548e;hb=f43a2df7614503708818c258439d3a7c90d65e95;hp=572cf2f892929e24e816b280670832ffdf7673a1;hpb=336a27e91dd0b85d6a2d921a1d58807bd4f77451;p=max%2Ftmk_keyboard.git diff --git a/tmk_core/doc/keymap.md b/tmk_core/doc/keymap.md index 572cf2f8..3a196a2d 100644 --- a/tmk_core/doc/keymap.md +++ b/tmk_core/doc/keymap.md @@ -51,8 +51,8 @@ The **layer state** indicates the current on/off status of all layers. It is def #### 0.1.2 The default layer The **default layer** is the base keymap layer (0-31) which is always active and considered the "bottom" of the stack. When the firmware boots, the default layer is the only active layer. It is set to layer 0 by default, though this can be changed ~~in *config.h*~~ via Boot Magic settings. - Initial state of Keymap Change base layout - ----------------------- ------------------ + Initial state of Keymap Change base layout + ----------------------- ------------------ 31 31 30 30 @@ -86,25 +86,26 @@ default_layer_state_set(1UL<<3); ### 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. +Note that ***higher layers have priority in the layer stack***. The firmware starts at the topmost active layer, and works down to the bottom to find the an active keycode. Once the search encounters any keycode other than **`KC_TRNS`** (transparent) on an active layer, the search is halted and the remaining lower layers aren't examined, even if they are active. + +**Note:** a layer must be activated before it may be included in the stack search. + +`KC_TRNS` is a special placeholder which can be used on overlay layers. This allows for the creation of "partial" layers which fall back on the lower layers, eliminating a good deal of repetition in keymap files. -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. -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. +The keymap is defined in the **`keymaps[]`** array, a 2-dimensional array of rows and columns corresponding to positions in the keyboard matrix. But most often the layers are defined using C macros to allow for easier reading and editing of the keymap files. To use complex actions you need to define `Fn` keycodes in the **`fn_actions[]`** array. -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'. +This is a keymap example for the [HHKB](http://en.wikipedia.org/wiki/Happy_Hacking_Keyboard) keyboard. +This example has three layers: the QWERTY base layer, and two overlay layers for cursor and mousekey control, respectively. In this example, - `Fn0` is a **momentary layer switching** key, you can use keys on Cursor layer while holding the key. + `Fn0` is a **momentary layer switching** key--you can use keys on the Cursor layer while holding the key. - `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. + `Fn1` is a momentary layer switching key with tapping function--tapping the key as one would normally use it, sends the semicolon **';'** keycode, while holding the key down switches layers. - `Fn2` is a **toggle layer switch** key, you can stay switched layer after releasing the key unlike momentary switching. + `Fn2` is a **toggle layer switch** key--pressing the key toggles the layer on until you press it again. You can find other keymap definitions in file `keymap.c` located on project directories.