Update documentation for Macro function and action_layer_mods

7 years ago · 4105939349
--- a/tmk_core/doc/keymap.md
+++ b/tmk_core/doc/keymap.md
@@ -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);

 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. 

 `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 )
 #### 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)

 #### 2.3.1 Macro Commands
 - **MACRO()**
 - **MACRO_NONE**
 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
@@ -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