Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC
ADC Home > Reference Library > Reference > Carbon > Events & Other Input > Carbon Event Manager Reference >

Next Page > Hide TOC

Carbon Event Manager Reference

Framework
Carbon/Carbon.h
Declared in
AEDataModel.h
CarbonEvents.h
CarbonEventsCore.h
HIToolbar.h
cssmspi.h

Overview

The Carbon Event Manager is the preferred API for handling events in Carbon applications. You can use this interface to handle events generated in response to user input as well as to create your own custom events. Because event handling is so fundamental to all applications, this document is relevant for everyone writing Carbon applications. To use this document, you should be familiar with Macintosh terminology and understand the basics of creating and manipulating the Mac OS user interface (windows, controls, menus, and so on).

For more information about HIObjects and the HIView subclass, see HIView Programming Guide.

Functions by Task

Creating and Manipulating Event Handlers

Creating and Manipulating Event Timers

Creating and Manipulating Events

Dispatching Events

Managing Secure Event Input

Managing Event Queues

Managing the Event Loop

Manipulating Event Time

Implementing Modal Windows

Tracking the Mouse

Working with Hot Keys

Callback-Related Functions

Miscellaneous

Functions

AcquireFirstMatchingEventInQueue

Obtains the first event that matches the specified list of event classes and kinds. 

EventRef AcquireFirstMatchingEventInQueue (
   EventQueueRef inQueue,
   ItemCount inNumTypes,
   const EventTypeSpec *inList,
   OptionBits inOptions
);

Parameters
inQueue

The queue to check.

inNumTypes

The number of event kinds for which to search. You may pass 0 if you also pass NULL for inList.

inList

The list of event classes and kinds to search for in the queue. You may pass NULL if inNumTypes is 0. Doing so effectively matches any event in the queue and causes this function to return the first event in the queue.

inOptions

Must be kEventQueueOptionsNone.

Return Value

An event reference, or NULL if no events match. The reference count for the event has been incremented (that is, it has been retained), so you must release the event reference.

Discussion

This function does not remove the event from the queue. To remove the event, call RemoveEventFromQueue.

This function does not call the run loop, so no timers fire as a result of calling this function. This function does not cause any window flushing to occur, but it does get new events from the window server.

This function should have better performance characteristics than the older EventAvail API.

Availability
Declared In
CarbonEventsCore.h

AddEventTypesToHandler

Adds events to an installed handler.

OSStatus AddEventTypesToHandler (
   EventHandlerRef inHandlerRef,
   ItemCount inNumTypes,
   const EventTypeSpec *inList
);

Parameters
inHandlerRef

The event handler to add events to.

inNumTypes

The number of events to add.

inList

A pointer to an array of EventTypeSpec structures.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

You can use this function to dynamically change which events you want your handler to respond to.

Availability
Declared In
CarbonEventsCore.h

BeginAppModalStateForWindow

Puts the window in an application-modal state, but does not process events. 

OSStatus BeginAppModalStateForWindow (
   WindowRef inWindow
);

Parameters
inWindow

The window you wish to behave modally. See the Window Manager documentation for a description of the WindowRef data type.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

This function is a lower level function than RunAppModalLoopForWindow. You use it if you want to enter an application modal state for a window but need to control the event loop yourself. Once you begin your application modal state, the menu bar will disable and prepare for the modal situation. You can then call low-level functions (such as ReceiveNextEvent) to run the event loop and process events.

Availability
Declared In
CarbonEvents.h

CallNextEventHandler

Calls the next handler in the handler chain.

OSStatus CallNextEventHandler (
   EventHandlerCallRef inCallRef,
   EventRef inEvent
);

Parameters
inCallRef

The event handler call reference passed into your event handler.

inEvent

The event you want to pass to the next handler.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

Calls through to the event handlers below you in the event handler stack of the target to which your handler is bound. You might use this to call through to the default toolbox handling in order to post-process the event. You can only call this routine from within an event handler.

Availability
Related Sample Code
Declared In
CarbonEventsCore.h

ConvertEventRefToEventRecord

Converts an event reference into an event record.

Boolean ConvertEventRefToEventRecord (
   EventRef inEvent,
   EventRecord *outEvent
);

Parameters
inEvent

The event reference to convert.

outEvent

The event record to fill out. See the Event Manager documentation for a description of the EventRecord data type.

Return Value

A Boolean value indicating whether the conversion was successful (true) or not (false).

Discussion

This function helps you when you need an EventRecord structure and all you have is a Carbon event reference. If the event can be converted, outEvent is filled in and the function returns true. If not, the function returns false and outEvent contains nullEvent.

This function can convert the following events:

Availability
Declared In
CarbonEvents.h

CopyEvent

Copies an event.

EventRef CopyEvent (
   EventRef inOther
);

Parameters
inOther

The event to copy.

Return Value

A new event reference for the specified event.

Discussion

The CopyEvent function makes an exact duplicate of an existing event reference. The reference count for the duplicate event reference is set to 1.

Availability
Declared In
CarbonEventsCore.h

CopyEventAs

Copies an existing event, allowing you to change the class and kind of the event.

EventRef CopyEventAs (
   CFAllocatorRef inAllocator,
   EventRef inOther,
   OSType inEventClass,
   UInt32 inEventKind
);

Parameters
inOther

The allocator to use to allocate the event data. Pass NULL or kCFAllocatorDefault to use the standard allocator.

inOther

The event to copy.

inEventClass

The new event class for the copy of the event.

inEventKind

The new event kind for the copy of the event.

Return Value

A new event reference or NULL if the inOther was NULL or memory for the new event could not be allocated.

Discussion

The CopyEventAs is useful during event flow and transformation. For example, this function is used when upgrading a raw mouse down to a window click event, to ensure that the window click event has exactly the same parameters as the original mouse down event.

Availability
Declared In
CarbonEventsCore.h

CopyServicesMenuCommandKeys

Obtains information about command key shortcuts in an application’s Services menu.

OSStatus CopyServicesMenuCommandKeys (
   CFArrayRef *outCommandKeyArray
);

Parameters
outCommandKeyArray

On return, an array of items in the Services menu that have command key shortcuts associated with them.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

Each array entry is a reference to a CFDictionary, and each dictionary contains information about a single command key shortcut for items in the application’s Services menu. Each dictionary contains the following keys: kHIServicesMenuProviderName, kHIServicesMenuItemName, kHIServicesMenuCharCode, and kHIServicesMenuKeyModifiers. The array must be released by the caller. The dictionaries do not need to be released because they are released automatically when the array is released.

Availability
Declared In
CarbonEvents.h

CopySymbolicHotKeys

Obtains information about symbolic hot keys in the Keyboard preferences pane.

OSStatus CopySymbolicHotKeys (
   CFArrayRef *outHotKeyArray
);

Parameters
outHotKeyArray

An array of dictionaries containing information about the systemwide symbolic hot keys defined in the Keyboard preferences pane, such as the Screen Capture, Universal Access, and Keyboard Navigation keys. The array does not include information about custom, application-specific command keys. You must release the array when you no longer need it. The dictionaries are automatically released when you release the array.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

Each array entry is a reference for a CFDictionary, and each dictionary contains information about a single hot key. There is currently no way to determine which hot key in the Keyboards preference pane corresponds to a specific dictionary. Each dictionary contains the following keys: kHISymbolicHotKeyCode, kHISymbolicHotKeyModifiers, and kHISymbolicHotKeyEnabled. For details, see “Symbolic Hot Key Definitions.”

The number of hot keys will increase in the future, so do not call this function unnecessarily or in highly performance-sensitive code.

Availability
Declared In
CarbonEvents.h

CreateEvent

Creates an event.

OSStatus CreateEvent (
   CFAllocatorRef inAllocator,
   UInt32 inClassID,
   UInt32 kind,
   EventTime when,
   EventAttributes flags,
   EventRef * outEvent
);

Parameters
inAllocator

A reference to the desired memory allocator to use to allocate memory for the event. Pass NULL to use the default allocator. See the Base Services documentation for a description of the CFAllocatorRef data type.

inClassID

The event class of the event to create.

kind

The event kind of the event to create.

when

The time the event occurred. Pass 0 to specify the current event time (as returned by the GetCurrentEventTime function).

flags

The event attributes to set. Currently you can pass kEventAttributeNone or kEventAttributeUserEvent.

outEvent

On return, a reference to the newly created event.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

You can use this function to create your own custom events or to simulate existing events. If you are creating custom events, you must make sure that the event signature (the combination of event class and event kind) does not conflict with any existing events.

Availability
Related Sample Code
Declared In
CarbonEventsCore.h

CreateTypeStringWithOSType

Converts an OSType string to a Core Foundation string. 

CFStringRef CreateTypeStringWithOSType (
   OSType inType
);

Return Value

The Core Foundation string version of the OSType string. A return value of NULL indicates that an error occurred. See the Base Services documentation for a description of the CFStringRef data type.

Discussion

You can use this function to create CFString versions of OSType data types to pass to the Services Manager. As this is a creation function, you must call CFRelease on your Core Foundation string when you no longer need it.

Availability
Declared In
CarbonEvents.h

DisableSecureEventInput

Disables secure event input mode.

OSStatus DisableSecureEventInput (
   void
);

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

When secure event input mode is enabled, keyboard input goes only to the application with keyboard focus and is not echoed to other applications that might be using the event monitor target to watch keyboard input. The EditText and EditUnicodeText controls automatically enter secure input mode when a password control has focus. If your application implements its own password entry, you should enable secure event input while the user enters text.

This function maintains a count of the number of times that it has been called. Secure event input is not disabled until DisableSecureEventInput has been called the same number of times. Be sure to disable secure event input if your application becomes inactive. If your application crashes, secure event input is automatically disabled if no other application has enabled it.

Availability
Declared In
CarbonEventsCore.h

DisposeEventComparatorUPP

Disposes of an event comparator UPP.

void DisposeEventComparatorUPP (
   EventComparatorUPP userUPP
);

Parameters
userUPP

The UPP you want to destroy.

Availability
Declared In
CarbonEventsCore.h

DisposeEventHandlerUPP

Disposes of an event handler UPP. 

void DisposeEventHandlerUPP (
   EventHandlerUPP userUPP
);

Parameters
userUPP

The event handler UPP you want to destroy.

Availability
Related Sample Code
Declared In
CarbonEventsCore.h

DisposeEventLoopIdleTimerUPP

Disposes of an event loop idle timer. 

void DisposeEventLoopIdleTimerUPP (
   EventLoopIdleTimerUPP userUPP
);

Availability
Declared In
CarbonEventsCore.h

DisposeEventLoopTimerUPP

Disposes of an event loop timer. 

void DisposeEventLoopTimerUPP (
   EventLoopTimerUPP userUPP
);

Availability
Declared In
CarbonEventsCore.h

EnableSecureEventInput

Enables secure event input mode. 

OSStatus EnableSecureEventInput (
   void
);

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

When secure event input mode is enabled, keyboard input goes only to the application with keyboard focus and is not echoed to other applications that might be using the event monitor target to watch keyboard input. The EditText and EditUnicodeText controls automatically enter secure input mode when a password control has focus. If your application implements its own password entry, you should enable secure event input while the user enters text.

This function maintains a count of the number of times that it has been called. Secure event input is not disabled until DisableSecureEventInput has been called the same number of times. Be sure to disable secure event input if your application becomes inactive. If your application crashes, secure event input is automatically disabled if no other application has enabled it.

Availability
Declared In
CarbonEventsCore.h

EndAppModalStateForWindow

Ends the application-modal state entered using the function BeginAppModalStateForWindow.

OSStatus EndAppModalStateForWindow (
   WindowRef inWindow
);

Parameters
inWindow

The window you wish to stop acting as application- modal. See the Window Manager documentation for a description of the WindowRef data type.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

This routine ends an app modal state started with BeginAppModalStateForWindow.

Availability
Declared In
CarbonEvents.h

FindSpecificEventInQueue

Finds a specific event in the event queue.

EventRef FindSpecificEventInQueue (
   EventQueueRef inQueue,
   EventComparatorUPP inComparator,
   void *inCompareData
);

Parameters
inQueue

The event queue to search.

inComparator

The comparison function to invoke for each event in the queue. See EventComparatorProcPtr for the required format of your comparison function A return value of true from the comparator indicates a match.

inCompareData

The data you wish to pass to your comparison function.

Return Value

An event reference.

Discussion

Returns the first event that matches a comparator function, or NULL if no events match.

Availability
Declared In
CarbonEventsCore.h

FlushEventQueue

Removes all events from the event queue.

OSStatus FlushEventQueue (
   EventQueueRef inQueue
);

Parameters
inQueue

The event queue to flush.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

Flushes all events from an event queue.

Availability
Declared In
CarbonEventsCore.h

FlushEventsMatchingListFromQueue

Removes events from the event queue by kind and class.

OSStatus FlushEventsMatchingListFromQueue (
   EventQueueRef inQueue,
   ItemCount inNumTypes,
   const EventTypeSpec *inList
);

Parameters
inQueue

The event queue to flush events from.

inNumTypes

The number of event kinds to flush.

inList

The list of event classes and kinds to flush from the queue.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Availability
Declared In
CarbonEventsCore.h

FlushSpecificEventsFromQueue

Removes specified events from the event queue.

OSStatus FlushSpecificEventsFromQueue (
   EventQueueRef inQueue,
   EventComparatorUPP inComparator,
   void *inCompareData
);

Parameters
inQueue

The event queue to flush events from.

inComparator

The comparison function to invoke for each event in the queue. See EventComparatorProcPtr for the required format of your comparison function. A return value of true from the comparator indicates that the event should be flushed.

inCompareData

The data you wish to pass to your comparison function.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Availability
Declared In
CarbonEventsCore.h

GetApplicationEventTarget

Obtains the event target reference for the application.

EventTargetRef GetApplicationEventTarget (
   void
);

Return Value

An event target reference.

Discussion

Once you obtain this reference, you can send events to the target and install event handlers on it.

Availability
Related Sample Code
Declared In
CarbonEvents.h

GetCFRunLoopFromEventLoop

Obtains a Core Foundation CFRunLoop from an Carbon event loop reference. 

CFTypeRef GetCFRunLoopFromEventLoop (
   EventLoopRef inEventLoop
);

Parameters
inEventLoop

The event loop reference to translate.

Return Value

A reference to the CFRunLoop.

Discussion

There isn’t necessarily a one-to-one correspondence between Carbon event loops and Core Foundation event loops, so you should use this function instead of simply calling the Core Foundation function CFRunLoopGetCurrent.

Availability
Declared In
CarbonEventsCore.h

GetControlEventTarget

Obtains the event target reference for the specified control.

EventTargetRef GetControlEventTarget (
   ControlRef inControl
);

Parameters
inControl

The control to return the target for. See the Control Manager documentation for a description of the ControlRef data type.

Return Value

An event target reference.

Discussion

Once you obtain this reference, you can send events to the target and install event handlers on it.

Availability
Related Sample Code
Declared In
CarbonEvents.h

GetCurrentEventKeyModifiers

Obtains the queue-synchronized keyboard modifier state.

UInt32 GetCurrentEventKeyModifiers (
   void
);

Return Value

A bit field indicating the queue-synchronized keyboard modifier state. This field is the same as the modifiers field returned in an Event Manager EventRecord structure, but it includes only the keyboard modifier flags.

Discussion

The queue-synchronized keyboard modifier state indicates the modifier state according to the event most recently dispatched through an event target. This state may be different from the hardware state obtained using GetCurrentKeyModifiers. For example, say the user invokes a Control-click with the mouse. If the user releases or changes a modifier key before the mouse down event is dispatched, the hardware state reflects the new modifier state, not the one that generated the original mouse event.

The most recently dispatched event may not necessarily be the event that your event handler is handling. For example, if a mouse-down event occurs, and you have a handler for the kEventWindowHandleContentClick event that is generated from the mouse-down, then the keyboard modifiers will be those that were attached to the mouse-down. The content-click event itself has a kEventParamKeyModifiers parameter, which is copied from the mouse-down event, but GetCurrentEventKeyModifiers returns the modifiers from the mouse-down, not from the content-click event, because it was the mouse-down event that was most recently dispatched through the event dispatcher.

Events that are not sent through the event dispatcher target will not update the current event key modifiers. Also, events arriving from outside the application, such as an AppleEvent or an Accessibility event, also will not update the modifiers. If your application modifies its behavior based on modifier state, you should parameterize your core code with the event modifiers, and determine the modifiers based on the origin of the behavior request. For a request that originates directly from user input, you can use GetCurrentEventKeyModifiers, but for a request that originates from an AppleEvent or Accessibility event, you would probably use no modifiers. GetCurrentEventKeyModifiers gives a more consistent user experience when the user input queue is being remote controlled or manipulated via non-hardware event sources such as speech or AppleEvents; using GetCurrentEventKeyModifiers is also much faster than using EventAvail(0, &eventRecord) or GetCurrentKeyModifiers.

GetCurrentEventKeyModifiers returns a valid modifier state only if your application is the active application. If your application is not active, then user input events are not flowing through the event dispatcher and the queue-synchronized state is not updated.

Availability
Declared In
CarbonEventsCore.h

GetCurrentEventLoop

Obtains a reference to the current event loop.

EventLoopRef GetCurrentEventLoop (
   void
);

Return Value

An event loop reference.

Discussion

This function returns the event loop for the current thread. If the current thread is a cooperative thread, the main event loop is returned.

Availability
Related Sample Code
Declared In
CarbonEventsCore.h

GetCurrentEventQueue

Obtains the current event queue. 

EventQueueRef GetCurrentEventQueue (
   void
);

Return Value

An event queue reference.

Discussion

This function obtains the event queue for the current thread. If the current thread is a cooperative thread, the main event queue is returned.

Availability
Declared In
CarbonEventsCore.h

GetCurrentEventTime

Returns the current time since last system startup, in seconds. 

EventTime GetCurrentEventTime (
   void
);

Return Value

EventTime.

Discussion

Returns the current time since last system startup in seconds.

Availability
Related Sample Code
Declared In
CarbonEventsCore.h

GetEventClass

Returns the class of an event (for example, window, mouse, or keyboard).

OSType GetEventClass (
   EventRef inEvent
);

Parameters
inEvent

The event in question.

Return Value

The class ID of the event. See “Event Class Constants” for more details.

Availability
Related Sample Code
Declared In
CarbonEventsCore.h

GetEventDispatcherTarget

Obtains the event target reference for the standard toolbox dispatcher.

EventTargetRef GetEventDispatcherTarget (
   void
);

