/core/externals/update-engine/externals/google-toolbox-for-mac/AppKit/GTMCarbonEvent.h

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