Carbon Event Manager Reference 2006-07-24 Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR Apple Computer, Inc. REPRESENTATION, EITHER EXPRESS OR © 2003, 2006 Apple Computer, Inc. IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, All rights reserved. MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED “AS IS,” AND No part of this publication may be YOU, THE READER, ARE ASSUMING THE reproduced, stored in a retrieval system, or ENTIRE RISK AS TO ITS QUALITY AND transmitted, in any form or by any means, ACCURACY. mechanical, electronic, photocopying, IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, recording, or otherwise, without prior OR CONSEQUENTIAL DAMAGES written permission of Apple Computer, Inc., RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if with the following exceptions: Any person advised of the possibility of such damages. is hereby authorized to store documentation THE WARRANTY AND REMEDIES SET on a single computer for personal use only FORTH ABOVE ARE EXCLUSIVE AND IN and to print copies of documentation for LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, personal use provided that the or employee is authorized to make any documentation contains Apple’s copyright modification, extension, or addition to this notice. warranty. Some states do not allow the exclusion or The Apple logo is a trademark of Apple limitation of implied warranties or liability for Computer, Inc. incidental or consequential damages, so the above limitation or exclusion may not apply to Use of the “keyboard” Apple logo you. This warranty gives you specific legal rights, and you may also have other rights which (Option-Shift-K) for commercial purposes vary from state to state. without the prior written consent of Apple may constitute trademark infringement and unfair competition in violation of federal and state laws. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled or Apple-licensed computers. Every effort has been made to ensure that the information in this document is accurate. Apple is not responsible for typographical errors. Apple Computer, Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Carbon, Cocoa, iBook, Mac, Mac OS, Macintosh, PowerBook, Quartz, and QuickDraw are trademarks of Apple Computer, Inc., registered in the United States and other countries. eMac is a trademark of Apple Computer, Inc. Simultaneously published in the United States and Canada. Contents Carbon Event Manager Reference 11 Introduction 11 Functions by Task 11 Creating and Manipulating Event Handlers 11 Creating and Manipulating Event Timers 12 Creating and Manipulating Events 12 Dispatching Events 13 Managing Secure Event Input 13 Managing Event Queues 14 Managing the Event Loop 14 Manipulating Event Time 15 Implementing Modal Windows 15 Tracking the Mouse 16 Working with Hot Keys 17 Callback-Related Functions 17 Miscellaneous 18 Functions 18 AcquireFirstMatchingEventInQueue 18 AddEventTypesToHandler 19 BeginAppModalStateForWindow 20 CallNextEventHandler 20 ConvertEventRefToEventRecord 21 CopyEvent 22 CopyEventAs 22 CopyServicesMenuCommandKeys 23 CopySymbolicHotKeys 23 CreateEvent 24 CreateTypeStringWithOSType 25 DisableSecureEventInput 25 DisposeEventComparatorUPP 26 DisposeEventHandlerUPP 26 DisposeEventLoopIdleTimerUPP 27 DisposeEventLoopTimerUPP 27 EnableSecureEventInput 27 EndAppModalStateForWindow 28 FindSpecificEventInQueue 28 FlushEventQueue 29 3 2006-07-24 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS FlushEventsMatchingListFromQueue 29 FlushSpecificEventsFromQueue 30 GetApplicationEventTarget 30 GetCFRunLoopFromEventLoop 31 GetControlEventTarget 31 GetCurrentEventKeyModifiers 31 GetCurrentEventLoop 32 GetCurrentEventQueue 33 GetCurrentEventTime 33 GetEventClass 33 GetEventDispatcherTarget 34 GetEventKind 34 GetEventMonitorTarget 35 GetEventParameter 36 GetEventRetainCount 37 GetEventTime 37 GetLastUserEventTime 37 GetMainEventLoop 38 GetMainEventQueue 38 GetMenuEventTarget 38 GetNumEventsInQueue 39 GetSymbolicHotKeyMode 39 GetUserFocusEventTarget 40 GetUserFocusWindow 40 GetWindowCancelButton 41 GetWindowDefaultButton 41 GetWindowEventTarget 42 HIMouseTrackingGetParameters 42 InstallEventHandler 43 InstallEventLoopIdleTimer 44 InstallEventLoopTimer 45 InstallStandardEventHandler 47 InvokeEventComparatorUPP 47 InvokeEventHandlerUPP 48 InvokeEventLoopIdleTimerUPP 49 InvokeEventLoopTimerUPP 49 IsEventInMask 49 IsEventInQueue 50 IsMouseCoalescingEnabled 50 IsSecureEventInputEnabled 51 IsUserCancelEventRef 51 NewEventComparatorUPP 52 NewEventHandlerUPP 52 NewEventLoopIdleTimerUPP 53 NewEventLoopTimerUPP 53 PopSymbolicHotKeyMode 53 4 2006-07-24 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS PostEventToQueue 54 ProcessHICommand 54 PushSymbolicHotKeyMode 55 QuitApplicationEventLoop 56 QuitAppModalLoopForWindow 56 QuitEventLoop 56 ReceiveNextEvent 57 RegisterEventHotKey 58 RegisterToolboxObjectClass 59 ReleaseEvent 60 RemoveEventFromQueue 60 RemoveEventHandler 61 RemoveEventLoopTimer 61 RemoveEventTypesFromHandler 62 RetainEvent 62 RunApplicationEventLoop 63 RunAppModalLoopForWindow 63 RunCurrentEventLoop 64 SendEventToEventTarget 64 SendEventToEventTargetWithOptions 65 SetEventLoopTimerNextFireTime 65 SetEventParameter 66 SetEventTime 67 SetMouseCoalescingEnabled 67 SetUserFocusWindow 68 SetWindowCancelButton 68 SetWindowDefaultButton 69 TrackMouseLocation 70 TrackMouseLocationWithOptions 71 TrackMouseRegion 72 UnregisterEventHotKey 73 UnregisterToolboxObjectClass 73 Callbacks 74 EventComparatorProcPtr 74 EventHandlerProcPtr 74 EventLoopIdleTimerProcPtr 75 EventLoopTimerProcPtr 76 Data Types 76 EventClassID 76 EventComparatorUPP 76 EventHandlerCallRef 76 EventHandlerUPP 77 EventLoopTimerUPP 77 EventLoopIdleTimerUPP 77 EventHandlerRef 77 EventHotKeyID 77 5 2006-07-24 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS EventHotKeyRef 78 EventLoopIdleTimerMessage 78 EventLoopRef 78 EventLoopTimerRef 79 EventParamName 79 EventParamType 79 EventQueueRef 79 EventRef 80 EventTargetRef 80 EventTime 80 EventTimeout 80 EventTimerInterval 80 EventType 80 EventTypeSpec 81 HICommand 81 HICommandExtended 82 MouseTrackingRef 83 MouseTrackingRegionID 83 TabletPointRec 83 TabletProximityRec 85 ToolboxObjectClassRef 86 Constants 86 Basic Event Constants 86 Apple Event Constants 96 Appearance Manager Event Constants 97 Application Event Constants 98 Command Events 102 Control Events 110 Ink Events 128 Keyboard Events 129 Menu Events 134 Mouse Events 148 Services Manager Constants 156 Tablet Event Constants 158 Text Input Events 160 Text Service Manager Document Events 169 Timer Constants 170 Toolbar Events 171 Volume Events 172 Window Events 173 Result Codes 204 Appendix A Deprecated Carbon Event Manager Functions 207 Deprecated in Mac OS X v10.4 207 ChangeMouseTrackingRegion 207 6 2006-07-24 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS ClipMouseTrackingRegion 207 ClipWindowMouseTrackingRegions 208 CreateMouseTrackingRegion 208 GetMouseTrackingRegionID 209 GetMouseTrackingRegionRefCon 210 MoveMouseTrackingRegion 210 MoveWindowMouseTrackingRegions 211 ReleaseMouseTrackingRegion 211 ReleaseWindowMouseTrackingRegions 212 RetainMouseTrackingRegion 212 SetMouseTrackingRegionEnabled 213 SetWindowMouseTrackingRegionsEnabled 213 Document Revision History 215 Index 217 7 2006-07-24 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS 8 2006-07-24 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. Tables Carbon Event Manager Reference 11 Table 1 Parameter names and types for AppleEvent kinds 97 Table 2 Parameter names and types for application event kinds 101 Table 3 Parameter names and types for command event kinds 103 Table 4 Parameter names and types for common control event kinds 118 Table 5 Parameter names and types for ink event kinds 128 Table 6 Parameter names and types for keyboard event kinds 130 Table 7 Parameter names and types for menu event kinds 141 Table 8 Parameter names and types for mouse event kinds 149 Table 9 Parameter names and types for Service class events 157 Table 10 Required parameter names and types for text input event kinds 162 Table 11 Parameter names and types for window action event kinds 178 Table 12 Parameter names and types for window activation event kinds 181 Table 13 Parameter names and types for window state change event kinds 187 Table 14 Parameter names and types for window refresh event kinds 189 Table 15 Parameter names and types for window cursor change event kinds 189 Table 16 Parameter names and types for window focus event kinds 191 Table 17 Parameter names and types for window sheet event kinds 192 Table 18 Parameter names and types for window drawer event kinds 193 Table 19 Parameter names and types for window definition event kinds 195 9 2006-07-24 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. TABLES 10 2006-07-24 | © 2003, 2006 Apple Computer, Inc. All Rights Reserved. Carbon Event Manager Reference Framework: Carbon/Carbon.h Declared in: CarbonEventsCore.h CarbonEvents.h Introduction The Carbon Event Manager is the preferred API for handling events in Carbon applications. You