Better control over SRShortcutAction triggering policy

[Kentzo]

Currently the shortcut is triggered either by non-modifier key-up or key-down event and additional matching is done by checking the modifier flags. It does not handle modifier-only shortcuts.

Terminology

Shortcut Sequence: sequence of key-down and key-up events from the first key-down through the last key-up
Non-Modifier Key: any other key than NSEvent.ModifierFlags
Modifier Key: any of the NSEvent.ModifierFlags keys
Active Modifier Keys: modifier keys as reported by NSEvent.modifierFlags
Shortcut Sequence Modifier Keys: modifier keys that were pressed within Shortcut Sequence but are currently up
Required Modifier Keys: modifier keys required by the shortcut

Triggering Policies

In examples bellow underscore highlights modifier key events recognized by the policy. bold highlights the key event that triggered policy recognition. strikethrough highlights keys that are ignored by the policy.

Triggered by Non-Modifier Key Down / Up

• When Required Modifier Keys equal Active Modifier Keys:
  shift-a: shift-down-a-down/a-up
• When Active Modifier Keys contain Required Modifier Keys:
  shift-a: shift-down-ctrl-down-a-down/a-up

Triggered by Modifier Key Down

• When Required Modifier Keys match Active Modifier Keys exactly:
  ctrl-shift: ctrl-down-shift-down
• When Active Modifier Keys include Required Modifier Keys:
  ctrl-shift: ctrl-down-cmd-down-shift-down

Triggered by Modifier Key Up

• When Required Modifier Keys contain Active Modifier Keys:
  cmd-ctrl-shift: cmd-down-ctrl-down-shift-down-ctrl-up
• When Required Modifier Keys contain Shortcut Sequence Modifier Keys:
  cmd-ctrl-shift: cmd-down-ctrl-down-cmd-up-shift-down-shift-up-ctrl-up
• When Active Modifier Keys contain Required Modifier Keys:
  cmd-ctrl-shift: cmd-down-ctrl-down-opt-down-shift-down-ctrl-up
• When Shortcut Sequence Modifier Keys contain Required Modifier Keys:
  cmd-ctrl-shift: cmd-down-ctrl-down-opt-down-cmd-up-shift-down-opt-up-shift-up-ctrl-up

Testimonials

@bryanforbes needs to globally handle an exact match of a modifier-only shortcut for both key down and key up.

[lwouis]

It took me a while to really understand what you detailed here. I think it's very nice and complete! I think you should clarify that the 6 options you listed would be parameters set by the library user, to customize the behavior they want on their shortcut.

I have an objection regarding the 3rd section "Triggered by Modifier Key Up". I think the distinction contains vs equals that you made with policies of the first 2 sections is great, and should also be available for the 3rd section. Once the library user has decider if if they want contains or equal for their shortcut, they could also specify the up-trigger policy of "first key" vs "last key". I think it should combine:

	First Key Up	Last Key Up
Contain
Equal

This is how I see section 3:

Triggered by Modifier Key Up

1. When Required Modifier Keys equals Active Modifier Keys, and First Key Up:
   ctrl-shift: ctrl-down-shift-down-ctrl-up
2. When Required Modifier Keys equals Active Modifier Keys, and Last Key Up:
   ctrl-shift: ctrl-down-shift-down-ctrl-up-shift-up
3. When Required Modifier Keys contain Active Modifier Keys, and First Key Up:
   ctrl-shift: ctrl-down-cmd-down-shift-down-alt-up-ctrl-up
4. When Required Modifier Keys contain Active Modifier Keys, and Last Key Up:
   ctrl-shift: ctrl-down-cmd-down-shift-down-alt-up-ctrl-up-shift-up

A little bit more justification for all the use-cases:

• Contain vs Equal. Some users will want an exact match, some will not mind other modifiers being pressed.
  E.g. an app has cmd+v for normal paste and cmd+shit+v for rich text paste. They will want to use Equal here so that normal paste doesn't trigger on cmd+shit+v.

• First Key Up vs Last Key Up. Some users will want to trigger as soon as one key is released, some will want to trigger only once all are released.
  E.g. an app that has 2 modifiers-only shortcut and want the user to quickly alternative. Let's say cmd-alt buys something, and cmd-shift sells something. Here the app may want to let the user hold cmd and alternate between alt and shift to quickly buy and sell.

[Kentzo]

Did a couple of clarifications and added the missing policies you pointed out.

A couple of things:

• key-up cannot be "active" since it's no longer pressed.
• in [3] and [4] I see alt-up but not alt-down in the sequence

[lwouis]

key-up cannot be "active" since it's no longer pressed.

I was not sure what you meant with the underlining. Now you made it clearer. I think there is an issue with the approach though. In almost all policies, you can look at the currently pressed or not-pressed keys when a key triggers a up or down event, and that local context is enough. However, in the Triggered by Modifier Key Up + Last Key Up scenario, there needs to be memory that keys were at one point all down. Then when a key up event triggers, we can compare with that memory. Only once the last key up event trigger, we can say "all the modifiers of a registered shortcut were down at one point, and all these modifiers are up now, so we should trigger the shortcut.

Since that's the only policy that requires a global tracking that the others don't, I would suggest implementing it later potentially. Maybe no actual user need that policy for now. For my app, and I think for @bryanforbes's app, I think First Key Up does the job.

Basically I think it's nice to enumerate all possible cases to be complete, but since these sophisticated policies may require a lot of work or add new constraints to ShortcutRecorder, it would be reasonable to skip them for the time being, and focus on the small gap needed by the two actual users who are blocked to use ShortcutRecorder in their app at the moment. I'm thinking of that as a 80/20 kind of thing

in [3] and [4] I see 1alt-up1 but not 1alt-down1 in the sequence

Yes it is not there. I wanted to illustrate inputs ignored since it's a contain policy. alt had been pressed previously in my mind, but maybe it's clearer to add it somewhere there, why not.

[lwouis]

Hi @Kentzo! Is this issue on your roadmap? I'm kind of waiting on it to be implemented for alt-tab-macos. If you don't have bandwidth to implement that use-case in the coming months, please let me know, that way I can look into another framework as a plan B. Thank you! :)

[Kentzo]

It's definitely on my list, but I'm quite busy atm for the open source projects I maintain.

If you have a commercial interest in this and would like to expedite the process, please contact me and we can arrange something.

[Kentzo]

Added support for modifier-only key-up and key-down events when modifier flags match exactly.