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

• InstallEventHandler
• InstallStandardEventHandler
• RemoveEventHandler
• AddEventTypesToHandler
• RemoveEventTypesFromHandler
• CallNextEventHandler
• RegisterEventHotKey
• UnregisterEventHotKey
• RegisterToolboxObjectClass Deprecated in OS X v10.4
• UnregisterToolboxObjectClass Deprecated in OS X v10.4

Creating and Manipulating Event Timers

• InstallEventLoopTimer
• InstallEventLoopIdleTimer
• RemoveEventLoopTimer
• SetEventLoopTimerNextFireTime

Creating and Manipulating Events

• GetEventClass
• GetEventKind
• GetEventParameter
• SetEventParameter
• CreateEvent
• CopyEvent
• CopyEventAs
• RetainEvent
• ReleaseEvent
• GetEventRetainCount
• ConvertEventRefToEventRecord
• IsEventInMask
• GetEventMonitorTarget

Dispatching Events

• SendEventToEventTarget
• SendEventToEventTargetWithOptions
• GetControlEventTarget
• GetWindowEventTarget
• GetMenuEventTarget
• GetApplicationEventTarget
• GetEventDispatcherTarget
• GetUserFocusEventTarget
• ProcessHICommand

Managing Secure Event Input

• EnableSecureEventInput
• DisableSecureEventInput
• IsSecureEventInputEnabled

Managing Event Queues

• GetCurrentEventQueue
• GetMainEventQueue
• PostEventToQueue
• RemoveEventFromQueue
• IsEventInQueue
• AcquireFirstMatchingEventInQueue
• FlushEventsMatchingListFromQueue
• FindSpecificEventInQueue
• FlushSpecificEventsFromQueue
• FlushEventQueue
• GetNumEventsInQueue

Managing the Event Loop

• RunApplicationEventLoop
• QuitApplicationEventLoop
• GetMainEventLoop
• GetCurrentEventLoop
• GetCFRunLoopFromEventLoop
• RunCurrentEventLoop
• QuitEventLoop
• ReceiveNextEvent

Manipulating Event Time

• GetCurrentEventTime
• GetEventTime
• SetEventTime
• GetLastUserEventTime

Implementing Modal Windows

• RunAppModalLoopForWindow
• QuitAppModalLoopForWindow
• BeginAppModalStateForWindow
• EndAppModalStateForWindow

Tracking the Mouse

• TrackMouseLocation
• TrackMouseLocationWithOptions
• TrackMouseRegion
• HIMouseTrackingGetParameters
• ChangeMouseTrackingRegion Deprecated in OS X v10.4
• ClipMouseTrackingRegion Deprecated in OS X v10.4
• ClipWindowMouseTrackingRegions Deprecated in OS X v10.4
• CreateMouseTrackingRegion Deprecated in OS X v10.4
• GetMouseTrackingRegionID Deprecated in OS X v10.4
• GetMouseTrackingRegionRefCon Deprecated in OS X v10.4
• MoveMouseTrackingRegion Deprecated in OS X v10.4
• MoveWindowMouseTrackingRegions Deprecated in OS X v10.4
• ReleaseMouseTrackingRegion Deprecated in OS X v10.4
• ReleaseWindowMouseTrackingRegions Deprecated in OS X v10.4
• RetainMouseTrackingRegion Deprecated in OS X v10.4
• SetMouseTrackingRegionEnabled Deprecated in OS X v10.4
• SetWindowMouseTrackingRegionsEnabled Deprecated in OS X v10.4

Working with Hot Keys

• CopySymbolicHotKeys
• PushSymbolicHotKeyMode
• PopSymbolicHotKeyMode
• GetSymbolicHotKeyMode

Callback-Related Functions

• NewEventComparatorUPP
• InvokeEventComparatorUPP
• DisposeEventComparatorUPP
• NewEventHandlerUPP
• DisposeEventHandlerUPP
• InvokeEventHandlerUPP
• NewEventLoopTimerUPP
• InvokeEventLoopTimerUPP
• DisposeEventLoopTimerUPP
• NewEventLoopIdleTimerUPP
• InvokeEventLoopIdleTimerUPP
• DisposeEventLoopIdleTimerUPP

