Fake key renaming / semantics

[crantok]

I started using kanata last week and I am loving the power it gives me over my keyboards.

I implemented Shift Lock using deffakekeys, as advised. My implementation works well and I've included that code below. As a result of that, I am curious about a couple of things. My questions are me trying to scratch an itch. They are not things I need answers to in order to use kanata, so this is low priority.

1. From programming Visual Basic back in the 20th century, on-press-fakekey looks like the name of an event handler to me, but I am actually using this function to trigger an event (a key press.) Is there an intentionality in this naming that I am missing?
2. To press a key I have to call on-press-fakekey and give it the name of a fake key (which is an alias of another key) but to release that same key I have called release-key with the non-fake key name. What is the reason for requiring that key presses are done with fake keys while releases can be done with either fake or non-fake keys?

(deffakekeys
  shift lshift
)

(defalias

  shlok
    (fork
      (tap-hold
        150
        150
        (multi
          (on-press-fakekey shift press)
          (cmd bash -c "notify-send -u critical -r 101 'Shift Lock is ON!'")
        )
        lshift
      )
      (multi
        (release-key lshift)
        (cmd bash -c "notify-send -u normal -r 101 'Shift Lock is off.'")
      )
      (lshift)
    )

)

[jtroo]

The reasoning behind the naming is that there is an on-release-fakekey counterpart that also activates a fake key action (tap/press/release/toggle) which activates when the key is released. In that sense the on-press and on-release actions are event handlers for the press and release of the defsrc key they are associated to, with the fakekey part of the name meaning that the event handlers will then trigger an action on fake keys.

[crantok]

That left me with more questions than I had before, so I went back and looked at the docs again and that led me to #80. If I understand correctly, on-press-fakekey is setting the state of the fake key defined in deffakekeys to pressed and simultaneously executing an action. That's not event-handling in the sense that I've understood it, but maybe that's not important.

Is it a problem that I never release my fake key above? I haven't noticed any unwanted behaviour, but I wonder whether that's because my example is simple.

Thinking about the original rationale for fake keys, it was specifically about being able to respond to a key release. My code is about emitting a press and release (at different times) of a real key, which seems to be something different, but uses the fake key system anyway. I guess I'm not going to understand this unless I start looking at the moving parts, so in my head I will label this as "It's complicated" and just accept the fact that it works.

[jtroo]

on-press-fakekey is setting the state of the fake key defined in deffakekeys to pressed

That's not an accurate description. When the key associated with the action is pressed, on-press-fakekey applies the action on the defined fake key.

In your sample you have:

(on-press-fakekey shift press)

I think the confusion might be that your current use case just so happens to be described by the inaccurate description - which does not hold in general. To give some hopefully clarifying examples, this could also be (on-press-fakekey shift release), (on-press-fakekey shift tap), or (on-press-fakekey shift toggle). on-press vs. on-release is when the action happens, the 1st parameter is the fake key being operated on, and the 2nd parameter is the action actually taken.

[jtroo]

I suppose another confusing factor is:

What is the reason for requiring that key presses are done with fake keys while releases can be done with either fake or non-fake keys?

Your use case happens to be doable with either action. But a fake key might be associated with an action that is not releasable by release-key, for example mlft or macro-repeat.

[crantok]

on-press-fakekey is setting the state of the fake key defined in deffakekeys to pressed

That's not an accurate description. When the key associated with the action is pressed, on-press-fakekey applies the action on the defined fake key.

I beg your pardon, I did not express myself well. I meant: "If I understand correctly, on-press-fakekey as I'm using it in my code is setting the state of the fake key shift to pressed..."

The reasoning behind the naming is that there is an on-release-fakekey counterpart that also activates a fake key action (tap/press/release/toggle) which activates when the key is released. In that sense the on-press and on-release actions are event handlers for the press and release of the defsrc key they are associated to, with the fakekey part of the name meaning that the event handlers will then trigger an action on fake keys.

I understand this now. I think I would have got there much quicker if
(on-press-fakekey <fake key name> <key action>): Activate a fake key action when pressing the key mapped to this action.
was instead expressed as
(on-press-trigger-fakekey-event <fake key name> <event type>): Trigger an event on a fake key when pressing the defsrc key mapped to this action.

Also, it might have helped to include an example where the fake keys did not ultimately map directly to defsrc keys, and showed both press and release events being handled on a single defsrc key, e.g...

(deffakekeys
  foo (macro f o o)
  bar (macro b a r)
)

(defalias
  foobar (multi (on-press-fakekey foo tap) (on-release-fakekey bar tap))
)

(defsrc
  q
)

(deflayer use-fake-keys
  @foobar
)

