Clarify (and correct minor errors in) layers.md

Nothing actually changed in layers.md to reflect the subtle layer change
semantics differences introduced by separating shifts from locks on the stack,
but some clarifications would be helpful.

Signed-off-by: Michael Richters <gedankenexperimenter@gmail.com>
pull/1039/head
Michael Richters 4 years ago
parent 2e2954542f
commit f42fba55b0
No known key found for this signature in database
GPG Key ID: 1288FD13E4EEF0C0

@ -40,9 +40,9 @@ explore a few use-cases.
## Layer keys ## Layer keys
- `LockLayer(n)`: Locking a layer will activate it when the key toggles on, and - `LockLayer(n)`: Locking a layer will activate it when the key toggles on, and
the layer will remain active until unlocked (with `UnlockLayer(n)`), even if the layer will remain active until unlocked (with `UnlockLayer(n)` or by
we release the layer key meanwhile. Think of it like a `Caps lock` or `Num pressing `LockLayer(n)` again), even if we release the layer key
lock` key. meanwhile. Think of it like a `Caps lock` or `Num lock` key.
- `ShiftToLayer(n)`: Unlike `LockLayer`, this only activates the layer until the - `ShiftToLayer(n)`: Unlike `LockLayer`, this only activates the layer until the
key is held. Once the key is released, the layer deactivates. This behaviour key is held. Once the key is released, the layer deactivates. This behaviour
is very similar to that of modifiers. is very similar to that of modifiers.
@ -68,7 +68,7 @@ less hand movement is required!
### Shifted layers ### Shifted layers
There are many great examples for shifted layers, such as a symbols layer. Lets There are many great examples for shifted layers, such as a symbols layer. Let's
say we have a number of often used symbols which we want easy access to, say we have a number of often used symbols which we want easy access to,
preferably near the home row. For example, the various parentheses, brackets and preferably near the home row. For example, the various parentheses, brackets and
the like are often used in programming. Having them on the home row is the like are often used in programming. Having them on the home row is
@ -77,7 +77,7 @@ time, for a symbol or two. As such, locking the layer would be
counter-productive. Instead, we use a layer shift key, like if it was a counter-productive. Instead, we use a layer shift key, like if it was a
modifier. modifier.
As a concrete example, lets imagine a small, ortholinear keyboard, like the As a concrete example, let's imagine a small, ortholinear keyboard, like the
Planck. On the bottom row, on the right side of the space bar, we'd have a layer Planck. On the bottom row, on the right side of the space bar, we'd have a layer
shift key (lets call that `Fn` for now), that takes us to the symbol layer. On shift key (lets call that `Fn` for now), that takes us to the symbol layer. On
the symbol layer, we'd have `{`, `}`, `[`, `]`, `(`, and `)` on the home row. To the symbol layer, we'd have `{`, `}`, `[`, `]`, `(`, and `)` on the home row. To
@ -97,13 +97,13 @@ layer.
### Moving to layers ### Moving to layers
Moving to a layer is very similar to locking one. The only difference is that Moving to a layer is very similar to locking one. The only difference is that
moving disables all other layers. This in turn, has a few consequences: to go moving disables all other layers. This in turn, has consequences: we can't
back to wherever we came from, we can't use `UnlockLayer(n)`, because no other return to the previous layer state by repeating the same key. Unlocking a layer
layers are active. We explicitly have to use _another_ `MoveToLayer(n)` key if that has been activated by `MoveToLayer(n)` will instead cause Kaleidoscope to
we want to move elsewhere. fall back to the default base layer.
The major advantage of moving to a layer - as opposed to locking one - is the The major advantage of moving to a layer - as opposed to locking one - is the
cognitive load. With moving, there is no transparency. There is only one layer cognitive load. With moving, there is no transparency.[^1] There is only one layer
active at any given time. It's a simpler concept to grasp. active at any given time. It's a simpler concept to grasp.
## Layers, transparency, and how lookup works ## Layers, transparency, and how lookup works
@ -120,7 +120,7 @@ layer, and see if there's a non-transparent key there. If there is, it will use
that. If there isn't, it will start walking backwards on the stack of _active_ that. If there isn't, it will start walking backwards on the stack of _active_
layers to find the highest one with a non-transparent key. The first one it layers to find the highest one with a non-transparent key. The first one it
finds is whose key it will use. If it finds none, then a transparent key will finds is whose key it will use. If it finds none, then a transparent key will
act like a blank one, and do nothing. act like a blank one, and do nothing.[^1]
It is important to note that transparent keys are looked up from active layers It is important to note that transparent keys are looked up from active layers
only, from most recently activated to least. Lets consider that we have three only, from most recently activated to least. Lets consider that we have three
@ -140,3 +140,7 @@ look there first. If we activate layer 1 as well, then - since now layer 1 is
the most recently activated layer - the firmware will look the code up from the most recently activated layer - the firmware will look the code up from
layer 1, without looking at layer 2. It would only look at layer 2 if the key layer 1, without looking at layer 2. It would only look at layer 2 if the key
was transparent on layer 1. was transparent on layer 1.
[^1]: Except that the base layer is always active implicitly, so if all active
layers are transparent for a particular key, its value will come from the
base layer.

Loading…
Cancel
Save