summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorEric.a Gebhart <e.a.gebhart@gmail.com>2023-02-12 11:31:04 -0500
committerGitHub <noreply@github.com>2023-02-13 03:31:04 +1100
commitdb1eeea4788de062eccf327da5844fc3f46844f9 (patch)
treecb8537e4a0222c84d0cd653661eb94a579000036 /docs
parentbbf7a20b33de2d203518687cb5cd1aa85005ea27 (diff)
Add combo hook to allow per layer combo reference layers. (#16699)
Co-authored-by: Drashna Jaelre <drashna@live.com> Co-authored-by: Sergey Vlasov <sigprof@gmail.com>
Diffstat (limited to 'docs')
-rw-r--r--docs/feature_combo.md50
1 files changed, 50 insertions, 0 deletions
diff --git a/docs/feature_combo.md b/docs/feature_combo.md
index c45e3fd0e4..75c78c4cd4 100644
--- a/docs/feature_combo.md
+++ b/docs/feature_combo.md
@@ -328,6 +328,51 @@ If you, for example, use multiple base layers for different key layouts, one for
With `#define COMBO_ONLY_FROM_LAYER 0` in config.h, the combos' keys are always checked from layer `0`, even if other layers are active.
+### Combo reference layers by layer.
+
+If not using `COMBO_ONLY_FROM_LAYER` it is possible to specify a
+combo reference layer for any layer using the `combo_ref_from_layer` hook.
+The combo macros automatically create this function from the `COMBO_REF_LAYER()`
+entries given.
+
+This function returns the assigned reference layer for the current layer.
+if there is no match, it returns the default reference layer if set,
+or the current layer otherwise. A default layer can be set with
+`DEFAULT_REF_LAYER(_MY_COMBO_REF_LAYER)`
+
+If not set, the default reference layer selection from the automatically generated
+`combo-ref-from-layer()` will be the current layer.
+
+The following `combo_ref_from_layer` function
+will give a reference layer of _QWERTY for the _DVORAK layer and
+will give the _NAV layer as a reference to it's self. All other layers
+will have the default for their combo reference layer. If the default
+is not set, all other layers will reference themselves.
+
+ ```c
+ #define COMBO_REF_DEFAULT _MY_COMBO_LAYER
+ ...
+
+ uint8_t combo_ref_from_layer(uint8_t layer){
+ switch (get_highest_layer(layer_state)){
+ case _DVORAK: return _QWERTY;
+ case _NAV: return _NAV;
+ default: return _MY_COMBO_LAYER;
+ }
+ return layer; // important if default is not in case.
+ }
+
+ ```
+
+ The equivalent definition using the combo macros is this:
+
+ ```c
+ COMBO_REF_LAYER(_DVORAK, _QWERTY)
+ COMBO_REF_LAYER(_NAV, _NAV)
+ DEFAULT_REF_LAYER(_MY_COMBO_LAYER).
+ ```
+
+
## User callbacks
In addition to the keycodes, there are a few functions that you can use to set the status, or check it:
@@ -350,6 +395,11 @@ First, you need to add `VPATH += keyboards/gboards` to your `rules.mk`. Next, in
Then, write your combos in `combos.def` file in the following manner:
```c
+// Alternate reference layers by layer
+// Layer Reference layer
+COMBO_REF_LAYER(_DVORAK, _QWERTY) // reference the qwerty layer for dvorak.
+COMBO_REF_LAYER(_NAV, _NAV) // explicit reference to self instead of the default.
+
// name result chord keys
COMB(AB_ESC, KC_ESC, KC_A, KC_B)
COMB(JK_TAB, KC_TAB, KC_J, KC_K)