…which does exist. Oops.
Actually, I think the one that is more misleading is ShiftToLayer(), which really implies that only one layer is active at a time.
1 Like
I have a MagicCombo set up to switch layouts, since it’s not something I do often enough to warrant dedicating a whole key to it; looks like this
2 Likes
I agree that the wording doesn’t convey unambiguously.
My metaphor for the keymaps is like a kids picture book with transparent overlay pages, but of course that fails because with a keymap stack you can apply each layer independently without the ones below it, while in a picture book if you are looking at layer 3 then layers 1 and 2 are also active.
A metaphor of a stack of layers with toggle switches would more closely reflect the design than my picture book, so I see the merit of “Toggle.”
However, the metaphor is a bit weak it the sense that it doesn’t evoke a physical analog, and so isn’t viscerally compelling for folks. No one is likely to have an “aha” moment about toggle switches and layers. It’s more correct but less evocative.
I will noodle. What comes immediately to mind is Russian dolls, with the inner doll being zero and the ability to surround zero with an arbitrary set of larger dolls in a fixed order, but adding the third dimension muddles things.
I can imagine transparencies on a pivot that can be rotated in and out independently, but can’t think of a real world object that works that way. Has to be something.
1 Like
The reason “ToggleLayer” works better than “LockLayer” for me is that for each layer, that function reverses the layer’s state, which matches common usage of the verb “to toggle”. The opposite of “toggling” something is to “toggle” it again, whereas the opposite of “locking” is “unlocking”. If I lock my door, then lock it again, it isn’t unlocked. But if I toggle a light switch to turn it on, then toggle it again, the light turns off.
Regarding the layer metaphor, it’s quite intuitive to me, but mostly because of vector graphics and photo editing, not real-world objects. I do feel that while the concept of “toggling” layers doesn’t directly promote understanding of the layer stack and masking structure, the “LockLayer” and “ShiftToLayer” names can be actively misleading.
2 Likes
I understand where you’re coming from. I’ll continue to ponder naming, but I don’t expect to make any changes soon. If I’m going to change those names again or add synonyms, I really, really only want to do it once. If we changed to use “ToggleLayer” instead of LockLayer, would you rename ‘ShiftToLayer’?
@algernon and I have been trying to talk through the merits of having layers act as overlays at all in the default case. It’s a powerful feature, but adds both conceptual complexity and runtime complexity. If we can figure out a way to handle the ‘interesting’ use cases that folks are currently using a stack of ‘overlay’ layers for, I personally, would really like to see the feature moved out to a non-default plugin.
One of Kaleidoscope’s goals is to be easy for beginners to get their heads around. Nobody believes we’re there today or that we’ll be there next week. But, long term, it’s what I’m shooting for.
One thing that can help achieve that is having a small, clean, well-factored core and moving complex behavior into modules that have well-defined APIs. The current stacked layers system is relatively complex and is something that 95% of users are unlikely to need. To be clear, the feature won’t get pulled out of Kaleidoscope’s core unless we can figure out a way to get the functionality we currently offer.
3 Likes
I actually like ShiftToLayer a lot more than LockLayer to me means, lock my layer and do not switch it to anything other than the fn layer, it also means, disable NumLock. LockLayer could be thought of as most restrictive while allowing pass thru for fn layer(s). If I want to switch to another layer, then I have to unlock the current layer I’m in to allow it to be switched.
I can already see my co-workers messing with my M01 and accidentally switching to another layer (improbable but not impossible).
Whereas LockToLayer would switch to another layer AND lock it at the same time. Necessary? Probably not at the moment, but think 20-25 years later and what if the M01 or M01 variants become as ubiquitous as 104s? I can only see security increasing and input devices getting “intelligent” or more aware of their state as time progresses.
If I were naming those functions, and didn’t have to deal with any refactoring, I’d call them “ToggleLayer” and “ShiftLayer” (dropping the “To”). I’m not convinced that it’s worth the time it would take, though. Also, I would probably choose different names for lots of other functions, at least some of which I know you and @algernon have already put some thought into, so this may just be a matter of different personal preferences. I certainly don’t think you should change anything just based on my preferences — I am clearly an outlier here in many ways.
I see what you mean about the conceptual complexity of the stacked, masking layers, but I would be sorry to see it go. I can think of a couple of use cases where it helps; if I have some time to write those up coherently, I will.
I’m fine with dropping the “To”, whatever the convention is, we should adhere to that as much as possible. I don’t think Jesse wants to change anything to anyone’s whims, rather he wants us to engage in this type of dialogue, because not all users are gonna be uber geeks, I’m certainly not one of them. So I think the ultimate goal is to make M01 and modding it accessible for the enthusiast(s) and not just the experts. Hence my $.02. I tend to read things (especially in regards to online/text only communication) in a monotone as to not inject my biases or preconceived notions into what may or may not be there (intended by the authors of their posts).
This is all new to everyone I’m sure, some confusion and growing pains are probably in store for us but with all the brain power behind this project, I have no doubts it’ll be fine.
Just to clarify, we’ve mostly been discussing the names of the two functions, not what they do.
LockLayer(N) turns on layer “N” if it was off, and turns it off if it was on. (Edit: I originally wrote “if it was off”, which was wrong)
ShiftToLayer(N) turns on layer “N” while the key is held down, and turns it off when that key is released (with a few caveats).
I brought up the subject of these names because it sounded like someone was confused about the functions (and how layers work in Kaleidoscope), possibly in part because of the names.
Aren’t both equally important? Again, what is our intended audience? A name should be reflective of what it does, this would make things more intuitive, is that what we’re trying for?
Now I’m confused. If I turn something that was off, off, aren’t I turning it on? Turning the off switch to off is turning it to on. It’s like disabling the off state.
ok…
state on:
enable = on, nothing changes
disable = turn on to off, state change from on to off
state off:
enable = off, nothing changes
disable = turn off the off state, change from off to on
state unknown or zero or not set:
enable = turn on
disable = turn off
I’m gonna have to go eat some ice cream after this…
Sorry; that was a typo: it turns it off if it was on. LockLayer always changes the on/off state of the target layer.
(we actually have an UnlockLayer() that’s a synonym for LockLayer(). I’d thought that promoting it would cause more confusion than it solved)
If that’s the case and I only have two layers + fn and num, then I’d personally prefer toggle. My default layer is Dvorak, with a secondary of QWERTY. Then ToggleLayer turns on QWERTY and ToggleLayer turns off QWERTY, returning me back to my default layer (Dvorak).
But in all reality, if its well documented and there are read me files (with examples), then most folks can probably figure it out. Average user, probably not.
LockLayer does just that, locks it down from being manipulated, with the exception of ShiftToLayer. Hitting LockLayer again, would not toggle it off, it would just keep it locked. You would need the sequence mapped to UnlockLayer to unlock the M01 to switch layers. If requiring an UnlockLayer key sequence to be defined and used is too risky, then LockLayer would just toggle locking the M01 on and off, the other option is if no UnlockLayer is defined, then LockLayer would default to acting as a toggle switch. Whatever Jesse decides is fine, I’m just here for the keyboard.
I can’t tell if you’re describing how you think it works, or how you think it should work. Or if you’re just talking about how you think functions with those names ought to work.
@jesse, maybe it would be useful to have a function named SwitchToLayer(N) which activates layer N (regardless of its previous state), and deactivates all layers higher than N. Its momentary counterpart could be ShiftToLayer(N), which would do the same, but only while the key is held. Of course, that would be more involved than the current functions, because it would have to store the previous layer state in order to restore it on release, but if people start having difficulty understanding the layer masking, it might make things easier. The more basic functions that just switch layers on or off (or toggle them) would still be accessible for people who want to take full advantage of layers, of course.
As it is, one could create a sketch where a key defined as LockLayer(N) has no visible effect because it’s on a layer above N that completely masks it, but when that higher level is switched off, the keyboard might be in a surprising state because layer N has been turned on and off an unknown number of times. And the current ShiftToLayer(N) might have no effect at all from a higher layer, or even more surprising — some keys might seem to work, but others don’t, or are (apparently) unpredictable (because sometimes ShiftToLayer(N) gets called from N+1, and sometimes from N-1 when N+1 is off…
1 Like
My gut feeling is that before we extend the API further, we need more concrete use cases and specific examples of things that are difficult with what we have now.
3 Likes
haha. My apologies Mike.
How I think it should work.
What I envision is LockLayer as a security/anti-tampering feature. It simply locks whatever layer is active so that if you or another user were to try to “switch” to another layer, it wouldn’t work. However, it would still allow you to ShiftToLayer (allowing use of the fn keys). Hope this helps clarify.
How algernon explains it, I think it works as a toggle. I haven’t had a chance to try it yet though.
Well, the “lock” is meant to evoke “Caps Lock” and “Num Lock”, in the sense that you don’t have to hold down the key, rather than a “lockout” to prevent someone from messing up your keyboard. But that’s less interesting to me than the bit about “whatever layer is active”, which implies that you’re thinking of it as having only one active layer at a time, which is not how Kaleidoscope layers work.
Maybe most people wouldn’t notice, because they’ll just use the default keymap or make just a few simple changes, but if a user wants to do something complex, it might require a better understanding of how layer masking works, because without that a key defined on layer 5 as ShiftToLayer(4) could be a major source of frustration because it appears not to work.
Ahh, I see your point. Base layer would have been more accurate or appropriate. To me, its minor semantics. When I think active, I’m actually thinking what “state” is my M01 in. QWERTY is the default state, pressing fn overlays a layer over my base -my default state, fn + bksp = delete, and not bksp because the fn layer takes precedence, therefore my base layer is no longer active, if the fn layer is active, anything not defined by the function layer will default back
to the base layer (q is not defined in my fn layer, so pressing “q” in QWERTY gets me “q”, but pressing fn + q still nets me a “q”). To me, you can’t have two things active at once, how would Kaleidoscope know if I want backspace or delete?
I’d have to ask Jesse. When we press space on our M01, it sends a space to the OS. When we press fn + space, it sends an enter to the OS. I know its defined via keymap, but please elaborate. Is the M01 sending an enter as defined via key map, or is it taking the space and transforming it to an enter, then sending it to the OS?
Keymaps are a couple abstraction layers away from the string of bits that get sent to your computer when you press a key.
When you press a key or a chord of keys the firmware takes that pattern of keypresses, compares it to the currently active stack of keymaps, and determines what code to send to the computer.
So whether you press the SPACE key or FN+SPACE the job of the firmware is to interpret your keypress into a string of bits. It’s not “taking the space and transforming it,” it’s taking a keypress or chord and translating it.
3 Likes