From e2f2c228d1f50f1916d761bba9f73c8091d0ed1a Mon Sep 17 00:00:00 2001 From: HBBisenieks Date: Fri, 4 Mar 2022 14:54:28 -0800 Subject: [PATCH] changes per https://github.com/KMKfw/kmk_firmware/pull/350\#issuecomment-1059061967 --- docs/layers.md | 117 +++++++++++++++---------------------------------- 1 file changed, 36 insertions(+), 81 deletions(-) diff --git a/docs/layers.md b/docs/layers.md index 58e5fea..733eba0 100644 --- a/docs/layers.md +++ b/docs/layers.md @@ -9,107 +9,62 @@ keyboard.modules.append(Layers()) ## Keycodes -|Key |Description | -|-----------------|------------------------------------------------------------------------| -|`KC.DF(layer)` |Switches the default layer | -|`KC.MO(layer)` |Momentarily activates layer, switches off when you let go | -|`KC.LM(layer, mod)` |As `MO(layer)` but with `mod` active | -|`KC.LT(layer, kc)` |Momentarily activates layer if held, sends kc if tapped | -|`KC.TG(layer)` |Toggles the layer (enables it if no active, and vise versa) | -|`KC.TO(layer)` |Activates layer and deactivates all other layers | -|`KC.TT(layer)` |Momentarily activates layer if held, toggles it if tapped repeatedly | +|Key |Description | +|-----------------|--------------------------------------------------------------------------| +|`KC.DF(layer)` |Switches the default layer until the next time the keyboard powers off | +|`KC.MO(layer)` |Momentarily activates layer, switches off when you let go | +|`KC.LM(layer, mod)` |As `MO(layer)` but with `mod` active | +|`KC.LT(layer, kc)` |Momentarily activates layer if held, sends kc if tapped | +|`KC.TG(layer)` |Toggles the layer (enables it if no active, and vise versa) | +|`KC.TO(layer)` |Activates layer and deactivates all other layers | +|`KC.TT(layer)` |Momentarily activates layer if held, toggles it if tapped repeatedly | ## Custom HoldTap Behavior `KC.TT` and `KC.LT` use the same heuristic to determine taps and holds as ModTap. Check out the [ModTap doc](modtap.md) to find out more. +## Working with Layers +When starting out, care should be taken when working with layers, since it's possible to lock +yourself to a layer with no way of returning to the base layer short of unplugging your +keyboard. This is especially easy to do when using the `KC.TO()` keycode, which deactivates +all other layers in the stack. + +Some helpful guidelines to keep in mind as you design your layers: +- Only reference higher-numbered layers from a given layer +- Leave keys as `KC.TRNS` in higher layers when they would overlap with a layer-switch + +### Using Multiple Base Layers +In some cases, you may want to have more than one base layer (for instance you want to use +both QWERTY and Dvorak layouts, or you have a custom gamepad that can switch between +different games). In this case, best practice is to have these layers be the lowest, i.e. +defined first in your keymap. These layers are mutually-exclusive, so treat changing default +layers with `KC.DF()` the same way that you would treat using `KC.TO()` + ## Example Code -For the below examples, assume an example 3x3 keyboard with 3 layers as follows: +For our example, let's take a simple 3x3 macropad with two layers as follows: ```python -#EXAMPLE = example code +from kmk.modules.layers import Layers +keyboard.modules.append(Layers()) + +# Layer Keys +MOMENTARY = KC.MO(1) +MOD_LAYER = KC.LM(1, KC.RCTL) +LAYER_TAP = KC.LT(1, KC.END, prefer_hold=True, tap_interrupted=False, tap_time=250) # any tap longer than 250ms will be interpreted as a hold keyboard.keymap = [ # Base layer - [ - KC.A, KC.B, KC.C, - KC.D, KC.E, KC.F, - KC.G, KC.H, EXAMPLE, - ], - - # Arrow layer [ KC.NO, KC.UP, KC.NO, KC.LEFT,KC.DOWN,KC.RGHT, - KC.NO, KC.NO, KC.TRNS, + MOMENTARY, LAYER_TAP, MOD_LAYER, ], # Function Layer [ KC.F1, KC.F2, KC.F3, KC.F4, KC.F5, KC.F6, - KC.NO, KC.NO, KC.TRNS, + KC.TRNS,KC.TRNS,KC.TRNS, ], ] ``` - -### KC.DF() -Changes the default layer until the keyboard is powered off. The following would change the above keymap -so that the `EXAMPLE` key would set the arrow layer to be default until the kyeboard is powered off. - -```python -EXAMPLE = KC.DF(1) -``` - -### KC.MO() -Activates specified layer while held, similar to how the `Fn` key works on a normal keyboard. The following -would activate the Function layer while held. - -```python -EXAMPLE = KC.MO(2) -``` - -### KC.LM() -Activates the specified layer with the specified modifier key active, which can be nicer than holding down -multiple keys. The following example activates the Function layer with the `RALT` (right Alt) key active, too. - -```python -EXAMPLE = KC.LM(2, KC.RALT) -``` - -### KC.LT() -Activates the specified layer when held but passes the specified keycode when tapped. The following would -activate the Arrow layer when held but send an "i" when tapped. - -```python -EXAMPLE = KC.LT(1, KC.I) -``` - -### KC.TG() -Toggles the specified layer on/off when tapped. Other active layers below the toggled layer in the stack -may be applicable if the toggled layer has `KC.TRNS` in the same position. The following would toggle the -Arrow layer on/off when tapped (note the `KC.TRNS` in the bottom-right position of the Arrow layer allows -the `EXAMPLE` key to be pressed on the base layer even when the Arrow layer is active). - -```python -EXAMPLE = KC.TG(1) -``` - -### KC.TO() -Toggles the specified layer _and deactivates all other layers._ *NOTE:* be careful using this keycode! If -you don't have another layer switch on the toggled layer, the only way to return to the base layer is to -power-cycle the keyboard. The following would turn the keyboard into a navigation pad with 5 useless keys -until it was restarted by activating the Arrow layer and deactivating the base layer. - -```python -EXAMPLE = KC.TO(1) -``` - -### KC.TT() -Momentarily switches to the specified layer when held or toggles that same layer when tapped. The following -would momentarily activate the Function layer when held or toggle that layer when tapped (note that the layer -can be toggled back thanks to the `KC.TRNS` on the Function layer, similar to the `KC.TG()` example above). - -```python -EXAMPLE = KC.TT(2) -```