Miscellaneous

• CopyServicesMenuCommandKeys
• CreateTypeStringWithOSType
• GetCurrentEventKeyModifiers
• IsMouseCoalescingEnabled
• SetMouseCoalescingEnabled
• IsUserCancelEventRef

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

AddEventTypesToHandler

Adds events to an installed handler.

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

BeginAppModalStateForWindow

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

OSStatus BeginAppModalStateForWindow (
   WindowRef inWindow
);

CallNextEventHandler

Calls the next handler in the handler chain.

OSStatus CallNextEventHandler (
   EventHandlerCallRef inCallRef,
   EventRef inEvent
);

ConvertEventRefToEventRecord

Converts an event reference into an event record.

Boolean ConvertEventRefToEventRecord (
   EventRef inEvent,
   EventRecord *outEvent
);

CopyEvent

Copies an event.

EventRef CopyEvent (
   EventRef inOther
);

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

CopyServicesMenuCommandKeys

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

OSStatus CopyServicesMenuCommandKeys (
   CFArrayRef *outCommandKeyArray
);

CopySymbolicHotKeys

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

OSStatus CopySymbolicHotKeys (
   CFArrayRef *outHotKeyArray
);

CreateEvent

Creates an event.

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

CreateTypeStringWithOSType

Converts an OSType string to a Core Foundation string.

CFStringRef CreateTypeStringWithOSType (
   OSType inType
);

DisableSecureEventInput

Disables secure event input mode.

OSStatus DisableSecureEventInput (
   void
);

DisposeEventComparatorUPP

Disposes of an event comparator UPP.

void DisposeEventComparatorUPP (
   EventComparatorUPP userUPP
);

DisposeEventHandlerUPP

Disposes of an event handler UPP.

void DisposeEventHandlerUPP (
   EventHandlerUPP userUPP
);

DisposeEventLoopIdleTimerUPP

Disposes of an event loop idle timer.

void DisposeEventLoopIdleTimerUPP (
   EventLoopIdleTimerUPP userUPP
);

DisposeEventLoopTimerUPP

Disposes of an event loop timer.

void DisposeEventLoopTimerUPP (
   EventLoopTimerUPP userUPP
);

EnableSecureEventInput

Enables secure event input mode.

OSStatus EnableSecureEventInput (
   void
);

EndAppModalStateForWindow

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

OSStatus EndAppModalStateForWindow (
   WindowRef inWindow
);

FindSpecificEventInQueue

Finds a specific event in the event queue.

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

FlushEventQueue

Removes all events from the event queue.

OSStatus FlushEventQueue (
   EventQueueRef inQueue
);

FlushEventsMatchingListFromQueue

Removes events from the event queue by kind and class.

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

FlushSpecificEventsFromQueue

Removes specified events from the event queue.

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

GetApplicationEventTarget

Obtains the event target reference for the application.

EventTargetRef GetApplicationEventTarget (
   void
);

GetCFRunLoopFromEventLoop

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

CFTypeRef GetCFRunLoopFromEventLoop (
   EventLoopRef inEventLoop
);

GetControlEventTarget

Obtains the event target reference for the specified control.

EventTargetRef GetControlEventTarget (
   ControlRef inControl
);

GetCurrentEventKeyModifiers

Obtains the queue-synchronized keyboard modifier state.

UInt32 GetCurrentEventKeyModifiers (
   void
);

GetCurrentEventLoop

Obtains a reference to the current event loop.

EventLoopRef GetCurrentEventLoop (
   void
);

GetCurrentEventQueue

Obtains the current event queue.

EventQueueRef GetCurrentEventQueue (
   void
);

GetCurrentEventTime

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

EventTime GetCurrentEventTime (
   void
);

GetEventClass

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

OSType GetEventClass (
   EventRef inEvent
);

GetEventDispatcherTarget

