[Core] Tri Layer Keys (#19795)

Co-authored-by: wilba <[email protected]>
Co-authored-by: Pablo Martínez <[email protected]>
Co-authored-by: Joel Challis <[email protected]>
Co-authored-by: Nick Brassel <[email protected]>

docs/_summary.md

@@ -93,6 +93,7 @@
     * [Swap Hands](feature_swap_hands.md)
     * [Tap Dance](feature_tap_dance.md)
     * [Tap-Hold Configuration](tap_hold.md)
+    * [Tri Layer](feature_tri_layer.md)
     * [Unicode](feature_unicode.md)
     * [Userspace](feature_userspace.md)
     * [WPM Calculation](feature_wpm.md)

docs/feature_tri_layer.md

@@ -0,0 +1,48 @@
+# Tri Layers :id=tri-layers
+
+This enables support for the OLKB style "Tri Layer" keycodes.  These function similar to the `MO` (momentary) function key, but if both the "Lower" and "Upper" keys are pressed, it activates a third "Adjust" layer.  To enable this functionality, add this line to your `rules.mk`:
+
+```make
+TRI_LAYER_ENABLE = yes
+```
+
+Note that the "upper", "lower" and "adjust" names don't have a particular significance, they are just used to identify and clarify the behavior. Layers are processed from highest numeric value to lowest, however the values are not required to be consecutive.
+
+For a detailed explanation of how the layer stack works, check out [Keymap Overview](keymap.md#keymap-and-layers).
+
+## Keycodes :id=keycodes
+
+| Keycode              | Alias     | Description                                                                                             |
+|----------------------|-----------|---------------------------------------------------------------------------------------------------------|
+| `QK_TRI_LAYER_LOWER` | `TL_LOWR` | Momentarily enables the "lower" layer. Enables the "adjust" layer if the "upper" layer is also enabled" |
+| `QK_TRI_LAYER_UPPER` | `TL_UPPR` | Momentarily enables the "upper" layer. Enables the "adjust" layer if the "lower" layer is also enabled" |
+
+## Configuration
+
+To change the default values for the layers, you can change these defines, in your `config.h`
+
+| Config name              | Default | Description                              |
+|--------------------------|---------|------------------------------------------|
+| `TRI_LAYER_LOWER_LAYER`  | `1`     | Sets the default for the "lower" layer.  |
+| `TRI_LAYER_UPPER_LAYER`  | `2`     | Sets the default for the "upper" layer.  |
+| `TRI_LAYER_ADJUST_LAYER` | `3`     | Sets the default for the "adjust" layer. |
+
+Eg, if you wanted to set the "Adjust" layer to be layer 5, you'd add this to your `config.h`: 
+
+```c
+#define TRI_LAYER_ADJUST_LAYER 5
+```
+
+## Functions
+
+| Function name                                |  Description                                    |
+|----------------------------------------------|-------------------------------------------------|
+| `set_tri_layer_lower_layer(layer)`           | Changes the "lower" layer*.                     |
+| `set_tri_layer_upper_layer(layer)`           | Changes the "upper" layer*.                     |
+| `set_tri_layer_adjust_layer(layer)`          | Changes the "adjust" layer*.                    |
+| `set_tri_layer_layers(lower, upper, adjust)` | Stes the "lower", "upper" and "adjust" layers*. |
+| `get_tri_layer_lower_layer()`                | Gets the current "lower" layer.                 |
+| `get_tri_layer_upper_layer()`                | Gets the current "upper" layer.                 |
+| `get_tri_layer_adjust_layer()`               | Gets the current "adjust" layer.                |
+
+!> Note: these settings are not persisent, and will be reset to the default on power loss or power cycling of the controller.