/*! @header NDHotKeyEvent.h @abstract Header file for the class NDHotKeyEvent @discussion

NDHotKeyEvent provides a thread safe Objective-C interface to HotKey events as well as some additional feature to key track of all the hot keys in your application.

Thread Saftey

By default the class object NDHotKeyEvent is not thread safe as the underlying functions that it relies on are not thread safe and the mechanism for keeping track of all of the NDHotKeyEvent instances is not thread safe either. Thread saftey can be enable be defining the flag NDHotKeyEventThreadSafe before compiling.

Even with the flag NDHotKeyEventThreadSafe defined instances of NDHotKeyEvent will still not be thread safe, that is, it is safe to invoke methods of different instance with different threads as well as class methods, but it is not safe to invoke methods of the same instance with different threads.

The functions stringForKeyCodeAndModifierFlags and unicharForKeyCode are never thread safe.

Created by Nathan Day on Wed Feb 26 2003.
Copyright © 2002 Nathan Day. All rights reserved.

*/ #import #import /*! @defined NDHotKeyEventThreadSafe @abstract A flag to enable thread safety. @discussion By default the class object NDHotKeyEvent is not thread safe. Defining the this flag will make th class methods of NDHotKeyEvent thread safe, see introduction for more details.. */ enum { /*! @const NDHotKeyNoEvent @abstract A value returned from the method -[NDHotKeyEvent currentEventType] @discussion This value is returned if the hot key has not been pressed yet. */ NDHotKeyNoEvent = 0, /*! @const NDHotKeyPressedEvent @abstract A value returned from the method -[NDHotKeyEvent currentEventType] @discussion This value is returned if hot key was pressed last. */ NDHotKeyPressedEvent, /*! @const NDHotKeyReleasedEvent @abstract A value returned from the method -[NDHotKeyEvent currentEventType] @discussion This value is returned if hot key was released last. */ NDHotKeyReleasedEvent }; /*! @const NDHotKeyDefaultSignature @abstract The default signature @discussion This is the default signature that will be used if you start using NDHotKeyEvent without setting the signature first. */ extern const OSType NDHotKeyDefaultSignature; /*! @class NDHotKeyEvent @abstract Class to represent a HotKey @discussion

This class is a wrapper for Carbon Event HotKeys and provides some feature to key track of all the hot keys in your application. It can be used to be notified of key down as well as key up evernts and when a hot key is being taken by another object (see the protocol NDHotKeyEventTragetWillChange)