Obtains the event target reference for the standard toolbox dispatcher.

EventTargetRef GetEventDispatcherTarget (
   void
);

GetEventKind

Returns the event kind for the specified event.

UInt32 GetEventKind (
   EventRef inEvent
);

GetEventMonitorTarget

Obtains an event monitor target.

EventTargetRef GetEventMonitorTarget (
   void
);

GetEventParameter

Obtains a parameter from the specified event.

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

GetEventRetainCount

Returns the reference count of an event.

ItemCount GetEventRetainCount (
   EventRef inEvent
);

GetEventTime

Returns the time a specific event occurred.

EventTime GetEventTime (
   EventRef inEvent
);

GetLastUserEventTime

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

EventTime GetLastUserEventTime (
   void
);

GetMainEventLoop

Obtains a reference to the main event loop.

EventLoopRef GetMainEventLoop (
   void
);

GetMainEventQueue

Obtains the main event queue.

EventQueueRef GetMainEventQueue (
   void
);

GetMenuEventTarget

Obtains an event target reference for the specified menu.

EventTargetRef GetMenuEventTarget (
   MenuRef inMenu
);

GetNumEventsInQueue

Returns the number of events in the event queue.

ItemCount GetNumEventsInQueue (
   EventQueueRef inQueue
);

GetSymbolicHotKeyMode

Obtains the current hot key mode.

OptionBits GetSymbolicHotKeyMode (
   void
);

GetUserFocusEventTarget

Obtains the event target reference for the user focus.

EventTargetRef GetUserFocusEventTarget (
   void
);

GetWindowEventTarget

Obtains the event target reference for a specified window.

EventTargetRef GetWindowEventTarget (
   WindowRef inWindow
);

HIMouseTrackingGetParameters

Obtains information about how mouse tracking loops should behave.

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

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

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

InstallEventLoopTimer

Installs a timer.

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

InstallStandardEventHandler

Installs the standard event handler for the specified target.

OSStatus InstallStandardEventHandler (
   EventTargetRef inTarget
);

InvokeEventComparatorUPP

Calls an event comparator function through a UPP.

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

InvokeEventHandlerUPP

Calls an event handler through a UPP.

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

InvokeEventLoopIdleTimerUPP

Calls an event loop idle timer through a UPP.

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

InvokeEventLoopTimerUPP

Calls an event loop timer through a UPP.

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

IsEventInMask

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

Boolean IsEventInMask (
   EventRef inEvent,
   EventMask inMask
);

IsEventInQueue

Determines whether an event is in a particular queue.

Boolean IsEventInQueue (
   EventQueueRef inQueue,
   EventRef inEvent
);

IsMouseCoalescingEnabled

Indicates whether mouse coalescing is enabled.

Boolean IsMouseCoalescingEnabled (
   void
);

IsSecureEventInputEnabled

Determines whether secure event input mode is enabled.

Boolean IsSecureEventInputEnabled (
   void
);

IsUserCancelEventRef

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

Boolean IsUserCancelEventRef (
   EventRef event
);

NewEventComparatorUPP

Creates an event comparator UPP.

EventComparatorUPP NewEventComparatorUPP (
   EventComparatorProcPtr userRoutine
);

NewEventHandlerUPP

Creates an event handler UPP.

EventHandlerUPP NewEventHandlerUPP (
   EventHandlerProcPtr userRoutine
);

NewEventLoopIdleTimerUPP

Creates an event loop idle timer UPP.

EventLoopIdleTimerUPP NewEventLoopIdleTimerUPP (
   EventLoopIdleTimerProcPtr userRoutine
);

NewEventLoopTimerUPP

Creates an event loop timer UPP.

EventLoopTimerUPP NewEventLoopTimerUPP (
   EventLoopTimerProcPtr userRoutine
);

PopSymbolicHotKeyMode

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

void PopSymbolicHotKeyMode (
   void *inToken
);

PostEventToQueue

Adds an event to the specified event queue.

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

ProcessHICommand

Sends a command to the command chain.

