# ShortcutRecorder

Inherits from | NSControl : NSView : NSResponder : NSObject
Conforms to | NSCoding (NSResponder) NSObject (NSObject)
Declared in | ShortcutRecorder.h

## Class Description

`ShortcutRecorder` is a subclass of `NSControl` that intercepts keyboard events.

`ShortcutRecorder` uses `ShortcutRecorderCell` to implement its user interface and main functions.

`ShortcutRecorderCell` internally stores the current key combination in its own `KeyCombo` structure. This structure stores the virtual key code in a member named `code` and the key mask (Cocoa-style) in a member named `flags`. `ShortcutRecorderCell` provides two methods for conversion (both ways) between Cocoa-style key mask flags and Carbon-style.

Before `ShortcutRecorder` sets the key combination you enter, it will make a bona fide attempt to make sure the key combination isn't already in use. It will check menu items contained in menus in the menu bar and system-wide shortcuts for any chance of collision, and if your delegate answers to a specific method, it will also check with your delegate for clearance. Your delegate can be a good way to check for shortcuts assigned to menu items in pop up menus, registered "hotkeys" and so on.

Additionally, you can provide, separately, key masks for allowed modifier keys and for required modifier keys. By not including a modifier in the allowed key mask, it's effectively prohibited, and by including a modifier in the required key mask, it's effectively active on all key combinations by default. The required key mask bests the allowed key mask - the required key mask is applied at the very end, after the modifiers not allowed have been filtered out.

In order to get the key combination when it is changed, you must assign a delegate to `ShortcutRecorder`. If using it directly, instead assign a delegate to `ShortcutRecorderCell`, which has similar delegate methods.

