feat(fake-keys): add fake keys feature

[jtroo]

This commit adds full functionality of the fake keys feature. Examples
and descriptions of intended use cases are added to the kanata.kbd file.

Closes #80

[mklcp]

Hey, just a quick question on fake keys: what is the use of the block deffakeys?

For the few use cases I've seen, it's always

• Define some alias that are based on real keys, e.g.

  ctl lctl
  sft lsft
  lsft lsft
  met lmet

However the fakekey aliases don't really create a new virtual key (as described in #230), and most of the time they are straightforwardly based on existing keys, e.g. ctl for lctl

• Use on-press-fakekey or on-release-fakekey either in a defalias or a deffakekeys block. But why not only allow them in defalias? That would be more simple.

So as far as I understand, fakekeys don't create a new virtual key, they just define a custom action with on-press-fakekey or on-release-fakekey.

In (on-press-fakekey ctl release), it's the whole expression in-between parentheses that is a fake key, in the same way that (tap-hold 200 200 a @num) creates a "fake" key that taps a or @num according to timeouts.

So I read (defalias fcr (on-press-fakekey ctl release) as create a fake key named fcr that, when pressed (and only when pressed), release the ctl key (which is based on lctl).

If all of this is correct, the code could be simplified by removing the deffakekeys block.

In #80, you said it made more sense regarding how keyberon works, to NOT separate the prososed press-only/release-only/tap part from the on-press/on-release.
I agree with you, and I'm not saying that they should be separated. I just note that, despite being currently tied together, the syntax could be simplified.

fakekeys would still be able to take complex actions as arguments, everything would just be defined in defalias.

[jtroo]

So I read (defalias fcr (on-press-fakekey ctl release) as create a fake key named fcr that, when pressed (and only when pressed), release the ctl key (which is based on lctl).

This is not a correct understanding of the implementation.

The purpose of the deffakekeys block is to give a label to the keyberon layout position that is associated with the action corresponding to said label.

So in (on-press-fakekey ctl release), it is not the whole action that is the fake key. It is only ctl.

Similarly in (defalias fcr (on-press-fakekey ctl release)), the way this is currently parsed, fcr is a label for the entire action, which can be assigned to real key positions. fcr is placed in a HashMap cache for easy assignment to any number of key positions, though usually it is only one. But if fcr is never assigned to a key position, then it does not exist anywhere in the keyberon layout. Aliases are a configuration parsing concept rather than a keyberon state concept.

---

A different example to illustrate:

(defcfg)

(deffakekeys
  hello (macro h e l l o)
  bye (macro b y e)
)

(defsrc 
  1 
  2
)

(defalias
  @one (on-release-fakekey hello tap)
  @two (on-release-fakekey bye tap)
  @three (macro o h spc n o)
)

(deflayer default 
  @one 
  @two  
)

• (on-release-fakekey hello tap) gets placed in the keyberon layout at the position associated with the real 1 key.
• (on-release-fakekey bye tap) gets placed in the keyberon layout at the position associated with the real 2 key.
• (macro o h spc n o) does not exist anywhere after the configuration is parsed and processed
• (macro h e l l o) gets placed in the keyberon layout at a non-pressable-by-real-keys position, i:1, j:0.
• (macro b y e) gets placed in the keyberon layout at a non-pressable-by-real-keys position, i:1, j:1.

---

So maybe I'm misunderstanding something in your comment - in the proposed removal of deffakekeys, how would the implementation consistently determine the layout position of hello that should be acted upon by (on-release-fakekey hello tap)?

Or perhaps you're suggesting that defalias be used to allow shortcuts, and also be used to address the fake key position? If so, to me that seems like it might get confusing, and I would prefer the separation of concepts.

[mklcp]

Or perhaps you're suggesting that defalias be used to allow shortcuts, and also be used to address the fake key position? If so, to me that seems like it might get confusing, and I would prefer the separation of concepts.

What I don't understand is what is the interest of doing all of this. All your explanations highlight how an alias and a fake key have a different implementation. Then you say, they ought to get a different syntax. But conceptually, I don't see many differences, and I don't understand what is the point of having (macro h e l l o) getting placed "in the keyberon layout at a non-pressable-by-real-keys position". From the point of view of the user, it seems to me that what matters is what kanata outputs, not whether it's processed in a keyberon layer or as a custom action.

[jtroo]

One advantage: when the configuration matches the model more closely, it's easier to implement, there's less code, which means fewer chances to introduce bugs.

Since the idea of fake keys, which is primarily for release-only/press-only keys or for usage by defseq, is already fairly advanced (in my opinion of course), it doesn't seem high priority to me to improve its ergonomics. In addition, a configuration is used far more often than is written, so some friction in configuration, as long as it works, is acceptable to me.

If you or someone else is willing to volunteer their time to improve the ergonomics of this feature or any others, PRs are very welcome!

[mklcp]

That makes sense. I'll see for improving ergonomics but as you said, just set up a working configuration and forgetting about it is easier !