OSStatus ProcessHICommand (
   const HICommand *inCommand
);

PushSymbolicHotKeyMode

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

void * PushSymbolicHotKeyMode (
   OptionBits inOptions
);

QuitApplicationEventLoop

Terminates the application event loop.

void QuitApplicationEventLoop (
   void
);

QuitAppModalLoopForWindow

Quits the application-modal state for a window.

OSStatus QuitAppModalLoopForWindow (
   WindowRef inWindow
);

QuitEventLoop

Causes a specific event loop to terminate.

OSStatus QuitEventLoop (
   EventLoopRef inEventLoop
);

ReceiveNextEvent

Waits for the next event of a specified type.

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

RegisterEventHotKey

Registers a global hot key.

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

ReleaseEvent

Releases, and possibly disposes of, the specified event.

void ReleaseEvent (
   EventRef inEvent
);

RemoveEventFromQueue

Removes an event from the event queue.

OSStatus RemoveEventFromQueue (
   EventQueueRef inQueue,
   EventRef inEvent
);

RemoveEventHandler

Removes the specified event handler.

OSStatus RemoveEventHandler (
   EventHandlerRef inHandlerRef
);

RemoveEventLoopTimer

Removes the specified timer.

OSStatus RemoveEventLoopTimer (
   EventLoopTimerRef inTimer
);

RemoveEventTypesFromHandler

Removes events from an installed event handler.

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

RetainEvent

Increments the reference count of an event.

EventRef RetainEvent (
   EventRef inEvent
);

RunApplicationEventLoop

Runs the application event loop.

void RunApplicationEventLoop (
   void
);

RunAppModalLoopForWindow

Puts the window in an application-modal state.

OSStatus RunAppModalLoopForWindow (
   WindowRef inWindow
);

RunCurrentEventLoop

Executes the event loop in the current thread.

OSStatus RunCurrentEventLoop (
   EventTimeout inTimeout
);

SendEventToEventTarget

Sends an event to the specified event target.

OSStatus SendEventToEventTarget (
   EventRef inEvent,
   EventTargetRef inTarget
);

SendEventToEventTargetWithOptions

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

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

SetEventLoopTimerNextFireTime

Sets the next time that the specified timer will fire.

OSStatus SetEventLoopTimerNextFireTime (
   EventLoopTimerRef inTimer,
   EventTimerInterval inNextFire
);

SetEventParameter

Sets a parameter associated with a particular event.

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

SetEventTime

Sets the event time for a given event.

OSStatus SetEventTime (
   EventRef inEvent,
   EventTime inTime
);

SetMouseCoalescingEnabled

Turns mouse coalescing on or off.

OSStatus SetMouseCoalescingEnabled (
   Boolean inNewState,
   Boolean *outOldState
);

TrackMouseLocation

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

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

TrackMouseLocationWithOptions

Tracks the mouse with additional options.

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

TrackMouseRegion

Tracks the mouse within a region.

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

UnregisterEventHotKey

Unregisters a global hot key.

OSStatus UnregisterEventHotKey (
   EventHotKeyRef inHotKey
);

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

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

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

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

Data Types

EventClassID

Represents an event class ID.

typedef UInt32 EventClassID;

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;

EventHandlerUPP

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

typedef EventHandlerProcPtr EventHandlerUPP;

EventLoopTimerUPP

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

typedef EventLoopTimerProcPtr EventLoopTimerUPP;

EventLoopIdleTimerUPP

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

typedef EventLoopIdleTimerProcPtr EventLoopIdleTimerUPP;

EventHandlerRef

Represents an installed event handler.

typedef struct OpaqueEventHandlerRef * EventHandlerRef;

EventHotKeyID

Represents the ID of a global hot key.

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

EventHotKeyRef

Represents a registered global hot key.

typedef struct OpaqueEventHotKeyRef * EventHotKeyRef;

EventLoopIdleTimerMessage

Represents an idle timer message.

typedef UInt16 EventLoopIdleTimerMessage;

EventLoopRef

Represents an event loop.

