Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

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
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
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
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
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
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
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
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
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
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
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
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
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
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