[jtroo]

Naming as usual is one of the hard problems of computer science 😉. I don't think I would have chosen the suggested name though, it's nearly twice as long haha, and the extra clarity would need to be balanced against the verbosity when writing the config.

Though I suppose we could use both names that refer to the same function too.

PRs to improve documentation and examples are very welcome!

[crantok]

I'm a big fan of self-documenting code. I've not understood the widespread desire for terse function names since the first time someone pointed out one of mine that could have been more expressive. I would be very happy to submit a PR for a documentation change.

…

On Wed, 28 Feb 2024, 01:31 jtroo, ***@***.***> wrote: Naming as usual is one of the hard problems of computer science 😉. I don't think I would have chosen the suggested name though, it's nearly twice as long haha, and the extra clarity would need to be balanced against the verbosity when writing the config. Though I suppose we could use both names that refer to the same function too. PRs to improve documentation and examples are very welcome! — Reply to this email directly, view it on GitHub <#790 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AADMEDHHO73SNU4SO76LNN3YV2CHVAVCNFSM6AAAAABD32MYPCVHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM4DMMJSGI2TI> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[gerhard-h]

I think renaming the whole fake-key stuff in not a bad idea, because the name fakekey itself has no meaning, that tells us something about its use cases. Also for us users fake keys are very real (maybe keyberon thinks differently) and don't deserve its diminutive name.

I'll just start brainstorming:
fake keys -> named events or event keys ...
deffakekeys -> defevent
(on-press-fakekey mykey toggle) -> (event-on-press mykey toggle) or (on-press-handler mykey toggle)

But with this syntax, it is not obvious at first, why naming your events like keys is still a smart thing to do.

[crantok]

If this is an overly emotive subject then please ignore this comment: I'd be interested in anyone's thoughts about why long names are a bad thing. My view has tended to be that finding something that is intuitive to 80% of new users eclipses concerns about name length.

[jtroo]

No worries.

Opinions all mine of course.

It's about the externalities to the words/names themselves. Some disorganized thought:

When writing and reading in the actual file, how many tokens with significant meaning can I fit onto a single line? Too few significant tokens per line makes it verbose and a chore to read - I have to scroll lines more and there's less meaning on a given page. Too many is hard to interpret what's going on.

A balance does need to exist between terse naming and descriptive naming, and it's subjective where the good balance point is.

[rszyma]

I'd be interested in anyone's thoughts about why long names are a bad thing

in this particular case, "virtual" isn't a long word alone, but "deffakekeys" is already pretty long cluster of letters and "defvirtualkeys" would be even longer. One could argue "why not use _ or - between the words" to make it easier to read, well it could be "def-virtual-keys" but that would break consistency with other existing top-level construct names.

[crantok]

I know this is going to sound pedantic, but your answer doesn't actually say anything about why long would be bad.
Subjectively: I find defvirtualkeys easier to read than deffakekeys. I think it's the "ff" and "keke" in the latter that slows me down. YMMV.

[rszyma]

I know this is going to sound pedantic, but your answer doesn't actually say anything about why long would be bad.

To answer this directly: long isn't bad, but if it can be short and be equally precise then short is better, because it's faster to read and write.

Subjectively: I find defvirtualkeys easier to read than deffakekeys.

If you think "virtual" is both more readable and more precise, that indicates we potentially found a great candidate to replace "fake".

[crantok]

The alternate defalias syntax proposed is not consistent with the rest of defalias usage. If this is a single-responsibility declaration of a fake key, @shift and @foo are not usable in deflayer whereas all other aliases are.

Ah! I see. That makes a lot of sense. Thank you.

[jtroo]

Random thought that popped into my head:

I am quite fond of the way the present action reads when taken literally, left-to-right. I don't recall if this was by accident or had some intent behind it.

To clarify though, not to the specific word choice - e.g. I'm not attached to "fake" in any way.

(defalias
  tap-foo-on-press (on-press-fakekey foo tap)
  toggle-foo-on-release (on-release-fakekey foo toggle)
)

Reading (on-press-fakekey foo tap) left to right,

• on-press: when I press this
• -fakekey foo: I will, to fakekey foo,
• tap: tap it

Reading (on-release-fakekey foo toggle) left to right,

• on-release: when I release this
• -fakekey foo: I will, to fakekey foo,
• toggle: toggle it

[crantok]

That's great once you know (and remember) what those functions are for, but the words in the function names have higher visual binding than the arguments, so on-press-fakekey ... looks more like "when a fake key is pressed, do something."

[jtroo]

the words in the function names have higher visual binding than the arguments

Great point!

[gerhard-h]