typedef struct OpaqueEventLoopRef * EventLoopRef;

EventLoopTimerRef

Represents an installed event timer.

typedef struct __EventLoopTimer * EventLoopTimerRef;

EventParamName

Represents an event parameter constant.

typedef OSType EventParamName;

EventParamType

Represents an event parameter type constant.

typedef OSType EventParamType;

EventQueueRef

Represents an event queue.

typedef struct OpaqueEventQueueRef * EventQueueRef;

EventRef

Represents an opaque data structure that identifies individual events.

typedef struct OpaqueEventRef * EventRef;

EventTargetRef

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

typedef struct OpaqueEventTargetRef * EventTargetRef;

EventTime

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

typedef double EventTime;

EventTimeout

Represents a timeout interval, in seconds.

typedef EventTime EventTimeout;

EventTimerInterval

Specifies the period of an event timer, in seconds.

typedef EventTime EventTimerInterval;

EventType

Represents an event type.

typedef UInt32 EventType;

EventTypeSpec

Describes the class and kind of an event.

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

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.

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.

MouseTrackingRef

Represents a mouse tracking region

typedef struct OpaqueMouseTrackingRef * MouseTrackingRef;

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.

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.

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.

ToolboxObjectClassRef

Represents a toolbox object class.

typedef struct OpaqueToolboxObjectClassRef * ToolboxObjectClassRef;

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 OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventClassKeyboard

Events related to the keyboard.

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventClassTextInput

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

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventClassApplication

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

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventClassAppleEvent

Apple Events.

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventClassMenu

Menu-related events.

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventClassWindow

Window-related events.

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventClassControl

Control-related events.

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventClassCommand

Command events (HICommands).

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventClassTablet

Events related to tablet input.

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventClassVolume

Events related to File Manager volumes.

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventClassAppearance

Events related to the Appearance Manager.

Available in OS X v10.1 and later.

Declared in CarbonEvents.h.

kEventClassService

Events related to the Services Manager.

Available in OS X v10.1 and later.

Declared in CarbonEvents.h.

kEventClassToolbar

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

Available in OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventClassToolbarItem

Events related to toolbar items.

Available in OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventClassToolbarItemView

Events related to toolbar item views.

Available in OS X v10.3 and later.

Declared in CarbonEvents.h.

kEventClassAccessibility

Events related to application accessibility features.

Available in OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventClassSystem

Events related to the system.

Available in OS X v10.3 and later.

Declared in CarbonEvents.h.

kEventClassInk

Events related to ink.

Available in OS X v10.3 and later.

Declared in CarbonEvents.h.

kEventClassTSMDocumentAccess

Events related to Text Services Manager document access.

Available in OS X v10.3 and later.

Declared in CarbonEvents.h.

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 OS X v10.0 and later.

Declared in CarbonEventsCore.h.

kEventAttributeUserEvent

An event generated in response to a user action.

Available in 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 OS X v10.3 and later.

Declared in CarbonEventsCore.h.

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 OS X v10.0 and later.

Declared in CarbonEventsCore.h.

kEventPriorityStandard

Normal priority of events. Most events are standard priority.

Available in OS X v10.0 and later.

Declared in CarbonEventsCore.h.

kEventPriorityHigh

Highest priority.

Available in OS X v10.0 and later.

Declared in CarbonEventsCore.h.

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 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 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 OS X v10.0 and later.

Declared in CarbonEventsCore.h.

kEventRemoveFromQueue

Remove the event from the queue after examining.

Available in OS X v10.0 and later.

Declared in CarbonEventsCore.h.

Direct Object Parameter

Define the direct object parameter.

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

Constants

kEventParamDirectObject

Type varies depending on event.

Available in OS X v10.0 and later.

Declared in CarbonEventsCore.h.

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 OS X v10.2 and later.

Declared in CarbonEvents.h.

typeEventTargetRef

The parameter type for kEventParamPostTarget.

Available in 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 OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamGrafPort

typeGrafPtr

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamDragRef

