Quartz Event Services Reference
Total Page:16
File Type:pdf, Size:1020Kb
Quartz Event Services Reference 2006-10-03 REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS Apple Computer, Inc. DOCUMENT, ITS QUALITY, ACCURACY, © 2006 Apple Computer, Inc. MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS All rights reserved. DOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND No part of this publication may be ACCURACY. reproduced, stored in a retrieval system, or IN NO EVENT WILL APPLE BE LIABLE FOR transmitted, in any form or by any means, DIRECT, INDIRECT, SPECIAL, INCIDENTAL, mechanical, electronic, photocopying, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR recording, or otherwise, without prior INACCURACY IN THIS DOCUMENT, even if written permission of Apple Computer, Inc., advised of the possibility of such damages. with the following exceptions: Any person THE WARRANTY AND REMEDIES SET is hereby authorized to store documentation FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, on a single computer for personal use only EXPRESS OR IMPLIED. No Apple dealer, agent, and to print copies of documentation for or employee is authorized to make any modification, extension, or addition to this personal use provided that the warranty. documentation contains Apple’s copyright Some states do not allow the exclusion or notice. limitation of implied warranties or liability for incidental or consequential damages, so the The Apple logo is a trademark of Apple above limitation or exclusion may not apply to Computer, Inc. you. This warranty gives you specific legal rights, and you may also have other rights which Use of the “keyboard” Apple logo vary from state to state. (Option-Shift-K) for commercial purposes 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, Inkwell, Mac, Mac OS, and Quartz are trademarks of Apple Computer, Inc., registered in the United States and other countries. Times is a registered trademark of Heidelberger Druckmaschinen AG, available from Linotype Library GmbH. Simultaneously published in the United States and Canada. Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR Contents Quartz Event Services Reference 7 Introduction 7 Functions by Task 8 Working With Quartz Events 8 Working With Quartz Event Taps 9 Working With Quartz Event Sources 9 Obsolete Functions 10 Functions 11 CGEnableEventStateCombining 11 CGEventCreate 12 CGEventCreateCopy 12 CGEventCreateData 13 CGEventCreateFromData 13 CGEventCreateKeyboardEvent 14 CGEventCreateMouseEvent 14 CGEventCreateSourceFromEvent 15 CGEventGetDoubleValueField 16 CGEventGetFlags 16 CGEventGetIntegerValueField 16 CGEventGetLocation 17 CGEventGetTimestamp 17 CGEventGetType 18 CGEventGetTypeID 18 CGEventKeyboardGetUnicodeString 18 CGEventKeyboardSetUnicodeString 19 CGEventMaskBit 20 CGEventPost 20 CGEventPostToPSN 21 CGEventSetDoubleValueField 21 CGEventSetFlags 22 CGEventSetIntegerValueField 22 CGEventSetLocation 23 CGEventSetSource 23 CGEventSetTimestamp 24 CGEventSetType 24 CGEventSourceButtonState 25 CGEventSourceCounterForEventType 25 3 2006-10-03 | © 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS CGEventSourceCreate 26 CGEventSourceFlagsState 26 CGEventSourceGetKeyboardType 27 CGEventSourceGetLocalEventsFilterDuringSuppressionState 27 CGEventSourceGetLocalEventsSuppressionInterval 28 CGEventSourceGetSourceStateID 28 CGEventSourceGetTypeID 29 CGEventSourceGetUserData 29 CGEventSourceKeyState 30 CGEventSourceSecondsSinceLastEventType 30 CGEventSourceSetKeyboardType 30 CGEventSourceSetLocalEventsFilterDuringSuppressionState 31 CGEventSourceSetLocalEventsSuppressionInterval 32 CGEventSourceSetUserData 32 CGEventTapCreate 33 CGEventTapCreateForPSN 34 CGEventTapEnable 35 CGEventTapIsEnabled 36 CGEventTapPostEvent 36 CGGetEventTapList 37 CGInhibitLocalEvents 37 CGPostKeyboardEvent 38 CGPostMouseEvent 39 CGPostScrollWheelEvent 40 CGSetLocalEventsFilterDuringSuppressionState 40 CGSetLocalEventsSuppressionInterval 41 Callbacks 42 CGEventTapCallback 42 Data Types 43 CGButtonCount 43 CGCharCode 43 CGEventMask 43 CGEventRef 44 CGEventSourceKeyboardType 44 CGEventSourceRef 44 CGEventTapInformation 45 CGEventTapProxy 46 CGEventTimestamp 46 CGKeyCode 46 CGWheelCount 47 Constants 47 Event Fields 47 Event Filter Masks 52 Event Flags 53 Event Source States 54 Event Source Token 55 4 2006-10-03 | © 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS Event Suppression States 55 Event Tap Locations 56 Event Tap Options 56 Event Tap Placement 57 Event Types 57 Event Type Mask 58 Mouse Buttons 58 Mouse Subtypes 59 Document Revision History 61 Index 63 5 2006-10-03 | © 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS 6 2006-10-03 | © 2006 Apple Computer, Inc. All Rights Reserved. Quartz Event Services Reference Framework: ApplicationServices/ApplicationServices.h Declared in: CGEvent.h CGEventSource.h CGEventTypes.h CGRemoteOperation.h Introduction This document describes the C API for event taps. Introduced in Mac OS X version 10.4, event taps are filters used to observe and alter the stream of low-level user input events in Mac OS X. Event taps make it possible to monitor and filter input events from several points within the system, prior to their delivery to a foreground application. Event taps complement and extend the capabilities of the Carbon event monitor mechanism, which allows an application to observe input events delivered to other processes (see the function GetEventMonitorTarget). Event taps are designed to serve as a Section 508 enabling technology. For example, consider a software system to assist a person with language impairments, designed to perform keyboard filtering with spoken review. Such a system could use an event tap to monitor all keystrokes, perform dictionary checks and matches, and recite the assembled word back to the user on detection of a word break in the input stream. If acceptable to the user, as indicated by an additional input keystroke or other gesture, the events would be posted into the system for delivery to the foreground application. Event taps are a safe replacement for jGNEFilters, a mechanism used for enabling technologies in the Classic Mac OS environment (see Technical Note TN1060). Event taps provide functionality similar to the Win32 functions SetWinEventHook when used to establish an out-of-context event hook, and SendInput. Quartz Event Services also includes an older set of event-related functions declared in the file CGRemoteOperation.h. These functions are still supported, but they are not recommended for new development. Introduction 7 2006-10-03 | © 2006 Apple Computer, Inc. All Rights Reserved. Quartz Event Services Reference Functions by Task Working With Quartz Events CGEventGetTypeID (page 18) Returns the type identifier for the opaque type CGEventRef. CGEventCreate (page 12) Returns a new Quartz event. CGEventCreateData (page 13) Returns a flattened data representation of a Quartz event. CGEventCreateFromData (page 13) Returns a Quartz event created from a flattened data representation of the event. CGEventCreateMouseEvent (page 14) Returns a new Quartz mouse event. CGEventCreateKeyboardEvent (page 14) Returns a new Quartz keyboard event. CGEventCreateCopy (page 12) Returns a copy of an existing Quartz event. CGEventCreateSourceFromEvent (page 15) Returns a Quartz event source created from an existing Quartz event. CGEventSetSource (page 23) Sets the event source of a Quartz event. CGEventGetType (page 18) Returns the event type of a Quartz event (left mouse down, for example). CGEventSetType (page 24) Sets the event type of a Quartz event (left mouse down, for example). CGEventGetTimestamp (page 17) Returns the timestamp of a Quartz event. CGEventSetTimestamp (page 24) Sets the timestamp of a Quartz event. CGEventGetLocation (page 17) Returns the location of a Quartz mouse event. CGEventSetLocation (page 23) Sets the location of a Quartz mouse event. CGEventGetFlags (page 16) Returns the event flags of a Quartz event. CGEventSetFlags (page 22) Sets the event flags of a Quartz event. 8 Functions by Task 2006-10-03 | © 2006 Apple Computer, Inc. All Rights Reserved. Quartz Event Services Reference CGEventKeyboardGetUnicodeString (page 18) Returns the Unicode string associated with a Quartz keyboard event. CGEventKeyboardSetUnicodeString (page 19) Sets the Unicode string associated with a Quartz keyboard event. CGEventGetIntegerValueField (page 16) Returns an integer representation of the value of a field in a Quartz event. CGEventSetIntegerValueField (page 22) Sets the value of a field in a Quartz event to a specified integer. CGEventGetDoubleValueField (page 16) Returns a floating point representation of the value of a field in a Quartz event. CGEventSetDoubleValueField (page 21) Sets the value of a field in a Quartz event to a specified floating point number. Working With