From cd0926808c881bd281443e3bcc3aa422e063cefb Mon Sep 17 00:00:00 2001 From: Tomáš Znamenáček Date: Tue, 13 Jan 2015 08:47:43 +0100 Subject: Changed headerdoc markup to work better with CocoaDocs (closes #55). --- CHANGES | 3 +++ Framework/MASDictionaryTransformer.h | 12 ++++++------ Framework/MASShortcut.h | 34 +++++++++++++++++----------------- Framework/MASShortcutBinder.h | 28 ++++++++++++++-------------- Framework/MASShortcutMonitor.h | 4 ++-- 5 files changed, 42 insertions(+), 39 deletions(-) diff --git a/CHANGES b/CHANGES index 8237ae6..6f70664 100644 --- a/CHANGES +++ b/CHANGES @@ -1,3 +1,6 @@ +Unreleased yet + - Headerdoc markup that plays better with CocoaDocs. + 2.0.1 2015/1/9 - Trivial Podspec fix. diff --git a/Framework/MASDictionaryTransformer.h b/Framework/MASDictionaryTransformer.h index eced1bb..8f8e084 100644 --- a/Framework/MASDictionaryTransformer.h +++ b/Framework/MASDictionaryTransformer.h @@ -1,17 +1,17 @@ extern NSString *const MASDictionaryTransformerName; /** - @brief Converts shortcuts for storage in user defaults. + Converts shortcuts for storage in user defaults. User defaults can’t stored custom types directly, they have to - be serialized to @p NSData or some other supported type like an - @p NSDictionary. In Cocoa Bindings, the conversion can be done + be serialized to `NSData` or some other supported type like an + `NSDictionary`. In Cocoa Bindings, the conversion can be done using value transformers like this one. - There’s a built-in transformer (@p NSKeyedUnarchiveFromDataTransformerName) - that converts any @p NSCoding types to @p NSData, but with shortcuts + There’s a built-in transformer (`NSKeyedUnarchiveFromDataTransformerName`) + that converts any `NSCoding` types to `NSData`, but with shortcuts it makes sense to use a dictionary instead – the defaults look better - when inspected with the @p defaults command-line utility and the + when inspected with the `defaults` command-line utility and the format is compatible with an older sortcut library called Shortcut Recorder. */ diff --git a/Framework/MASShortcut.h b/Framework/MASShortcut.h index 3e1bedf..8ba1b53 100644 --- a/Framework/MASShortcut.h +++ b/Framework/MASShortcut.h @@ -1,7 +1,7 @@ #import "MASKeyCodes.h" /** - @brief 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 @@ -11,49 +11,49 @@ @interface MASShortcut : NSObject /** - @brief The virtual key code for the keyboard key. + The virtual key code for the keyboard key. - @Hardware independent, same as in NSEvent. 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; /** - @brief 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; /** - @brief Same as @p keyCode, just a different type. + Same as `keyCode`, just a different type. */ @property (nonatomic, readonly) UInt32 carbonKeyCode; /** - @brief Carbon modifier flags. + Carbon modifier flags. - A bit sum of @p cmdKey, @p optionKey, etc. + A bit sum of `cmdKey`, `optionKey`, etc. */ @property (nonatomic, readonly) UInt32 carbonFlags; /** - @brief 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`. */ @property (nonatomic, readonly) NSString *keyCodeString; /** - @brief A key-code string used in key equivalent matching. + A key-code string used in key equivalent matching. - For precise meaning of “key equivalents” see the @p keyEquivalent - property of @p NSMenuItem. Here the string is used to support shortcut + 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 @p NSMenu. + for display in `NSMenu`. */ @property (nonatomic, readonly) NSString *keyCodeStringForKeyEquivalent; /** - @brief 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 +61,9 @@ + (instancetype)shortcutWithKeyCode:(NSUInteger)code modifierFlags:(NSUInteger)flags; /** - @brief 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; diff --git a/Framework/MASShortcutBinder.h b/Framework/MASShortcutBinder.h index 1592e90..1e65e0d 100644 --- a/Framework/MASShortcutBinder.h +++ b/Framework/MASShortcutBinder.h @@ -1,22 +1,22 @@ #import "MASShortcutMonitor.h" /** - @brief Binds actions to user defaults keys. + Binds actions to user defaults keys. If you store shortcuts in user defaults (for example by binding - a @p MASShortcutView to user defaults), you can use this class to + a `MASShortcutView` to user defaults), you can use this class to connect an action directly to a user defaults key. If the shortcut stored under the key changes, the action will get automatically updated to the new one. - This class is mostly a wrapper around a @p MASShortcutMonitor. It + This class is mostly a wrapper around a `MASShortcutMonitor`. It watches the changes in user defaults and updates the shortcut monitor accordingly with the new shortcuts. */ @interface MASShortcutBinder : NSObject /** - @brief A convenience shared instance. + A convenience shared instance. You may use it so that you don’t have to manage an instance by hand, but it’s perfectly fine to allocate and use a separate instance instead. @@ -24,23 +24,23 @@ + (instancetype) sharedBinder; /** - @brief The underlying shortcut monitor. + The underlying shortcut monitor. */ @property(strong) MASShortcutMonitor *shortcutMonitor; /** - @brief Binding options customizing the access to user defaults. + Binding options customizing the access to user defaults. - As an example, you can use @p NSValueTransformerNameBindingOption to customize + As an example, you can use `NSValueTransformerNameBindingOption` to customize the storage format used for the shortcuts. By default the shortcuts are converted - from @p NSData (@p NSKeyedUnarchiveFromDataTransformerName). Note that if the - binder is to work with @p MASShortcutView, both object have to use the same storage + from `NSData` (`NSKeyedUnarchiveFromDataTransformerName`). Note that if the + binder is to work with `MASShortcutView`, both object have to use the same storage format. */ @property(copy) NSDictionary *bindingOptions; /** - @brief Binds given action to a shortcut stored under the given defaults key. + Binds given action to a shortcut stored under the given defaults key. In other words, no matter what shortcut you store under the given key, pressing it will always trigger the given action. @@ -48,19 +48,19 @@ - (void) bindShortcutWithDefaultsKey: (NSString*) defaultsKeyName toAction: (dispatch_block_t) action; /** - @brief Disconnect the binding between user defaults and action. + Disconnect the binding between user defaults and action. In other words, the shortcut stored under the given key will no longer trigger an action. */ - (void) breakBindingWithDefaultsKey: (NSString*) defaultsKeyName; /** - @brief Register default shortcuts in user defaults. + Register default shortcuts in user defaults. - This is a convenience frontent to [NSUserDefaults registerDefaults]. + This is a convenience frontent to `[NSUserDefaults registerDefaults]`. The dictionary should contain a map of user defaults’ keys to appropriate keyboard shortcuts. The shortcuts will be transformed according to - @p bindingOptions and registered using @p registerDefaults. + `bindingOptions` and registered using `registerDefaults`. */ - (void) registerDefaultShortcuts: (NSDictionary*) defaultShortcuts; diff --git a/Framework/MASShortcutMonitor.h b/Framework/MASShortcutMonitor.h index 609686a..69affc1 100644 --- a/Framework/MASShortcutMonitor.h +++ b/Framework/MASShortcutMonitor.h @@ -1,7 +1,7 @@ #import "MASShortcut.h" /** - @brief Executes action when a shortcut is pressed. + Executes action when a shortcut is pressed. There can only be one instance of this class, otherwise things will probably not work. (There’s a Carbon event handler inside @@ -13,7 +13,7 @@ + (instancetype) sharedMonitor; /** - @brief Register a shortcut along with an action. + Register a shortcut along with an action. Attempting to insert an already registered shortcut probably won’t work. It may burn your house or cut your fingers. You have been warned. -- cgit v1.2.3 From 807c5d782bf533242d17ca05276df48b3c867c42 Mon Sep 17 00:00:00 2001 From: Tomáš Znamenáček Date: Tue, 13 Jan 2015 09:14:23 +0100 Subject: Added a barebones Travis config file. --- .travis.yml | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 .travis.yml diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..c37db22 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,3 @@ +language: objective-c +xcode_project: MASShortcut.xcodeproj +xcode_scheme: Tests -- cgit v1.2.3 From a0452955316091e38c7b7a7364656e9fd52daaac Mon Sep 17 00:00:00 2001 From: Tomáš Znamenáček Date: Tue, 13 Jan 2015 09:21:28 +0100 Subject: Added shared Xcode schemes to help Travis with the build. --- .travis.yml | 2 +- .../xcshareddata/xcschemes/Demo.xcscheme | 86 ++++++++++++++++ .../xcshareddata/xcschemes/MASShortcut.xcscheme | 110 +++++++++++++++++++++ 3 files changed, 197 insertions(+), 1 deletion(-) create mode 100644 MASShortcut.xcodeproj/xcshareddata/xcschemes/Demo.xcscheme create mode 100644 MASShortcut.xcodeproj/xcshareddata/xcschemes/MASShortcut.xcscheme diff --git a/.travis.yml b/.travis.yml index c37db22..7d4103d 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,3 +1,3 @@ language: objective-c xcode_project: MASShortcut.xcodeproj -xcode_scheme: Tests +xcode_scheme: MASShortcut diff --git a/MASShortcut.xcodeproj/xcshareddata/xcschemes/Demo.xcscheme b/MASShortcut.xcodeproj/xcshareddata/xcschemes/Demo.xcscheme new file mode 100644 index 0000000..3a55207 --- /dev/null +++ b/MASShortcut.xcodeproj/xcshareddata/xcschemes/Demo.xcscheme @@ -0,0 +1,86 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/MASShortcut.xcodeproj/xcshareddata/xcschemes/MASShortcut.xcscheme b/MASShortcut.xcodeproj/xcshareddata/xcschemes/MASShortcut.xcscheme new file mode 100644 index 0000000..5f510c4 --- /dev/null +++ b/MASShortcut.xcodeproj/xcshareddata/xcschemes/MASShortcut.xcscheme @@ -0,0 +1,110 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -- cgit v1.2.3 From 62c142a7f5718fa1c7523d1bd6f6f22430c0329b Mon Sep 17 00:00:00 2001 From: Tomáš Znamenáček Date: Tue, 13 Jan 2015 13:24:59 +0100 Subject: Added the Travis build status badge to the README. --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 30e8341..9a98ddb 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ +[![Build Status](https://travis-ci.org/shpakovski/MASShortcut.svg?branch=master)](https://travis-ci.org/shpakovski/MASShortcut) + # Intro 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. -- cgit v1.2.3