`ShortcutRecorder` will not register "hotkeys" for you - it will do nothing outside of keeping the key combination entered into it and make sure it passes the constraints you can set on it (and also some of which you can't - checking for collisions with menu items and system-wide shortcuts).

## Defined Structures

### KeyCombo

unsigned int flags
  The Cocoa-style modifier key mask. Set this to `0` for no flags.
signed short code
  The virtual key code. Set to `-1` for no code.

#### Discussion

`KeyCombo` is defined in ShortcutRecorderCell.h. Both member fields use the formats used in `NSEvent`.

## Methods by Task

## Instance Methods

### allowedFlags

Returns the allowed flags of the receiver.

- (unsigned int)allowedFlags

#### Return Value

Returns the allowed flags (Cocoa-style) of the receiver.

#### Discussion

`ShortcutRecorder` implements this method by invoking the same method in its `ShortcutRecorderCell` object.

#### See also:

- `- setAllowedFlags:`

### autosaveName

Returns the autosave name of the receiver under which it is automatically saved.

- (NSString *)autosaveName

#### Return Value

If no name has been set, this method returns `nil`.

#### Discussion

`ShortcutRecorder` implements this method by invoking the same method in its `ShortcutRecorderCell` object.

#### See also:

- `- setAutosaveName:`

### carbonToCocoaFlags:

Returns carbonFlags as Cocoa-style flags.

- (unsigned int)carbonToCocoaFlags:(unsigned int)carbonFlags

#### Parameters

carbonFlags
  The key mask to convert.

#### Return Value

Returns carbonFlags as Cocoa-style flags.

#### Discussion

`ShortcutRecorder` implements this method by invoking the same method in its `ShortcutRecorderCell` object.

#### See also:

- `- cocoaToCarbonFlags:`

### cocoaToCarbonFlags:

Returns cocoaFlags as Carbon-style flags.

- (unsigned int)cocoaToCarbonFlags:(unsigned int)cocoaFlags

#### Parameters

cocoaFlags
  The key mask to convert.

#### Return Value

Returns cocoaFlags as Cocoa-style flags.

#### Discussion

`ShortcutRecorder` implements this method by invoking the same method in its `ShortcutRecorderCell` object.

#### See also:

- `- carbonToCocoaFlags:`

### delegate

Returns the receiver's delegate.

- (id)delegate

#### Return Value

Returns the receiver's delegate, or `nil` if no delegate has been set.

#### See also:

- `- setDelegate:`

### keyCombo

Returns the currently stored key combo.

- (KeyCombo)keyCombo

#### Return Value

Returns the currently stored key combo (a `KeyCombo` structure).

#### Discussion

`ShortcutRecorder` implements this method by invoking the same method in its `ShortcutRecorderCell` object.

#### See also:

- `- setKeyCombo:`

### keyComboString

Returns the receiver's current key combo, formatted in a way that's presentable in the UI.

- (NSString *)keyComboString

#### Return Value

Returns the formatted string of the receiver's current key combo. If no valid key combo has been set, this method returns `nil`.

#### Discussion

This formats the key combo in a way that's presentable in the UI as-is. This means, for example, presenting the modifier keys, special keys (like Escape) and the arrow keys with their respective "fancy glyphs". `ShortcutRecorder` implements this method by invoking the same method in its `ShortcutRecorderCell` object.

#### See also:

- `- keyCombo:`

### requiredFlags

Returns the required flags of the receiver.

- (unsigned int)requiredFlags

#### Return Value

Returns the allowed flags (Cocoa-style) of the receiver.

#### Discussion

By default, no modifier flag is required. `ShortcutRecorder` implements this method by invoking the same method in its `ShortcutRecorderCell` object.

#### See also:

- `- setRequiredFlags:`

### setAllowedFlags:

Sets the receiver's allowed flags to flags.

- (void)setAllowedFlags:(unsigned int)flags

#### Parameters

flags
  The new Cocoa-style key mask.

#### Discussion

`ShortcutRecorder` implements this method by invoking the same method in its `ShortcutRecorderCell` object.

#### See also:

- `- allowedFlags`

### setAutosaveName:

Changes the name of the receiver under which it is automatically saved.

- (void)setAutosaveName:(NSString *)aName

#### Parameters

aName
  The new autosave name.

#### Discussion

Sets the receiver's autosave name to aName, or clears it if aName is `nil` or `@""`. `ShortcutRecorder` implements this method by invoking the same method in its `ShortcutRecorderCell` object.

#### See also:

- `- autosaveName`

### setDelegate:

Sets the receiver's delegate.

- (void)setDelegate:(id)aDelegate

#### Parameters

aDelegate
  The new delegate.

#### Discussion

Sets the receiver's delegate to aDelegate, or clears it if aDelegate is `nil`.

#### See also:

- `- delegate`

### setKeyCombo:

Sets the receiver's key combo to aKeyCombo in consideration of the allowed and required flags.

- (void)setKeyCombo:(KeyCombo)aKeyCombo

#### Parameters

aKeyCombo
  The new key combo.

#### Discussion

`ShortcutRecorder` implements this method by invoking the same method in its `ShortcutRecorderCell` object.

#### See also:

- `- keyCombo`
- `- allowedFlags`
- `- requiredFlags`

### setRequiredFlags:

Sets the receiver's required flags to flags.

- (void)setRequiredFlags:(unsigned int)flags

#### Parameters

flags
  The new Cocoa-style key mask.

#### Discussion

`ShortcutRecorder` implements this method by invoking the same method in its `ShortcutRecorderCell` object.

#### See also:

- `- requiredFlags`

## Delegate Methods by Task

## Delegate Methods

### shortcutRecorder:keyComboDidChange:

Informs the delegate that the key combo has changed.

- (void)shortcutRecorder:(ShortcutRecorder *)aRecorder keyComboDidChange:(KeyCombo)newKeyCombo

#### Parameters

aRecorder
  The `ShortcutRecorder` having been changed.
newKeyCombo
  The new key combination in `KeyCombo` form.

### shortcutRecorder:isKeyCode:andFlagsTaken:reason:

Called before the receiver verifies its key combo system wide and in all menus.

- (BOOL)shortcutRecorder:(ShortcutRecorder *)aRecorder isKeyCode:(unsigned short)keyCode andFlagsTaken:(unsigned int)flags reason:(NSString **)aReason

#### Parameters

aRecorder
  The `ShortcutRecorder` about to be changed.
keyCode
  The virtual key code in the proposed key combination.
flags
  The Cocoa-style modifier key mask in the proposed key combination.
aReason
  The reason, as a pointer to an `NSString`, why the key combination is occupied.

#### Return Value

Reports whether the `ShortcutRecorder` should accept the key combination or not. If not, an alert will be displayed with the contents in aReason.

#### Discussion

Return `YES` to sign a collision (an alert will be shown with the text in aReason), `NO` to continue the chain of verification.