Functions



AddEventTypesToHandler

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

Adds additional events to an event handler that has already been installed.

Parameters

NameDescription
inHandlerRefThe event handler to add the additional events to.

inNumTypesThe number of events to add.

inListA pointer to an array of EventTypeSpec entries.

Result: An operating system result code.

CallNextEventHandler

OSStatus CallNextEventHandler(EventHandlerCallRef inCallRef,
 EventRef inEvent);

Calls thru 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 thru to the default toolbox handling in order to post-process the event. You can only call this routine from within an event handler.

Parameters

NameDescription
inCallRefThe event handler call ref passed into your event handler.

inEventThe event to pass thru.

Result: An operating system result code.

ConvertEventRefToEventRecord

Boolean ConvertEventRefToEventRecord(EventRef inEvent,
 EventRecord * outEvent);

This is a convenience routine to help you if there are places in your application where you need an EventRecord and all you have is an EventRef. If the event can be converted, outEvent is filled in and the function returns true. If not, false is returned and outEvent will contain a nullEvent.

Parameters

NameDescription
inEventThe EventRef to convert into an EventRecord.

outEventThe EventRecord to fill out.

Result: A boolean indicating if the conversion was successful (true) or not (false).

FindSpecificEventInQueue

EventRef FindSpecificEventInQueue(EventQueueRef inQueue,
 EventComparatorUPP comparator,
 void * compareData);

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

Parameters

NameDescription
inQueueThe event queue to search.

comparatorThe comparison function to invoke for each event in the queue.

compareDataThe data you wish to pass to your comparison function.

Result: An event reference.

FlushEventQueue

OSStatus FlushEventQueue(EventQueueRef inQueue);

Flushes all events from an event queue.

Parameters

NameDescription
inQueueThe event queue to flush.

Result: An operating system result code.

FlushEventsMatchingListFromQueue

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

Flushes events matching a specified list of classes and kinds from an event queue.

Parameters

NameDescription
inQueueThe event queue to flush events from.

inNumTypesThe number of event kinds to flush.

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

Result: An operating system result code.

FlushSpecificEventsFromQueue

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

Flushes events that match a comparator function.

Parameters

NameDescription
inQueueThe event queue to flush events from.

inComparatorThe comparison function to invoke for each event in the queue.

inCompareDataThe data you wish to pass to your comparison function.

Result: An operating system result code.

GetApplicationEventTarget

EventTargetRef GetApplicationEventTarget(void);

Returns the EventTargetRef for the application. Once you obtain this reference, you can send events to the target and install event handler on it.

Result: An EventTargetRef.

GetControlEventTarget

EventTargetRef GetControlEventTarget(ControlRef inControl);

Returns the EventTargetRef for the specified control. Once you obtain this reference, you can send events to the target and install event handler on it.

Parameters

NameDescription
inControlThe control to return the target for.

Result: An EventTargetRef.

GetCurrentEventLoop

EventLoopRef GetCurrentEventLoop(void);

Returns the current event loop for the current thread. If the current thread is a cooperative thread, the main event loop is returned.

Result: An event loop reference.

GetCurrentEventQueue

EventQueueRef GetCurrentEventQueue(void);

Returns the current event queue for the current thread. If the current thread is a cooperative thread, the main event queue is returned.

Result: An event queue reference.

GetCurrentEventTime

EventTime GetCurrentEventTime(void);

Returns the current time since last system startup in seconds.

Result: EventTime.

GetEventClass

UInt32 GetEventClass(EventRef inEvent);

Returns the class of the given event, such as mouse, keyboard, etc.

Parameters

NameDescription
inEventThe event in question.

Result: The class ID of the event.

GetEventKind

UInt32 GetEventKind(EventRef inEvent);

Returns the kind of the given event (mousedown, etc.). Event kinds overlap between event classes, e.g. kEventMouseDown and kEventAppActivated have the same value (1). The combination of class and kind is what determines an event signature.

Parameters

NameDescription
inEventThe event in question.

Result: The kind of the event.

GetEventParameter

OSStatus GetEventParameter(EventRef inEvent,
 EventParamName inName,
 EventParamType inDesiredType,
 EventParamType * outActualType, /* can be NULL */
 UInt32 inBufferSize,
 UInt32 * outActualSize, /* can be NULL */
 const void * ioBuffer);

Gets a piece of data from the given event, if it exists.

Parameters

NameDescription
inEventThe event to get the parameter from.

inNameThe symbolic name of the parameter.