typeDragRef

Available in OS X v10.0 and later.

Declared in CarbonEventsCore.h.

kEventParamMenuRef

typeMenuRef

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamEventRef

typeEventRef

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamControlRef

typeControlRef

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamRgnHandle

typeQDRgnHandle

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamEnabled

typeBoolean

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamDimensions

typeQDPoint

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamBounds

typeQDRectangle

Available in OS X v10.3 and later.

Declared in CarbonEvents.h.

kEventParamAvailableBounds

typeQDRectangle

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamAEEventID

typeType

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamAEEventClass

typeType

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamCGContextRef

typeCGContextRef

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamDeviceDepth

typeShortInteger

Available in OS X v10.1 and later.

Declared in CarbonEvents.h.

kEventParamDeviceColor

typeBoolean

Available in OS X v10.1 and later.

Declared in CarbonEvents.h.

kEventParamMutableArray

typeCFMutableArrayRef

Available in OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventParamResult

Any type, depending on the event

Available in OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventParamMinimumSize

typeHISize

Available in OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventParamMaximumSize

typeHISize

Available in OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventParamAttributes

typeUInt32

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamReason

typeUInt32

Available in OS X v10.3 and later.

Declared in CarbonEvents.h.

kEventParamTransactionID

typeUInt32

Available in OS X v10.3 and later.

Declared in CarbonEvents.h.

kEventParamGDevice

typeGDHandle

Available in OS X v10.3 and later.

Declared in CarbonEvents.h.

kEventParamIndex

typeCFIndex

Available in OS X v10.3 and later.

Declared in CarbonEvents.h.

kEventParamUserData

typeVoidPtr

Available in OS X v10.3 and later.

Declared in CarbonEvents.h.

kEventParamShape

typeHIShapeRef

Available in OS X v10.4 and later.

Declared in CarbonEvents.h.

typeWindowRef

WindowRef

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

typeGrafPtr

CGrafPtr

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

typeGWorldPtr

GWorldPtr

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

typeDragRef

DragRef

Available in OS X v10.0 and later.

Declared in CarbonEventsCore.h.

typeMenuRef

MenuRef

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

typeControlRef

ControlRef

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

typeCollection

Collection

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

typeQDRgnHandle

RgnHandle

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

typeOSStatus

OSStatus

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

typeCFIndex

CFIndex

Available in OS X v10.2 and later.

Declared in CarbonEvents.h.

typeCGContextRef

CGContextRef

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

typeHIPoint

HIPoint

Available in OS X v10.1 and later.

Declared in CarbonEvents.h.

typeHISize

HISize

Available in OS X v10.2 and later.

Declared in CarbonEvents.h.

typeHIRect

HIRect

Available in OS X v10.2 and later.

Declared in CarbonEvents.h.

typeHIShapeRef

HIShapeRef

Available in OS X v10.4 and later.

Declared in CarbonEvents.h.

typeVoidPtr

Void

Available in OS X v10.2 and later.

Declared in CarbonEvents.h.

typeGDHandle

GDHandle

Available in OS X v10.3 and later.

Declared in CarbonEvents.h.

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 OS X v10.5 and later.

Declared in AEDataModel.h.

typeCFMutableAttributedStringRef

A Core Foundation mutable attributed string.

Available in OS X v10.5 and later.

Declared in AEDataModel.h.

typeCFStringRef

A Core Foundation string.

Available in OS X v10.1 and later.

Declared in AEDataModel.h.

typeCFMutableStringRef

A Core Foundation mutable string.

Available in OS X v10.2 and later.

Declared in AEDataModel.h.

typeCFArrayRef

A Core Foundation array.

Available in OS X v10.3 and later.

Declared in AEDataModel.h.

typeCFMutableArrayRef

A Core Foundation mutable array.

Available in OS X v10.1 and later.

Declared in AEDataModel.h.

typeCFDictionaryRef

A Core Foundation dictionary.

Available in OS X v10.3 and later.

Declared in AEDataModel.h.

