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

  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