diff options
Diffstat (limited to 'Framework/MASShortcut.h')
| -rw-r--r-- | Framework/MASShortcut.h | 57 |
1 files changed, 34 insertions, 23 deletions
diff --git a/Framework/MASShortcut.h b/Framework/MASShortcut.h index 8ba1b53..8f420e4 100644 --- a/Framework/MASShortcut.h +++ b/Framework/MASShortcut.h @@ -1,59 +1,70 @@ #import "MASKeyCodes.h" /** - A model class to hold a key combination. + A model class to hold a key combination. - This class just represents a combination of keys. It does not care if - the combination is valid or can be used as a hotkey, it doesn’t watch - the input system for the shortcut appearance, nor it does access user - defaults. + This class just represents a combination of keys. It does not care if + the combination is valid or can be used as a hotkey, it doesn’t watch + the input system for the shortcut appearance, nor it does access user + defaults. */ @interface MASShortcut : NSObject <NSSecureCoding, NSCopying> /** - The virtual key code for the keyboard key. + The virtual key code for the keyboard key. - Hardware independent, same as in `NSEvent`. See `Events.h` in the HIToolbox - framework for a complete list, or Command-click this symbol: `kVK_ANSI_A`. + Hardware independent, same as in `NSEvent`. See `Events.h` in the HIToolbox + framework for a complete list, or Command-click this symbol: `kVK_ANSI_A`. */ @property (nonatomic, readonly) NSUInteger keyCode; /** - Cocoa keyboard modifier flags. + Cocoa keyboard modifier flags. - Same as in `NSEvent`: `NSCommandKeyMask`, `NSAlternateKeyMask`, etc. + Same as in `NSEvent`: `NSCommandKeyMask`, `NSAlternateKeyMask`, etc. */ @property (nonatomic, readonly) NSUInteger modifierFlags; /** - Same as `keyCode`, just a different type. + Same as `keyCode`, just a different type. */ @property (nonatomic, readonly) UInt32 carbonKeyCode; /** - Carbon modifier flags. + Carbon modifier flags. - A bit sum of `cmdKey`, `optionKey`, etc. + A bit sum of `cmdKey`, `optionKey`, etc. */ @property (nonatomic, readonly) UInt32 carbonFlags; /** - A string representing the “key” part of a shortcut, like the `5` in `⌘5`. + A string representing the “key” part of a shortcut, like the `5` in `⌘5`. + + @warning The value may change depending on the active keyboard layout. + For example for the `^2` keyboard shortcut (`kVK_ANSI_2+NSControlKeyMask` + to be precise) the `keyCodeString` is `2` on the US keyboard, but `ě` when + the Czech keyboard layout is active. See the spec for details. */ @property (nonatomic, readonly) NSString *keyCodeString; /** - A key-code string used in key equivalent matching. - - For precise meaning of “key equivalents” see the `keyEquivalent` - property of `NSMenuItem`. Here the string is used to support shortcut - validation (“is the shortcut already taken in this menu?”) and - for display in `NSMenu`. + A key-code string used in key equivalent matching. + + For precise meaning of “key equivalents” see the `keyEquivalent` + property of `NSMenuItem`. Here the string is used to support shortcut + validation (“is the shortcut already taken in this menu?”) and + for display in `NSMenu`. + + The value of this property may differ from `keyCodeString`. For example + the Russian keyboard has a `Г` (Ge) Cyrillic character in place of the + latin `U` key. This means you can create a `^Г` shortcut, but in menus + that’s always displayed as `^U`. So the `keyCodeString` returns `Г` + and `keyCodeStringForKeyEquivalent` returns `U`. */ @property (nonatomic, readonly) NSString *keyCodeStringForKeyEquivalent; /** - A string representing the shortcut modifiers, like the `⌘` in `⌘5`. + A string representing the shortcut modifiers, like the `⌘` in `⌘5`. */ @property (nonatomic, readonly) NSString *modifierFlagsString; @@ -61,9 +72,9 @@ + (instancetype)shortcutWithKeyCode:(NSUInteger)code modifierFlags:(NSUInteger)flags; /** - Creates a new shortcut from an `NSEvent` object. + Creates a new shortcut from an `NSEvent` object. - This is just a convenience initializer that reads the key code and modifiers from an `NSEvent`. + This is just a convenience initializer that reads the key code and modifiers from an `NSEvent`. */ + (instancetype)shortcutWithEvent:(NSEvent *)anEvent; |