[Feature] Simple helper function to check if a shortcut is being invoked

[dgellow]

Describe the problem this feature would solve

Problem originally reported via CommunityToolkit/WindowsCommunityToolkit#4008.

To set the context, three points:

1. In Windows, pressing down the key AltGr is equivalent to pressing down the keys AltLeft and Control at the same time (both key are considered Down).
2. AltGr is generally used by non-US keyboard layouts to write special characters (for example the German keyboard uses AltGr+q to emit the character "@").
3. Keyboard shortcuts are usually in the form of Control+<key>

Because of this, naive code such as the following may fail to distinguish a between a situation where the user tries to write a special character, and where they want to invoke a shortcut:

private void Editor_KeyDown(object sender, KeyRoutedEventArgs e) {
    if (CoreWindow.GetForCurrentThread().GetKeyState(VirtualKey.Control).HasFlag(CoreVirtualKeyStates.Down)) {
      // Control is down!
      // Now let's check if "q" is also pressed
      if (CoreWindow.GetForCurrentThread().GetKeyState(VirtualKey.Q).HasFlag(CoreVirtualKeyStates.Down)) {
        // "q" is pressed, let's do our shortcut action
        DoSomething();
      }
    }
}

With this logic every time a user with a German layout will try to write the character "@" (i.e AltGr+q) they will instead perform DoSomething().

A correct way to check for shortcuts is by ensuring that AltLeft (called MenuLeft in the Windows lingo) is not pressed, but Control is:

private void Editor_KeyDown(object sender, KeyRoutedEventArgs e) {
    var ctrlDown = CoreWindow.GetForCurrentThread().GetKeyState(VirtualKey.Control).HasFlag(CoreVirtualKeyStates.Down);
    var altDown = CoreWindow.GetForCurrentThread().GetKeyState(VirtualKey.Menu).HasFlag(CoreVirtualKeyStates.Down);
    
    if (ctrlDown && !altDown) {

      // Now let's check if "q" is also pressed
      if (CoreWindow.GetForCurrentThread().GetKeyState(VirtualKey.Q).HasFlag(CoreVirtualKeyStates.Down)) {
        // "q" is pressed, let's do our shortcut action
        DoSomething();
      }
    }
}

Of course that's tedious to do and very easy to forget.

Describe the solution

My opinion is that a simple helper IsShortcutKeyDown (the exact name and implementation are to be defined) would ensure that shortcuts are implemented correctly, without conflicts with user keyboard layouts:

// Check that the "shortcut key" is pressed down. Shorcuts are performed by pressing 'Control+<key>', but not when
// 'Alt' is also pressed down. That's to avoid blocking the use of 'AltGr'.
public bool IsShortcutKeyDown() {
  var ctrlDown = CoreWindow.GetForCurrentThread().GetKeyState(VirtualKey.Control).HasFlag(CoreVirtualKeyStates.Down);
  var altDown = CoreWindow.GetForCurrentThread().GetKeyState(VirtualKey.Menu).HasFlag(CoreVirtualKeyStates.Down);
  return ctrlDown && !altDown;
}

Whenever a developer wants to check if the user is invoking a shortcut they should use this helper instead of manually checking for Control being down.

Our example becomes:

private void Editor_KeyDown(object sender, KeyRoutedEventArgs e) {
    if (IsShortCutKeyDown()) {
      // Now let's check if "q" is also pressed
      if (CoreWindow.GetForCurrentThread().GetKeyState(VirtualKey.Q).HasFlag(CoreVirtualKeyStates.Down)) {
        // "q" is pressed, let's do our shortcut action
        DoSomething();
      }
    }
}

Describe alternatives you've considered

• The status quo, which is ok-ish but relies on developers being aware of details they are likely to not know.

Additional context & Screenshots

Initially reported and discussed in #4008, more contextual details can be found there.

[ghost]

Hello, 'dgellow! Thanks for submitting a new feature request. I've automatically added a vote 👍 reaction to help get things started. Other community members can vote to help us prioritize this feature in the future!

[dgellow]

Open questions:

1. Is WindowsCommunityToolkit the good library to implement and expose such a helper? Or would WinUI or another library be a better choice?
2. In the Toolkit, what would be a good namespace to expose the helper?
3. In #4008 @michael-hawker mentions the case of WinUI 3 and the fact that CoreWndow changed. Should the helper function takes that point in consideration, and if yes, how exactly?
4. Should the helper be limited to checking that Control is down, and AltLeft isn't, or should it do something slightly more involved but that would maybe offer a nicer API (such as bool IsShortcutActive(VirtualKey key), a function checking if the user pressed Control+<key>, but not Alt)?

[michael-hawker]

@chingucoding WinUI 2 doesn't really have public helpers and only controls. Thoughts on if it'd be useful to try and do something there or would they only consider it for WinUI 3? Otherwise, it's easy enough for us to find a spot in the Toolkit for us on the managed side and expose it in a compatible way with WinUI 3 for future migrations.

[marcelwgn]

WinUI already exposes a few converters, however those always were born out of a need in a specific control. Having this inside WinUI 2 would be really cool, however I'm not sure how inline it is with the plan for WinUI 2 as a product. @ranjeshj @SavoySchuler @MikeHillberg what do you think about this?

Having this inside the WCT seems the easiest, however I am not sure about C++\WinRT folks though. Having this inside WinUI would be better though. We can try, but I am not sure where it would be or how it would fit in the product its self.