*/ @interface NDHotKeyEvent : NSObject { @private EventHotKeyRef reference; unsigned short keyCode; unichar character; unsigned int modifierFlags; int currentEventType; id target; SEL selectorReleased, selectorPressed; struct { unsigned individual : 1; unsigned collective : 1; } isEnabled; } /*! @method install @abstract Install the event key handler @discussion install is called before hot keys can be used. You normally don't need to invoke this method your self but in a multithreaded you might want to invoke this method before creating any threads. install is designed to be thread safe but the effects of calling Apples InstallEventHandler() funtion from anything other than the main thread is unknown. @result Returns true if install succeeded. */ + (BOOL)install; /*! @method setSignature: @abstract Set the hot key signature for this application @discussion This should only be called once, before trying to enable any hot keys. @param signature The four char code signature to identify all hot keys for this application, could your applications signature. */ + (void)setSignature:(OSType)signature; /*! @method signature @abstract Get the hot key signature for this application @discussion Used to identify the hot key handler for this application. @result The four char code signature. */ + (OSType)signature; /*! @method setAllEnabled: @abstract Set enabled for all instances of NDHotKeyEvent @discussion Used to enable or disable all hot keys. This method is not the same as sending the message setEnabled: to every single NDHotKeyEvent instance. Enabling with this method only enables the hot keys that where enable prior to using this method to disable all hot keys. @param flag YES to enable, NO to disable. @result Returns YES if succesful. */ + (BOOL)setAllEnabled:(BOOL)flag; /*! @method isEnabledKeyCode:modifierFlags: @abstract Is hot key combination enabled. @abstract Test to see if a key code and modifier flaf combination are enabled. @param keyCode The key code used by the keyboard, can vary across hardware. @param modifierFlags The modifer flags, ( NSCommandKeyMask, NSControlKeyMask, NSAlternateKeyMask, NSShiftKeyMask ). @result Returns YES if enabled. */ + (BOOL)isEnabledKeyCode:(unsigned short)keyCode modifierFlags:(unsigned int)modifierFlags; /*! @method getHotKeyForKeyCode:modifierFlags: @abstract Get an NDHotKeyEvent @discussion Gets a NDHotKeyEvent for the supplied key code and modifer flags by either finding one that has already been created or by creating a new one.. @param keyCode The key code used by the keyboard, can vary across hardware. @param aChar The character, used for display purposes only. @param modifierFlags The modifer flags, ( NSCommandKeyMask, NSControlKeyMask, NSAlternateKeyMask, NSShiftKeyMask ). @result The NDHotKeyEvent obejct or nil if failure. */ + (NDHotKeyEvent *)getHotKeyForKeyCode:(unsigned short)keyCode character:(unichar)aChar modifierFlags:(unsigned int)modifierFlags; /*! @method findHotKeyForKeyCode:modifierFlags: @abstract Find an NDHotKeyEvent @discussion Finds the NDHotKeyEvent for the supplied key code and modifer flags. @param keyCode The key code used by the keyboard, can vary across hardware. @param modifierFlags The modifer flags, ( NSCommandKeyMask, NSControlKeyMask, NSAlternateKeyMask, NSShiftKeyMask ). @result The NDHotKeyEvent obejct or nil if none found. */ + (NDHotKeyEvent *)findHotKeyForKeyCode:(unsigned short)keyCode modifierFlags:(unsigned int)modifierFlags; /*! @method hotKeyWithKeyCode:character:modifierFlags: @abstract Get a NDHotKeyEvent object. @discussion Returns a new hot key for the supplied hot key combination, if there is already a hot key for the supplied key code and modifer flags then nil is returned. @param keyCode The key code used by the keyboard, can vary across hardware. @param aChar The character, used for display purposes only. @param modifierFlags The modifer flags, ( NSCommandKeyMask, NSControlKeyMask, NSAlternateKeyMask, NSShiftKeyMask ). @result An new NDHotKeyEvent or nil if failure. */ + (id)hotKeyWithKeyCode:(unsigned short)keyCode character:(unichar)aChar modifierFlags:(unsigned int)modifer; /*! @method hotKeyWithKeyCode:character:modifierFlags:target:selector: @abstract Get a NDHotKeyEvent object. @discussion Returns a new hot key for the supplied hot key combination and target object and selector, if there is already a hot key for the supplied key code and modifer flags then nil is returned. @param keyCode The key code used by the keyboard, can vary across hardware. @param aChar The character, used for display purposes only. @param modifierFlags The modifer flags, ( NSCommandKeyMask, NSControlKeyMask, NSAlternateKeyMask, NSShiftKeyMask ). @param target The target of hot key event. @param selector The selector sent when hot key is released @result A new NDHotKeyEvent */ + (id)hotKeyWithKeyCode:(unsigned short)keyCode character:(unichar)aChar modifierFlags:(unsigned int)modifer target:(id)target selector:(SEL)selector; /*! @method initWithPropertyList: @abstract creates a NDHotKeyEvent with a property list. @discussion This can be used for archiving purposes, but it is possible that it will not work if the users keyboard is changed, ie between machines. @param propertyList A property list object @result A initialized NDHotKeyEvent */ + (id)hotKeyWithWithPropertyList:(id)propertyList; /*! @method initWithKeyCode:character:modifierFlags:target:selector: @abstract Initialize a NDHotKeyEvent object. @discussion Initialize the reciever with the supplied hot key combination and target object and selector, if there is already a hot key for the supplied key code and modifer flags then nil is returned. @param keyCode The key code used by the keyboard, can vary across hardware. @param aChar The character, used for display purposes only. @param modifierFlags The modifer flags, ( NSCommandKeyMask, NSControlKeyMask, NSAlternateKeyMask, NSShiftKeyMask ). @param target The target of hot key event. @param selector The selector sent when hot key is released @result A initialized NDHotKeyEvent */ - (id)initWithKeyCode:(unsigned short)keyCode character:(unichar)aChar modifierFlags:(unsigned int)modifer target:(id)target selector:(SEL)selector; /*! @method initWithKeyCode:character:modifierFlags @abstract Initialize a NDHotKeyEvent object. @discussion Initialize the reciever with the supplied hot key combination, if there is already a hot key for the supplied key code and modifer flags then nil is returned. @param keyCode The key code used by the keyboard, can vary across hardware. @param aChar The character, used for display purposes only. @param modifierFlags The modifer flags, ( NSCommandKeyMask, NSControlKeyMask, NSAlternateKeyMask, NSShiftKeyMask ). @result A initialized NDHotKeyEvent */ - (id)initWithKeyCode:(unsigned short)keyCode character:(unichar)aChar modifierFlags:(unsigned int)modifer; /*! @method initWithPropertyList: @abstract Initializes the reciever with a property list. @discussion This can be used for archiving purposes, but it is possible that it will not work if the users keyboard is changed, ie between machines. The following properties are initialised
  • Key Code
  • Character
  • Modifier Flags
  • Selector Pressed
  • Selector Released
@param propertyList A property list object @result A initialized NDHotKeyEvent */ - (id)initWithPropertyList:(id)propertyList; /*! @method propertyList @abstract Returns a property list for the reciever. @discussion This can be used for archiving purposes, but it is possible that it will not work if the users keyboard is changed, ie between machines. The property list returned contains the following properties;
  • Key Code
  • Character
  • Modifier Flags
  • Selector Pressed
  • Selector Released
@result The property list object. */ - (id)propertyList; /*! @method initWithCoder: @abstract Initializes a newly allocated instance from data in decoder. @discussion Decodes the following properties of a NDHotKeyEvent;
  • Key Code
  • Character
  • Modifier Flags
  • Selector Pressed
  • Selector Released
Will use Keyed Coding if [decoder allowsKeyedCoding] == YES. @param decoder A subclass of NSCoder @result A initialized NDHotKeyEvent */ - (id)initWithCoder:(NSCoder *)decoder; /*! @method encodeWithCoder: @abstract Encodes the receiver using encoder @discussion Encodes the following properties of a NDHotKeyEvent;
  • Key Code
  • Character
  • Modifier Flags
  • Selector Pressed
  • Selector Released
Will use Keyed Coding if [encoder allowsKeyedCoding] == YES. @param encoder A subclass of NSCoder. */ - (void)encodeWithCoder:(NSCoder *)encoder; /*! @method setEnabled: @abstract Set the hot key enabled or disable. @discussion setEnabled: registers or unregisters the recievers hot key combination. @param flag YES to enable, NO to disable. @result Returns YES if successful */ - (BOOL)setEnabled:(BOOL)flag; /*! @method isEnabled @abstract Find out if a hot key is enabled. @discussion Returns YES if the hot key is registered. @result YES if enabled. */ - (BOOL)isEnabled; /*! @method target @abstract Get the hot key event target. @discussion Returns the object that is sent the key pressed and key released hot key events, see the methods -selector, -selectorReleased and selectorPressed. @result The target object. */ - (id)target; /*! @method selector @abstract The selector for a key released event. @discussion This is the selector sent when the hot key combination for the reciever is released. This is the same selector has returned from the method [NDHotKeyEvent selectorReleased] @result The method selector. */ - (SEL)selector; /*! @method selectorReleased @abstract The selector for a key released event. @discussion This is the selector sent when the hot key combination for the reciever is released. This is the same selector has returned from the method [NDHotKeyEvent selector] @result The method selector. */ - (SEL)selectorReleased; /*! @method selectorPressed @abstract The selector for a key pressed event. @discussion This is the selector sent when the hot key combination for the reciever is pressed. @result The method selector. */ - (SEL)selectorPressed; /*! @method currentEventType @abstract Get the current hot key event type. @discussion This value returns what event last occured. Can be used in your target when it is sent a event message to find out what event occured, possible values are
ValueDescription
NDHotKeyNoEventThe hot key has not been pressed yet.
NDHotKeyPressedEventThe hot key was pressed last.
NDHotKeyReleasedEventThe hot key was released last.
@result The last event type. */ - (int)currentEventType; /*! @method setTarget:selector: @abstract Set the hot key target. @discussion Set the target object and selector to be sent when the hot key is released. @param target The traget object. @param selector The selector. @result returns YES if successful. */ - (BOOL)setTarget:(id)target selector:(SEL)selector; /*! @method setTarget:selectorReleased:selectorPressed: @abstract Set the hot key target. @discussion Set the target object and selector to be sent when the hot key is pressed and wehn it is released. @param target The traget object. @param selectorReleased The key released selector. @param selectorPressed The key pressed selector. @result returns YES if successful. */ - (BOOL)setTarget:(id)target selectorReleased:(SEL)selectorReleased selectorPressed:(SEL)selectorPressed; /*! @method performHotKeyReleased @abstract Invoke the target with the release selector. @discussion Use to send the selector for a release event, though this method can be called by you. */ - (void)performHotKeyReleased; /*! @method performHotKeyPressed @abstract Invoke the target with the press selector. @discussion Use to send the selector for a presse event, though this method can be called by you. */ - (void)performHotKeyPressed; /*! @method keyCode @abstract Get the hot key key code. @discussion The key code for the hot key, this is hardware specific. @result The key code. */ - (unsigned short)keyCode; /*! @method character @abstract Get the hot key character. @discussion This is the character for the key code, without modifier keys. The character is for display purposes only and dose not determine the key code. @result A uni code character. */ - (unichar)character; /*! @method modifierFlags @abstract Get the hot key modifer key flags. @discussion The modifierFlags can be a bitwise and combination of NSControlKeyMask, NSAlternateKeyMask, NSShiftKeyMask, and NSCommandKeyMask. @result The modifer key flags. */ - (unsigned int)modifierFlags; /*! @method stringValue @abstract Get a string got the hot keys. @discussion This is a string that can be used for display purposes. @result A NSString */ - (NSString *)stringValue; @end /*! @protocol NSObject(NDHotKeyEventTragetWillChange) @abstract Informal protocol used to inform a NDHotKeyEvent target of events. @discussion The informal protocol NDHotKeyEventTragetWillChange defines a method used to notify a NDHotKeyEvent target that the target will change. */ @interface NSObject (NDHotKeyEventTragetWillChange) /*! @method targetWillChangeToObject:forHotKeyEvent: @abstract Message sent to a target object to inform it that the target is going to change. @discussion This method can be used to notify the receiver that it will no longer be the target for a NDHotKeyEvent or used to prevent the target from changing by returning NO @param target The new target for the NDHotKeyEvent @param hotKeyEvent The NDHotKeyEvent for which the target is changing. @result Return NO to prevent the target from changing, otherwise return YES. */ - (BOOL)targetWillChangeToObject:(id)target forHotKeyEvent:(NDHotKeyEvent *)hotKeyEvent; @end /*! @function stringForKeyCodeAndModifierFlags @abstract Get a string for hot key parameters. @discussion Returns a string representation of the passed in hot key values. @param keyCode A key code. @param aChar A character representation of the key code. @param modifierFlags modifer flags, comman, option, shift and control. @result A NSString representing the hot key combination. */ NSString * stringForKeyCodeAndModifierFlags( unsigned short keyCode, unichar aChar, unsigned int modifierFlags ); /*! @function unicharForKeyCode @abstract Get a unicode charater for the key combination. @discussion The uncode chararter for the key combination. @param keyCode The key code used by the keyboard, can vary across hardware. @result A unichar */ unichar unicharForKeyCode( unsigned short keyCode );