X-Git-Url: https://git.friedersdorff.com/?a=blobdiff_plain;f=tmk_core%2Fdoc%2Fkeymap.md;h=87b72e059bc249a2e7d48f1a4154cc3955b80828;hb=a499c19cd0fc8aac8d63d4009145b1f7265ee607;hp=4c9b974c8d23bbe7feef5646b68e95e996d0a4e8;hpb=b17d2d176c2ba3460cf101d3b45b24653a952955;p=max%2Ftmk_keyboard.git diff --git a/tmk_core/doc/keymap.md b/tmk_core/doc/keymap.md index 4c9b974c..87b72e05 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 @@ -95,7 +95,7 @@ Note that ***higher layers have priority in the layer stack***. The firmware sta ### 0.3 Keymap Example -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. +The keymap is defined in the **`uint8_t 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` action in the **`action_t fn_actions[]`** array. 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. @@ -109,7 +109,7 @@ In this example, You can find other keymap definitions in file `keymap.c` located on project directories. - static const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { + const uint8_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { /* 0: Qwerty * ,-----------------------------------------------------------. * |Esc| 1| 2| 3| 4| 5| 6| 7| 8| 9| 0| -| =| \| `| @@ -167,7 +167,7 @@ You can find other keymap definitions in file `keymap.c` located on project dire LGUI,LALT, BTN1, RALT,TRNS), }; - static const uint16_t PROGMEM fn_actions[] = { + const action_t PROGMEM fn_actions[] = { ACTION_LAYER_MOMENTARY(1), // FN0 ACTION_LAYER_TAP_KEY(2, KC_SCLN), // FN1 ACTION_LAYER_TOGGLE(2), // FN2 @@ -214,7 +214,7 @@ 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.*** +`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 `action_t 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.*** ### 1.6 Keycode Table See keycode table in [`doc/keycode.txt`](./keycode.txt) for description of keycodes. @@ -379,19 +379,33 @@ Default Layer also has bitwise operations, they are executed when key is release ACTION_DEFAULT_LAYER_BIT_SET(part, bits) - ### 2.3 Macro action -***TBD*** +`Macro` actions allow you to register a complex sequence of keystrokes when a key is pressed, where macros are simple sequences of keypresses. + + ACTION_MACRO(id) + ACTION_MACRO_TAP(id) + +`id` is an 8-bit user-defined value the macro getter function can use to pick the specific macro. + + +#### 2.3.1 Implementing Macro getter function +To implement `macro` functions, the macro lookup list must be implemented: + + const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt); -`Macro` action indicates complex key strokes. - - MACRO( D(LSHIFT), D(D), END ) - MACRO( U(D), U(LSHIFT), END ) - MACRO( I(255), T(H), T(E), T(L), T(L), W(255), T(O), END ) +The function must always return a valid macro, and default implementation of `action_get_macro` always returns `MACRO_NONE` which has no effect. + +#### 2.3.1.1 Limitations +Similar to the Function Action system, the selector functions is passed a `keyrecord_t` object, so it can inspect the key state (e.g. different macros on key press or release), and key itself. + +Unlike the Function Action system,`macros` are pre-recorded key sequences, so you can only select from a list. If you want to use dynamic macros then you should look at the more complex function action system. -#### 2.3.1 Macro Commands -- **MACRO()** -- **MACRO_NONE** +#### 2.3.2 Implementing/Defining Macro sequences +Macros are of the form (must be wrapped by the `MACRO` function, and end with an `END` mark) + + MACRO( ..., END ) + +Within each macro, the following commands can be used: - **I()** change interval of stroke. - **D()** press key @@ -401,19 +415,25 @@ Default Layer also has bitwise operations, they are executed when key is release - **SM()** store modifier state - **RM()** restore modifier state - **CM()** clear modifier state -- **END** end mark + +e.g.: + + MACRO( D(LSHIFT), D(D), END ) // hold down LSHIFT and D - will print 'D' + MACRO( U(D), U(LSHIFT), END ) // release U and LSHIFT keys (an event.pressed == False counterpart for the one above) + MACRO( I(255), T(H), T(E), T(L), T(L), W(255), T(O), END ) // slowly print out h-e-l-l---o #### 2.3.2 Examples -***TBD*** + +in keymap.c, define `action_get_macro` const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) { switch (id) { - case HELLO: + case 0: return (record->event.pressed ? MACRO( I(0), T(H), T(E), T(L), T(L), W(255), T(O), END ) : MACRO_NONE ); - case ALT_TAB: + case 1: return (record->event.pressed ? MACRO( D(LALT), D(TAB), END ) : MACRO( U(TAB), END )); @@ -421,7 +441,12 @@ Default Layer also has bitwise operations, they are executed when key is release return MACRO_NONE; } - +in keymap.c, bind items in `fn_actions` to the macro function + + const action_t PROGMEM fn_actions[] = { + [0] = ACTION_MACRO(0), // will print 'hello' for example + [1] = ACTION_MACRO(1), + }; ### 2.4 Function action @@ -443,7 +468,7 @@ To define tappable `Function` action in keymap use this. #### 2.4.3 Implement user function `Function` actions can be defined freely with C by user in callback function: - void keymap_call_function(keyrecord_t *event, uint8_t id, uint8_t opt) + void action_function(keyrecord_t *record, uint8_t id, uint8_t opt); This C function is called every time key is operated, argument `id` selects action to be performed and `opt` can be used for option. Function `id` can be 0-255 and `opt` can be 0-15. @@ -544,6 +569,7 @@ This registers modifier key(s) simultaneously with layer switching. ACTION_LAYER_MODS(2, MOD_LSFT | MOD_LALT) +This function can only register left-sided modifiers. The handedness of the modifier (left/right) is an extra bit that is not able to be passed through into the layer system. See: [`common/action_code.h`](../common/action_code.h), the spec for ACT_LAYER_TAP only allows four bits for the mods, whereas the mods themselves require five bits, with the high bit being the left/right handedness. ## 4. Tapping @@ -598,13 +624,13 @@ Legacy Keymap uses two arrays `fn_layer[]` and `fn_keycode[]` to define 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. - static const uint8_t PROGMEM fn_layer[] = { + const uint8_t PROGMEM fn_layer[] = { 1, // Fn0 2, // Fn1 2, // Fn2 }; - static const uint8_t PROGMEM fn_keycode[] = { + const uint8_t PROGMEM fn_keycode[] = { KC_NO, // Fn0 KC_NO, // Fn1 KC_SPC, // Fn2