Allow the ability to distinguish between key presses and key repeats

[SaschaCowley]

Related issues, PRs or discussions

#20750

What is the current state of the codebase?

It is currently not possible to distinguish between keyboard input generated by the user pressing a key, and that generated by system key repeat when they continue to hold a key down.

Why are changes required?

For some scripts, it may be desirable to only perform an action when the gesture that triggered the script is first performed, even if the key combination is held down.

What technical changes are required?

Both options:

• Add an isAutoRepeat: bool = False attribute to inputCore.InputGesture.
• Modify keyboardHandler.internal_keyDownEvent to keep track of the most recent non-modifier key. When building the InputGesture, if the current set of modifier and non-modifier keys is equal to the previous set of modifier and non-modifier keys, set isAutoRepeat = True.
• Ensure that keyboardHandler.internal_keyUpEvent unsets the non-modifier key when released.

Then, either:

• Scripts that wish to perform an action only on the initial press of a key can return early if gesture.isAutoRepeat == True; or
• Alternatively:
  • Add the ability for scripts to specify whether they should be executed for system key repetitions. For instance, with a allowOnRepeat: bool = True parameter to scriptHandler.script.
  • Update inputCore.InputManager.executeGesture to skip gestures where gesture.isAutoRepeat and not gesture.script.allowOnRepeat.
  • The isAutoRepeat attribute could be made internal if this approach is taken.

Are the proposed technical changes API breaking?

No:

• The modifications to inputCore.InputGesture are additive;
• The modifications to keyboardHandler.internal_keyDownEvent and internal_keyUpEvent only affect the types of state it tracks, which will be held in new module-scoped variables.
• If scripts have to manage this themselves, the change is opt-in only; the default behaviour remains the same.
• If a new parameter is added to scriptHandler.script, its default maintains the current behaviour; scripts must opt in to the new behaviour explicitly.

Are there potential risks or issues with the proposed implementation?

Involves a new module-level variable in keyboardHandler.
The new logic should be reviewed carefully; mistakes in the keyboard proc have the potential to render the keyboard unusable.

[CyrilleB79]

If you only filter auto (system) repetition) but not manual ones, allowOnAutoRepeat would be best suitable.

[SaschaCowley]

@CyrilleB79 my thinking is that this would only identify system-generated key repeats (i.e. from holding down the same key combination).
My preference would be for this to be a script property, though making this a property of the gesture is more akin to the way the script repeat count works. That being said, I'm not a fan of the way we handle multi-press gestures (not that I have a concrete idea of how to do it better).

[CyrilleB79]

Yes @SaschaCowley that's what I had understood. My previous comment was just about the name since only system key repeatition was involved.

[LeonarddeR]

Some random thoughts.

1. I think isAutoRepeat should be public, were it only for the fact that some braille displays support auto repeat. I at least know that ALVA BC6 does so. Drivers setting the new boolean get the benefits for free.
2. Please also consider key repeat for braille gestures #17891. That makes me think that it doesn't make a difference whether a gesture is either auto repeated by its source (Windows auto repeat or Alva BC6 auto repeat) or whether the repeat is generated by a display driver itself (e.g. a driver emitting additional gestures for keys behing held).