/core/externals/google-toolbox-for-mac/AppKit/GTMCarbonEvent.h
C++ Header | 412 lines | 106 code | 53 blank | 253 comment | 0 complexity | eb82714f6e6761041684b6cacc8ebc9d MD5 | raw file
1// 2// GTMCarbonEvent.h 3// 4// Copyright 2006-2008 Google Inc. 5// 6// Licensed under the Apache License, Version 2.0 (the "License"); you may not 7// use this file except in compliance with the License. You may obtain a copy 8// of the License at 9// 10// http://www.apache.org/licenses/LICENSE-2.0 11// 12// Unless required by applicable law or agreed to in writing, software 13// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 14// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 15// License for the specific language governing permissions and limitations under 16// the License. 17// 18 19#import <Foundation/Foundation.h> 20#import <Carbon/Carbon.h> 21 22#import "GTMDefines.h" 23 24@class GTMCarbonEventHandler; 25@class GTMCarbonHotKey; 26 27// Objective C wrapper for a Carbon Event 28@interface GTMCarbonEvent : NSObject <NSCopying> { 29 @private 30 EventRef event_; //Event we are wrapping. STRONG 31} 32 33 34// Create an event of class |inClass| and kind |inKind| 35// 36// Returns: 37// Autoreleased GTMCarbonEvent 38// 39+ (id)eventWithClass:(UInt32)inClass kind:(UInt32)kind; 40 41// Create an event based on |event|. Retains |event|. 42// 43// Returns: 44// Autoreleased GTMCarbonEvent 45// 46+ (id)eventWithEvent:(EventRef)event; 47 48// Create an event based on the event currently being handled. 49// 50// Returns: 51// Autoreleased GTMCarbonEvent 52// 53+ (id)currentEvent; 54 55// Create an event of class |inClass| and kind |inKind| 56// 57// Returns: 58// GTMCarbonEvent 59// 60- (id)initWithClass:(UInt32)inClass kind:(UInt32)kind; 61 62// Create an event based on |event|. Retains |event|. 63// 64// Returns: 65// GTMCarbonEvent 66// 67- (id)initWithEvent:(EventRef)event; 68 69// Get the event's class. 70// 71// Returns: 72// event class 73// 74- (UInt32)eventClass; 75 76// Get the event's kind. 77// 78// Returns: 79// event kind 80// 81- (UInt32)eventKind; 82 83// Set the event's time. 84// 85// Arguments: 86// time - the time you want associated with the event 87// 88- (void)setTime:(EventTime)eventTime; 89 90// Get the event's time. 91// 92// Returns: 93// the time associated with the event 94// 95- (EventTime)time; 96 97// Get the event's eventref for passing to other carbon functions. 98// 99// Returns: 100// the event ref associated with the event 101// 102- (EventRef)event; 103 104// Sets (or adds) a parameter to an event. Try not to use this function 105// directly. Look at the PARAM_TEMPLATE_DECL/DEFN macros below. 106// 107// Arguments: 108// name - the parameter name. 109// type - the parameter type. 110// size - the size of the data that |data| points to. 111// data - pointer to the data you want to set the parameter to. 112// 113- (void)setParameterNamed:(EventParamName)name 114 type:(EventParamType)type 115 size:(ByteCount)size 116 data:(const void *)data; 117 118 119// Gets a parameter from an event. Try not to use this function 120// directly. Look at the PARAM_TEMPLATE_DECL/DEFN macros below. 121// 122// Arguments: 123// name - the parameter name. 124// type - the parameter type. 125// size - the size of the data that |data| points to. 126// data - pointer to the buffer that you want to fill with your data. 127// 128// Returns: 129// YES is parameter is retrieved successfully. NO if parameter doesn't exist. 130// 131- (BOOL)getParameterNamed:(EventParamName)name 132 type:(EventParamType)type 133 size:(ByteCount)size 134 data:(void *)data; 135 136// Gets a the size of a parameter from an event. 137// 138// Arguments: 139// name - the parameter name. 140// type - the parameter type. 141// 142// Returns: 143// The size of the buffer required to hold the parameter. 0 if parameter 144// doesn't exist. 145// 146- (ByteCount)sizeOfParameterNamed:(EventParamName)name 147 type:(EventParamType)type; 148 149// Sends event to an event target with options 150// 151// Arguments: 152// target - target to send event to. 153// options - options to send event. See SendEventToEventTargetWithOptions 154// for details. 155// 156// Returns: 157// OSStatus value. 158// 159- (OSStatus)sendToTarget:(GTMCarbonEventHandler *)target 160 options:(OptionBits)options; 161 162// Post event to an event queue. 163// 164// Arguments: 165// queue - queue to post it to. 166// priority - priority to post it with 167// 168// Returns: 169// OSStatus value. 170// 171- (OSStatus)postToQueue:(EventQueueRef)queue priority:(EventPriority)priority; 172 173// Post event to current queue with standard priority. 174// 175- (void)postToCurrentQueue; 176 177// Post event to main queue with standard priority. 178// 179- (void)postToMainQueue; 180 181@end 182 183// Macros for defining simple set/get parameter methods for GTMCarbonEvent. See 184// the category GTMCarbonEvent (GTMCarbonEventGettersAndSetters) for an example 185// of their use. GTM_PARAM_TEMPLATE_DECL2/DEFN2 is for the case where the 186// parameter name is different than the parameter type (rare, but it does 187// occur...e.g. for a Rect, the name is typeQDRectangle, and the type is Rect, 188// so it would be GTM_PARAM_TEMPLATE_DECL2(QDRectangle, Rect) ). In most cases 189// you will just use GTM_PARAM_TEMPLATE_DECL/DEFN. 190#define GTM_PARAM_TEMPLATE_DECL2(paramName, paramType) \ 191- (void)set##paramName##ParameterNamed:(EventParamName)name data:(paramType *)data; \ 192- (BOOL)get##paramName##ParameterNamed:(EventParamName)name data:(paramType *)data; 193 194#define GTM_PARAM_TEMPLATE_DEFN2(paramName, paramType) \ 195- (void)set##paramName##ParameterNamed:(EventParamName)name data:(paramType *)data { \ 196[self setParameterNamed:name type:type##paramName size:sizeof(paramType) data:data]; \ 197} \ 198- (BOOL)get##paramName##ParameterNamed:(EventParamName)name data:(paramType *)data { \ 199return [self getParameterNamed:name type:type##paramName size:sizeof(paramType) data:data]; \ 200} 201 202#define GTM_PARAM_TEMPLATE_DECL(paramType) GTM_PARAM_TEMPLATE_DECL2(paramType, paramType) 203#define GTM_PARAM_TEMPLATE_DEFN(paramType) GTM_PARAM_TEMPLATE_DEFN2(paramType, paramType) 204 205 206// Category defining some basic types that we want to be able to easily set and 207// get from GTMCarbonEvents 208@interface GTMCarbonEvent (GTMCarbonEventGettersAndSetters) 209GTM_PARAM_TEMPLATE_DECL(UInt32) 210GTM_PARAM_TEMPLATE_DECL(EventHotKeyID) 211@end 212 213// Utility function for converting between modifier types 214// Arguments: 215// inCocoaModifiers - keyboard modifiers in carbon form 216// (NSCommandKeyMask etc) 217// Returns: 218// Carbon modifiers equivalent to |inCocoaModifiers| (cmdKey etc) 219GTM_EXTERN UInt32 GTMCocoaToCarbonKeyModifiers(NSUInteger inCocoaModifiers); 220 221// Utility function for converting between modifier types 222// Arguments: 223// inCarbonModifiers - keyboard modifiers in carbon form (cmdKey etc) 224// Returns: 225// cocoa modifiers equivalent to |inCocoaModifiers| (NSCommandKeyMask etc) 226GTM_EXTERN NSUInteger GTMCarbonToCocoaKeyModifiers(UInt32 inCarbonModifiers); 227 228// An "abstract" superclass for objects that handle events such as 229// menus, HIObjects, etc. 230// 231// Subclasses are expected to override the eventTarget and 232// handleEvent:handler: methods to customize them. 233@interface GTMCarbonEventHandler : NSObject { 234 @private 235 // handler we are wrapping 236 // lazily created in the eventHandler method 237 EventHandlerRef eventHandler_; 238 __weak id delegate_; // Our delegate 239 // Does our delegate respond to the gtm_eventHandler:receivedEvent:handler: 240 // selector? Cached for performance reasons. 241 BOOL delegateRespondsToHandleEvent_; 242} 243 244// Registers the event handler to listen for |events|. 245// 246// Arguments: 247// events - an array of EventTypeSpec. The events to register for. 248// count - the number of EventTypeSpecs in events. 249// 250- (void)registerForEvents:(const EventTypeSpec *)events count:(size_t)count; 251 252// Causes the event handler to stop listening for |events|. 253// 254// Arguments: 255// events - an array of EventTypeSpec. The events to register for. 256// count - the number of EventTypeSpecs in events. 257// 258- (void)unregisterForEvents:(const EventTypeSpec *)events count:(size_t)count; 259 260// To be overridden by subclasses to respond to events. 261// 262// All subclasses should call [super handleEvent:handler:] if they 263// don't handle the event themselves. 264// 265// Arguments: 266// event - the event to be handled 267// handler - the call ref in case you want to call CallNextEventHandler 268// in your method 269// Returns: 270// OSStatus - usually either noErr or eventNotHandledErr 271// 272- (OSStatus)handleEvent:(GTMCarbonEvent *)event 273 handler:(EventHandlerCallRef)handler; 274 275// To be overridden by subclasses to return the event target for the class. 276// GTMCarbonEventHandler's implementation returns NULL. 277// 278// Returns: 279// The event target ref. 280// 281- (EventTargetRef)eventTarget; 282 283// Gets the underlying EventHandlerRef for that this class wraps. 284// 285// Returns: 286// The EventHandlerRef this class wraps. 287// 288- (EventHandlerRef)eventHandler; 289 290// Gets the delegate for the handler 291// 292// Returns: 293// the delegate 294- (id)delegate; 295 296// Sets the delegate for the handler 297// 298// Arguments: 299// delegate - the delegate to set to 300- (void)setDelegate:(id)delegate; 301 302@end 303 304// Category for methods that a delegate of GTMCarbonEventHandlerDelegate may 305// want to implement. 306@interface NSObject (GTMCarbonEventHandlerDelegate) 307 308// If a delegate implements this method it gets called before every event 309// that the handler gets sent. If it returns anything but eventNotHandledErr, 310// the handlers handlerEvent:handler: method will not be called, and 311// the return value returned by the delegate will be returned back to the 312// carbon event dispatch system. This allows you to override any method 313// that a handler may implement. 314// 315// Arguments: 316// delegate - the delegate to set to 317// 318- (OSStatus)gtm_eventHandler:(GTMCarbonEventHandler *)sender 319 receivedEvent:(GTMCarbonEvent *)event 320 handler:(EventHandlerCallRef)handler; 321 322@end 323 324// A general OSType for use when setting properties on GTMCarbonEvent objects. 325// This is the "signature" as part of commandIDs, controlsIDs, and properties. 326// 'GooG' 327GTM_EXTERN const OSType kGTMCarbonFrameworkSignature; 328 329// An event handler class representing the event monitor event handler 330// 331// there is only one of these per application. This way you can put 332// event handlers directly on the dispatcher if necessary. 333@interface GTMCarbonEventMonitorHandler : GTMCarbonEventHandler 334// Accessor to get the GTMCarbonEventMonitorHandler singleton. 335// 336// Returns: 337// pointer to the GTMCarbonEventMonitorHandler singleton. 338+ (GTMCarbonEventMonitorHandler *)sharedEventMonitorHandler; 339@end 340 341// An event handler class representing the application event handler. 342// 343// there is only one of these per application. This way you can put 344// event handlers directly on the application if necessary. 345@interface GTMCarbonEventApplicationEventHandler : GTMCarbonEventHandler 346// Accessor to get the GTMCarbonEventApplicationEventHandler singleton. 347// 348// Returns: 349// pointer to the GTMCarbonEventApplicationEventHandler singleton. 350+ (GTMCarbonEventApplicationEventHandler *)sharedApplicationEventHandler; 351@end 352 353// An event handler class representing the toolbox dispatcher event handler 354// 355// there is only one of these per application. This way you can put 356// event handlers directly on the dispatcher if necessary. 357@interface GTMCarbonEventDispatcherHandler : GTMCarbonEventHandler { 358 @private 359 NSMutableArray *hotkeys_; // Collection of registered hotkeys 360} 361 362// Accessor to get the GTMCarbonEventDispatcherHandler singleton. 363// 364// Returns: 365// pointer to the GTMCarbonEventDispatcherHandler singleton. 366+ (GTMCarbonEventDispatcherHandler *)sharedEventDispatcherHandler; 367 368// Registers a hotkey. When the hotkey is executed by the user, target will be 369// called with selector. 370// Arguments: 371// keyCode - the virtual keycode of the hotkey 372// cocoaModifiers - the modifiers that need to be used with |keyCode|. NB 373// that these are cocoa modifiers, so NSCommandKeyMask etc. 374// target - instance that will get |action| called when the hotkey fires 375// action - the method to call on |target| when the hotkey fires 376// userInfo - storage for callers use 377// onPress - is YES, the hotkey fires on the keydown (usual) otherwise 378// it fires on the key up. 379// Returns: 380// a GTMCarbonHotKey. Note that all hotkeys are unregistered 381// automatically when an app quits. Will be nil on failure. 382- (GTMCarbonHotKey *)registerHotKey:(NSUInteger)keyCode 383 modifiers:(NSUInteger)cocoaModifiers 384 target:(id)target 385 action:(SEL)action 386 userInfo:(id)userInfo 387 whenPressed:(BOOL)onPress; 388 389// Unregisters a hotkey previously registered with registerHotKey. 390// Arguments: 391// keyRef - the EventHotKeyRef to unregister 392- (void)unregisterHotKey:(GTMCarbonHotKey *)keyRef; 393 394@end 395 396// Wrapper for all the info we need about a hotkey that we can store in a 397// Foundation storage class. We expecct selector to have this signature: 398// - (void)hitHotKey:(GTMCarbonHotKey *)key; 399@interface GTMCarbonHotKey : NSObject { 400 @private 401 EventHotKeyID id_; // EventHotKeyID for this hotkey. 402 EventHotKeyRef hotKeyRef_; 403 id target_; // Object we are going to call when the hotkey is hit 404 SEL selector_; // Selector we are going to call on target_ 405 BOOL onKeyDown_; // Do we do it on key down or on key up? 406 id userInfo_; 407} 408 409- (id)userInfo; 410- (EventHotKeyRef)hotKeyRef; 411- (BOOL)onKeyDown; 412@end