Key equivalent matching for non-US English keyboard layouts

On non-Latin keyboard layouts, the ⌘ layer switches the keyboard to a Latin/English-like layout. E.g. pressing ⌘ switches ב into C.

You can observe this behavior in Accessibility Keyboard.

This non-Latin layout ⌘ switch does all the work here. For non-Latin layouts, keyboard localization (menu-only) would be only used here for some special characters like ⌘[ or to switch arrow keys based on the UI directionality.

I encourage you to add input methods like Hebrew in System Settings › Keyboard and run tests within your app to make sure events are caught.

Also, based on the shortcut you want, catching via the key code instead of the key character may be best.

Thank you for your reply. I've observed the switch to a Latin/English-like layout (using Accessibility Keyboard) when pressing ⌘ for the Hebrew layout.

The question is how an implementation of performKeyEquivalent would correctly account for and support this?

Based on the performKeyEquivalent documentation here, and the Handling Key Events documentation here, the implementation should check the unmodified characters of the incoming events:

You should extract the characters for a key equivalent using the NSEvent method charactersIgnoringModifiers.

The implementation should extract the characters for a key equivalent from the passed-in NSEvent object using the charactersIgnoringModifiers method and then examine them to determine if they are a key equivalent it recognizes.

Which naively would be something like:

- (BOOL)performKeyEquivalent:(NSEvent *)event
{
    if (event.modifierFlags & NSEventModifierFlagCommand) {
        if ([event.charactersIgnoringModifiers isEqualToString:@"c"])
            return YES;
    }
    return NO;
}

But this implementation would fail to catch the Latin layer of the Hebrew layout.

Assuming the documentation is incomplete, a more robust implementation would perhaps be something like:

- (BOOL)performKeyEquivalent:(NSEvent *)event
{
    if (event.modifierFlags & NSEventModifierFlagCommand) {
        if ([event.charactersIgnoringModifiers isEqualToString:@"c"])
            return YES;
        if ([event.characters isEqualToString:@"c"])
            return YES;
    }
    return NO;
}

But is that correct? Are there cases where comparing against both the modified and unmodified characters will fail or produce unexpected matches? Should the behavior be different based on properties of the keyboard layout?

[NSEvent _matchesKeyEquivalent:modifierMask:] seems to handle this correctly, but contains references to text input APIs like TISCopyCurrentKeyboardInputSource, TSMGetInputSourceProperty, and TSMGetDeadKeyState, which seems to indicate the naive approach above is not sufficient to match AppKit's own behavior.

The goal would be for the custom control to respond to performKeyEquivalent the same way an NSButton or NSMenuItem would in terms of which events are considered matches and which are not. In particular, for a generic control that allows user defined key equivalents, so without relying on specifics of any particular key equivalent.

To test things further, I've created a custom keyboard layout (attached), with the following mappings:

+----------+--------------+--------------------+----------+
| Key code | Physical key | No modifiers layer |  ⌘ layer |
+----------+--------------+--------------------+----------+
|     7    |       x      |          e         |     c    |
+----------+--------------+--------------------+----------+
|     8    |       c      |          a         |     b    |
+----------+--------------+--------------------+----------+
|     9    |       v      |          c         |     d    |
+----------+--------------+--------------------+----------+

Testing with an NSButton with .keyEquivalent = @"c" and .keyEquivalentModifierMask = NSEventModifierFlagCommand, I'm observing:

• Pressing the c key alone, or with ⌘, does not trigger the button, so the logic in NSButton does not seem to be based on the key code of the event (8)
• Pressing the x key alone does not trigger the button, but pressing ⌘x does, so the logic does seems to match on NSEvent.characters
• Pressing the v key alone does not trigger the button, nor does pressing ⌘v, so the logic does not to match on NSEvent.charactersIgnoringModifiers

The behavior observed for [NSEvent _matchesKeyEquivalent:modifierMask:] seems to be exactly the same.

This would indicate that a "correct and robust" implementation is:

- (BOOL)performKeyEquivalent:(NSEvent *)event
{
    if (event.modifierFlags & self.keyEquivalentModifierMask 
        && [event.characters isEqualToString:self.keyEquivalent])
        return YES;

    return NO;
}

It this the case? Are the more things to consider? Thanks!