typeCFMutableDictionaryRef

A Core Foundation mutable dictionary.

Available in OS X v10.3 and later.

Declared in AEDataModel.h.

typeCFNumberRef

A Core Foundation number.

Available in OS X v10.5 and later.

Declared in AEDataModel.h.

typeCFBooleanRef

A Core Foundation Boolean value.

Available in OS X v10.5 and later.

Declared in AEDataModel.h.

typeCFTypeRef

A Core Foundation type.

Available in OS X v10.2 and later.

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 OS X v10.0 and later.

Declared in CarbonEvents.h.

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 OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventHighLevelEvent

Equivalent to kEventAppleEvent.

Available in 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 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 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 OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventAppDeactivated

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

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventAppQuit

The application is quitting.

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventAppLaunchNotification

Response to asynchronous application launch.

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventAppLaunched

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

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventAppTerminated

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

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventAppFrontSwitched

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

Available in 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 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 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 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 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 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 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 OS X v10.3 and later.

Declared in CarbonEvents.h.

kEventAppHidden

The application was hidden.

Available in OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventAppShown

The application was shown.

Available in OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventAppSystemUIModeChanged

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

Available in 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 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 OS X v10.3 and later.

Declared in CarbonEvents.h.

Application Event Parameters

Define constants for parameters to application events.

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

Constants

kEventParamProcessID

typeProcessSerialNumber

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamLaunchRefCon

typeWildcard

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamLaunchErr

typeOSStatus

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventParamSystemUIMode

typeUInt32

Available in 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 OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventCommandProcess

Same as kEventProcessCommand.

Available in 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 OS X v10.0 and later.

Declared in CarbonEvents.h.

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 OS X v10.0 and later.

Declared in CarbonEvents.h.

kHICommandCancel

The Cancel button in a dialog or alert.

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kHICommandQuit

The application should quit.

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kHICommandUndo

The last editing operation should be undone.

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kHICommandRedo

The last editing operation should be redone.

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kHICommandCut

The selected items should be cut.

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kHICommandCopy

The selected items should be copied.

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kHICommandPaste

The contents of the clipboard should be pasted.

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kHICommandClear

The selected items should be deleted.

Available in OS X v10.0 and later.

Declared in CarbonEvents.h.

kHICommandSelectAll

All items in the active window should be selected.

Available in 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 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 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 OS X v10.1 and later.

Declared in CarbonEvents.h.

kHICommandPreferences

The Preferences menu item has been selected.

Available in 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 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 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 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 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 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 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 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 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 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 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 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 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 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 OS X v10.0 and later.

Declared in CarbonEvents.h.

kHICommandNew

A new document or item should be created.

Available in OS X v10.1 and later.

Declared in CarbonEvents.h.

kHICommandOpen

The user wants to open an existing document.

Available in 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 OS X v10.1 and later.

Declared in CarbonEvents.h.

kHICommandSave

The active document should be saved.

Available in 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 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 OS X v10.1 and later.

Declared in CarbonEvents.h.

kHICommandPrint

The active window should be printed.

Available in 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 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 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 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 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 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 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 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 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 OS X v10.4 and later.

Declared in CarbonEvents.h.

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 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 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 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 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 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 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 OS X v10.0 through OS X v10.2.

Declared in CarbonEvents.h.

kEventControlDefDispose

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

Available in OS X v10.0 through 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 OS X v10.2 and later.

Declared in CarbonEvents.h.

kEventControlDragReceive

Sent when a drag item is dropped within your view.

Available in 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 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 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 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 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 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 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 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 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 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 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 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 OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlAddedSubControl

Sent when a control is embedded within your control.

Available in 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 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 OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlTitleChanged

Sent when your control’s title changes.

Available in 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 OS X v10.0 and later.

Declared in CarbonEvents.h.

kEventControlHiliteChanged

Sent when a control’s highlight state changes.

Available in 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 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 OS X v10.0 and later.

Not available to 64-bit applications.

Declared in CarbonEvents.h.