Return Value

An event target reference.

Discussion

The standard toolbox dispatcher is the default mechanism for dispatching events to the appropriate event targets. You typically don’t need to call this, but some applications may need to pick events off the event queue and call the dispatcher themselves. This allows you to do just that instead of calling RunApplicationEventLoop to handle it all.

If desired, you can attach event handlers to the event dispatcher target. Doing so allows you to intercept any events before they can be sent to the appropriate event targets.

Availability
Declared In
CarbonEvents.h

GetEventKind

Returns the event kind for the specified event.

UInt32 GetEventKind (
   EventRef inEvent
);

Parameters
inEvent

The event in question.

Return Value

The kind of the event.

Discussion

Event kind values overlap in different event classes. For example, kEventMouseDown and kEventAppActivated both have the same value (1). The combination of class and kind determines a unique event signature.

Availability
Related Sample Code
Declared In
CarbonEventsCore.h

GetEventMonitorTarget

Obtains an event monitor target.

EventTargetRef GetEventMonitorTarget (
   void
);

Return Value

An event monitor target.

Discussion

The event monitor target is a special event target used to monitor user input events across all processes. When an event handler is installed on the event monitor target, the Carbon Event Manager examines the EventTypeSpec for user input event types, such as mouse-down, mouse-up, and key-down. It then requests that the WindowServer make copies of any of these events that are sent to any process, and delivers them to the current process. These events are queued into the main thread’s event queue and are sent directly to the event handlers installed on the event monitor target during normal event dispatching. Monitored events are not sent through the normal event dispatching path for the current process. Instead, they pass through the event dispatcher target and are sent directly to the event monitor target.Handlers installed on the event monitor target receive events only when the current application is inactive. When the current application is active, all events flow through the event dispatcher target, and no events are sent to the event monitor target. Currently, the event monitor supports the following event kinds: kEventRawKeyDown, kEventRawKeyUp, kEventRawKeyRepeat, kEventRawKeyModifiersChange, kEventMouseDown, kEventMouseUp, kEventMouseMoved, kEventMouseDragged, kEventMouseWheelMoved, kEventTabletPoint, and kEventTabletProximity.To prevent keyboard events from being passed to other applications, Carbon and Cocoa password-edit-text controls enable a secure input mode while the focus is on the control. Their password-edit-text controls prevent the monitoring event target from being used to capture password keystrokes. For added security, GetEventMonitorTarget requires that “Enable access for assistive devices” be checked in the Universal Access preference pane in order to monitor kEventRawKeyDown, kEventRawKeyUp, and kEventRawKeyRepeat events. If this control is not checked, you can still install handlers for these events on the event monitor target, but no events of these types will be sent to your handler. Administrator privileges are required to enable this feature. You can determine whether this control is checked using the AXAPIEnabled function in AXUIElement.h.

Availability
Declared In
CarbonEvents.h

GetEventParameter

Obtains a parameter from the specified event. 

OSStatus GetEventParameter (
   EventRef inEvent,
   EventParamName inName,
   EventParamType inDesiredType,
   EventParamType *outActualType,
   ByteCount inBufferSize,
   ByteCount *outActualSize,
   void *outData
);

Parameters
inEvent

The event to get the parameter from.

inName

The symbolic name of the parameter (for example, kEventParamDirectObject). The Carbon Event Manager defines a number of constants defining possible parameters.

inDesiredType

The desired type of the parameter (for example, typeWindowRef). The Carbon Event Manager automatically uses AppleEvent coercion handlers to convert the data in the event into the desired type, if possible. The Carbon Event Manager defines a number of constants to indicate possible parameter types. Pass typeWildCard to request that the data be returned in its original format.

outActualType

The actual type of the parameter (can be NULL if you are not interested in receiving this information).

inBufferSize

The size of the output buffer.

outActualSize

The actual size of the data, or NULL if you don’t want this information.

outData

The pointer to the buffer receiving the parameter data.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

Events often contain additional useful pieces of data, such as the location of a mouse-down event or the window in which an event occurred.

Availability
Related Sample Code
Declared In
CarbonEventsCore.h

GetEventRetainCount

Returns the reference count of an event.

ItemCount GetEventRetainCount (
   EventRef inEvent
);

Return Value

The current reference count for the specified event.

Discussion

When an event is created, its reference count is 1. Calls to RetainEvent increment this count; calls to ReleaseEvent decrement the count.

Availability
Declared In
CarbonEventsCore.h

GetEventTime

Returns the time a specific event occurred. 

EventTime GetEventTime (
   EventRef inEvent
);

Parameters
inEvent

The event in question.

Return Value

The time the event occurred.

Discussion

Returns the time the event specified occurred, specified as an EventTime value, which is a floating point number representing seconds since the last system startup.

Availability
Related Sample Code
Declared In
CarbonEventsCore.h

GetLastUserEventTime

Returns the last time a user input event arrived in the main event queue of the application.

EventTime GetLastUserEventTime (
   void
);

Return Value

The time of the last user event.

Discussion

A user input event is something generated by the user, typically a hardware event such as a mouse-click or key-down event.

Availability
Declared In
CarbonEvents.h

GetMainEventLoop

Obtains a reference to the main event loop.

EventLoopRef GetMainEventLoop (
   void
);

Return Value

An event loop reference.

Discussion

The main loop is the event loop for the main application thread.

Availability
Related Sample Code
Declared In
CarbonEventsCore.h

GetMainEventQueue

Obtains the main event queue. 

EventQueueRef GetMainEventQueue (
   void
);

Return Value

An event queue reference.

Discussion

The main queue is the event queue for the main application thread.

Availability
Related Sample Code
Declared In
CarbonEventsCore.h

GetMenuEventTarget

Obtains an event target reference for the specified menu. 

EventTargetRef GetMenuEventTarget (
   MenuRef inMenu
);

Parameters
inMenu

The menu to return the target for. See the Menu Manager documentation for a description of the MenuRef data type.

Return Value

An event target reference.

Discussion

Once you obtain this reference, you can send events to the target and install event handlers on it.

Availability
Declared In
CarbonEvents.h

GetNumEventsInQueue

Returns the number of events in the event queue.

ItemCount GetNumEventsInQueue (
   EventQueueRef inQueue
);

Parameters
inQueue

The event queue to query.

Return Value

The number of items in the queue.

Discussion

Returns the number of events in an event queue.

Availability
Declared In
CarbonEventsCore.h

GetSymbolicHotKeyMode

Obtains the current hot key mode.

OptionBits GetSymbolicHotKeyMode (
   void
);

Return Value

The mode request at the top of the hot key mode stack. If there are no mode requests on the stack, this function returns 0 to indicate that hot keys are currently enabled.

Discussion

Unless the “Enable access for assistive devices” checkbox is checked in the Universal Access preference pane, all hot keys are enabled, even if this function returns a nonzero value. This means that hot keys enabled by the caller may be disabled for the current user session if they were disabled by another process.

Availability
Declared In
CarbonEvents.h

GetUserFocusEventTarget

Obtains the event target reference for the user focus.

EventTargetRef GetUserFocusEventTarget (
   void
);

Return Value

An event target reference.

Discussion

This event target always references the current user focus. For example, if you install a handler on this target, then your handler will be called whenever an event is sent to the user focus. Keyboard events are always sent to this target.

Availability
Declared In
CarbonEvents.h

GetWindowEventTarget

Obtains the event target reference for a specified window. 

EventTargetRef GetWindowEventTarget (
   WindowRef inWindow
);

Parameters
inWindow

The window to return the event target for. See the QuickDraw Manager documentation for a description of the WindowRef data type.

Return Value

An event target reference.

Discussion

Once you obtain this reference, you can send events to the target and install an event handler on it.

Availability
Related Sample Code
Declared In
CarbonEvents.h

HIMouseTrackingGetParameters

Obtains information about how mouse tracking loops should behave.

OSStatus HIMouseTrackingGetParameters (
   OSType inSelector,
   EventTime *outTime,
   HISize *outDistance
);

Parameters
inSelector

The type of information to obtain. Currently, the only supported selector is kMouseParamsSticky.

outTime

When sticky mode is select, on return, the maximum time between mouse-down and mouse-up. If the time between events is longer than this value, sticky mode should not be invoked. Pass NULL if you don’t need this information.

outDistance

When sticky mode is select, on return, the maximum distance between mouse-down and mouse-up. If the distance between events is longer than this value, sticky mode should not be invoked. Pass NULL if you don’t need this information.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

Mouse tracking loops use different timeouts and wander distances to determine their behavior. This function provides a generic service for requesting this information.

Availability
Declared In
CarbonEvents.h

InstallEventHandler

Installs an event handler on a specified event target. 

OSStatus InstallEventHandler (
   EventTargetRef inTarget,
   EventHandlerUPP inHandler,
   ItemCount inNumTypes,
   const EventTypeSpec *inList,
   void *inUserData,
   EventHandlerRef *outRef
);

Parameters
inTarget

The event target to register your handler with.

inHandler

A pointer to your event handler function.

inNumTypes

The number of events you are registering for.

inList

A pointer to an array of EventTypeSpec entries representing the events you are interested in.

inUserData

The value you pass in this parameter is passed to your event handler function when it is called.

outRef

On return, an event handler reference, which you can use later to remove the handler. You can pass NULL if you don’t want the reference—when the target is disposed, the handler is disposed as well.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

After being installed, your handler will be called when an event you registered for is sent to the specified event target. Note that CarbonEvents.h defines several macros which you can use for particular event classes. These macros simply combine the appropriate GetxxxEventTarget call with InstallEventHandler.

Be sure to remove the event handler when you no longer need it by calling RemoveEventHandler. Doing so is especially important if the handler calls code that may disappear. For example, if a plugin installs an event handler and is later removed without removing the handler, the system may attempt to call back to the now nonexistent plugin code.

Availability
Related Sample Code
Declared In
CarbonEventsCore.h

InstallEventLoopIdleTimer

Installs a timer that fires only when there is no user activity.

OSStatus InstallEventLoopIdleTimer (
   EventLoopRef inEventLoop,
   EventTimerInterval inDelay,
   EventTimerInterval inInterval,
   EventLoopIdleTimerUPP inTimerProc,
   void *inTimerData,
   EventLoopTimerRef *outTimer
);

Parameters
inEventLoop

The event loop to add the timer.

inFireDelay

The delay before first firing this timer, in seconds. In Mac OS X v10.3 and earlier, this delay must be greater than zero. In Mac OS X v10.4 and later, the delay must be greater than or equal to zero. You cannot pass kEventDurationForever.

inInterval

The timer interval, in seconds. Pass 0 or kEventDurationForever for a one-shot timer.

inTimerProc

The function to call when the timer fires.

inTimerData

Data to pass to the timer function when called.

outTimer

A reference to the newly installed timer.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

An idle timer is the same as a standard event timer except that it fires only when no user events are being received. That is, if the system receives no user events for the inFireDelay delay time, the idle timer fires, and will continue to fire at the rate specified by inInterval. If the user begins activity again, the timer stops and resets. For example, you could use an idle timer in a search engine to begin a search 2 seconds after the user stops typing in the search text field.

The callback function for idle timers takes an additional parameter that tells the callback the user status. See EventLoopIdleTimerProcPtr and “Idle Timer Event Constants” for more information.

Be sure to dispose of the timer when you no longer need it by calling RemoveEventLoopTimer. Doing so is especially important if your timer calls code that may no longer exist. For example, if a plugin creates a timer that calls back to it, the timer will attempt to call it even after the plugin is removed.

Availability
Declared In
CarbonEventsCore.h

InstallEventLoopTimer

Installs a timer.

OSStatus InstallEventLoopTimer (
   EventLoopRef inEventLoop,
   EventTimerInterval inFireDelay,
   EventTimerInterval inInterval,
   EventLoopTimerUPP inTimerProc,
   void *inTimerData,
   EventLoopTimerRef *outTimer
);

Parameters
inEventLoop

The event loop to add the timer.

inFireDelay

The delay before first firing this timer, in seconds. In Mac OS X v10.3 and earlier, the delay must be greater than zero. In Mac OS X v10.4, the delay can be greater than or equal to zero.