o on-press-fakekey ... looks more like "when a fake key is pressed, do something."

maybe not putting the argument typ in the function name like
on-press-fire or on-press-trigger or on-press-do or on-press-event or just on-press helps

maybe moving the argument into the function name like
on-press-press,... or on-press-do-toggle,...
with the only argument being a event key or a statefull key, eventfull key, trigger key, fire key

[crantok]

I am quite fond of the way the present action reads when taken literally, left-to-right. I don't recall if this was by accident or had some intent behind it.

I'm so glad you made this explicit because I woke up this morning with this...

(on-press toggle-fakekey foo)

[rszyma]

regular typing can interfere with the intended effect and cause undesired behaviour

I'm failing to think of a way it potentially could interfere differently than acting on a fakekey controlling bare key already could. Could you provide an example where such interference would happen?

[jtroo]

(on-press press-key lctl)

The way this would work under the hood is to press the lctl key position in the keyberon layout. When the physical key is pressed then released, a release event is sent to the keyberon state for the same layout position and the earlier state will be cleared, and a release event sent to the OS - potentially undesired effect.

(deffakekeys lctl lctl)
(on-press press-fakekey lctl)

This does not have the same issue. Pressing/releasing/tapping the physical lctl key does not inherently interfere with the fake key's layout position.

[rszyma]

The way this would work under the hood is to press the lctl key position in the keyberon layout. When the physical key is pressed then released, a release event is sent to the keyberon state for the same layout position and the earlier state will be cleared, and a release event sent to the OS - potentially undesired effect.

Thanks for explaining this. But why would that be an undersirable effect?

Pressing/releasing/tapping the physical lctl key does not inherently interfere with the fake key's layout position.

Based on what I understand that you're saying right now, the config in top comment should't work, because release-key shouldn't interfere with the state of fakekey (specifically pressed/unpressed state), and by the fact that it is never released, it can't be re-pressed, therefore the underlying key can't be re-pressed. But it apparently works? Where am I wrong?

[jtroo]

release-key operates on keycode states and not on layout positions, which is why it works.

One example why it is undesirable is that without fake keys, it is Impossible to make the physical lctl key be a press-only or toggle for itself - if one desired that.

Another odd (to me) effect would be that the output behaviour of press-key would be implicitly active-layer dependent, whereas fake keys are the same on every layer.

[jtroo]

To me, reading press-key lctl or perhaps only-press lctl suggests the keycode and not the keyberon layout position, but the implementation I would be willing to do is to operate on layout position.

This discrepancy to me would be undesirable.

But perhaps someone else would be willing to put in the work to make this sensible, e.g. implicitly generate fake keys with only-press, or some other design.

[jtroo]

Implemented in #852 (no documentation updates yet). Will leave open for a while for feedback. Taken from the tests, the syntax looks like below.

examples of new syntax

  (on-press   press-virtualkey hello)
  (on-press release-virtualkey hello)
  (on-press  toggle-virtualkey hello)
  (on-press     tap-virtualkey hello)
  (on-press   press-vkey bye)
  (on-press release-vkey bye)
  (on-press  toggle-vkey bye)
  (on-press     tap-vkey bye)
  (on-release   press-virtualkey hello)
  (on-release release-virtualkey hello)
  (on-release  toggle-virtualkey hello)
  (on-release     tap-virtualkey hello)
  (on-release   press-vkey bye)
  (on-release release-vkey bye)
  (on-release  toggle-vkey bye)
  (on-release     tap-vkey bye)
  (on-idle 100   press-virtualkey hello)
  (on-idle 100 release-virtualkey hello)
  (on-idle 100  toggle-virtualkey hello)
  (on-idle 100     tap-virtualkey hello)
  (on-idle 100   press-vkey bye)
  (on-idle 100 release-vkey bye)
  (on-idle 100  toggle-vkey bye)
  (on-idle 200     tap-vkey bye)

Something notable is that on-idle moves the number parameter representing milliseconds to the first parameter rather than the last, to make it more sensible (in my head at least) when reading left-to-right. i.e.

• on-idle
• for 100ms
• press-vkey
• keyname

But perhaps this change is not worth the change from before. For example, for those that want to migrate configurations, so I'm questioning if I should keep the changed order or keep the order the same as the original.

As an aside here's a vim command to migrate config (basic tests):

vim substitute cmd

:%s/\von-idle-fakekey\s+(\w+)\s+(\w+)\s+(\d+)/on-idle \3 \1 \2/

[crantok]

Love it.

Your new on-idle argument order looks great to me. (This is not functionality that I have used yet.)

[gerhard-h]

I prefer the new idle-timeout position