ShortcutRecorder

Inherits from
Conforms to
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

Saving and restoring state

Key combination control

Modifier flag control

Displaying the key combination

Conversion of flags

Setting the delegate

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

Delegate Methods by Task

Delegate methods

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.