inDesiredTypeThe desired type of the parameter. At present we do not support coercion, so this parameter must be the actual type of data stored in the event, or an error will be returned.

outActualTypeThe actual type of the parameter, can be NULL if you are not interested in receiving this information.

inBufferSizeThe size of the output buffer specified by ioBuffer.

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

ioBufferThe pointer to the buffer which will receive the parameter data.

Result: An operating system result code.

GetEventTime

EventTime GetEventTime(EventRef inEvent);

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

Parameters

NameDescription
inEventThe event in question.

Result: The time the event occurred.

GetMainEventLoop

EventLoopRef GetMainEventLoop(void);

Returns the event loop object for the main application thread.

Result: An event loop reference.

GetMainEventQueue

EventQueueRef GetMainEventQueue(void);

Returns the event queue object for the main application thread.

Result: An event queue reference.

GetMenuEventTarget

EventTargetRef GetMenuEventTarget(MenuRef inMenu);

Returns the EventTargetRef for the specified menu. Once you obtain this reference, you can send events to the target and install event handler on it.

Parameters

NameDescription
inMenuThe menu to return the target for.

Result: An EventTargetRef.

GetNumEventsInQueue

UInt32 GetNumEventsInQueue(EventQueueRef inQueue);

Returns the number of events in an event queue.

Parameters

NameDescription
inQueueThe event queue to query.

Result: The number of items in the queue.

GetUserFocusEventTarget

EventTargetRef GetUserFocusEventTarget(void);

Returns the EventTargetRef for the current user focus at the time of the call. Keyboard events are always sent to this target.

NOTE: Since there is no way to determine the type of object the target is bound to at present, if you install a handler onto this target, you have no way of knowing whether you are installing on a control, window, or even the application. For this reason, you should never use this target to install an event handler. It exists only as a receiver for events.

Result: An EventTargetRef.

GetWindowEventTarget

EventTargetRef GetWindowEventTarget(WindowRef inWindow);

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

Parameters

NameDescription
inWindowThe window to return the target for.

Result: An EventTargetRef.

InstallEventHandler

OSStatus InstallEventHandler(EventTargetRef inTarget,
 EventHandlerUPP inHandler,
 UInt32 inNumTypes,
 const EventTypeSpec * inList,
 void * inUserData,
 EventHandlerRef * outRef) /* can be NULL */;

Installs an event handler on a specified target. Your handler proc will be called with the events you registered with when an event of the corresponding type and class are send to the target you are installing your handler on.

Parameters

NameDescription
inTargetThe target to register your handler with.

inHandlerA pointer to your handler function.

inNumTypesThe number of events you are registering for.

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

inUserDataThe value passed in this parameter is passed on to your event handler proc when it is called.

outRefReceives an EventHandlerRef, which you can use later to remove the handler. You can pass null if you don't want the reference - when the target is disposed, the handler will be disposed as well.

Result: An operating system result code.

InstallEventLoopTimer

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

Installs a timer onto the event loop specified. The timer can either fire once or repeatedly at a specified interval depending on the parameters passed to this function.

Parameters

NameDescription
inEventLoopThe event loop to add the timer.

inFireDelayThe delay before first firing this timer (can be 0).

inIntervalThe timer interval (pass 0 for one-shot timers).

inTimerProcThe routine to call when the timer fires.

inTimerDataData to pass to the timer proc when called.

outTimerA reference to the newly installed timer.

Result: An operating system status code.

IsEventInMask

Boolean IsEventInMask(EventRef inEvent,
 EventMask inMask);

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

Parameters

NameDescription
inEventThe EventRef to convert into an EventRecord.

inMaskThe mask to consider.

Result: A boolean indicating if the event was considered to be in the mask provided.

IsEventInQueue

Boolean IsEventInQueue(EventQueueRef inQueue,
 EventRef inEvent);

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

Parameters

NameDescription
inQueueThe queue to check.

inEventThe event in question.

Result: A boolean value.

IsUserCancelEventRef

Boolean IsUserCancelEventRef(EventRef event);

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

Result: A boolean value indicating whether the event is a user cancel event.

PostEventToQueue

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

Posts an event to the queue specified. This automatically wakes up the event loop of the thread the queue belongs to. After posting the event, you should release the event. The event queue retains it.

Parameters

NameDescription
inQueueThe event queue to post the event onto.

inEventThe event to post.

inPriorityThe priority of the event.

Result: An operating system result code.

QuitEventLoop

