v.0.5.0 (#10)

Release of v0.5.0:
- 3+ finger roll interpretation
- simplified configuration (no more custom keycodes are needed)
- no more SMTD_KEYCODES_BEGIN and SMTD_KEYCODES_END are needed
- simplified SMTD_MT, SMTD_LT and other macros
- bunch of useful macros
- some bug fixes

Author: stasmarkin

.gitignore

@@ -54,4 +54,7 @@ dkms.conf
 .idea
 
 cmake-build-debug
-CMakeLists.txt
+CMakeLists.txt
+
+build/
+.claude/

.run/Python tests.run.xml

@@ -0,0 +1,17 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Python tests" type="tests" factoryName="Autodetect">
+    <module name="sm_td" />
+    <option name="ENV_FILES" value="" />
+    <option name="INTERPRETER_OPTIONS" value="" />
+    <option name="PARENT_ENVS" value="true" />
+    <option name="SDK_HOME" value="" />
+    <option name="WORKING_DIRECTORY" value="$PROJECT_DIR$/tests" />
+    <option name="IS_MODULE_SDK" value="true" />
+    <option name="ADD_CONTENT_ROOTS" value="true" />
+    <option name="ADD_SOURCE_ROOTS" value="true" />
+    <option name="_new_additionalArguments" value="&quot;&quot;" />
+    <option name="_new_target" value="&quot;$PROJECT_DIR$/tests&quot;" />
+    <option name="_new_targetType" value="&quot;PATH&quot;" />
+    <method v="2" />
+  </configuration>
+</component>

LICENSE

@@ -1,3 +1,7 @@
+```
+This documentation is written for version 0.4.1.
+It is a bit outdated for later versions of SM_TD.
+```
 
 This is the `SM Tap Dance` (`sm_td` or `smtd` for short) user library for QMK.
 The main goal of this library is to ultimately fix the Home Row Mods (HRM) and Tap Dance problems in QMK.

README.md

@@ -3,7 +3,7 @@
 1. Add `DEFERRED_EXEC_ENABLE = yes` to your `rules.mk` file.
 2. Add `#define MAX_DEFERRED_EXECUTORS 10` (or add 10 if you already use it) to your `config.h` file.
 3. Clone the `sm_td.h` repository into your `keymaps/your_keymap` folder (next to your `keymap.c`)
-4. Add `#include "sm_td.h"` to your `keymap.c` file. !!! WARNING !!! There is a bug in v0.4.0 and the library would compile with a "'SMTD_KEYCODES_BEGIN' undeclared" error. You need to put this #include "sm_td.h" right after you define your custom keycodes enum (described on p.6).
+4. Add `#include "sm_td.h"` to your `keymap.c` file
 5. Check `!process_smtd` first in your `process_record_user` function like this
    ```c
    bool process_record_user(uint16_t keycode, keyrecord_t *record) {
@@ -16,37 +16,21 @@
    }
    ```
 
-6. Add `SMTD_KEYCODES_BEGIN` and `SMTD_KEYCODES_END` to you custom keycodes, and put each new custom keycode you want to use with `sm_td` between them.
-   For example, if you want to use `A`, `S`, `D` and `F` for HRM, you need to create a custom keycode for them like this
+6. Create a `smtd_resolution on_smtd_action(uint16_t keycode, smtd_action action, uint8_t tap_count)` function. This is a function to configure behaviour for keys.
+   For example, if you want to use `KC_A`, `KC_S`, `KC_D` and `KC_F` for HRM, your `on_smtd_action()` function will look like this
    ```c
-   enum custom_keycodes {
-       SMTD_KEYCODES_BEGIN = SAFE_RANGE,
-       CKC_A, // reads as C(ustom) + KC_A, but you may give any name here
-       CKC_S,
-       CKC_D,
-       CKC_F,
-       SMTD_KEYCODES_END,
-   };
-   ```
-   Please don't forget to put ; at the end of the enum definition. Normally it's not necessary, but if you put #include "sm_td.h" it will break compilation.
-   Note that `SAFE_RANGE` is a predefined constant in QMK, and is used [to define custom keycodes](https://docs.qmk.fm/custom_quantum_functions).
-   You need to put it on the beginning of your custom keycodes enum.
-   Some keyboards may have their own `SAFE_RANGE` constant, so you need to check your firmware for this constant.
-
-7. Place all your custom keycodes on the desired key positions in your `keymaps`.
-8. Create a `void on_smtd_action(uint16_t keycode, smtd_action action, uint8_t tap_count)` function that would handle all the actions of the custom keycodes you defined in the previous step.
-   For example, if you want to use `CKC_A`, `CKC_S`, `CKC_D` and `CKC_F` for HRM, your `on_smtd_action()` function will look like this
-   ```c
-   void on_smtd_action(uint16_t keycode, smtd_action action, uint8_t tap_count) {
+   smtd_resolution on_smtd_action(uint16_t keycode, smtd_action action, uint8_t tap_count) {
        switch (keycode) {
-           SMTD_MT(CKC_A, KC_A, KC_LEFT_GUI)
-           SMTD_MT(CKC_S, KC_S, KC_LEFT_ALT)
-           SMTD_MT(CKC_D, KC_D, KC_LEFT_CTRL)
-           SMTD_MT(CKC_F, KC_F, KC_LSFT)
+           SMTD_MT(KC_A, KC_LEFT_GUI)
+           SMTD_MT(KC_S, KC_LEFT_ALT)
+           SMTD_MT(KC_D, KC_LEFT_CTRL)
+           SMTD_MT(KC_F, KC_LSFT)
        }
+   
+       return SMTD_RESOLUTION_NONE;
    }
    ```
-   See extensive documentation in the [Customization Guide](https://github.com/stasmarkin/sm_td/blob/main/docs/050_customization.md) with cool [Examples](https://github.com/stasmarkin/sm_td/blob/main/docs/60_customization_examples.md)
+   See extensive documentation in the [Customization Guide](https://github.com/stasmarkin/sm_td/blob/main/docs/050_customization.md) for all available customisations.
 
-9. (optional) Add global configuration parameters to your `config.h` file (see [timeouts](https://github.com/stasmarkin/sm_td/blob/main/docs/070_customization_timeouts.md) and [feature flags](https://github.com/stasmarkin/sm_td/blob/main/docs/080_customization_features.md)).
-10. (optional) Add per-key configuration (see [timeouts](https://github.com/stasmarkin/sm_td/blob/main/docs/070_customization_timeouts.md) and [feature flags](https://github.com/stasmarkin/sm_td/blob/main/docs/080_customization_features.md)).
+7. (optional) Add global configuration parameters to your `config.h` file (see [timeouts](https://github.com/stasmarkin/sm_td/blob/main/docs/070_customization_timeouts.md) and [feature flags](https://github.com/stasmarkin/sm_td/blob/main/docs/080_customization_features.md)).
+8. (optional) Add per-key configuration (see [timeouts](https://github.com/stasmarkin/sm_td/blob/main/docs/070_customization_timeouts.md) and [feature flags](https://github.com/stasmarkin/sm_td/blob/main/docs/080_customization_features.md)).

docs/000_overview.md

@@ -1,3 +1,11 @@
+#### `v0.5.0`
+- 3+ finger roll interpretation
+- simplified configuration (no more custom keycodes are needed)
+- no more SMTD_KEYCODES_BEGIN and SMTD_KEYCODES_END are needed
+- simplified SMTD_MT, SMTD_LT and other macros
+- bunch of useful macros
+- some bug fixes
+
 #### `v0.4.0`
 - simplified installation process (no need to init each key with `SMTD()` macro)
 - added useful `SMTD_MT()`, `SMTD_MTE()`, `SMTD_LT()` macros for easier customization
@@ -9,7 +17,7 @@
 - optional delay between simultaneous key presses (see SMTD_GLOBAL_SIMULTANEOUS_PRESSES_DELAY_MS in [feature flags](https://github.com/stasmarkin/sm_td/blob/main/docs/080_customization_features.md))
 
 #### `v0.3.0`
-- bug fix on pressing same macro key on stage SMTD_STAGE_RELEASE
+- bug fix on pressing same macro key on stage SMTD_STAGE_TOUCH_RELEASE
 - reduce args number for get_smtd_timeout_default and smtd_feature_enabled_default functions (see Upgrade instructions)
 - better stage naming
 - comprehensive documentation

docs/010_installation_guide.md

@@ -1,3 +1,12 @@
+## `v0.4.0` → `v0.5.0`
+- replace `sm_td.h` with newer version
+- remove SMTD_KEYCODES_BEGIN and SMTD_KEYCODES_END (if you want to)
+- change function `void on_smtd_action(...)` to `smtd_resolution on_smtd_action(...)`
+- add `return SMTD_RESOLUTION_UNHANDLED;` as the last line of `on_smtd_action(...)` function
+- next you have to upgrade SMTD_* macros. There are two ways of doing this:
+  - **Option 1**: (recommended, but long) for every SMTD_MT (or _LT) macro remove the first argument with custom keycode. So, instead of `SMTD_MT(CKC_A, KC_A, KC_LEFT_GUI, 2)` just leave `SMTD_MT(KC_A, KC_LEFT_GUI, 2)`. You also need to replace every occurrence of CKC_A to KC_A (so, put it in your keycodes matrix, combos and so on). And remove CKC_A from custom_keycodes entirely. 
+  - **Option 2**: (fast, but ugly) replace SMTD_MT with SMTD_MT_ON_MKEY.  So, instead of `SMTD_MT(CKC_A, KC_A, KC_LEFT_GUI, 2)` you just write `SMTD_MT_ON_MKEY(CKC_A, KC_A, KC_LEFT_GUI, 2)`. That's it. 
+
 ## `v0.3.1` → `v0.4.0`
 - replace `sm_td.h` with newer version
 - remove `smtd_state smtd_states[]` and `size_t smtd_states_size`

docs/015_releases.md

@@ -1,13 +1,9 @@
-## Three fingers roll
+## Partial Combo support
 
-If you press 3 keys simultaneously smtd will interpret this as hold + hold + top (read 3.3: Deep Explanation: Three keys and states stack). That's what usually expected in 99% cases, but anyway that breaks fast 3+ fingers rolls while typing. It will be fixed in verison v.1.1.0
+`COMBO_ACTION` + `process_combo_event()` is only a supported API for QMK's combo feature.
+See [official documentation](https://docs.qmk.fm/features/combo#examples)
 
-
-## Rattle modification key with Mods Recall feature
-
-For example, you hit `↓shift` (that is not a part of smtd), `↓smtd_macro`, `↑shift` and `↑smtd_macro`. Actual tap of smtd_macro wouldn't be sent to OS until you physically release that key. So OS will receive that sequence: `↓shift`, `↑shift` (from physical pressing and releasing shift key), then `↓shift` (from mod recall), `↓↑smtd_macro_tap_action` and `↑shift`. Some programs (like Intellij IDEA) may interpret double shift press as a shortcut for some actions.
-
-To overcome that issue you should put shift modifier as another macro for smtd, so smtd would be able to correctly handle intercepting states for two keys.
+Simple `COMBO()` are not supported yet
 
 
 ## Twice quantum key processing before users code

docs/020_upgrade_instructions.md

@@ -1,7 +1,64 @@
+```
+This documentation is written for version 0.4.1.
+It is a bit outdated for later versions of SM_TD.
+```
+
+
+## What is `on_smtd_action()` function?
+
+When you press a key, all state machines in the stack start working.
+Other keys you press after the sm_td state machine has run will also be processed by the sm_td state machine.
+This state machine might decide to postpone the processing of the key you pressed, so that it will be considered a tap or hold later.
+You don't have to worry about this, sm_td will process all keys you press in the correct order and in a very predictable way.
+You don't need to understand the internal implementation of the state machine stack, but you do need to know what output you will get from sm_td's state machine.
+As soon as you press keys assigned to sm_td, it will call the `on_smtd_action()` function with the following arguments
+- uint16_t keycode - keycode of the key you pressed
+- smtd_action action - result interpreted action (`SMTD_ACTION_TOUCH`, `SMTD_ACTION_TAP`, `SMTD_ACTION_HOLD`, `SMTD_ACTION_RELEASE`). tap, hold and release are self-explanatory. Touch action fired on key press (without knowing if it is a tap or hold).
+- uint8_t tap_count - number of consecutive taps before the current action. (will be reset after hold, pause or any other keypress)
+
+There are only two execution flows for the `on_smtd_action` function:
+- `SMTD_ACTION_TOUCH` → `SMTD_ACTION_TAP`.
+- `SMTD_ACTION_TOUCH` → `SMTD_ACTION_HOLD` → `SMTD_ACTION_RELEASE`.
+
+Consider the following example to understand the execution flow.
+Let's say you want to tap, tap, hold and tap again a custom key `KC`. Here are your finger movements:
+
+- `↓KC` 50ms `↑KC` (first tap finished) 50ms
+- `↓KC` 50ms `↑KC` (second tap finished) 50ms
+- `↓KC` 200ms (holding long enough for hold action) `↑KC` 50ms
+- `↓KC` 50ms `↑KC` (third tap finished)
+
+For this example, you will get the following `on_smtd_action()` calls:
+- `on_smtd_action(KC, SMTD_ACTION_TOUCH, 0)` right after pressing `↓KC`
+- `on_smtd_action(KC, SMTD_ACTION_TAP, 0)` right after releasing `↑KC` (first tap finished)
+- `on_smtd_action(KC, SMTD_ACTION_TOUCH, 1)` right after pressing `↓KC` second time
+- `on_smtd_action(KC, SMTD_ACTION_TAP, 1)` right after releasing `↑KC` second time (second tap finished)
+- `on_smtd_action(KC, SMTD_ACTION_TOUCH, 2)` right after pressing `↓KC` third time
+- `on_smtd_action(KC, SMTD_ACTION_HOLD, 2)` after holding `KC` long enough
+- `on_smtd_action(KC, SMTD_ACTION_RELEASE, 2)` right after releasing `↑KC` (hold)
+- `on_smtd_action(KC, SMTD_ACTION_TOUCH, 0)` right after pressing `↓KC` fourth time
+- `on_smtd_action(KC, SMTD_ACTION_TAP, 0)` right after releasing `↑KC` (third tap finished)
+
+
+
+## How to add custom behavior to sm_td keycodes?
+
 You need to put all the handlers of your sm_td keycodes into the `on_smtd_action()` function. It's called with the following arguments
 - `uint16_t keycode` - keycode of the macro key you pressed
-- smtd_action action` - result interpreted action (SMTD_ACTION_TOUCH, SMTD_ACTION_TAP, SMTD_ACTION_HOLD, SMTD_ACTION_RELEASE). tap, hold and release are self-explanatory. The touch action is fired on every key press (without knowing if it is a tap or a hold).
-- uint8_t tap_count` - Number of consecutive taps before the current action. (will be reset after hold, pause or any other keypress)
+- `smtd_action action` - result interpreted action (SMTD_ACTION_TOUCH, SMTD_ACTION_TAP, SMTD_ACTION_HOLD, SMTD_ACTION_RELEASE). tap, hold and release are self-explanatory. The touch action is fired on every key press (without knowing if it is a tap or a hold).
+- `uint8_t tap_count` - Number of consecutive taps before the current action. (will be reset after hold, pause or any other keypress)
+
+### `smtd_resolution` return value
+
+The function should return a `smtd_resolution` value to indicate how the action was handled:
+- `SMTD_RESOLUTION_UNHANDLED` - The action was not handled by some custom code. `sm_td` will handle it as normal key action
+- `SMTD_RESOLUTION_UNCERTAIN` - The action is not yet determined (for example, tapping MT key may result in mod or key, so on tap resolution is uncertain)
+- `SMTD_RESOLUTION_DETERMINED` - The action was handled and determined
+
+The rule of thumb is to return `SMTD_RESOLUTION_UNCERTAIN` on `SMTD_ACTION_TOUCH` and `SMTD_RESOLUTION_DETERMINED` on all other actions.
+This will be enough for 99.8% of cases. In the other 0.2% contact me, I'm really curious what are you trying to achieve.
+
+### `on_smtd_action()` execution flow
 
 There are only two execution flows for the `on_smtd_action` function:
 - `SMTD_ACTION_TOUCH` → `SMTD_ACTION_TAP`.
@@ -11,8 +68,11 @@ You will never get a tap between hold and release or miss a touch action. So you
 
 One possible structure to describe macro behavior is nested switch-cases. Top level for macro key selection, second for action, third (optional) for tap_count. For example
 
+
+--- EVERYTHING BELOW IS A BIT OUTDATED ---
+
 ```c
-void on_smtd_action(uint16_t keycode, smtd_action action, uint8_t tap_count) {
+smtd_resolution on_smtd_action(uint16_t keycode, smtd_action action, uint8_t tap_count) {
     switch (keycode) {
         case CUSTOM_KEYCODE_1: {
             switch (action) {
@@ -52,12 +112,13 @@ void on_smtd_action(uint16_t keycode, smtd_action action, uint8_t tap_count) {
                     }
                     break;
             } // end of switch (action)
-            break;
+            return SMTD_RESOLUTION_DETERMINED;
         } // end of case CUSTOM_KEYCODE_1
 
         // put all your custom keycodes here
 
     } // end of switch (keycode)
+    return SMTD_RESOLUTION_UNHANDLED;
 } // end of on_smtd_action function
 ```
 
@@ -69,8 +130,8 @@ There are special macros to make your code more compact and easier:
 They handle custom keycodes in the same way as the standard QMK `MT()` or `LT()` functions.
 So instead of writing a multiline handler for each sm_td keycode, you can write something like this
 
-```
-void on_smtd_action(uint16_t keycode, smtd_action action, uint8_t tap_count) { }
+```c
+smtd_resolution on_smtd_action(uint16_t keycode, smtd_action action, uint8_t tap_count) {
     switch (keycode) {
         SMTD_MT(CKC_A, KC_A, KC_LEFT_GUI)
         SMTD_MT(CKC_S, KC_S, KC_LEFT_ALT)
@@ -80,6 +141,8 @@ void on_smtd_action(uint16_t keycode, smtd_action action, uint8_t tap_count) { }
         SMTD_LT(CKC_SPACE, KC_SPACE, LAYER_NUM)
         SMTD_LT(CKC_ENTER, KC_ENTER, LAYER_FN)
     } // End of switch (keycode)
+    
+    return SMTD_RESOLUTION_UNHANDLED;
 } // End of on_smtd_action function
 ```