In Mac OS X and CarbonLib 1.5 and later, you may pass kEventDurationForever to stop the timer from firing at all until SetEventLoopTimerNextFireTime is used to start it; in earlier versions of CarbonLib, to achieve the same effect, just pass zero and then immediately call SetEventLoopTimerNextFireTime( timer, (kEventDurationForever ) before returning control to your event loop.

inInterval

The timer interval, in seconds. Pass 0 or (in Mac OS X and CarbonLib 1.5 and later) kEventDurationForever for a one-shot timer.

inTimerProc

The function to call when the timer fires.

inTimerData

Data to pass to the timer function when called.

outTimer

A reference to the newly installed timer.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

Installs a timer onto the event loop specified. The timer can either fire once or repeatedly at a specified interval depending on the parameters passed to this function. It executes at task level and should not be confused with Time Manager tasks or any other interrupt-level callback. This means you can call toolbox functions, allocate memory, and draw without worrying about consequences. When a timer fires, it calls the callback you specified when the timer was installed.

Timers in general have two uses: as a timeout mechanism and as a periodic task. An everyday example of using a timer for a timeout might be a light that goes out if no motion is detected in a room for 5 minutes. For this, you might install a timer which will fire in 5 minutes. If motion is detected, you would reset the timer fire time and let the clock start over. If no motion is detected for the full 5 minutes, the timer will fire and you could power off the light. A periodic timer is one that fires at regular intervals (say every second or so). You might use such a timer to blink the insertion point in your editor, and so on.

One advantage of timers is that you can install the timer right from the code that wants the time. For example, the standard editable text control can install a timer to blink the cursor when it’s active, meaning that the Control Manager function IdleControls is a no-op for that control and doesn’t need to be called. When the control is inactive, it removes its timer and doesn’t waste CPU time in that state.

Currently, if you do decide to draw when your timer is called, be sure to save and restore the current port so that calling your timer doesn’t inadvertently change the port out from under someone.

Be sure to dispose of the timer when you no longer need it by calling RemoveEventLoopTimer. Doing so is especially important if your timer calls code that may no longer exist. For example, if a plugin creates a timer that calls back to it, the timer will attempt to call it even after the plugin is removed.

Availability
Related Sample Code
Declared In
CarbonEventsCore.h

InstallStandardEventHandler

Installs the standard event handler for the specified target.

OSStatus InstallStandardEventHandler (
   EventTargetRef inTarget
);

Parameters
inTarget

The event target for which you want to install the standard handler.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

Currently you can install the standard handler only for window event targets. To install the standard application handler, you must call RunApplicationEventLoop.

Note that events may also have default behaviors or standard definitions which define how an event is handled if you choose not to handle it yourself. Default behavior is the response that occurs whenever you choose not to handle the event, whether or not you have a standard handler installed. Standard definition behavior defines how an event is handled based on that element’s standard definition. For example, the standard menu definition provides some default responses for menu events you do not handle. However if you are using your own custom definition, you cannot assume that these default responses will occur.

You can also install the standard handler for a window event target by calling ChangeWindowAttributes to set the kWindowStandardHandlerAttribute window attribute on the window.

Availability
Declared In
CarbonEventsCore.h

InvokeEventComparatorUPP

Calls an event comparator function through a UPP. 

Boolean InvokeEventComparatorUPP (
   EventRef inEvent,
   void *inCompareData,
   EventComparatorUPP userUPP
);

Parameters
inEvent

The event to compare against.

inCompareData

Application-specific data. Typically this is the data you passed when calling FindSpecificEventInQueue or FlushSpecificEventsFromQueue.

userUPP

A UPP to the comparator function you want to invoke.

Return Value

Returns true if the comparator function indicates a match with the specified event, false otherwise.

Discussion

You call this function only if you need to invoke your event comparator callback yourself. In most cases you don’t need to call this function.

Availability
Declared In
CarbonEventsCore.h

InvokeEventHandlerUPP

Calls an event handler through a UPP.

OSStatus InvokeEventHandlerUPP (
   EventHandlerCallRef inHandlerCallRef,
   EventRef inEvent,
   void *inUserData,
   EventHandlerUPP userUPP
);

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

You use this function only if you need to invoke an event handler yourself. In most cases you don’t need to call this function.

Availability
Declared In
CarbonEventsCore.h

InvokeEventLoopIdleTimerUPP

Calls an event loop idle timer through a UPP. 

void InvokeEventLoopIdleTimerUPP (
   EventLoopTimerRef inTimer,
   EventLoopIdleTimerMessage inState,
   void *inUserData,
   EventLoopIdleTimerUPP userUPP
);

Discussion

You use this function only if you need to invoke an idle event timer callback yourself. In most cases you don’t need to call this function.

Availability
Declared In
CarbonEventsCore.h

InvokeEventLoopTimerUPP

Calls an event loop timer through a UPP. 

void InvokeEventLoopTimerUPP (
   EventLoopTimerRef inTimer,
   void *inUserData,
   EventLoopTimerUPP userUPP
);

Discussion

You use this function only if you need to invoke an event timer callback yourself. In most cases you don’t need to call this function.

Availability
Declared In
CarbonEventsCore.h

IsEventInMask

Determines whether an event reference matches a WaitNextEvent-style event mask.

Boolean IsEventInMask (
   EventRef inEvent,
   EventMask inMask
);

Parameters
inEvent

The event reference to check against the event mask.

inMask

The mask to consider. See the Event Manager documentation for a description of the EventMask data type.

Return Value

A Boolean whose value is TRUE if the event was in the mask; otherwise, FALSE.

Discussion

This is a companion function for ConvertEventRefToEventRecord, and is provided as a convenience function to help you if there are places in your application where you want to check an EventRef to see if it matches a classic EventMask bitfield. If the event matches, the function returns true.

Availability
Declared In
CarbonEvents.h

IsEventInQueue

Determines whether an event is in a particular queue. 

Boolean IsEventInQueue (
   EventQueueRef inQueue,
   EventRef inEvent
);

Parameters
inQueue

The queue to check.

inEvent

The event in question.

Return Value

Returns true if the specified event is posted to a queue.

Availability
Declared In
CarbonEventsCore.h

IsMouseCoalescingEnabled

Indicates whether mouse coalescing is enabled. 

Boolean IsMouseCoalescingEnabled (
   void
);

Return Value

A Boolean whose value is TRUE if mouse coalescing is on; otherwise, FALSE.

Discussion

If mouse coalescing is enabled, intermediate mouse movement events are merged into the most recent event, so that only one mouse moved or mouse dragged event is in the event queue at any time. For example, when the user moves the mouse across the screen, more mouse moved events are generated than most applications care about. Rather than place all these events in the queue (which would probably slow down the application), the Carbon Event Manager first checks to see if a mouse moved event already exists. If a mouse moved event already exists, that event is updated with the position and delta information from the more recently-generated event.

Availability
Declared In
CarbonEvents.h

IsSecureEventInputEnabled

Determines whether secure event input mode is enabled. 

Boolean IsSecureEventInputEnabled (
   void
);

Return Value

A Boolean whose value is TRUE if secure event input mode is enabled; otherwise, FALSE.

Discussion

This function determines whether secure event input is enabled by any process, not just the current process. Secure event input may be disabled in the current process but enabled in another process, in which case, this function returns TRUE.

Availability
Declared In
CarbonEventsCore.h

IsUserCancelEventRef

Returns whether the specified event indicates the user wishes to cancel an operation.

Boolean IsUserCancelEventRef (
   EventRef event
);

Return Value

A Boolean value indicating whether the event is a user cancel event.

Discussion

Tests the event given to see whether the event represents a user cancel event. Currently this is defined to be either the escape key being pressed or command-period being pressed.

Availability
Declared In
CarbonEvents.h

NewEventComparatorUPP

Creates an event comparator UPP.

EventComparatorUPP NewEventComparatorUPP (
   EventComparatorProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your event comparator callback function.

Return Value

The UPP for your callback function.

Discussion

When calling FindSpecificEventInQueue or FlushSpecificEventsFromQueue, you must pass a universal procedure pointer (UPP) to your event comparator instead of a standard procedure pointer.

Availability
Declared In
CarbonEventsCore.h

NewEventHandlerUPP

Creates an event handler UPP.

EventHandlerUPP NewEventHandlerUPP (
   EventHandlerProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your event handler.

Return Value

The UPP for your event handler.

Discussion

When registering your event handler with InstallEventHandler, you must pass a universal procedure pointer (UPP) to your event handler instead of a standard procedure pointer.

Availability
Related Sample Code
Declared In
CarbonEventsCore.h

NewEventLoopIdleTimerUPP

Creates an event loop idle timer UPP. 

EventLoopIdleTimerUPP NewEventLoopIdleTimerUPP (
   EventLoopIdleTimerProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your idle event timer callback function.

Return Value

The UPP for your event loop idle timer callback function.

Availability
Declared In
CarbonEventsCore.h

NewEventLoopTimerUPP

Creates an event loop timer UPP. 

EventLoopTimerUPP NewEventLoopTimerUPP (
   EventLoopTimerProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your event timer callback function.

Return Value

The UPP for your event timer callback function.

Availability
Related Sample Code
Declared In
CarbonEventsCore.h

PopSymbolicHotKeyMode

Removes a hot key mode request from the hot key mode stack.

void PopSymbolicHotKeyMode (
   void *inToken
);

Parameters
inToken

The hot key mode token that was returned by a previous call to PushSymbolicHotKeyMode.

Discussion

If the request is the topmost request on the stack, the hot key mode changes to the next request on the stack. If there are other mode requests on top of this request on the stack, the mode does not change.

Availability
Declared In
CarbonEvents.h

PostEventToQueue

Adds an event to the specified event queue.

OSStatus PostEventToQueue (
   EventQueueRef inQueue,
   EventRef inEvent,
   EventPriority inPriority
);

Parameters
inQueue

The event queue to post the event onto.

inEvent

The event to post.

inPriority

The priority of the event. See “Event Priority Constants” for a list of possible constants to pass.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

Posts an event to the queue specified and increments its retain count. This automatically wakes up the event loop of the thread the queue belongs to.

Availability
Related Sample Code
Declared In
CarbonEventsCore.h

ProcessHICommand

Sends a command to the command chain.

OSStatus ProcessHICommand (
   const HICommand *inCommand
);

Return Value

A result code. See “Carbon Event Manager Result Codes”

Discussion

ProcessHICommand is a convenience function for sending a “process command” event through the command chain (for example, from menu to user focus to application). The command event is sent initially to either a menu (if the command represents a menu command) or the current user focus. If the function returns eventNotHandledErr, the command was not handled by any element in the chain.

Availability
Declared In
CarbonEvents.h

PushSymbolicHotKeyMode

Sets a new mode for enabling and disabling symbolic hot keys.

void * PushSymbolicHotKeyMode (
   OptionBits inOptions
);

Parameters
inOptions

The requested symbolic hot key mode. For details, see “Hot Key Constants.”

Return Value

A token that is passed to PopSymbolicHotKeyMode to remove this mode request when it is no longer needed.

Discussion

The Event Manager maintains a stack of hot key modes that have been requested by calls to this function. The most recently pushed mode is the mode that is currently in use.

Disabling hot keys can significantly affect the usability of Mac OS X. For this reason, applications are allowed to disable hot keys only if the “Enable access for assistive devices” checkbox is checked in the Universal Access preference pane. If this checkbox is not checked when this function is called, the requested hot key mode is pushed onto the mode stack and a valid token is returned but the actual hot key mode is unchanged.

If the frontmost application pushes a new hot key mode that disables any hot keys, the new mode is active only while the application remains the frontmost application. If the application is deactivated or exits without re-enabling hot keys, the hot key mode automatically reverts to the previous mode.

Availability
Declared In
CarbonEvents.h

QuitApplicationEventLoop

Terminates the application event loop.

void QuitApplicationEventLoop (
   void
);

Discussion

This function is used to quit the RunApplicationEventLoop function. Typically, your application doesn’t need to call this. If your application has the Quit menu item tagged with the kHICommandQuit menu command ID, the toolbox will automatically call this for your application, automatically terminating your event loop. If your application wants to do pre-processing before the event loop exits, it should intercept either the kHICommandQuit menu command, or the kEventAppQuit event.

Availability
Related Sample Code
Declared In
CarbonEvents.h

QuitAppModalLoopForWindow

Quits the application-modal state for a window. 

OSStatus QuitAppModalLoopForWindow (
   WindowRef inWindow
);

Parameters
inWindow

The window that is leaving the modal state. See the Window Manager documentation for a description of the WindowRef data type.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

This function is used to quit a currently running call to RunAppModalLoopForWindow (that is, it terminates a modal loop). Typically you call this from a handler you have installed on the modal window in question when the user clicks the appropriate button (Ok, Cancel, and so on).

Availability
Declared In
CarbonEvents.h

QuitEventLoop

Causes a specific event loop to terminate.

OSStatus QuitEventLoop (
   EventLoopRef inEventLoop
);

Parameters
inEventLoop

The event loop to terminate.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

Usage of this is similar to WakeUpProcess, in that it causes the event loop specified to return immediately (as opposed to timing out). Typically you use this call in conjunction with RunCurrentEventLoop.

Availability
Declared In
CarbonEventsCore.h

ReceiveNextEvent

Waits for the next event of a specified type.

OSStatus ReceiveNextEvent (
   ItemCount inNumTypes,
   const EventTypeSpec *inList,
   EventTimeout inTimeout,
   Boolean inPullEvent,
   EventRef *outEvent
);

Parameters
inNumTypes

The number of event types to wait for (0 if any event should cause this function to return).

inList

The list of event types we are waiting for (pass NULL if any event should cause this function to return).

inTimeout

The time to wait before returning (passing kEventDurationForever is preferred).

inPullEvent

Pass true for this parameter to remove the next matching event from the queue.

outEvent

A pointer to the next event that matches the list passed in. If you passed true in the inPullEvent parameter, the event is owned by you, and you should release it when done.

Return Value

A result indicating whether an event was received, the timeout expired, or the current event loop was quit. See “Carbon Event Manager Result Codes” for possible values.

Discussion

This function tries to fetch the next event of a specified type. If no events in the event queue match, this function will run the current event loop until an event that matches arrives, or the timeout expires. Except for timers firing, your application is blocked waiting for events to arrive when inside this function.

Availability
Declared In
CarbonEventsCore.h

RegisterEventHotKey

Registers a global hot key.

OSStatus RegisterEventHotKey (
   UInt32 inHotKeyCode,
   UInt32 inHotKeyModifiers,
   EventHotKeyID inHotKeyID,
   EventTargetRef inTarget,
   OptionBits inOptions,
   EventHotKeyRef *outRef
);

Parameters
inHotKeyCode

The virtual key code of the hot key you want to register.

inHotKeyModifiers

The keyboard modifiers to look for. In Mac OS X v10.2 and earlier, if you do not specify a modifier key, this function returns paramErr. In Mac OS X v10.3 and later, passing 0 does not cause an error.

inHotKeyID

The application-specified hot key ID. You will receive this ID in the kEventHotKeyPressed event as the direct object parameter.

inTarget

The target to notify when the hot key is pressed.

inOptions

Currently unused. You must pass 0.

outRef

On return, a reference to the new hot key. You need this reference if you later wish to unregister it.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

This function registers a global hot key based on the virtual key code and modifiers you pass in. When the user enters the hot-key combination, a kEventHotKeyPressed event is sent to the target you specified. Only one such combination can exist for the current application (that is, multiple entities in the same application cannot register for the same hot key combination). The same hot key can, however, be registered by multiple applications. This means that multiple applications can potentially be notified when a particular hot key is requested. This might not necessarily be desirable, but it is how it works at present.

Availability
Declared In
CarbonEvents.h

ReleaseEvent

Releases, and possibly disposes of, the specified event.

void ReleaseEvent (
   EventRef inEvent
);

Parameters
inEvent

The event to release.

Discussion

This function decrements the reference count of an event. If the reference count reaches 0, the event is disposed.

Availability
Related Sample Code
Declared In
CarbonEventsCore.h

RemoveEventFromQueue

Removes an event from the event queue.

OSStatus RemoveEventFromQueue (
   EventQueueRef inQueue,
   EventRef inEvent
);

Parameters
inQueue

The queue to remove the event from.

inEvent

The event to remove.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

Removes the given event from the queue on which it was posted and decrements its retain count.

Availability
Declared In
CarbonEventsCore.h

RemoveEventHandler

Removes the specified event handler.

OSStatus RemoveEventHandler (
   EventHandlerRef inHandlerRef
);

Parameters
inHandlerRef

The handler ref to remove (returned in a call to InstallEventHandler). After you call this function, the handler reference is considered invalid and can no longer be used.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

Removes an event handler from the event target to which it was bound.

Availability
Related Sample Code
Declared In
CarbonEventsCore.h

RemoveEventLoopTimer

Removes the specified timer.

OSStatus RemoveEventLoopTimer (
   EventLoopTimerRef inTimer
);

Parameters
inTimer

The timer to remove.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

Removes a timer that was previously installed by a call to InstallEventLoopTimer or InstallEventLoopIdleTimer. You call this function when you are done using a timer.

Availability
Related Sample Code
Declared In
CarbonEventsCore.h

RemoveEventTypesFromHandler

Removes events from an installed event handler.

OSStatus RemoveEventTypesFromHandler (
   EventHandlerRef inHandlerRef,
   ItemCount inNumTypes,
   const EventTypeSpec *inList
);

Parameters
inHandlerRef

The event handler to remove the events from.

inNumTypes

The number of events to remove.

inList

A pointer to an array of EventTypeSpec structures.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

You can use this function dynamically change which events you want your handler to respond to.

Availability
Declared In
CarbonEventsCore.h

RetainEvent

Increments the reference count of an event.

EventRef RetainEvent (
   EventRef inEvent
);

Parameters
inEvent

The event to retain.

Return Value

The event reference you passed in the inEvent parameter. A value of NULL indicates an error condition.

Discussion

The RetainEvent function increments an event’s reference count by 1. You can use this function to ensure that an event is never disposed of by another event handler. However, if the event system or some other event handler changes the event, those changes are reflected in your reference. To create a separate, unique copy of an event, use CopyEvent instead.

Availability
Declared In
CarbonEventsCore.h

RunApplicationEventLoop

Runs the application event loop.

void RunApplicationEventLoop (
   void
);

Discussion

This function is used as the main event loop for a Carbon Event-based application. Once entered, this function waits for events to arrive and dispatches them to your event handlers automatically.

Note that calling RunApplicationEventLoop also installs the standard application handler, which provides standard handler responses for menu and application events.

Availability
Related Sample Code
Declared In
CarbonEvents.h

RunAppModalLoopForWindow

Puts the window in an application-modal state. 

OSStatus RunAppModalLoopForWindow (
   WindowRef inWindow
);

Parameters
inWindow

The window you wish to behave modally. See the Window Manager documentation for a description of the WindowRef data type.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

This function is used as a replacement for the Dialog Manager function ModalDialog to drive a Carbon Event-based modal dialog. Once called, this function will not exit until QuitAppModalLoopForWindow is called.

While in the modal state, the standard toolbox dispatcher processes events only for the modal window and any that are above it (that is, closer to the front). This feature allows you to create stacked modal dialogs, if desired.

Availability
Declared In
CarbonEvents.h

RunCurrentEventLoop

Executes the event loop in the current thread. 

OSStatus RunCurrentEventLoop (
   EventTimeout inTimeout
);

Parameters
inTimeout

The time to wait until returning (can be kEventDurationForever).

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

This function “runs” the event loop, returning only if aborted or the timeout specified is reached. The event loop is mostly blocked while in this function, occasionally waking up to fire timers or pick up events. The typical use of this function is to cause the current thread to wait for some operation to complete, most likely on another thread of execution.

Availability
Declared In
CarbonEventsCore.h

SendEventToEventTarget

Sends an event to the specified event target. 

OSStatus SendEventToEventTarget (
   EventRef inEvent,
   EventTargetRef inTarget
);

Parameters
inEvent

The event to send.

inTarget

The target to send it to.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

If you are creating your own events, you can dispatch them immediately to an event target by calling this function.

Availability
Related Sample Code
Declared In
CarbonEventsCore.h

SendEventToEventTargetWithOptions

Sends an event to the specified event target with propagation options. 

OSStatus SendEventToEventTargetWithOptions (
   EventRef inEvent,
   EventTargetRef inTarget,
   OptionBits inOptions
);

Parameters
inEvent

The event to send.

inTarget

The target to send it to.

inOptions

Options indicating how the event should be propagated. See “Event Target Propagation Options” for a list of possible values.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

This function is identical to SendEventToEventTarget except that you can specify how the event is propagated using options.

Availability
Declared In
CarbonEventsCore.h

SetEventLoopTimerNextFireTime

Sets the next time that the specified timer will fire.

OSStatus SetEventLoopTimerNextFireTime (
   EventLoopTimerRef inTimer,
   EventTimerInterval inNextFire
);

Parameters
inTimer

The timer whose firing time you want to set.

inNextFire

The interval from the current time to wait until firing the timer again.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

This function is used to “reset” a timer. It controls the next time the timer fires. This will override any interval you might have set. For example, if you have a timer that fires every second, and you call this function setting the next time to 5 seconds from now, the timer will sleep for 5 seconds, then fire. The timer will then resume its one second interval. This function acts as if you removed the timer and reinstalled it with a new first-fire delay.

Availability
Declared In
CarbonEventsCore.h

SetEventParameter

Sets a parameter associated with a particular event. 

OSStatus SetEventParameter (
   EventRef inEvent,
   EventParamName inName,
   EventParamType inType,
   ByteCount inSize,
   const void *inDataPtr
);

Parameters
inEvent

The event to set the data for.

inName

The symbolic name of the parameter.

inType

The symbolic type of the parameter.

inSize

The size of the parameter data.

inDataPtr

A pointer to the parameter data.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

When creating events, you may want to specify additional event-related information, such as the mouse location or the window in which the event occurred. To set these you call SetEventParameter, specifying the type and value for the desired parameter.

Availability
Related Sample Code
Declared In
CarbonEventsCore.h

SetEventTime

Sets the event time for a given event. 

OSStatus SetEventTime (
   EventRef inEvent,
   EventTime inTime
);

Parameters
inEvent

The event in question.

inTime

The new time.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

This function allows you to set the time of a given event, if you so desire. In general, you would never use this function, except for those special cases where you reuse an event from time to time instead of creating a new event each time.

Availability
Declared In
CarbonEventsCore.h

SetMouseCoalescingEnabled

Turns mouse coalescing on or off.

OSStatus SetMouseCoalescingEnabled (
   Boolean inNewState,
   Boolean *outOldState
);

Parameters
inNewState

Pass true to turn mouse coalescing on, false otherwise.

outOldState

A Boolean value indicating the previous mouse coalescing state (that is, before you called this function to set it). You can use this value if you want to save the previous state for later restoration. If you don’t need this state information, pass NULL.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

See IsMouseCoalescingEnabled for a definition of mouse coalescing.

Availability
Declared In
CarbonEvents.h

TrackMouseLocation

Tracks the mouse, blocking your application when there is no activity.

OSStatus TrackMouseLocation (
   GrafPtr inPort,
   Point *outPt,
   MouseTrackingResult *outResult
);

Parameters
inPort

The graphics port to consider for mouse coordinates. You can pass NULL for this parameter to indicate the current port. The mouse location is returned in terms of local coordinates of this port. See the QuickDraw Manager documentation for a description of the GrafPtr data type.

outPt

On exit, a pointer to the mouse location from the last mouse event that caused this function to exit.

outResult

On exit, a pointer to a value representing what kind of event was received that cause the function to exit, such as kMouseTrackingMouseReleased.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

Once entered, this function waits for certain mouse events (move, mouse down, mouse up). When one of these events occurs, the function returns and tells the caller what happened and where the mouse is currently located. While there is no activity, the current event loop is run, effectively blocking the current thread (save for any timers that fire). This helps to minimize CPU usage when there is nothing going on.

Availability
Declared In
CarbonEvents.h

TrackMouseLocationWithOptions

Tracks the mouse with additional options. 

OSStatus TrackMouseLocationWithOptions (
   GrafPtr inPort,
   OptionBits inOptions,
   EventTimeout inTimeout,
   Point *outPt,
   UInt32 *outModifiers,
   MouseTrackingResult *outResult
);

Parameters
inPort

The graphics port (GrafPort) to consider for mouse coordinates. You can pass NULL for this parameter to indicate the current port. The mouse location is returned in global coordinates. See the QuickDraw Manager documentation for a description of the GrafPtr data type.

inOptions

The only option supported by this function at present is the option to have the toolbox leave mouse up events in the queue, rather than pulling them (which is the default). See “Mouse Tracking Option Constant” for more information.

inTimeout

The amount of time to wait for an event. If no events arrive within this time, kMouseTrackingTimedOut is returned in outResult.

outPt

On return, a pointer to the mouse location from the last mouse event that caused this function to exit. If a timeout or key modifiers changed event caused this function to exit, the current mouse position at the time is returned.

outModifiers

On return, a pointer to the most recent state of the keyboard modifiers.

outResult

On return, a pointer to a value indicating the kind of event that caused the function to exit, such as kMouseTrackingMouseReleased.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

Once entered, this function waits for certain mouse events (move, mouse down, mouse up). When one of these events occurs, the function returns and tells the caller what happened and where the mouse is currently located. While there is no activity, the current event loop is run, effectively blocking the current thread (save for any timers that fire). This helps to minimize CPU usage when there is nothing going on.

Availability
Related Sample Code
Declared In
CarbonEvents.h

TrackMouseRegion

Tracks the mouse within a region.

OSStatus TrackMouseRegion (
   GrafPtr inPort,
   RgnHandle inRegion,
   Boolean *ioWasInRgn,
   MouseTrackingResult *outResult
);

Parameters
inPort

The graphics port to consider for mouse coordinates. You can pass NULL for this parameter to indicate the current port. See the QuickDraw Manager documentation for a description of the GrafPtr data type.

inRegion

The region to consider. This should be in the coordinates of the port you passed to inPort. See the QuickDraw Manager documentation for a description of the RgnHandle data type.

ioWasInRgn

On entering the region, this parameter should be set to true if the mouse is currently inside the region passed in inRegion, or false if the mouse is currently outside the region. On exit, this parameter is updated to reflect the current reality. For example, if the outResult parameter returns kMouseTrackingMouseExited, ioWasInRgn will be set to false when this function exits. Because it is updated from within, you should only need to set this yourself before the first call to this function in your tracking loop.

outResult

On exit, a pointer to a value indicating the kind of event that caused the function to exit, such as kMouseTrackingMouseEntered.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

This function is largely identical to TrackMouseLocation. The difference between TrackMouseLocation and TrackMouseRegion is that TrackMouseRegion only returns when the mouse enters or exits a specified region that you pass in to the function, as opposed to whenever the mouse moves (it also returns for mouse up/down events). This is useful if you don’t need to know intermediate mouse events, but rather just if the mouse enters or leaves an area.

Note that in some cases you may prefer to register one or more special mouse tracking regions and receive events when the mouse enters or exits the region. However, this alternative method does not automatically inform you about mouse up and mouse down actions. See CreateMouseTrackingRegion for more details.

Availability
Declared In
CarbonEvents.h

UnregisterEventHotKey

Unregisters a global hot key. 

OSStatus UnregisterEventHotKey (
   EventHotKeyRef inHotKey
);

Parameters
inHotKey

The event hot key reference of the hot key you want to unregister.

Return Value

A result code. See “Carbon Event Manager Result Codes.”

Discussion

Unregisters a global hot key that was previously registered with the function RegisterEventHotKey. You do not need to unregister a hot key when your application terminates; the system takes care of that for you. You can use this function if the user changes a hot key for something in your application—you would unregister the previous key and register your new key.

Availability
Declared In
CarbonEvents.h

Callbacks

EventComparatorProcPtr

Defines the format of your event comparator callback function.

typedef Boolean (*EventComparatorProcPtr) (
   EventRef inEvent,
   void * inCompareData
);

If you name your function MyEventComparatorProc, you would declare it like this:

Boolean MyEventComparatorProc (
   EventRef inEvent,
   void * inCompareData
);

Parameters
inEvent

The event to compare.

inCompareData

The data you passed to FindSpecificEventInQueue or FlushSpecificEventsFromQueue.

Return Value

A Boolean value indicating whether the event matches (true) or not (false).

Discussion

You use this callback function when searching the event queue using functions such as FindSpecificEventInQueue.

Availability
Declared In
CarbonEventsCore.h

EventHandlerProcPtr

Defines the format of your event handler. 

typedef OSStatus (*EventHandlerProcPtr) (
   EventHandlerCallRef inHandlerCallRef,
   EventRef inEvent,
   void * inUserData
);

If you name your function MyEventHandlerProc, you would declare it like this:

OSStatus MyEventHandlerProc (
   EventHandlerCallRef inHandlerCallRef,
   EventRef inEvent,
   void * inUserData
);

Parameters
inHandlerCallRef

A reference to the current handler call chain. This is passed to your handler so that you can call CallNextEventHandler if you need to.

inEvent

The event that triggered this call.

inUserData

The application-specific data you passed in to InstallEventHandler.

Return Value

A result code. See “Carbon Event Manager Result Codes.” Returning noErr indicates you handled the event. Returning eventNotHandledErr indicates you did not handle the event and perhaps other handlers in the calling chain should take action.

Discussion

Callback to install on an event target.

Availability
Declared In
CarbonEventsCore.h

EventLoopIdleTimerProcPtr

Defines the format of your idle timer callback function.

typedef void (*EventLoopIdleTimerProcPtr) (
   EventLoopTimerRef inTimer,
   EventLoopIdleTimerMessage inState,
   void * inUserData
);

If you name your function MyEventLoopTimerProc, you would declare it like this:

void MyEventLoopTimerProc (
   EventLoopTimerRef inTimer,
   EventLoopIdleTimerMessage inState,
   void * inUserData
);

Parameters
inTimer

The timer that fired.

inState

The state of the idle period. See “Idle Timer Event Constants” for a list of possible constants you can receive.

inUserData

The application-specific data you passed into InstallEventLoopIdleTimer.

Discussion

Called when an idle timer fires.

Availability
Declared In
CarbonEventsCore.h

EventLoopTimerProcPtr

Defines the format of your event loop timer callback function. 

typedef void (*EventLoopTimerProcPtr) (
   EventLoopTimerRef inTimer,
   void * inUserData
);

If you name your function MyEventLoopTimerProc, you would declare it like this:

void MyEventLoopTimerProc (
   EventLoopTimerRef inTimer,
   void * inUserData
);

Parameters
inTimer

The timer that fired.

inUserData

The data you passed into InstallEventLoopTimer.

Discussion

Called when a timer fires.

Availability
Declared In
CarbonEventsCore.h

Data Types

EventClassID

Represents an event class ID. 

typedef UInt32 EventClassID;

Availability
Declared In
CarbonEvents.h

EventComparatorUPP

Represents a universal procedure pointer to an event comparator callback function.

typedef EventComparatorProcPtr EventComparatorUPP

EventHandlerCallRef

Indicates the next handler in the event handler calling hierarchy. 

typedef struct OpaqueEventHandlerCallRef * EventHandlerCallRef;

Discussion

This structure is passed to your event handler, which can then choose to pass control to the next handler in the calling hierarchy (such as a standard event handler). Doing so is a convenient way to add pre- or post-processing to the standard event handler. See the CallNextEventHandler function for more information.

Availability
Declared In
CarbonEventsCore.h

EventHandlerUPP

Represents a universal procedure pointer for an event handler callback function.

typedef EventHandlerProcPtr EventHandlerUPP;

Availability
Declared In
CarbonEventsCore.h

EventLoopTimerUPP

Represents a universal procedure pointer for an event timer callback function.

typedef EventLoopTimerProcPtr EventLoopTimerUPP;

Availability
Declared In
CarbonEventsCore.h

EventLoopIdleTimerUPP

Represents a universal procedure pointer for an idle event timer callback function. 

typedef EventLoopIdleTimerProcPtr EventLoopIdleTimerUPP;

Availability
Declared In
CarbonEventsCore.h

EventHandlerRef

Represents an installed event handler. 

typedef struct OpaqueEventHandlerRef * EventHandlerRef;

Discussion

You receive an event handler reference when you install your handler using InstallEventHandler. You can use this reference when calling functions such as RemoveEventHandler and AddEventTypesToHandler.

Availability
Declared In
CarbonEventsCore.h

EventHotKeyID

Represents the ID of a global hot key. 

struct EventHotKeyID {
   OSType signature;
   UInt32 id;
};
typedef struct EventHotKeyID EventHotKeyID;

Discussion

You register a hot key using the RegisterEventHotKey function.

Availability
Declared In
CarbonEvents.h

EventHotKeyRef

Represents a registered global hot key. 

typedef struct OpaqueEventHotKeyRef * EventHotKeyRef;

Discussion

You register a hot key using the RegisterEventHotKey function.

Availability
Declared In
CarbonEvents.h

EventLoopIdleTimerMessage

Represents an idle timer message.

typedef UInt16 EventLoopIdleTimerMessage;

Discussion

Sent to idle timer callback functions to indicate the current idle status. See “Idle Timer Event Constants” for a list of possible values.

Availability
Declared In
CarbonEventsCore.h

EventLoopRef

Represents an event loop. 

typedef struct OpaqueEventLoopRef * EventLoopRef;

Discussion

The EventLoopRef type represents an event loop, which is the conceptual entity that you run to fetch events from hardware and other sources and also fires timers that might be installed with InstallEventLoopTimer or InstallEventLoopIdleTimer. The term “run” is a bit of a misnomer, as the event loop’s goal is to stay as blocked as possible to minimize CPU usage for the current application. The event loop is run implicitly through calls to functions like ReceiveNextEvent, RunApplicationEventLoop, or even the Classic Event Manager function WaitNextEvent. It can also be run explicitly through a call to RunCurrentEventLoop. Each preemptive thread can have an event loop. Cooperative threads share the main thread’s event loop.

Availability
Declared In
CarbonEventsCore.h

EventLoopTimerRef

Represents an installed event timer. 

typedef struct __EventLoopTimer * EventLoopTimerRef;

Discussion

The EventLoopTimerRef type represents a timer function that is called either once or at regular intervals. See InstallEventLoopTimer and InstallEventLoopIdleTimer for more information about event timers.

Availability
Declared In
CarbonEventsCore.h

EventParamName

Represents an event parameter constant.

typedef OSType EventParamName;

Discussion

You specify an event parameter name when calling GetEventParameter or SetEventParameter. Parameter names indicate what kind of event parameter you want to set or obtain (such as kEventParamDirectObject). For specific types, see the tables of event parameters and types associated with each class of events (for example, Table 8).

Availability
Declared In
CarbonEventsCore.h

EventParamType

Represents an event parameter type constant. 

typedef OSType EventParamType;

Discussion

You specify an event parameter type when calling GetEventParameter or SetEventParameter. Event parameter types indicate the data type of the parameter you want to set or obtain (such as typeBoolean). For specific types, see the tables of event parameters and types associated with each class of events (for example, Table 11).

Availability
Declared In
CarbonEventsCore.h

EventQueueRef

Represents an event queue. 

typedef struct OpaqueEventQueueRef * EventQueueRef;

Availability
Declared In
CarbonEventsCore.h

EventRef

Represents an opaque data structure that identifies individual events.

typedef struct OpaqueEventRef * EventRef;

Availability
Declared In
CarbonEventsCore.h

EventTargetRef

Represents an event target (such as a window or control). 

typedef struct OpaqueEventTargetRef * EventTargetRef;

Availability
Declared In
CarbonEventsCore.h

EventTime

Represents a time value in seconds. An absolute EventTime value is seconds since boot time. 

typedef double EventTime;

Availability
Declared In
CarbonEventsCore.h

EventTimeout

Represents a timeout interval, in seconds.

typedef EventTime EventTimeout;

Availability
Declared In
CarbonEventsCore.h

EventTimerInterval

Specifies the period of an event timer, in seconds. 

typedef EventTime EventTimerInterval;

Availability
Declared In
CarbonEventsCore.h

EventType

Represents an event type.

typedef UInt32 EventType;

Availability
Declared In
cssmspi.h

EventTypeSpec

Describes the class and kind of an event.

struct EventTypeSpec {
   UInt32 eventClass;
   UInt32 eventKind;
};
typedef struct EventTypeSpec EventTypeSpec;

Discussion

This structure is used to specify an event. Typically, you pass a static array of EventTypeSpec structures into functions such as InstallEventHandler, as well as functions such as FlushEventsMatchingListFromQueue.

Availability
Declared In
CarbonEventsCore.h

HICommand

Represents a command event; this structure has been superseded by the HICommandExtended structure.

struct HICommand {
   UInt32 attributes
   UInt32 commandID
   struct {
      MenuRef menuRef;
      MenuItemIndex menuItemIndex;
   } menu;
};
typedef struct HICommand HICommand;

Fields
attributes

Attributes of the command event.

commandID

The command ID of the command event.

menuRef

A reference to the menu containing the HICommand.

menuItemIndex

The index number of the menu item containing the HICommand.

Availability
Declared In
CarbonEvents.h

HICommandExtended

Represents an extended command event.

struct HICommandExtended {
   UInt32 attributes;
   UInt32 commandID;
   union {
      controlRef control;
      windowRef window;
      struct {
         MenuRef menuRef;
         MenuItemIndex menuItemIndex;
      } menu;
   } source;
};
typedef struct HICommandExtended HICommandExtended;

Fields
attributes

Attributes of the command event. The value of this field (indicating whether the source of the command event is a control, window, or menu) determines what reference is stored in the union. See “Command Event Source Constants” for a list of possible values.

commandID

The command ID of the command event.

controlRef

The control that produced the command event.

windowRef

The window that produced the command event.

menuRef

A reference to the menu containing the command event.

menuItemIndex

The index number of the menu item containing the command event.

Discussion

The HICommandExtended structure was introduced in Mac OS X v10.2 and CarbonLib 1.6. Because the HICommand and HICommandExtended structures are exactly the same size and have the same fields at the same offsets, you can use an HICommandExtended structure at runtime while running on any version of CarbonLib or Mac OS X. The only difference is that the HICommandExtended structure has a union that allows you to get type-safe access to the source object. The originator of the command determines whether the structure actually contains a ControlRef, WindowRef, MenuRef, or nothing at all. You can determine what is in the command by checking the attributes field.

For example, in Mac OS X v10.2 and later, when a push button is clicked, the Control Manager sends a command event containing the push button’s command ID, sets the kHICommandFromControl bit in the attributes field, and stores the button’s ControlRef in the source.control field. In Mac OS X v10.0 and v10.1, the same command event is sent, but the kHICommandFromControl, kHICommandFromMenu, and kHICommandFromWindow attributes are not set, and the source.controlRef, source.menu.menuRef and source.windowRef fields are not initialized, respectively. Your code can use an HICommandExtended structure when running on Mac OS X v10.0 and v10.1 as long as it first checks the kHICommandFromControl, kHICommandFromMenu, and kHICommandFromWindow attributes before accessing the source.control, menu.control, and window.control fields.

Availability
Declared In
CarbonEvents.h

MouseTrackingRef

Represents a mouse tracking region

typedef struct OpaqueMouseTrackingRef * MouseTrackingRef;

Discussion

Use CreateMouseTrackingRegion to create a mouse tracking region.

Availability
Declared In
CarbonEvents.h

MouseTrackingRegionID

Represents a mouse tracking region identifier. 

struct MouseTrackingRegionID {
   OSType signature;
   SInt32 id;
};
typedef struct MouseTrackingRegionID MouseTrackingRegionID;

Fields
signature

A four-character code (such as 'moof')that uniquely identifies the application that owns this mouse tracking region.

id

An integer that identifies the mouse tracking region in this application.

Discussion

Each application can register multiple mouse tracking regions as long as each region has a unique ID. Use CreateMouseTrackingRegion to create a mouse tracking region.

Availability
Declared In
CarbonEvents.h

TabletPointRec

Defines a tablet point structure.

struct TabletPointRec {
   SInt32 absX;
   SInt32 absY;
   SInt32 absZ;
   UInt16 buttons;
   UInt16 pressure;
   SInt16 tiltX;
   SInt16 tiltY;
   UInt16 rotation;
   SInt16 tangentialPressure;
   UInt16 deviceID;
   SInt16 vendor1;
   SInt16 vendor2;
   SInt16 vendor3;
};
typedef struct TabletPointRec TabletPointRec;
typedef TabletPointRec TabletPointerRec;

Fields
absX

The x-coordinate of the pointer, in tablet space (at full tablet resolution).

absY

The y-coordinate of the pointer, in tablet space (at full tablet resolution).

absZ

The z-coordinate of the pointer, in tablet space (at full tablet resolution).

buttons

The buttons that are pressed. This integer is interpreted as a bit field, with bit 0 indicating the first button, bit 1 the second button, and so on. A value of 1 indicates that the button is down.

pressure

The scaled pressure value. The pressure value is in the range 0 to 65535.

tiltX

The scaled tilt x value. The tilt value is in the range -32767 to 32767.

tiltY

The scaled tilt y value. The tilt value is in the range -32767 to 32767.

rotation

The device rotation as a fixed-point value in a 10.6 format.

tangentialPressure

The tangential pressure on the device. This pressure is in the range -32767 to 32767.

deviceID

A unique system-assigned device ID. This ID matches the device ID you receive for the kEventTabletProximity event.

vendor1

A vendor-defined value.

vendor2

A vendor-defined value.

vendor3

A vendor-defined value.

Discussion

You receive this structure in the kEventParamTabletPointRec parameter for the kEventTabletPoint event.

Availability
Declared In
CarbonEvents.h

TabletProximityRec

Defines a tablet proximity structure.

struct TabletProximityRec {
   UInt16 vendorID;
   UInt16 tabletID;
   UInt16 pointerID;
   UInt16 deviceID;
   UInt16 systemTabletID;
   UInt16 vendorPointerType;
   UInt32 pointerSerialNumber;
   UInt64 uniqueID;
   UInt32 capabilityMask;
   UInt8 pointerType;
   UInt8 enterProximity;
};
typedef struct TabletProximityRec TabletProximityRec;

Fields
vendorID

A vendor-defined ID. This value is typically the USB vendor ID.

tabletID

A vendor-defined ID for the tablet. This value is typically the USB product ID for the tablet.

pointerID

A vendor-defined ID for the pointing device (for example, a pen).

deviceID

A unique system-assigned device ID. This ID matches the device ID you receive for the kEventTabletPoint event.

systemTabletID

A system-assigned unique tablet ID.

vendorPointerType

A vendor-defined pointer type.

pointerSerialNumber

A vendor-defined serial number for the pointing device.

uniqueID

A vendor-defined ID for this pointer.

capabilityMask

A bit mask representing the capabilities of this device.

pointerType

The type of pointing device.

enterProximity

The proximity value. A nonzero value indicates that the pointer is entering the tablet proximity; zero indicates that it is leaving.

Discussion

You receive this structure in the kEventParamTabletProximityRec parameter for the kEventTabletProximity event.

Availability
Declared In
CarbonEvents.h

ToolboxObjectClassRef

Represents a toolbox object class.

typedef struct OpaqueToolboxObjectClassRef * ToolboxObjectClassRef;

Discussion

Typically you use toolbox object classes to specify custom user interface elements. See RegisterToolboxObjectClass for more information.

Availability
Declared In
CarbonEvents.h

Constants

Basic Event Constants

Event Class Constants

Define constants for specifying event classes.

typedef UInt32 EventClass;
enum {
   kEventClassMouse = 'mous',
   kEventClassKeyboard = 'keyb',
   kEventClassTextInput = 'text',
   kEventClassApplication = 'appl',
   kEventClassAppleEvent = 'eppc',
   kEventClassMenu = 'menu',
   kEventClassWindow = 'wind',
   kEventClassControl = 'cntl',
   kEventClassCommand = 'cmds',
   kEventClassTablet = 'tblt',
   kEventClassVolume = 'vol ',
   kEventClassAppearance = 'appm',
   kEventClassService = 'serv',
   kEventClassToolbar = 'tbar',
   kEventClassToolbarItem = 'tbit',
   kEventClassToolbarItemView = 'tbiv',
   kEventClassAccessibility = 'acce'.
   kEventClassSystem = 'macs',
   kEventClassInk = 'ink ',
   kEventClassTSMDocumentAccess = 'tdac'
};

Constants
kEventClassMouse

Events related to the mouse (mouse down/up/moved).

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventClassKeyboard

Events related to the keyboard.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventClassTextInput

Events related to text input (by keyboard or by input method).

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventClassApplication

Application-level events (launch, quit, and so on).

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventClassAppleEvent

Apple Events.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventClassMenu

Menu-related events.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventClassWindow

Window-related events.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventClassControl

Control-related events.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventClassCommand

Command events (HICommands).

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventClassTablet

Events related to tablet input.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventClassVolume

Events related to File Manager volumes.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventClassAppearance

Events related to the Appearance Manager.

Available in Mac OS X v10.1 and later.

Declared in CarbonEvents.h.

kEventClassService

Events related to the Services Manager.

Available in Mac OS X v10.1 and later.

Declared in CarbonEvents.h.

kEventClassToolbar

Events related to the toolbar (not the toolbar window class).

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventClassToolbarItem

Events related to toolbar items.

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventClassToolbarItemView

Events related to toolbar item views.

Available in Mac OS X v10.3 and later.

Declared in CarbonEvents.h.

kEventClassAccessibility

Events related to application accessibility features.

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventClassSystem

Events related to the system.

Available in Mac OS X v10.3 and later.

Declared in CarbonEvents.h.

kEventClassInk

Events related to ink.

Available in Mac OS X v10.3 and later.

Declared in CarbonEvents.h.

kEventClassTSMDocumentAccess

Events related to Text Services Manager document access.

Available in Mac OS X v10.3 and later.

Declared in CarbonEvents.h.

Discussion

Event classes specify broad categories of events, grouped according to the object they are associated with. Within an event class are specific event types.

Event Attributes

Define constants for special attributes of an event.

typedef UInt32 EventAttributes;
enum {
   kEventAttributeNone = 0,
   kEventAttributeUserEvent = (1 << 0),
   kEventAttributeMonitored= 1 << 3
};

Constants
kEventAttributeNone

No attributes.

Available in Mac OS X v10.0 and later.

Declared in CarbonEventsCore.h.

kEventAttributeUserEvent

An event generated in response to a user action.

Available in Mac OS X v10.0 and later.

Declared in CarbonEventsCore.h.

kEventAttributeMonitored

An event that was not originally targeted to this process but has been provided to this process because an event handler for this event type has been installed on the event monitoring target. The event dispatcher sends events with this attribute directly to the event monitor target.

Available in Mac OS X v10.3 and later.

Declared in CarbonEventsCore.h.

Discussion

You use these attributes only if you are creating your own events.

Event Priority Constants

Define event priority constants.

typedef SInt16 EventPriority;
enum {
   kEventPriorityLow = 0,
   kEventPriorityStandard = 1,
   kEventPriorityHigh = 2
};

Constants
kEventPriorityLow

Lowest priority. Currently only window update events are posted at this priority.

Available in Mac OS X v10.0 and later.

Declared in CarbonEventsCore.h.

kEventPriorityStandard

Normal priority of events. Most events are standard priority.

Available in Mac OS X v10.0 and later.

Declared in CarbonEventsCore.h.

kEventPriorityHigh

Highest priority.

Available in Mac OS X v10.0 and later.

Declared in CarbonEventsCore.h.

Discussion

These values define the relative priority of an event, and are used when posting events with PostEventToQueue. In general events are pulled from the queue in order of first posted to last posted. These priorities are a way to alter that behavior when posting events. You can post a standard priority event and then a high priority event, and the high priority event will be pulled from the queue first.

Event Target Propagation Options

Define options for the SendEventToEventTargetWithOptions function.

enum {
   kEventTargetDontPropagate = (1 << 0),
   kEventTargetSendToAllHandlers = (1 << 1)
};

Constants
kEventTargetDontPropagate

Do not propagate this event to any other event target. That is, even if the handler returns eventNotHandledErr, the event is not propagated up the handler chain. When passed an event sent with this option, CallNextEventHandler only calls other event handlers installed on the current event target; it does not propagate the event to other event targets.

Available in Mac OS X v10.2 and later.

Declared in CarbonEventsCore.h.

kEventTargetSendToAllHandlers

Send this event to all event targets in the handler chain, regardless of any handler’s return value. For example, if sent to a control, after returning, the event is sent to the owning window and then to the application. Note that the Carbon Event Manager keeps track of the strongest result code when progressing up the handler chain. That is, if the first handler returns noErr, and the second handler returns eventNotHandledErr, the result returned is noErr.

Available in Mac OS X v10.2 and later.

Declared in CarbonEventsCore.h.

Event Queue Constants

Define constants for specifying how events should be handled on the queue.

enum {
   kEventLeaveInQueue = false,
   kEventRemoveFromQueue = true
};

Constants
kEventLeaveInQueue

Leave the event on the queue after examining.

Available in Mac OS X v10.0 and later.

Declared in CarbonEventsCore.h.

kEventRemoveFromQueue

Remove the event from the queue after examining.

Available in Mac OS X v10.0 and later.

Declared in CarbonEventsCore.h.

Discussion

When calling a function such as ReceiveNextEvent, you can specify whether to leave the event on the queue (peeking at it to determine its class, type, and so on), or to pull it before dispatching it to an event handler.

Direct Object Parameter

Define the direct object parameter.

enum {
   kEventParamDirectObject = '----'
};

Constants
kEventParamDirectObject

Type varies depending on event.

Available in Mac OS X v10.0 and later.

Declared in CarbonEventsCore.h.

Discussion

The direct object parameter is usable for a wide variety of events. It defines the “object the event acted upon or within.” For example, for window events, the direct object parameter returns a reference (that is a WindowRef) to the window in which the event occurred.

Event Target Parameter

Define constants for a special event target parameter and its type, that you can set for any created event.

enum {
   kEventParamPostTarget = 'ptrg',
   typeEventTargetRef = 'etrg'
};

Constants
kEventParamPostTarget

Specifies the target the event should be sent to. Instead of sending an event directly to a given target, you can set this parameter and post the event onto the event queue.

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

typeEventTargetRef

The parameter type for kEventParamPostTarget.

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

Object Reference Parameters and Types

Define constants for parameters that specify various objects and their types.

enum {
   kEventParamWindowRef = 'wind',
   kEventParamGrafPort = 'graf',
   kEventParamDragRef = 'drag',
   kEventParamMenuRef = 'menu',
   kEventParamEventRef = 'evnt',
   kEventParamControlRef = 'ctrl',
   kEventParamRgnHandle = 'rgnh',
   kEventParamEnabled = 'enab',
   kEventParamDimensions = 'dims',
   kEventParamBounds = 'boun',
   kEventParamAvailableBounds = 'avlb',
   kEventParamAEEventID = keyAEEventID,
   kEventParamAEEventClass = keyAEEventClass,
   kEventParamCGContextRef = 'cntx',
   kEventParamDeviceDepth = 'devd',
   kEventParamDeviceColor = 'devc',
   kEventParamMutableArray = 'marr',
   kEventParamResult = 'ansr',
   kEventParamMinimumSize = 'mnsz',
   kEventParamMaximumSize = 'mxsz',
   kEventParamAttributes = 'attr',
   kEventParamReason = 'why?',
   kEventParamTransactionID = 'trns',
   kEventParamGDevice = 'gdev',
   kEventParamIndex = 'indx',
   kEventParamUserData = 'usrd',
   kEventParamShape = 'shap',
   typeWindowRef = 'wind',
   typeGrafPtr = 'graf',
   typeGWorldPtr = 'gwld',
   typeDragRef = 'drag',
   typeMenuRef = 'menu',
   typeControlRef = 'ctrl',
   typeCollection = 'cltn',
   typeQDRgnHandle = 'rgnh',
   typeOSStatus = 'osst',
   typeCFIndex = 'cfix',
   typeCGContextRef = 'cntx',
   typeHIPoint = 'hipt',
   typeHISize = 'hisz',
   typeHIRect = 'hirc',
   typeHIShapeRef = 'shap',
   typeVoidPtr = 'void',
   typeGDHandle = 'gdev'
};

Constants
kEventParamWindowRef

A window reference. (typeWindowRef)

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamGrafPort

typeGrafPtr

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamDragRef

typeDragRef

Available in Mac OS X v10.0 and later.

Declared in CarbonEventsCore.h.

kEventParamMenuRef

typeMenuRef

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamEventRef

typeEventRef

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamControlRef

typeControlRef

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamRgnHandle

typeQDRgnHandle

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamEnabled

typeBoolean

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamDimensions

typeQDPoint

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamBounds

typeQDRectangle

Available in Mac OS X v10.3 and later.

Declared in CarbonEvents.h.

kEventParamAvailableBounds

typeQDRectangle

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamAEEventID

typeType

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamAEEventClass

typeType

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamCGContextRef

typeCGContextRef

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamDeviceDepth

typeShortInteger

Available in Mac OS X v10.1 and later.

Declared in CarbonEvents.h.

kEventParamDeviceColor

typeBoolean

Available in Mac OS X v10.1 and later.

Declared in CarbonEvents.h.

kEventParamMutableArray

typeCFMutableArrayRef

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventParamResult

Any type, depending on the event

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventParamMinimumSize

typeHISize

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventParamMaximumSize

typeHISize

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventParamAttributes

typeUInt32

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamReason

typeUInt32

Available in Mac OS X v10.3 and later.

Declared in CarbonEvents.h.

kEventParamTransactionID

typeUInt32

Available in Mac OS X v10.3 and later.

Declared in CarbonEvents.h.

kEventParamGDevice

typeGDHandle

Available in Mac OS X v10.3 and later.

Declared in CarbonEvents.h.

kEventParamIndex

typeCFIndex

Available in Mac OS X v10.3 and later.

Declared in CarbonEvents.h.

kEventParamUserData

typeVoidPtr

Available in Mac OS X v10.3 and later.

Declared in CarbonEvents.h.

kEventParamShape

typeHIShapeRef

Available in Mac OS X v10.4 and later.

Declared in CarbonEvents.h.

typeWindowRef

WindowRef

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

typeGrafPtr

CGrafPtr

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

typeGWorldPtr

GWorldPtr

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

typeDragRef

DragRef

Available in Mac OS X v10.0 and later.

Declared in CarbonEventsCore.h.

typeMenuRef

MenuRef

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

typeControlRef

ControlRef

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

typeCollection

Collection

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

typeQDRgnHandle

RgnHandle

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

typeOSStatus

OSStatus

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

typeCFIndex

CFIndex

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

typeCGContextRef

CGContextRef

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

typeHIPoint

HIPoint

Available in Mac OS X v10.1 and later.

Declared in CarbonEvents.h.

typeHISize

HISize

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

typeHIRect

HIRect

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

typeHIShapeRef

HIShapeRef

Available in Mac OS X v10.4 and later.

Declared in CarbonEvents.h.

typeVoidPtr

Void

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

typeGDHandle

GDHandle

Available in Mac OS X v10.3 and later.

Declared in CarbonEvents.h.

Discussion

You specify these parameters to obtain references to various objects such as windows, controls, graphics ports, and so on. See the various event kinds to determine the parameters available for each event. For example, Table 8 in “Mouse Events” lists the various parameters used in mouse events.

Core Foundation Object Types

Define type constants for Carbon event parameters that refer to Core Foundation objects.

enum {
   typeCFAttributedStringRef = 'cfas',
   typeCFMutableAttributedStringRef = 'cfaa',
   typeCFStringRef = 'cfst',
   typeCFMutableStringRef = 'cfms',
   typeCFArrayRef = 'cfar',
   typeCFMutableArrayRef = 'cfma',
   typeCFDictionaryRef = 'cfdc',
   typeCFMutableDictionaryRef = 'cfmd',
   typeCFNumberRef = 'cfnb',
   typeCFBooleanRef = 'cftf',
   typeCFTypeRef = 'cfty'
};

Constants
typeCFAttributedStringRef

A Core Foundation attributed string.

Available in Mac OS X v10.5 and later.

Declared in AEDataModel.h.

typeCFMutableAttributedStringRef

A Core Foundation mutable attributed string.

Available in Mac OS X v10.5 and later.

Declared in AEDataModel.h.

typeCFStringRef

A Core Foundation string.

Available in Mac OS X v10.1 and later.

Declared in AEDataModel.h.

typeCFMutableStringRef

A Core Foundation mutable string.

Available in Mac OS X v10.2 and later.

Declared in AEDataModel.h.

typeCFArrayRef

A Core Foundation array.

Available in Mac OS X v10.3 and later.

Declared in AEDataModel.h.

typeCFMutableArrayRef

A Core Foundation mutable array.

Available in Mac OS X v10.1 and later.

Declared in AEDataModel.h.

typeCFDictionaryRef

A Core Foundation dictionary.

Available in Mac OS X v10.3 and later.

Declared in AEDataModel.h.

typeCFMutableDictionaryRef

A Core Foundation mutable dictionary.

Available in Mac OS X v10.3 and later.

Declared in AEDataModel.h.

typeCFNumberRef

A Core Foundation number.

Available in Mac OS X v10.5 and later.

Declared in AEDataModel.h.

typeCFBooleanRef

A Core Foundation Boolean value.

Available in Mac OS X v10.5 and later.

Declared in AEDataModel.h.

typeCFTypeRef

A Core Foundation type.

Available in Mac OS X v10.2 and later.

Declared in AEDataModel.h.

Declared In
AEDataModel.h

Apple Event Constants

AppleEvent Constant

Define a constant related to events from kEventClassAppleEvent.

enum {
   kEventAppleEvent = 1
};

Constants
kEventAppleEvent

An AppleEvent event was received.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

Discussion

The standard application handler automatically calls the Apple Event Manager function AEProcessAppleEvent to handle Apple events.

Table 1 shows the parameter associated with AppleEvent events.

Table 1  Parameter names and types for AppleEvent kinds

Event kind

Parameter name

Parameter type

kEventAppleEvent

kEventParamAEEventID

typeType

Deprecated AppleEvent Event Constants

Define constants for older names for AppleEvent event constants.

enum {
   kEventClassEPPC = kEventClassAppleEvent,
   kEventHighLevelEvent = kEventAppleEvent
};

Constants
kEventClassEPPC

Equivalent to kEventClassAppleEvent.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventHighLevelEvent

Equivalent to kEventAppleEvent.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

Appearance Manager Event Constants

Appearance Manager Events

Define a constant related to events from kEventClassAppearance.

enum {
   kEventAppearanceScrollBarVariantChanged = 1
};

Constants
kEventAppearanceScrollBarVariantChanged

The scroll bar variant has changed.

Available in Mac OS X v10.1 and later.

Declared in CarbonEvents.h.

Appearance Manager Event Parameter

Define a constant for the parameter to Appearance Manager events.

enum {
   kEventParamNewScrollBarVariant = 'nsbv'
};

Constants
kEventParamNewScrollBarVariant

typeShortInteger

Available in Mac OS X v10.1 and later.

Declared in CarbonEvents.h.

Application Event Constants

Application Event Constants

Define constants related to events from kEventClassApplication.

enum {
   kEventAppActivated = 1,
   kEventAppDeactivated = 2,
   kEventAppQuit = 3,
   kEventAppLaunchNotification = 4,
   kEventAppLaunched = 5,
   kEventAppTerminated = 6,
   kEventAppFrontSwitched = 7,
   kEventAppFocusMenuBar = 8,
   kEventAppFocusNextDocumentWindow = 9,
   kEventAppFocusNextFloatingWindow = 10,
   kEventAppFocusToolbar = 11,
   kEventAppFocusDrawer = 12,
   kEventAppGetDockTileMenu = 20,
   kEventAppIsEventInInstantMouser = 104,
   kEventAppHidden = 107,
   kEventAppShown = 108,
   kEventAppSystemUIModeChanged = 109,
   kEventAppAvailableWindowBoundsChanged = 110,
   kEventAppActiveWindowChanged = 111
};

Constants
kEventAppActivated

The application was activated (resumed, in old parlance).

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventAppDeactivated

The application was deactivated (suspended, in old parlance).

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventAppQuit

The application is quitting.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventAppLaunchNotification

Response to asynchronous application launch.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventAppLaunched

Some other application was launched. (CarbonLib 1.3 or later)

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventAppTerminated

Some other application was terminated. (CarbonLib 1.3 or later)

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventAppFrontSwitched

The frontmost application has changed. (CarbonLib 1.3 or later)

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventAppFocusMenuBar

Request to switch the keyboard focus to the menu bar. The Carbon Event Manager handles this event by default.

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventAppFocusNextDocumentWindow

Request to shift keyboard focus to the next or previous document window (depending on the state of the Shift key). If there are no more document windows in the current process, focus should shift to the document window in the next (or previous) process.

If something other than a document window currently has keyboard focus, you should shift focus to the frontmost document window without changing the ordering of the windows.

If the document window does not have a focused area, you should set the focus to the main control within the window.

The Carbon Event Manager handles this event by default; if you handle this event, you should only check if the user focus is somewhere other than a document window, and if so, set the focus on the active document window. If the focus is already on a document window, your handler should always return eventNotHandledErr so that the default handler can rotate to the next window across all processes.

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventAppFocusNextFloatingWindow

Request to shift keyboard focus to the next or previous floating window (depending on the state of the Shift key).

If something other than a floating window currently has keyboard focus, you should shift focus to the frontmost floating window without changing the ordering of the windows.

If the floating window does not have a focused area, you should set the focus to the main control within the window.

The default behavior for this event is to send a kEventCommandProcess event containing kHICommandRotateFloatingWindowsForward or kHICommandRotateFloatingWindowsBackward.

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventAppFocusToolbar

Request to shift keyboard focus to the toolbar.

The default behavior for this event is to move the keyboard focus to the first item in the toolbar (assuming you are using the standard toolbar).

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventAppFocusDrawer

Request to shift keyboard focus to the drawer in the focused window.

The default behavior for this event is to move the focus to the first control in the drawer in the focused window if a drawer is present. If multiple drawers are present, focus is moved in clockwise order from one drawer to the next, starting with the top drawer, if any. If the modifiers parameter contains the shift key, focus is moved in reverse (counterclockwise) order.

Available in Mac OS X v10.4 and later.

Declared in CarbonEvents.h.

kEventAppGetDockTileMenu

Request to display a pop-up menu by the application’s dock tile. You should return the menu reference of the menu to display in the kEventParamMenuRef parameter. The sender of this event releases this menu after the Dock displays it, so if you supply a permanently allocated menu reference, you should call the Menu Manager function RetainMenu on it before returning from your handler.

The default behavior for this event is to return the menu (if any) supplied by the SetApplicationDockTileMenu function (described in the Dock Manager Reference). Note that for most functions, it’s easier to set a menu using SetApplicationDockTileMenu rather than installing a handler for this event.

Available in Mac OS X v10.1 and later.

Declared in CarbonEvents.h.

kEventAppIsEventInInstantMouser

The given event’s global mouse location is over an “instant mousing” area. An instant mousing area is an area where a mouse down should not generate ink but should be interpreted as a click.

Available in Mac OS X v10.3 and later.

Declared in CarbonEvents.h.

kEventAppHidden

The application was hidden.

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventAppShown

The application was shown.

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventAppSystemUIModeChanged

The system user interface mode of the frontmost application has changed.

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventAppAvailableWindowBoundsChanged

The available window positioning bounds have changed. This event is currently sent when the Dock has changed position or size and when the display configuration has changed. A separate copy of this event is sent to each affected GDevice.

Available in Mac OS X v10.3 and later.

Declared in CarbonEvents.h.

kEventAppActiveWindowChanged

The active window in the current process has changed. The Window Manager uses ActiveNonFloatingWindow to track the active window. When SelectWindow is called on a window, that window is made the new active window. At that time, the Window Manager also posts a kEventAppActiveWindowChanged event to the main event queue.

If more than one window is activated sequentially before the event loop is run, a single kEventAppActiveWindowChanged event is left in the event queue. Its PreviousActiveWindow parameter will be the window that was originally active, and its CurrentActiveWindow parameter will be the window that was finally active.

Available in Mac OS X v10.3 and later.

Declared in CarbonEvents.h.

Discussion

You can pass any of these constants when registering an event handler. You can also pass these constants to the CreateEvent function to specify the type of application event you want to create.

Table 2 shows the event parameters associated with application events.

Table 2  Parameter names and types for application event kinds

Event kind

Parameter name

Parameter type

kEventAppActivated

kEventParamWindowRef

typeWindowRef

kEventAppDeactivated

None

kEventAppQuit

None

kEventAppLaunchNotification

kEventParamProcessID

typeProcessSerialNumber

kEventParamLaunchRefCon

typeUInt32

kEventParamLaunchErr

typeOSStatus

kEventAppLaunched

kEventParamProcessID

typeProcessSerialNumber

kEventAppTerminated

kEventParamProcessID

typeProcessSerialNumber

kEventAppFrontSwitched

kEventParamProcessID

typeProcessSerialNumber

kEventAppFocusMenuBar

kEventParamKeyModifiers

typeUInt32

kEventAppFocusNextDocumentWindow

kEventParamKeyModifiers

typeUInt32

kEventAppFocusNextFloatingWindow

kEventParamKeyModifiers

typeUInt32

kEventAppFocusToolbar

kEventParamKeyModifiers

typeUInt32

kEventAppGetDockTileMenu

kEventParamMenuRef

typeMenuRef

kEventAppHidden

None

kEventAppShown

None

kEventAppSystemUIModeChanged

kEventParamSystemUIMode

typeUInt32

Application Event Parameters

Define constants for parameters to application events.

enum {
   kEventParamProcessID = 'psn ',
   kEventParamLaunchRefCon = 'lref',
   kEventParamLaunchErr = 'err ',
   kEventParamSystemUIMode = 'uimd'
};

Constants
kEventParamProcessID

typeProcessSerialNumber

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamLaunchRefCon

typeWildcard

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamLaunchErr

typeOSStatus

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamSystemUIMode

typeUInt32

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

Command Events

Command Event Constants

Define constants related to events from kEventClassCommand.

enum {
   kEventProcessCommand = 1,
   kEventCommandProcess = 1,
   kEventCommandUpdateStatus = 2
};

Constants
kEventProcessCommand

A command has been invoked and the application should handle it. This event is sent when the user chooses a menu item or when a control with a command is pressed. Some senders of this event will also include the modifier keys that were pressed by the user when the command was invoked, but this parameter is optional.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventCommandProcess

Same as kEventProcessCommand.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventCommandUpdateStatus

Sent when updates related to the command event may be required. When you receive this event, you should update the necessary user interface elements in your application to reflect the current status of the command. For example, if the command has the kHICommandFromMenu bit set, you should update the menu item state, text, and so on, to reflect the current state of your application.

Note that the standard handler for kEventMenuEnableItems automatically sends this event to your menu commands. As this can cause a performance hit if you have many menu items, you can choose to bypass these updates by installing a no-op handler for kEventMenuEnableItems that simply returns noErr.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

Discussion

You pass this constant to the CreateEvent function to indicate the type of command event you want to create. Future releases of the Carbon Event Manager will provide additional command event types.

Table 3 shows the parameters associated with command events.

Table 3  Parameter names and types for command event kinds

Event kind

Parameter name

Parameter type

kEventCommandProcess

kEventParamDirectObject

typeHICommand

kEventParamKeyModifiers (Optional)

typeUInt32

kEventParamMenuContext (Optional)

typeUInt32

kEventCommandUpdateStatus

kEventParamDirectObject

typeHICommand

kEventParamMenuContext (Optional)

typeUInt32

Standard Command ID Constants

Define command IDs for common menu commands and controls.

enum {
   kHICommandOK = 'ok  ',
   kHICommandCancel = 'not!',
   kHICommandQuit = 'quit',
   kHICommandUndo = 'undo',
   kHICommandRedo = 'redo',
   kHICommandCut = 'cut ',
   kHICommandCopy = 'copy',
   kHICommandPaste = 'past',
   kHICommandClear = 'clea',
   kHICommandSelectAll = 'sall',
   kHICommandHide = 'hide',
   kHICommandHideOthers = 'hido',
   kHICommandShowAll = 'shal',
   kHICommandPreferences = 'pref',
   kHICommandZoomWindow = 'zoom',
   kHICommandMinimizeWindow = 'mini',
   kHICommandMinimizeAll = 'mina',
   kHICommandMaximizeWindow = 'maxi',
   kHICommandMaximizeAll = 'maxa',
   kHICommandArrangeInFront = 'frnt',
   kHICommandBringAllToFront = 'bfrt',
   kHICommandWindowListSeparator = 'wldv',
   kHICommandWindowListTerminator = 'wlst',
   kHICommandSelectWindow = 'swin',
   kHICommandRotateWindowsForward = 'rotw',
   kHICommandRotateWindowsBackward = 'rotb',
   kHICommandRotateFloatingWindowsForward = 'rtfw',
   kHICommandRotateFloatingWindowsBackward = 'rtfb',
   kHICommandAbout = 'abou',
   kHICommandNew = 'new ',
   kHICommandOpen = 'open',
   kHICommandClose = 'clos',
   kHICommandSave = 'save',
   kHICommandSaveAs = 'svas',
   kHICommandRevert = 'rvrt',
   kHICommandPrint = 'prnt',
   kHICommandPageSetup = 'page',
   kHICommandAppHelp = 'ahlp',
   kHICommandShowCharacterPalette = 'chrp',
   kHICommandShowSpellingPanel = 'shsp',
   kHICommandCheckSpelling = 'cksp',
   kHICommandChangeSpelling = 'chsp',
   kHICommandCheckSpellingAsYouType = 'chsp',
   kHICommandIgnoreSpelling = 'igsp',
   kHICommandLearnWord = 'lrwd'
};

Constants
kHICommandOK

The OK button in a dialog or alert.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kHICommandCancel

The Cancel button in a dialog or alert.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kHICommandQuit

The application should quit.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kHICommandUndo

The last editing operation should be undone.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kHICommandRedo

The last editing operation should be redone.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kHICommandCut

The selected items should be cut.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kHICommandCopy

The selected items should be copied.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kHICommandPaste

The contents of the clipboard should be pasted.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kHICommandClear

The selected items should be deleted.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kHICommandSelectAll

All items in the active window should be selected.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kHICommandHide

The application should be hidden. The Menu Manager responds to this command automatically; your application does not need to handle it.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kHICommandHideOthers

Other applications should be hidden. The Menu Manager responds to this command automatically; your application does not need to handle it.

Available in Mac OS X v10.1 and later.

Declared in CarbonEvents.h.

kHICommandShowAll

All applications should become visible. The Menu Manager responds to this command automatically; your application does not need to handle it.

Available in Mac OS X v10.1 and later.

Declared in CarbonEvents.h.

kHICommandPreferences

The Preferences menu item has been selected.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kHICommandZoom

The active window should be zoomed in or out. The default application handler responds to this event automatically. Your application does not need to handle this event, but you may want to install a Carbon event handler for kEventWindowGetIdealSize to return the ideal size for your document windows.

kHICommandMinimizeWindow

The active window should be minimized. The default application handler will respond to this event automatically; your application does not need to handle it.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kHICommandMinimizeAll

All collapsable windows should be minimized. The default application handler responds to this event automatically; your application does not need to handle it.

Available in Mac OS X v10.1 and later.

Declared in CarbonEvents.h.

kHICommandMaximizeWindow

The active window should be maximized. Sent only on Mac OS 9. The default application handler will respond to this event automatically; your application does not need to handle it.

Available in Mac OS X v10.1 and later.

Declared in CarbonEvents.h.

kHICommandMaximizeAll

All collapsible windows should be maximized. This event is not sent or handled on Mac OS X.

Available in Mac OS X v10.1 and later.

Declared in CarbonEvents.h.

kHICommandArrangeInFront

All document-class windows should be arranged in a stack. The default application handler responds to this event automatically; your application does not need to handle it.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kHICommandBringAllToFront

All windows of this application should be brought in front of windows from other applications. Sent only on Mac OS X. The default application handler responds to this event automatically; your application does not need to handle it.

Available in Mac OS X v10.1 and later.

Declared in CarbonEvents.h.

kHICommandWindowListSeparator

A placeholder to mark the separator item dividing the Zoom/Minimize/Maximize/Arrange menu items in the standard Window menu from the menu items listing the visible windows. If you need to add your own menu items to the standard Window menu before the window list section, you can use GetIndMenuItemWithCommandID (described in the Menu Manager Reference in the User Experience section of the Carbon documentation) to look for the menu item with this command ID and insert your menu items before the item with this ID.

Available in Mac OS X v10.1 and later.

Declared in CarbonEvents.h.

kHICommandWindowListTerminator

Used as a placeholder to mark the end of the window list section of the standard Window menu. If you need to add your own menu items to the standard Window menu after the window list section, you can use GetIndMenuItemWithCommandID (described in the Menu Manager Reference in the User Experience section of the Carbon documentation) to look for the menu item with this command ID and insert your items after the item with this ID.

Available in Mac OS X v10.1 and later.

Declared in CarbonEvents.h.

kHICommandSelectWindow

A window in the standard Window menu has been selected and should be activated. In Mac OS X v10.3, this command is also sent by the toolbox whenever it needs to activate a window in your application. For example, it is used when a window is selected from the application’s Dock menu, and when a window that uses the standard window event handler is clicked. The default application handler responds to this event automatically; your application does not need to handle it.

Available in Mac OS X v10.1 and later.

Declared in CarbonEvents.h.

kHICommandRotateWindowsForward

The Rotate Windows hot key (cmd-~ by default) has been pressed. Non-floating windows should be rotated so that the window after the active window is activated. The default application handler responds to this event automatically; your application does not need to handle it.

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kHICommandRotateWindowsBackward

The Rotate Windows hot key (cmd-~ by default) has been pressed. Non-floating windows should be rotated so that the window before the active window is activated. The default application handler responds to this event automatically; your application does not need to handle it.

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kHICommandRotateFloatingWindowsForward

The floating window focus hot key (ctl-F6 by default) has been pressed, and floating windows should be rotated so that the window after the focused window is activated. The default application handler responds to this event automatically; your application does not need to handle it.

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kHICommandRotateFloatingWindowsBackward

The floating window focus hot key (ctl-F6 by default) has been pressed, and floating windows should be rotated so that the window before the focused window is activated. The default application handler responds to this event automatically; your application does not need to handle it.

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kHICommandAbout

The About menu item has been selected. In Mac OS X v10.3 and later, RunApplicationEventLoop installs a handler for this command ID on the application target that handles this event automatically by calling HIAboutBox. Your application can install its own handler if you want to display a customized about box.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kHICommandNew

A new document or item should be created.

Available in Mac OS X v10.1 and later.

Declared in CarbonEvents.h.

kHICommandOpen

The user wants to open an existing document.

Available in Mac OS X v10.1 and later.

Declared in CarbonEvents.h.

kHICommandClose

The active window should be closed. This command is typically be generated by a Close menu item. In Mac OS X v10.3 and later, the default application handler responds to this command by sending a kEventWindowClose event; on earlier systems, only the standard window event handler responded to this event.

Available in Mac OS X v10.1 and later.

Declared in CarbonEvents.h.

kHICommandSave

The active document should be saved.

Available in Mac OS X v10.1 and later.

Declared in CarbonEvents.h.

kHICommandSaveAs

The user wants to save the active document under a new name.

Available in Mac OS X v10.1 and later.

Declared in CarbonEvents.h.

kHICommandRevert

The contents of the active document should be reverted to the last saved version.

Available in Mac OS X v10.1 and later.

Declared in CarbonEvents.h.

kHICommandPrint

The active window should be printed.

Available in Mac OS X v10.1 and later.

Declared in CarbonEvents.h.

kHICommandPageSetup

The user wants to configure the current page margins, formatting, and print options.

Available in Mac OS X v10.1 and later.

Declared in CarbonEvents.h.

kHICommandAppHelp

The application’s help book should be displayed. The Help Manager installs a handler for this command ID on the Help menu returned by HMGetHelpMenu and responds to this event automatically. Your application does not need to handle it. In Mac OS X v10.4, the Help Manager installs a handler for this event on the application event target rather than on the Help menu.

Available in Mac OS X v10.1 and later.

Declared in CarbonEvents.h.

kHICommandShowCharacterPalette

The character palette needs to be shown. Events with this command ID are only generated in Mac OS X v10.3 and later. The toolbox will respond to this event automatically; your application does not need to handle it.

Available in Mac OS X v10.3 and later.

Declared in CarbonEvents.h.

kHICommandShowSpellingPanel

Display the spelling panel if it is not already visible. Events with this command ID are only generated in Mac OS X v10.4 and later. If spell checking has been enabled in the Multilingual Text Engine (MLTE) or an HITextView, this command is handled automatically.

Available in Mac OS X v10.4 and later.

Declared in CarbonEvents.h.

kHICommandCheckSpelling

Spell check the document now. Events with this command ID are only generated in Mac OS X v10.4 and later. If spell checking has been enabled in MLTE or an HITextView, this command is handled automatically.

Available in Mac OS X v10.4 and later.

Declared in CarbonEvents.h.

kHICommandChangeSpelling

Change the spelling. Events with this command ID are only generated in Mac OS X v10.4 and later. If spell checking has been enabled in MLTE or an HITextView, this command is handled automatically.

Available in Mac OS X v10.4 and later.

Declared in CarbonEvents.h.

kHICommandCheckSpellingAsYouType

Begin interactive spell checking. Events with this command ID are only generated in Mac OS X v10.4 and later. If spell checking has been enabled in MLTE or an HITextView, this command is handled automatically.

Available in Mac OS X v10.4 and later.

Declared in CarbonEvents.h.

kHICommandIgnoreSpelling

Ignore this word while spell checking this text view. Events with this command ID are only generated in Mac OS X v10.4 and later. If spell checking has been enabled in MLTE or an HITextView, this command is handled automatically.

Available in Mac OS X v10.4 and later.

Declared in CarbonEvents.h.

kHICommandLearnWord

Learn this spelling for all documents. Events with this command ID are generated only in Mac OS X v10.4 and later. If spell checking has been enabled in MLTE or an HITextView, this command is handled automatically.

Available in Mac OS X v10.4 and later.

Declared in CarbonEvents.h.

Discussion

You should use these values for standard menu and control commands rather than defining your own.

Command Event Source Constants

Define constants for the user interface element that produced an HICommand event.

enum {
   kHICommandFromMenu = (1L << 0),
   kHICommandFromControl = (1L << 1),
   kHICommandFromWindow = (1L << 2)
};

Constants
kHICommandFromMenu

This bit is set for commands generated from menu items in all versions of CarbonLib and Mac OS X.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kHICommandFromControl

The command event originated from a control. This bit was introduced in Mac OS X v10.2 and CarbonLib 1.6; it is never set in earlier versions of Mac OS X or CarbonLib.

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kHICommandFromWindow

The command event originated from a window. This bit was introduced in Mac OS X v10.2 and CarbonLib 1.6; it is never set in earlier versions of Mac OS X or CarbonLib.

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

Control Events

Control Event Constants

Define constants related to events from kEventClassControl.

enum {
   kEventControlInitialize = 1000,
   kEventControlDispose = 1001,
   kEventControlGetOptimalBounds = 1003,
   kEventControlDefInitialize = kEventControlInitialize,
   kEventControlDefDispose = kEventControlDispose,
   kEventControlHit = 1,
   kEventControlSimulateHit = 2,
   kEventControlHitTest = 3,
   kEventControlDraw = 4,
   kEventControlApplyBackground = 5,
   kEventControlApplyTextColor = 6,
   kEventControlSetFocusPart = 7,
   kEventControlGetFocusPart = 8,
   kEventControlActivate = 9,
   kEventControlDeactivate = 10,
   kEventControlSetCursor = 11,
   kEventControlContextualMenuClick = 12,
   kEventControlClick = 13,
   kEventControlGetNextFocusCandidate = 14,
   kEventControlGetAutoToggleValue = 15,
   kEventControlInterceptSubviewClick = 16,
   kEventControlGetClickActivation = 17,
   kEventControlDragEnter = 18,
   kEventControlDragWithin = 19,
   kEventControlDragLeave = 20,
   kEventControlDragReceive = 21,
   kEventControlTrack = 51,
   kEventControlGetScrollToHereStartPoint = 52,
   kEventControlGetIndicatorDragConstraint = 53,
   kEventControlIndicatorMoved = 54,
   kEventControlGhostingFinished = 55,
   kEventControlGetActionProcPart = 56,
   kEventControlGetPartRegion = 101,
   kEventControlGetPartBounds = 102,
   kEventControlSetData = 103,
   kEventControlGetData = 104,
   kEventControlGetSizeConstraints = 105,
   kEventControlValueFieldChanged = 151,
   kEventControlAddedSubControl = 152,
   kEventControlRemovingSubControl = 153,
   kEventControlBoundsChanged = 154,
   kEventControlTitleChanged = 158,
   kEventControlOwningWindowChanged = 159,
   kEventControlHiliteChanged = 160,
   kEventControlEnabledStateChanged = 161,
   kEventControlArbitraryMessage = 201
};

Constants
kEventControlInitialize

Sent when a control is created. Allows the control to initialize private data.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlDispose

Sent when a control is disposed. Allows the control to dispose of private data.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlGetOptimalBounds

Allows the control to report its best size and its text baseline based on its current settings. You should set the kEventParamControlOptimalBounds parameter to an appropriate rectangle. You should also set the kEventParamControlOptimalBaselineOffset parameter to be the offset from the top of your optimal bounds of a text baseline, if any. (Mac OS X only)

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlDefInitialize

Same as kEventControlInitialize. You can use this event when creating custom control definitions.

Available in Mac OS X v10.0 through Mac OS X v10.2.

Declared in CarbonEvents.h.

kEventControlDefDispose

Same as kEventControlDispose. You can use this event when creating custom control definitions.

Available in Mac OS X v10.0 through Mac OS X v10.2.

Declared in CarbonEvents.h.

kEventControlHit

Sent by the Control Manager functions TrackControl and HandleControlClick after handling a click in a control. If you do not handle this event, and the control has a command ID associated with it, then the Control Manager sends a kEventCommandProcess event to the control.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlSimulateHit

Sent when your control should simulate a click in response to some other action, such as a return key for a default button. The default behavior is to use the Control Manager function HiliteControl to highlight and unhighlight the part specified in the kEventParamControlPart parameter (simulating the hit) and then call the control’s action callback function. (Mac OS X only)

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlHitTest

Sent when someone wants to find out what part of your control is at a given point in local coordinates. You should set the kEventParamControlPart parameter to the appropriate part. (Mac OS X only)

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlDraw

Sent when your control should draw itself. The event can optionally contain parameters indicating which port to draw into and which part to constrain drawing to. (Mac OS X only)

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlApplyBackground

Sent when your control should apply its background color/pattern to the port specified so the subcontrol can properly erase. The port is optional; if it does not exist you should apply the background to the current port. Note that if you don’t handle this event, the event is propagated to the control’s parent. (Mac OS X only)

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in CarbonEvents.h.

kEventControlApplyTextColor

Sent when your control should apply a color/pattern to the specified port and context so a subcontrol can draw text which looks appropriate for your control’s background. The port is optional; if it does not exist, you should apply the text color to the current port. The context is also optional. (Mac OS X only)

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlSetFocusPart

Sent when your control is gaining, losing, or changing the focus. Set the focus to the part indicated by the kEventParamControlPart parameter. (Mac OS X only)

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlGetFocusPart

Sent when your the Control Manager wants to know what part of your control is currently focused. Set the kEventParamControlPart parameter to your currently focused part. If you don’t handle this event, the Control Manager sets the part parameter to the last part that was focused (or no part if the control lost focus). (Mac OS X only)

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlActivate

Sent when your control becomes active as a result of a call to ActivateControl. (Mac OS X only)

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlDeactivate

Sent when your control becomes inactive as a result of a call to DeactivateControl. (Mac OS X only)

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlSetCursor

Sent when your control is asked to change the cursor as a result of a call to the Control Manager function HandleControlSetCursor. (Mac OS X only)

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlContextualMenuClick

Sent when your control is asked to display a contextual menu as a result of a call to the Control Manager function HandleControlContextualMenuClick. (Mac OS X only)

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlClick

A mouse down occurred in a control. The standard window handler sets the keyboard focus to the control if it takes focus on clicks, and calls the Control Manager function HandleControlClick.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlGetNextFocusCandidate

Sent to allow a control to customize the focus order of its subcontrols. The current subcontrol with focus is stored in the kEventParamStartControl parameter. The desired focus direction is indicated by the kControlFocusNextPart or kControlFocusPrevPart constants, passed to you in the kEventParamControlPart parameter. The handler should return the next subcontrol in the kEventParamNextControl parameter. If the kEventParamStartControl parameter is NULL, return the first subcontrol in the specified focus direction. If no next subcontrol exists in the desired focus direction, return NULL or omit the kEventParamNextControl parameter.

The default behavior is to return the “most appropriate” peer control, which currently means the previous control in the ordering scheme.

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventControlGetAutoToggleValue

Sent when the system wants to auto-toggle a control. You can specify the value to use based on the current value of your control.

If the control has the kControlAutoToggles feature bit set, then the default behavior is as follows:

  • If the control does not behave like a radio button (the kControlHasRadioBehavior feature bit is not set), and its value is 1, then the kEventParamControlValue parameter is set to 0.

  • If the control’s value is anything other than 1, the kEventParamControlValue parameter is set to 0.

Otherwise, there is no default behavior.

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventControlInterceptSubviewClick

Sent when the HIViewGetViewForMouseClick function is called (typically by the Control Manager before it descends into subviews). A view can use this event to intercept mouse clicks that would normally be destined for one of its subviews. For example, the Toolbar control uses this event to intercept command-clicks so that it can handle dragging of its children. If the command key is down, the user wants to drag, so the handler returns noErr to indicate that this view (the Toolbar) should receive the click, not the child that was actually under the mouse.

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventControlGetClickActivation

Sent when a mouse click occurs in a background (inactive) control. This event is essentially the control version of kEventWindowGetClickActivation. The only differences are that the mouse location is view-relative and no window part parameter is passed to you.

This event is sent only when the standard window handler is installed. The default behavior is to activate the view and absorb the mouse click (that is, the click is not passed on to the view).

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventControlDragEnter

Sent when a drag item enters a view’s bounds. If you want to respond to the drag, your drag entered handler must return noErr If you return eventNotHandledErr then you will not receive further drag events, nor will you be able to receive the drag item.

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventControlDragWithin

Sent when a drag item has moved while in the view’s bounds (but not within any of its subviews). If the drag subsequently enters a subview, all additional drag events are directed to that subview.

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventControlDragLeave

Sent when a drag item leaves your view. You can use this event to unhighlight your view, and so on. (Available in Mac OS X v10.2 and later.)

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventControlDragReceive

Sent when a drag item is dropped within your view.

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventControlTrack

Sent to allow your control to completely replace the normal tracking that is part of a call to the Control Manager functions TrackControl or HandleControlClick. Set the kEventParamControlPart to the part hit during tracking.

This event is sent only to controls that return a non-zero control part code from kEventControlHitTest. If you are implementing a custom HIView and you need to receive this event, you must also handle kEventControlHitTest. The hit-test handler must place a valid control part code into the kEventParamControlPart parameter and return noErr.

The default behavior is to implement indicator tracking (if the mouse is down in an indicator part, such as for a scroll bar) or one-part tracking (if the mouse is down in a button or similar part). If the tracking is successful, the Control Manager passes back the part that was hit.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlGetScrollToHereStartPoint

Sent so your control can support “Scroll To Here” behavior during tracking. Set the kEventParamMouseLocation parameter to the mouse location in local coordinates which represents where a click would have needed to be to cause your indicator to be dragged to the incoming mouse location. (Mac OS X only)

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlGetIndicatorDragConstraint

Sent so your control can constrain the movement of its indicator during tracking. Set the kEventParamControlIndicatorDragConstraint parameter to the appropriate constraint. (Mac OS X only)

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlIndicatorMoved

Sent during live-tracking of the indicator so your control can update its value based on the new indicator position. During non-live tracking, this event lets you redraw the indicator ghost at the appropriate place. (Mac OS X only)

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlGhostingFinished

Sent at the end of non-live indicator tracking so your control can update its value based on the final ghost location. (Mac OS X only)

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlGetActionProcPart

Sent during tracking so your control can alter the part that is passed to its action callback based on modifier keys, etc. Set the kEventParamControlPart to the part you want to have sent. (Mac OS X only)

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlGetPartRegion

Sent when a client wants to get a particular region of your control. See the GetControlRegion function in the Control Manager. The kEventParamControlRegion contains a region for you to modify.

If the requested part is kControlStructureMetaPart, the default behavior is to pass back a region equal to the control’s bounds. Otherwise, there is no default behavior.

(Mac OS X only)

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlGetPartBounds

Sent when a client wants to get a particular rectangle of your control when it may be more efficient than asking for a region. Set the kEventParamControlPartBounds parameter to the appropriate rectangle. (Mac OS X only)

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlSetData

Sent when a client wants to change an arbitrary setting of your control. See the SetControlData function in the Control Manager. (Mac OS X only)

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlGetData

Sent when a client wants to get an arbitrary setting of your control. See the Control Manager function GetControlData. (Mac OS X only)

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlGetSizeConstraints

Sent when the HIViewGetSizeContraints function is called. You use this to let your custom view indicate its maximum and minimum size. A parent view can use this information to help it lay out subviews.

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventControlValueFieldChanged

Sent when your control’s value, minimum, maximum, or view size has changed. Useful so other entities can watch for your control’s value to change. If the window does not have compositing enabled, the default behavior is to redraw the control (but not its subcontrols). (Mac OS X only)

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlAddedSubControl

Sent when a control is embedded within your control.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlRemovingSubControl

Sent when one of your child controls will be removed from your control.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlBoundsChanged

Sent when your control’s bounding rectangle has changed. Note that the kEventParamOriginalBounds and kEventParamPreviousBounds parameters for this event contain the same value.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlTitleChanged

Sent when your control’s title changes.

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventControlOwningWindowChanged

Sent when one your control’s owning window has changed. Useful to update any dependencies that your control has on its owning window. (Mac OS X only)

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlHiliteChanged

Sent when a control’s highlight state changes.

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventControlEnabledStateChanged

Sent when a control’s enabled state changes (that is, when a control is enabled or disabled).

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventControlArbitraryMessage

Sent when someone tries to send an old-style CDEF message to your control. In most cases, you should implement Carbon event replacements for CDEF messages instead. If you do handle this event, but do not explicitly handle a particular CDEF message, you should propagate this event up the handler chain (either explicitly by calling CallNextEventHandler or implicitly by returning eventNotHandledErr), as some default behavior may be implemented for compatibility purposes. (Mac OS X only)

Available in Mac OS X v10.0 and later.

Not available to 64-bit applications.

Declared in CarbonEvents.h.

Discussion

You can specify any of these events when installing an event handler. You can also pass these constants to the CreateControlEvent function to specify the type of control event you want to create.

Note that many control events are not sent as a request for you to take action; rather they provide a way for the application to override default behavior. Because this is the case, most control events do not have a standard handler associated with them. Their default behavior occurs whether or not you have the standard window handler installed.

Table 4 shows the parameters available for control events.

Table 4  Parameter names and types for common control event kinds

Event kind

Parameter name

Parameter type

kEventControlInitialize

kEventParamDirectObject

typeControlRef

kEventParamInitCollection

typeCollection

kEventParamControlFeatures

typeUInt32

kEventControlDispose

kEventParamDirectObject

typeControlRef

kEventControlGetOptimalBounds

kEventParamDirectObject

typeControlRef

kEventParamControlOptimalBounds

typeQDRectangle

kEventParamControlOptimalBaselineOffset (Optional)

typeShortInteger

kEventControlHit

kEventParamDirectObject

typeControlRef

kEventParamControlPart

typeControlPartCode

kEventParamKeyModifiers

typeUInt32

kEventControlSimulateHit

kEventParamDirectObject

typeControlRef

kEventParamControlPart

typeControlPartCode

kEventParamKeyModifiers

typeUInt32

kEventControlHitTest

kEventParamDirectObject

typeControlRef

kEventParamMouseLocation

typeQDPoint

kEventParamControlPart

typeControlPartCode

kEventControlDraw

kEventParamDirectObject

typeControlRef

kEventParamControlPart (Optional)

typeControlPartCode

kEventParamGrafPort (Optional)

typeGrafPtr

kEventParamRgnHandle (Optional)

typeQDRgnHandle

kEventParamCGContextRef (Optional)

typeCGContextRef

kEventControlApplyBackground

kEventParamDirectObject

typeControlRef

kEventParamControlSubControl

typeControlRef

kEventParamControlDrawDepth

typeShortInteger

kEventParamGrafPort (Optional)

typeGrafPtr

kEventControlApplyTextColor

kEventParamDirectObject

typeControlRef

kEventParamControlSubControl

typeControlRef

kEventParamControlDrawDepth

typeShortInteger

kEventParamControlDrawInColor

typeBoolean

kEventParamGrafPort (Optional)

typeGrafPtr

kEventParamCGContextRef (Optional)

typeCGContextRef

kEventControlGetNextFocusCandidate

kEventParamNextControl

typeControlRef

kEventParamControlPart

typeControlPartCode

kEventControlGetAutoToggleValue

kEventParamDirectObject

typeControlRef

kEventParamControlPart

typeControlPartCode

kEventParamControlValue

typeLongInteger

kEventControlInterceptSubviewClick

kEventParamEventRef

typeEventRef

kEventControlGetClickActivation

kEventParamClickActivation

typeClickActivationResult

kEventControlDragEnter

kEventParamDirectObject

typeControlRef

kEventParamDragRef

typeDragRef

kEventControlDragWithin

kEventParamDirectObject

typeControlRef

kEventParamDragRef

typeDragRef

kEventControlDragLeave

kEventParamDirectObject

typeControlRef

kEventParamDragRef

typeDragRef

kEventControlDragReceive

kEventParamDirectObject

typeControlRef

kEventParamDragRef

typeDragRef

kEventControlSetFocusPart

kEventParamDirectObject

typeControlRef

kEventParamStartControl

typeControlRef

kEventParamControlPart

typeControlPartCode

kEventParamControlFocusEverything (Optional)

typeBoolean

kEventControlGetFocusPart

kEventParamDirectObject

typeControlRef

kEventParamControlPart

typeControlPartCode

kEventControlActivate

kEventParamDirectObject

typeControlRef

kEventControlDeactivate

kEventParamDirectObject

typeControlRef

kEventControlSetCursor

kEventParamDirectObject

typeControlRef

kEventParamMouseLocation

typeQDPoint

kEventParamKeyModifiers

typeUInt32

kEventControlContextualMenuClick

kEventParamDirectObject

typeControlRef

kEventParamMouseLocation

typeQDPoint

kEventControlTrack

kEventParamDirectObject

typeControlRef

kEventParamMouseLocation

typeQDPoint

kEventParamKeyModifiers

typeUInt32

kEventParamControlAction

typeControlActionUPP

kEventParamControlPart

typeControlPartCode

kEventControlGetScrollToHereStartPoint

kEventParamDirectObject

typeControlRef

kEventParamMouseLocation

typeQDPoint

kEventParamKeyModifiers

typeUInt32

kEventControlGetIndicatorDragConstraint

kEventParamDirectObject

typeControlRef

kEventParamMouseLocation

typeQDPoint

kEventParamKeyModifiers

typeUInt32

kEventParamControlIndicator DragConstraint

typeIndicatorDragConstraint

kEventControlIndicatorMoved

kEventParamDirectObject

typeControlRef

kEventParamControlIndicator Region

typeQDRgnHandle

kEventParamControlIsGhosting

typeBoolean

kEventControlGhostingFinished

kEventParamDirectObject

typeControlRef

kEventParamControlIndicator Offset

typeQDPoint

kEventControlGetActionProcPart

kEventParamDirectObject

typeControlRef

kEventParamKeyModifiers

typeUInt32

kEventParamControlPart

typeControlPartCode

kEventControlGetPartRegion

kEventParamDirectObject

typeControlRef

kEventParamControlPart

typeControlPartCode

kEventParamControlRegion

typeQDRgnHandle

kEventControlGetPartBounds

kEventParamDirectObject

typeControlRef

kEventParamControlPart

typeControlPartCode

kEventParamControlBounds

typeQDRectangle

kEventControlSetData

kEventParamDirectObject

typeControlRef

kEventParamControlPart

typeControlPartCode

kEventParamControlDataTag

typeEnumeration

kEventParamControlDataBuffer

typePtr

kEventParamControlDataBufferSize

typeLongInteger

kEventControlGetData

kEventParamDirectObject

typeControlRef

kEventParamControlPart

typeControlPartCode

kEventParamControlDataTag

typeEnumeration

kEventParamControlDataBuffer

typePtr

kEventParamControlDataBuffer Size

typeLongInteger

kEventControlGetSizeConstraints

kEventParamDirectObject

typeControlRef

kEventParamMinimumSize

typeHISize

kEventParamMaximumSize

typeHISize

kEventControlValueFieldChanged

kEventParamDirectObject

typeControlRef

kEventControlAddedSubControl

kEventParamDirectObject

typeControlRef

kEventParamControlSubControl

typeControlRef

kEventControlRemovingSubControl

kEventParamDirectObject

typeControlRef

kEventParamControlSubControl

typeControlRef

kEventControlBoundsChanged

kEventParamDirectObject

typeControlRef

kEventParamAttributes

typeUInt32

kEventParamOriginalBounds

typeQDRectangle

kEventParamPreviousBounds

typeQDRectangle

kEventParamCurrentBounds

typeQDRectangle

kEventControlOwningWindowChanged

kEventParamDirectObject

typeControlRef

kEventParamAttributes

typeUInt32

kEventParamControlOriginalOwningWindow

typeWindowRef

kEventParamControlCurrentOwningWindow

typeWindowRef

kEventControlHiliteStateChanged

kEventParamDirectObject

typeControlRef

kEventParamPreviousPart

typeControlPartCode

kEventParamCurrentPart

typeControlPartCode

kEventControlEnabledStateChanged

kEventParamDirectObject

typeControlRef

kEventControlArbitraryMessage

kEventParamDirectObject

typeControlRef

kEventParamControlMessage

typeShortInteger

kEventParamControlParam

typeLongInteger

kEventParamControlResult

typeLongInteger

Control Bounds Constants

Define control bounds change-event attributes.

enum {
   kControlBoundsChangeSizeChanged = (1 << 2),
   kControlBoundsChangePositionChanged = (1 << 3)
};

Constants
kControlBoundsChangeSizeChanged

The dimensions of the control (width and height) changed.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kControlBoundsChangePositionChanged

The position of the control changed (that is, the top-left corner moved).

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

Discussion

When the system sends out a kEventControlBoundsChanged event, it also sends along a parameter containing attributes of the event. These attributes can be used to determine what aspect of the control changed (position, size, or both).

Control Event Parameters

Define parameters related to control events. 

enum {
   kEventParamControlPart = 'cprt',
   kEventParamInitCollection = 'icol',
   kEventParamControlMessage = 'cmsg',
   kEventParamControlParam = 'cprm',
   kEventParamControlResult = 'crsl',
   kEventParamControlRegion = 'crgn',
   kEventParamControlAction = 'caup',
   kEventParamControlIndicatorDragConstraint = 'cidc',
   kEventParamControlIndicatorRegion = 'cirn',
   kEventParamControlIsGhosting = 'cgst',
   kEventParamControlIndicatorOffset = 'ciof',
   kEventParamControlClickActivationResult = 'ccar',
   kEventParamControlSubControl = 'csub',
   kEventParamControlOptimalBounds = 'cobn',
   kEventParamControlOptimalBaselineOffset = 'cobo',
   kEventParamControlDataTag = 'cdtg',
   kEventParamControlDataBuffer = 'cdbf',
   kEventParamControlDataBufferSize = 'cdbs',
   kEventParamControlDrawDepth = 'cddp',
   kEventParamControlDrawInColor = 'cdic',
   kEventParamControlFeatures = 'cftr',
   kEventParamControlPartBounds = 'cpbd',
   kEventParamControlOriginalOwningWindow = 'coow',
   kEventParamControlCurrentOwningWindow = 'ccow',
   kEventParamControlFocusEverything = 'cfev',
   kEventParamNextControl = 'cnxc',
   kEventParamStartControl = 'cstc',
   kEventParamControlSubview = 'csvw',
   kEventParamControlPreviousPart = 'copc',
   kEventParamControlCurrentPart = 'cnpc',
   kEventParamControlInvalRgn = 'civr',
   kEventParamControlValue = 'cval',
   kEventParamControlHit = 'chit',
   kEventParamControlPartAutoRepeats = 'caur',
   kEventParamControlFrameMetrics = 'cfmt',
   kEventParamControlWouldAcceptDrop = 'cldg',
   kEventParamControlPrefersShape = 'cpsh',
   typeControlActionUPP = 'caup',
   typeIndicatorDragConstraint = 'cidc',
   typeControlPartCode = 'cprt',
   typeControlFrameMetrics = 'cins'
};

Constants
kEventParamControlPart

typeControlPartCode

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamInitCollection

typeCollection

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamControlMessage

typeShortInteger

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamControlParam

typeLongInteger

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamControlResult

typeLongInteger

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamControlRegion

typeQDRgnHandle

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamControlAction

typeControlActionUPP

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamControlIndicatorDragConstraint

typeIndicatorDragConstraint

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamControlIndicatorRegion

typeQDRgnHandle

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamControlIsGhosting

typeBoolean

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamControlIndicatorOffset

typeQDPoint

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamControlClickActivationResult

typeClickActivationResult

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamControlSubControl

typeControlRef

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamControlOptimalBounds

typeQDRectangle

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamControlOptimalBaselineOffset

typeShortInteger

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamControlDataTag

typeEnumeration

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamControlDataBuffer

typePtr

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamControlDataBufferSize

typeLongInteger

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamControlDrawDepth

typeShortInteger

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamControlDrawInColor

typeBoolean

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamControlFeatures

typeUInt32

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamControlPartBounds

typeQDRectangle

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamControlOriginalOwningWindow

typeWindowRef

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamControlCurrentOwningWindow

typeWindowRef

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamControlFocusEverything

typeBoolean

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventParamNextControl

typeControlRef

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventParamStartControl

typeControlRef

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventParamControlSubview

typeControlRef

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventParamControlPreviousPart

typeControlPartCode

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventParamControlCurrentPart

typeControlPartCode

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventParamControlInvalRgn

typeQDRgnHandle

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventParamControlValue

typeLongInteger

Available in Mac OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventParamControlHit

typeBoolean

Available in Mac OS X v10.3 and later.

Declared in CarbonEvents.h.

kEventParamControlPartAutoRepeats

typeBoolean

Available in Mac OS X v10.3 and later.

Declared in CarbonEvents.h.

kEventParamControlFrameMetrics

typeControlFrameMetrics

Available in Mac OS X v10.3 and later.

Declared in CarbonEvents.h.

kEventParamControlWouldAcceptDrop

typeBoolean

Available in Mac OS X v10.3 and later.

Declared in CarbonEvents.h.

kEventParamControlPrefersShape

typeBoolean

Available in Mac OS X v10.4 and later.

Declared in CarbonEvents.h.

typeControlActionUPP

ControlActionUPP

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

typeIndicatorDragConstraint

IndicatorDragConstraint

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

typeControlPartCode

ControlPartCode

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

typeControlFrameMetrics

HIViewFrameMetrics

Available in Mac OS X v10.3 and later.

Declared in CarbonEvents.h.

Ink Events

Ink Event Constants

Define constants related to events from kEventClassInk.

enum {
   kEventInkPoint = 10,
   kEventInkGesture = 11,
   kEventInkText = 12
};

Constants
kEventInkPoint

A mouse event will be handled as an ink point and used for recognition. The Ink Manager has determined that the mouse event in kEventParamEventRef should be used for recognition. If the application handles the event and returns noErr, the Ink Manager does nothing further with the mouse event. If the application returns any other value (including eventNotHandledErr), the Ink Manager processes the point normally.

Available in Mac OS X v10.3 and later.

Declared in CarbonEvents.h.

kEventInkGesture

The Ink Manager recognizes the current ink phrase as one of the known system gestures. Applications can install a handler for these events to provide targeted gestures and support for context-dependent (tentative) gestures. Applications should return noErr if they handled the gesture. If the gesture was context dependent and does not apply to the current situation, applications should return eventNotHandledErr.

Available in Mac OS X v10.3 and later.

Declared in CarbonEvents.h.

kEventInkText

The Ink Manager recognizes a word. The kEventParamInkTextRef parameter contains the ink text reference with all the information about the word. For more information, see Ink.h.

Available in Mac OS X v10.3 and later.

Declared in CarbonEvents.h.

Discussion

Table 6 shows the parameters associated with ink events

Table 5  Parameter names and types for ink event kinds

Event kind

Parameter name

Parameter type

kEventInkPoint

kEventParamEventRef

typeEventRef

kEventInkGesture

kEventParamInkGesture

typeHIRect

kEventParamInkGestureBounds

typeHIRect

kEventParamInkGestureHotspot

typeHIPoint

kEventInkText

kEventParamInkTextRef

typePtr

kEventParamInkKeyboardShortcut

typeBoolean

Ink Event Parameters

Define constants for parameters to ink events.

enum {
   kEventParamInkTextRef = 'iwrd',
   kEventParamInkKeyboardShortcut = 'ikbd',
   kEventParamInkGestureKind = 'gknd',
   kEventParamInkGestureBounds = 'gbnd',
   kEventParamInkGestureHotspot = 'ghot'
};

Constants
kEventParamInkTextRef

The ink text reference containing the data for the word the Ink Manager recognized. (typePtr)

Available in Mac OS X v10.3 and later.

Declared in CarbonEvents.h.

kEventParamInkKeyboardShortcut

A Boolean whose value indicates whether the word the Ink Manager recognized is a keyboard shortcut. That is, the Command or Control key was pressed and the top-choice alternate text is a single character. (typeBoolean)

Available in Mac OS X v10.3 and later.

Declared in CarbonEvents.h.

kEventParamInkGestureKind

Kind of gesture. (typeUInt32)

Available in Mac OS X v10.3 and later.

Declared in CarbonEvents.h.

kEventParamInkGestureBounds

Bounds of the gesture in global coordinates. (typeHIRect)

Available in Mac OS X v10.3 and later.

Declared in CarbonEvents.h.

kEventParamInkGestureHotspot

Hotspot, in global coordinates, for the gesture. (typeHIPoint)

Available in Mac OS X v10.3 and later.

Declared in CarbonEvents.h.

Keyboard Events

Keyboard Event Constants

Define constants related to events from kEventClassKeyboard.

enum {
   kEventRawKeyDown = 1,
   kEventRawKeyRepeat = 2,
   kEventRawKeyUp = 3,
   kEventRawKeyModifiersChanged = 4,
   kEventHotKeyPressed = 5,
   kEventHotKeyReleased = 6
};

Constants
kEventRawKeyDown

A key was pressed.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventRawKeyRepeat

Sent periodically as a key is held down by the user.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventRawKeyUp

A key was released.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventRawKeyModifiersChanged

The keyboard modifiers have changed.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventHotKeyPressed

A registered hot key was pressed.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventHotKeyReleased

A registered hot key was released.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

Discussion

These events are the lowest-level keyboard events.

Table 6 shows the parameters associated with keyboard events.

Table 6  Parameter names and types for keyboard event kinds

Event kind

Parameter name

Parameter type

kEventRawKeyDown

kEventParamKeyMacCharCodes

typeChar

kEventParamKeyCode

typeUInt32

kEventParamKeyModifiers

typeUInt32

kEventParamKeyboardType

typeUInt32

kEventRawKeyRepeat

kEventParamKeyMacCharCodes

typeChar

kEventParamKeyCode

typeUInt32

kEventParamKeyModifiers

typeUInt32

kEventParamKeyboardType

typeUInt32

kEventRawKeyUp

kEventParamKeyMacCharCodes

typeChar

kEventParamKeyCode

typeUInt32

kEventParamKeyModifiers

typeUInt32

kEventParamKeyboardType

typeUInt32

kEventRawKeyModifiersChanged

kEventParamKeyModifiers

typeUInt32

kEventHotKeyPressed

kEventParamDirectObject

typeEventHotKeyID

kEventHotKeyReleased

kEventParamDirectObject

typeEventHotKeyID

Key Modifier Event Masks

Define values used to determine whether additional modifier keys are down for a keyboard or mouse event. 

enum {
   kEventKeyModifierNumLockMask = 1L << kEventKeyModifierNumLockBit,
   kEventKeyModifierFnMask = 1L << kEventKeyModifierFnBit
};

Constants
kEventKeyModifierNumLockMask

A bit mask containing kEventKeyModifierNumLockBit. (Mac OS X only)

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventKeyModifierFnMask

A bit mask containing kEventKeyModifierFnBit. (Mac OS X only)

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

Key Modifier Event Bits

Define key modifier change event bits.

enum {
   kEventKeyModifierNumLockBit = 16,
   kEventKeyModifierFnBit = 17
};

Constants
kEventKeyModifierNumLockBit

This keyboard event was generated either on the numeric keypad or in the numeric section of an iBook or PowerBook keyboard with the Num Lock key pressed. This state bit does not provide an indication of the Num Lock key on non-portable keyboards. This bit is set on Mac OS X only.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventKeyModifierFnBit

The Fn key was pressed when this keyboard event was generated. This bit is set on Mac OS X only.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

Discussion

Note that bits 8 through 15 (cmdKeyBit to rightControlKeyBit) are compatible with the Classic Event Manager modifiers.

Keyboard Event Parameters and Types

Define constants for parameters to raw keyboard events.

enum {
   kEventParamKeyCode = 'kcod',
   kEventParamKeyMacCharCodes = 'kchr',
   kEventParamKeyModifiers = 'kmod',
   kEventParamKeyUnicodes = 'kuni',
   kEventParamKeyboardType = 'kbdt',
   typeEventHotKeyID = 'hkid'
};

Constants
kEventParamKeyCode

typeUInt32

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamKeyMacCharCodes

typeChar

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamKeyModifiers

typeUInt32

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamKeyUnicodes

typeUnicodeText

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

typeEventHotKeyID

EventHotKeyID

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

Symbolic Hot Key Definitions

Define CFDictionaryRef keys returned by CopySymbolicHotKeys.

#define kHISymbolicHotKeyCode CFSTR("kHISymbolicHotKeyCode")
#define kHISymbolicHotKeyModifiers CFSTR("kHISymbolicHotKeyModifiers")
#define kHISymbolicHotKeyEnabled CFSTR("kHISymbolicHotKeyEnabled")

Constants
kHISymbolicHotKeyCode

The virtual key code of the hot key, represented as a CFNumber.

Available in Mac OS X v10.3 and later.

Declared in CarbonEvents.h.

kHISymbolicHotKeyModifiers

The hot key’s keyboard modifiers, represented as a CFNumber.

Available in Mac OS X v10.3 and later.

Declared in CarbonEvents.h.

kHISymbolicHotKeyEnabled

The enable state of the hot key, represented as a CFBoolean.

Available in Mac OS X v10.3 and later.

Declared in CarbonEvents.h.

Hot Key Constants

Define hot key states used by PushSymbolicHotKeyMode. 

enum {
   kHIHotKeyModeAllEnabled = 0,
   kHIHotKeyModeAllDisabled = (1 << 0),
   kHIHotKeyModeAllDisabledExceptUniversalAccess = (1 <<  1)
};

Constants
kHIHotKeyModeAllEnabled

All hot keys are enabled.

Available in Mac OS X v10.4 and later.

Declared in CarbonEvents.h.

kHIHotKeyModeAllDisabled

All hot keys are disabled.

Available in Mac OS X v10.4 and later.

Declared in CarbonEvents.h.

kHIHotKeyModeAllDisabledExceptUniversalAccess

All hot keys are disabled except for the Universal Access hot keys (that is, zooming, white-on-black, and enhanced contrast).

Available in Mac OS X v10.4 and later.

Declared in CarbonEvents.h.

Menu Events

Menu Event Constants

Define constants related to events from kEventClassMenu.

enum {
   kEventMenuBeginTracking = 1,
   kEventMenuEndTracking = 2,
   kEventMenuChangeTrackingMode = 3,
   kEventMenuOpening = 4,
   kEventMenuClosed = 5,
   kEventMenuTargetItem = 6,
   kEventMenuMatchKey = 7,
   kEventMenuEnableItems = 8,
   kEventMenuPopulate = 9,
   kEventMenuMeasureItemWidth = 100,
   kEventMenuMeasureItemHeight = 101,
   kEventMenuDrawItem = 102,
   kEventMenuDrawItemContent = 103,
   kEventMenuDispose = 1001,
   kEventMenuCalculateSize = 1004,
   kEventMenuCreateFrameView = 1005,
   kEventMenuGetFrameBounds = 1006,
   kEventMenuBecomeScrollable = 1007,
   kEventMenuCeaseToBeScrollable = 1008,
   kEventMenuBarShown = 2000,
   kEventMenuBarHidden = 2001
};

Constants
kEventMenuBeginTracking

The user has begun tracking the menubar or a pop-up menu. The direct object parameter is a valid menu reference if tracking a pop-up menu, or NULL if tracking the menubar. The kEventParamCurrentMenuTrackingMode parameter indicates whether the user is tracking the menus using the mouse or the keyboard. The handler may return userCanceledErr to stop menu tracking.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventMenuEndTracking

The user has finished tracking the menubar or a pop-up menu. In Mac OS X v10.3 and later, when a menu tracking session ends, the Menu Manager sends kEventMenuEndTracking to every menu that was opened during the session, in addition to the root menu. This is done to allow menus with dynamic content to remove that content at the end of menu tracking; for example, a menu containing many IconRefs might want to load the IconRefs dynamically in response to the kEventMenuMenuPopulate event and remove them in response to the kEventMenuEndTracking event to avoid the memory overhead of keeping the IconRef data in memory while the menu is not being displayed.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventMenuChangeTrackingMode

The user has switched from selecting a menu with the mouse to selecting with the keyboard, or from selecting with the keyboard to selecting with the mouse.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventMenuOpening

A menu is opening. This event is sent each time that the menu is opened (that is, more than once during a given tracking session if the user opens the menu multiple times). It is sent before the menu is actually drawn, so you can update the menu contents (including making changes that will alter the menu size) and the new contents will be drawn correctly. The kEventParamMenuFirstOpen parameter indicates whether this is the first time this menu has been opened during this menu tracking session. The handler may return userCanceledErr to prevent this menu from opening. Note that for most applications, you should handle the kEventMenuPopulate event instead.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventMenuClosed

A menu has been closed. Sent after the menu is hidden.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventMenuTargetItem

The mouse is moving over a particular menu item. This event is sent for both enabled and disabled items.

Available in Mac OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventMenuMatchKey

A menu is about to be examined for items that match a command key event. A handler for this event may perform its own command key matching and override the Menu Manager’s default matching algorithms. Returning noErr from your handler indicates that you have found a match. The handler for this event should not examine submenus of this menu for a match; a separate event will be sent for each submenu.

When called from IsMenuKeyEvent, the kEventParamEventRef parameter contains the event reference that was passed to IsMenuKeyEvent, for your handler to examine; when called from MenuKey or MenuEvent, the EventRef parameter contains an event created from the information passed to MenuKey or MenuEvent. Note that in the MenuKey case, no virtual key code (kEventParamKeyCode) or key modifiers (kEventParamKeyModifiers) will be available.

The kEventParamMenuEventOptions parameter contains a copy of the options that were passed to IsMenuKeyEvent, or 0 if called from MenuKey or MenuEvent. The only option that your handler will need to obey is kMenuEventIncludeDisabledItems.

If your handler finds a match, it should set the kEventParamMenuItemIndex parameter to contain the item index of the matching item, and return noErr. If it does not find a match, it should return menuItemNotFoundErr. Any other return value will cause the Menu Manager to use its default command key matching algorithm for this menu.

This event is sent after kEventMenuEnableItems.

In CarbonLib and Mac OS