Version bump to 2.1.2.

See #60 for a discussion. In short, keyCodeStringForKeyEquivalent
should be now correct even with non-ASCII keyboard layouts such as
Russian.

CHANGES

@@ -1,3 +1,7 @@
+2.1.2 2015/1/28
+    - Better key equivalent handling for non-ASCII layouts.
+      [Dmitry Obukhov]
+
 2.1.1 2015/1/16
     - Another headerdoc fix for CocoaDocs, hopefully the last one.
 

CONTRIBUTING.md

@@ -0,0 +1,21 @@
+# How to Release a New Version
+
+First, update the version numbers. (MASShortcut uses [Semantic Versioning](http://semver.org/), so please read the docs if you’re not sure what the deal is.) The version number is stored in `Framework/Info.plist` and `MASShortcut.podspec` (twice in both files).
+
+Then update the `CHANGES` file. Add information about the new version (see the previous versions for an example) and add the release date.
+
+Now commit the changes:
+
+    $ git commit -a -m "Version bump to x.y.z."
+
+And tag the last commit:
+
+    $ git tag -a x.y.z
+
+Now push both the commits and tags (`--tags`) to GitHub and push the new podspec to CocoaPods:
+
+    $ pod trunk push MASShortcut.podspec
+
+This will run sanity checks on the podspec and fail if the spec does not validate.
+
+That’s it. Go have a beer or a cup of tea to celebrate.

Framework/Info.plist

@@ -15,9 +15,9 @@
 	<key>CFBundlePackageType</key>
 	<string>FMWK</string>
 	<key>CFBundleShortVersionString</key>
-	<string>2.1.1</string>
+	<string>2.1.2</string>
 	<key>CFBundleVersion</key>
-	<string>2.1.1</string>
+	<string>2.1.2</string>
 	<key>NSHumanReadableCopyright</key>
 	<string>Copyright © 2014–2015 Vadim Shpakovski. All rights reserved.</string>
 </dict>

Framework/MASShortcut.h

@@ -39,6 +39,11 @@
 
 /**
  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;
 
@@ -49,6 +54,12 @@
  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;
 

Framework/MASShortcut.m

@@ -139,10 +139,10 @@ static NSString *const MASShortcutModifierFlags = @"ModifierFlags";
         case 115: return NSStringFromMASKeyCode(kMASShortcutGlyphNorthwestArrow);
     }
     
-    // Everything else should be printable so look it up in the current keyboard
+    // Everything else should be printable so look it up in the current ASCII capable keyboard layout
     OSStatus error = noErr;
     NSString *keystroke = nil;
-    TISInputSourceRef inputSource = TISCopyCurrentKeyboardLayoutInputSource();
+    TISInputSourceRef inputSource = TISCopyCurrentASCIICapableKeyboardLayoutInputSource();
     if (inputSource) {
         CFDataRef layoutDataRef = TISGetInputSourceProperty(inputSource, kTISPropertyUnicodeKeyLayoutData);
         if (layoutDataRef) {

MASShortcut.podspec

@@ -1,6 +1,6 @@
 Pod::Spec.new do |s|
   s.name                  = 'MASShortcut'
-  s.version               = '2.1.1'
+  s.version               = '2.1.2'
   s.summary               = 'Modern framework for managing global keyboard shortcuts compatible with Mac App Store'
   s.homepage              = 'https://github.com/shpakovski/MASShortcut'
   s.license               = 'BSD 2-clause'
@@ -9,7 +9,7 @@ Pod::Spec.new do |s|
 
   s.platform              = :osx
   s.osx.deployment_target = "10.6"
-  s.source                = { :git => 'https://github.com/shpakovski/MASShortcut.git', :tag => '2.1.1' }
+  s.source                = { :git => 'https://github.com/shpakovski/MASShortcut.git', :tag => '2.1.2' }
   s.source_files          = 'Framework/*.{h,m}'
   s.exclude_files         = 'Framework/*Tests.m'
   s.osx.frameworks        = 'Carbon', 'AppKit'

README.md

@@ -4,7 +4,27 @@
 
 Some time ago Cocoa developers used a brilliant framework [ShortcutRecorder](http://wafflesoftware.net/shortcut/) for managing keyboard shortcuts in application preferences. However, it became incompatible with the new plugin architecture of Xcode 4.
 
-The MASShortcut project introduces a modern API and user interface for recording, storing and using system-wide keyboard shortcuts. All code is compatible with recent Xcode & OS X versions and the sandboxed environment.
+The MASShortcut project introduces a modern API and user interface for recording, storing and using system-wide keyboard shortcuts.
+
+![Screenshot of the demo project](/Demo/screenshot.png?raw=true "This is how the demo looks like")
+
+Features:
+
+* Record and display keyboard shortcuts
+* Watch for shortcuts and execute actions, system-wide
+* A nice, [documented API](http://cocoadocs.org/docsets/MASShortcut/)
+* Can be configured to be compatible with Shortcut Recorder
+* Can be installed both through CocoaPods and as a Git submodule
+* Mac App Store friendly
+* Works on OS X 10.6 and up
+* Hacking-friendly codebase covered with tests
+
+Important features currently missing:
+
+* Localisation
+* Accessibility
+
+Pull requests welcome :)
 
 # Installation
 
@@ -16,6 +36,8 @@ If you want to stick to the 1.x branch, you can use the version smart match oper
 
     pod 'MASShortcut', '~> 1'
 
+Or can use Git submodules and link against the MASShortcut framework.
+
 # Usage
 
 I hope, it is really easy:

Spec.md

@@ -12,4 +12,14 @@ Please stay high-level when writing the spec, do not document particular classes
 * If the shortcut is Cmd-W or Cmd-Q, the recording must be cancelled and the keypress passed through to the system, closing the window or quitting the app.
 * If a shortcut is already taken by system and is enabled, it must be rejected. (Examples: Cmd-S, Cmd-N. TBD: What exactly does it mean that the shortcut is “enabled”?)
 * TBD: Option-key handling.
-* All other shortcuts must be accepted. (Examples: Ctrl-Esc, Cmd-Delete, F16.)
+* All other shortcuts must be accepted. (Examples: Ctrl-Esc, Cmd-Delete, F16.)
+
+# Formatting Shortcuts
+
+On different keyboard layouts (such as US and Czech), a single shortcut (a combination of physical keys) may be formatted into different strings.
+
+For example, the default system shortcut for toggling directly to Space #2 is Control–2. But when you switch to the Czech keyboard layout, the physical key with the `2` label now inserts the `ě` character. Thus, on most keyboard layouts the shortcut for toggling to Space #2 is called `^2`, but on the Czech layout it’s called `^ě`. (I stress that this is the same combination of hardware keys and the same `MASShortcut` instance.)
+
+This is reflected by the system: When you open the System Preferences → Keyboard → Shortcuts pane, the shortcuts displayed depend on the currently selected keyboard layout (try switching between the US and Czech keyboard layouts and reopening the preference pane).
+
+This means that the identity of a shortcut is given by its key code and modifiers (such as `kVK_ANSI_2` and `NSControlKeyMask`), not the `keyCodeString` returned by the `MASShortcut` class. This string may change depending on the current keyboard layout: `^2` with the US keyboard active, but `^ě` with the Czech keyboard active.