Kaleidoscope/docs/layers.md

# Layers

Layers are an integral part of Kaleidoscope, but a part that is perhaps harder
to master than many other things in the firmware. On these pages, we'll make an
attempt at explaining layers, what you can do with them, how, and a few common
use-cases.

We'll start with a quick use-case guide, before diving deeper into explanations!

## How do I...?

### How do I switch to a layer, so I can type multiple keys from there?

You can use `LockLayer(n)` or `MoveToLayer(n)`, depending on whether you want
other layers to be active at the same time or not. `LockLayer(n)` allows you to
build up a stack of layers, while with `MoveToLayer(n)` only the selected layer
will be active, without any stacking.

### How do I do make layer switching act similar to modifiers?

If you want the layer switch to be active only while the key is held, like in
the case of modifiers, the `ShiftToLayer(n)` method does just that.

## Layer theory

First of all, the most important thing to remember is that layers are like a
piece of foil, you can place many of them on top of each other, and see through
uncovered parts. In other words, you can have multiple layers all active at the
same time! As we'll see a few paragraphs later, this can be a very powerful
thing.

To better explain how this works in practice, lets look at what layer-related
keys we can place on the keymap first. Armed with that knowledge, we'll then
explore a few use-cases.

## Layer keys

- `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
  we release the layer key meanwhile. Think of it like a `Caps lock` or `Num
  lock` key.
- `ShiftToLayer(n)`: Unlike `LockLayer`, this only activates the layer until the
  key is held. Once the key is released, the layer deactivates. This behaviour
  is very similar to that of modifiers.
- `MoveToLayer(n)`: Moving to a layer is very similar to locking it, the only
  exception is that moving disables all other layers, so only the moved to layer
  will be active. This allows us to have a less powerful, but simpler way of
  dealing with layers, as we'll see below.
- `Key_KeymapNext_Momentary` / `Key_KeymapPrevious_Momentary`: These activate
  the next or the previous layer, momentarily, like `ShiftToLayer(n)`. What it
  considers `next`, is one layer higher than the currently highest active layer.
  Similarly, `previous` is one below the currently highest active layer.

## Use cases

### Locked layers

Locked layers are most useful when you'll want to spend more time on the target
layer. One such case is the numpad: when using it, we usually want to enter
longer numbers, or use the mathematical operator keys as well. Just imagine
hitting a layer lock key, and the right half of your keyboard turning into a
numpad! It's closer than the numpad on traditional full-size keyboards, thus
less hand movement is required!

### Shifted layers

There are many great examples for shifted layers, such as a symbols layer. Lets
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
the like are often used in programming. Having them on the home row is
incredibly convenient. In most cases, we only need this layer for a very short
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
modifier.

As a concrete example, lets 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
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
input `{`, we'd press `Fn + d`, for example. This is still two presses, very
much like `Shift + [`, but the keys are more convenient, because we use stronger
fingers to press them.

Another - and perhaps an even better - example would be a navigation layer, with
cursor keys laid over `WASD`. The reason why this would be a better example, is
because in this case, we often want to use modifiers along with the cursor keys,
such as `Shift` or `Control`. With a shifted layer, if we have transparent keys
at positions where the modifiers are on the base layer, we don't have to repeat
the modifier layout on the shifted layer! This makes it easier to experiment
with one's layout, because if we move modifiers, we only have to do that on one
layer.

### Moving to layers

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
back to wherever we came from, we can't use `UnlockLayer(n)`, because no other
layers are active. We explicitly have to use _another_ `MoveToLayer(n)` key if
we want to move elsewhere.

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
active at any given time. It's a simpler concept to grasp.

## Layers, transparency, and how lookup works

The thing that confuses many people about layers is that they can have
transparency. What even is a transparent key? Remember the first paragraphs:
layers are like a foil. They're see-through, unless parts of it are obstructed.
They're like overrides. Any layer you place on top of the existing stack, will
override keys in the layers below.

When you have multiple layers active, to figure out what a key does, the
firmware will first look at the key position on the topmost active 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_ 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 act like a blank
one, and do nothing.

It is important to note that transparent keys are looked up from active layers
only, from highest to lowest. Lets consider that we have three layers, 0, 1,
and 2. On a given position, we have a non-transparent key on layers 0 and 1, but
the same position is transparent on layer 2. If we have layer 0 and 2 active,
the key will be looked up from layer 0, because layer 2 is transparent. If we
activate layer 1 too, it will be looked up from there, since layer 1 is higher
in the stack than layer 0.

As we just saw, another important factor is that layers are ordered by their
index, not by the order of activation. Whether you activate layer 1 or 2 first
doesn't matter. What matters is their index. In other words, when you have layer
0 and 2 active, then activate layer 1, that is like placing the layer 1 foil
between 0 and 2.

A side-effect of this is that while you can activate a lower-indexed layer from
a higher index, the higher indexed one will still override the lower-indexed
one. As such, as a general rule of thumb, you want to order your layers in such
a way that this doesn't become a problem.

This can be a little confusing at first, but it is easy to get used to with some
practice. Once mastered, layers are an incredibly powerful feature.

Nevertheless, we have the `MoveToLayer(n)` method, where only one layer is ever
active. This way, we do not need to care about transparency, and we can freely
move from a higher layer to a lower one, because the higher one will get
disabled, and will not be able to shadow the lower-indexed one.