Consistency in transparency in keymaps

I’m looking at the Model01-Firmware.ino with an eye to making any duplicate keys from the QWERTY map transparent, and noticed that the ALT key is different in GENERIC_FN2. In QWERTY it’s Key_LeftAlt, and in GENERIC_FN2 it’s Key_RightAlt. I assume these are identical, and the different definition is accidental?

This does indeed sound like a mistake. I’ve just pushed an update that fixes it.

1 Like

I had assumed it was intentional, as a way to make right alt available for software that distinguishes between the two alt keys (i.e. AltGr).

By default, we map the butterfly key to Right Alt.

On the topic of keymaps and transparency, how do folks visualize this system?

I’m encountering places where 0 is called the highest layer, and others where it’s called the lowest.

Some comments talk about 0 as a base layer with the other layers as overlays, and the base layer keys “shining through” transparent keys in higher layer keymaps. I think this is the most intuitive explanation I’ve encountered, and the easiest to describe and visualize.

It would help with documentation and comprehension if it’s possible to choose one consistent metaphorical direction and standardize on it. Inconsistency in which way is up will end up being as likely to cause confusion as faucets that have the cold tap on the left.

The direction doesn’t matter, and of course there isn’t really an up or down anyway, but the inconsistency is confusing.


I think that 0 should be called the lowest layer, because we layer things on top of it. Within the firmware code, it is already treated as the lowest. My problem with the “base layer” terminology is that it suggests that you can’t turn it off, only apply overlays, which is not the case (although, the number of times one would want to turn it off is… limited). Nevertheless, “lowest layer” is - while appropriate - perhaps not the best way to refer to it. We could call it “default layer”, or “initial layer”, or something along those lines.

All in all, I agree that we need a direction, and in my opinion, that direction is for layer 0 to be the lowest. That makes most sense, and that is in agreement with the code too.

When is it turned off? I’m all for accurate and complete explanations!

I am happy to call it default or initial. I slightly prefer default.

I could mention that the default layer can be changed or turned off, but
only in unusual cases, so let’s ignore that possibility for the purposes of
an introductory explanation.

With the factory firmware, never. But you can create a firmware that turns it off. Off the top of my head, I can’t see why one would want to do that, but it is possible.

Oh, one use-case would be to get the keyboard into a state where the keys do nothing, without having an empty layer. Since you can control the keyboard via a serial protocol (if you have the Focus plugin enabled) it is possible to get the keyboard into this state, and back out of it. As a way to lock the keyboard, for example: all layers disabled on screen lock, re-enabled on screen unlock. Using a security key, you can unlock a screen without a keyboard, so… yeah. That’s one use-case, though a bit… forced.

In other words, this is not something one needs to know immediately, and is best explained later on in a more advanced section. :slight_smile:

1 Like

Another case where someone might want to deactivate all layers:

I had a friend in college who suffered from a wrist RSI and had his Athena account set up to lock the screen every so often to force himself to take typing breaks. Especially with standing desks, I can imagine someone who might want a keyboard that shuts down after a certain period (or pattern) of use, but still allows the user to continue interacting with the computer (screens, pointing devices, alternate keyboard). A timer could be used to restore the previous state.

It’s a bit contrived, but at least plausible, especially if the keyboard in question is plugged into many different systems.

1 Like

The TypingBreaks plugin was created just for this purpose :wink:

Ha! It’s been a while since I looked at the list of plugins. Does TypingBreaks work by deactivating all the layers?

Not quite, but it could, and likely should, because that would make the code perhaps a bit easier.

Edit: scratch that. Turning off layers would be more complicated, because we’d have to remember what layers were active before. On the other hand, it would allow us to be more lax about the plugin use order, and wouldn’t have to put TypingBreaks first for it to work reliably. So maybe it is worth it after all.

1 Like

I would argue that you don’t have to restore state when unlocking from TypingBreaks. If I’ve just been locked out for the default five minutes, chances are pretty good that I won’t remember what layers were active, anyway (other than the “base” layer).

I’m not even sure if most users would prefer to have whatever layers were active to be restored. I don’t even want to guess, since I’m one of the lucky ones who has no need of that plugin…

Yeah, remembering layers is a double-edged sword. There are cases where it is beneficial (when one has app-specific layers, or language-specific ones), and there are cases where it is not.

It would be great if it could correctly guess which layers you’d want when unlocking (anything that’s been active longer than some minimum time, for example), but my instinct is that the best behaviour is to restore previous layer state, but make sure not to end up with locked-on layers that were momentary at the time the lockout started. That seems like it would only require remembering one list (array? bitmap?) of active layers, stored when lockout timer starts, which I’m naïvely guessing isn’t too complex…

Uhhh… momentary layers… those and one-shots would make it much more complicated. So much so that it’s not worth the effort.

Ah. I see. There’s no way for TypingBreaks to know if a layer is OneShot-activated, or momentary (I’m not really sure if “momentary” is actually defined in a special way at all – layers.cpp looks like it’s not, really). Yeah.