OSStatus QuitEventLoop(EventLoopRef inEventLoop);

Causes a specific event loop to terminate. Usage of this is similar to WakeUpProcess, in that it causes the eventloop specified to return immediately (as opposed to timing out). Typically this call is used in conjunction with RunCurrentEventLoop.

Parameters

NameDescription
inEventLoopThe event loop to terminate.

Result: An operating system result code.

ReceiveNextEvent

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

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

Parameters

NameDescription
inNumTypesThe number of event types we are waiting for (0 if any event should cause this routine to return).

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

inTimeoutThe time to wait (passing kEventDurationForever is preferred).

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

outEventThe next event that matches the list passed in. If inPullEvent is true, the event is owned by you, and you will need to release it when done.

Result: A result indicating whether an event was received, the timeout expired, or the current event loop was quit.

RemoveEventFromQueue

OSStatus RemoveEventFromQueue(EventQueueRef inQueue,
 EventRef inEvent);

Removes the given event from the queue which it was posted. When you call this function, the event ownership is transferred to you, the caller, at no charge. You must release the event when you are through with it.

Parameters

NameDescription
inQueueThe queue to remove the event from.

inEventThe event to remove.

Result: An operating system result code.

RemoveEventHandler

OSStatus RemoveEventHandler(EventHandlerRef inHandlerRef);

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

Parameters

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

Result: An operating system result code.

RemoveEventLoopTimer

OSStatus RemoveEventLoopTimer(EventLoopTimerRef inTimer);

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

Parameters

NameDescription
inTimerThe timer to remove.

Result: An operating system status code.

RemoveEventTypesFromHandler

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

Removes events from an event handler that has already been installed.

Parameters

NameDescription
inHandlerRefThe event handler to remove the events from.

inNumTypesThe number of events to remove.

inListA pointer to an array of EventTypeSpec entries.

Result: An operating system status code.

RunCurrentEventLoop

OSStatus RunCurrentEventLoop(EventTimeout inTimeout);

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

Parameters

NameDescription
inTimeoutThe time to wait until returning (can be kEventDurationForever).

SendEventToEventTarget

OSStatus SendEventToEventTarget(EventRef inEvent,
 EventTargetRef inTarget);

Sends an event to the specified event target.

Parameters

NameDescription
inEventThe event to send.

inTargetThe target to send it to.

Result: An operating system result code.

SetEventLoopTimerNextFireTime

OSStatus SetEventLoopTimerNextFireTime(EventLoopTimerRef inTimer,
 EventTimerInterval inNextFire);

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

Parameters

NameDescription
inTimerThe timer to adjust

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

Result: An operating system status code.

SetEventParameter

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

Sets a piece of data for the given event.

Parameters

NameDescription
inEventThe event to set the data for.

inNameThe symbolic name of the parameter.

inTypeThe symbolic type of the parameter.

inSizeThe size of the parameter data.

inDataPtrThe pointer to the parameter data.

Result: An operating system result code.

SetEventTime

OSStatus SetEventTime(EventRef inEvent,
 EventTime inTime);

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

Parameters

NameDescription
inEventThe event in question.

inTimeThe new time.

Result: An operating system result code.

TrackMouseLocation

OSStatus TrackMouseLocation(GrafPtr inPort, /* can be NULL */
 Point * outPt,
 MouseTrackingResult * outResult);

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

Parameters

NameDescription
inPortThe grafport to consider for mouse coordinates. You can pass NULL for this parameter to indicate the current port. The mouse location is returned in terms of local coordinates of this port.

outPtOn exit, this parameter receives the mouse location from the last mouse event that caused this function to exit.

outResultOn exit, this parameter receives a value representing what kind of event was received that cause the function to exit, such as kMouseTrackingMouseReleased.

Result: An operating system result code.

TrackMouseRegion

OSStatus TrackMouseRegion(GrafPtr inPort, /* can be NULL */
 RgnHandle inRegion,
 Boolean * ioWasInRgn,
 MouseTrackingResult * outResult);

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

Parameters

NameDescription
inPortThe grafport to consider for mouse coordinates. You can pass NULL for this parameter to indicate the current port.

inRegionThe region to consider. This should be in the coordinates of the port you passed to inPort.

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

outResultOn exit, this parameter receives a value representing what kind of event was received that cause the function to exit, such as kMouseTrackingMouseEntered.

Result: An operating system result code.

© 2000 Apple Computer, Inc. — (Last Updated 7/7/2000)