OSStatus AddEventTypesToHandler(EventHandlerRef inHandlerRef, UInt32 inNumTypes, const EventTypeSpec * inList);
Adds additional events to an event handler that has already been
installed.
Result: An operating system result code.
Name Description inHandlerRef The event handler to add the additional events to. inNumTypes The number of events to add. inList A pointer to an array of EventTypeSpec entries.
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.
Result: An operating system result code.
Name Description inCallRef The event handler call ref passed into your event handler. inEvent The event to pass thru.
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.
Result: A boolean indicating if the conversion was successful (true) or not (false).
Name Description inEvent The EventRef to convert into an EventRecord. outEvent The EventRecord to fill out.
EventRef FindSpecificEventInQueue(EventQueueRef inQueue, EventComparatorUPP comparator, void * compareData);
Returns the first event that matches a comparator function, or NULL
if no events match.
Result: An event reference.
Name Description inQueue The event queue to search. comparator The comparison function to invoke for each event in the queue. compareData The data you wish to pass to your comparison function.
OSStatus FlushEventQueue(EventQueueRef inQueue);
Flushes all events from an event queue.
Result: An operating system result code.
Name Description inQueue The event queue to flush.
OSStatus FlushEventsMatchingListFromQueue(EventQueueRef inQueue, UInt32 inNumTypes, const EventTypeSpec * inList);
Flushes events matching a specified list of classes and kinds from an
event queue.
Result: An operating system result code.
Name Description inQueue The event queue to flush events from. inNumTypes The number of event kinds to flush. inList The list of event classes and kinds to flush from the queue.
OSStatus FlushSpecificEventsFromQueue(EventQueueRef inQueue, EventComparatorUPP inComparator, void * inCompareData);
Flushes events that match a comparator function.
Result: An operating system result code.
Name Description inQueue The event queue to flush events from. inComparator The comparison function to invoke for each event in the queue. inCompareData The data you wish to pass to your comparison function.
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.
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.
Result: An EventTargetRef.
Name Description inControl The control to return the target for.
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.
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.
EventTime GetCurrentEventTime(void);
Returns the current time since last system startup in seconds.
UInt32 GetEventClass(EventRef inEvent);
Returns the class of the given event, such as mouse, keyboard, etc.
Result: The class ID of the event.
Name Description inEvent The event in question.
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.
Result: The kind of the event.
Name Description inEvent The event in question.
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.
Result: An operating system result code.
Name Description inEvent The event to get the parameter from. inName The symbolic name of the parameter. inDesiredType The 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. outActualType The actual type of the parameter, can be NULL if you are not interested in receiving this information. inBufferSize The size of the output buffer specified by ioBuffer. outActualSize The actual size of the data, or NULL if you don't want this information. ioBuffer The pointer to the buffer which will receive the parameter data.
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.
Result: The time the event occurred.
Name Description inEvent The event in question.
EventLoopRef GetMainEventLoop(void);
Returns the event loop object for the main application thread.
EventQueueRef GetMainEventQueue(void);
Returns the event queue object for the main application thread.
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.
Result: An EventTargetRef.
Name Description inMenu The menu to return the target for.
UInt32 GetNumEventsInQueue(EventQueueRef inQueue);
Returns the number of events in an event queue.
Result: The number of items in the queue.
Name Description inQueue The event queue to query.
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.
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.
Result: An EventTargetRef.
Name Description inWindow The window to return the target for.
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.
Result: An operating system result code.
Name Description inTarget The target to register your handler with. inHandler A pointer to your handler function. inNumTypes The number of events you are registering for. inList A pointer to an array of EventTypeSpec entries representing the events you are interested in. inUserData The value passed in this parameter is passed on to your event handler proc when it is called. outRef Receives 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.
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.
Result: An operating system status code.
Name Description inEventLoop The event loop to add the timer. inFireDelay The delay before first firing this timer (can be 0). inInterval The timer interval (pass 0 for one-shot timers). inTimerProc The routine to call when the timer fires. inTimerData Data to pass to the timer proc when called. outTimer A reference to the newly installed timer.
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.
Result: A boolean indicating if the event was considered to be in the mask provided.
Name Description inEvent The EventRef to convert into an EventRecord. inMask The mask to consider.
Boolean IsEventInQueue(EventQueueRef inQueue, EventRef inEvent);
Returns true if the specified event is posted to a queue.
Result: A boolean value.
Name Description inQueue The queue to check. inEvent The event in question.
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.
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.
Result: An operating system result code.
Name Description inQueue The event queue to post the event onto. inEvent The event to post. inPriority The priority of the event.
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.
Result: An operating system result code.
Name Description inEventLoop The event loop to terminate.
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.
Result: A result indicating whether an event was received, the timeout expired, or the current event loop was quit.
Name Description inNumTypes The number of event types we are waiting for (0 if any event should cause this routine to return). inList The list of event types we are waiting for (pass NULL if any event should cause this routine to return). inTimeout The time to wait (passing kEventDurationForever is preferred). inPullEvent Pass true for this parameter to actually remove the next matching event from the queue. outEvent The 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.
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.
Result: An operating system result code.
Name Description inQueue The queue to remove the event from. inEvent The event to remove.
OSStatus RemoveEventHandler(EventHandlerRef inHandlerRef);
Removes an event handler from the target it was bound to.
Result: An operating system result code.
Name Description inHandlerRef The 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.
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.
Result: An operating system status code.
Name Description inTimer The timer to remove.
OSStatus RemoveEventTypesFromHandler(EventHandlerRef inHandlerRef, UInt32 inNumTypes, const EventTypeSpec * inList);
Removes events from an event handler that has already been installed.
Result: An operating system status code.
Name Description inHandlerRef The event handler to remove the events from. inNumTypes The number of events to remove. inList A pointer to an array of EventTypeSpec entries.
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.
Name Description inTimeout The time to wait until returning (can be kEventDurationForever).
OSStatus SendEventToEventTarget(EventRef inEvent, EventTargetRef inTarget);
Sends an event to the specified event target.
Result: An operating system result code.
Name Description inEvent The event to send. inTarget The target to send it to.
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.
Result: An operating system status code.
Name Description inTimer The timer to adjust inNextFire The interval from the current time to wait until firing the timer again.
OSStatus SetEventParameter(EventRef inEvent, EventParamName inName, EventParamType inType, UInt32 inSize, const void * inDataPtr);
Sets a piece of data for the given event.
Result: An operating system result code.
Name Description inEvent The event to set the data for. inName The symbolic name of the parameter. inType The symbolic type of the parameter. inSize The size of the parameter data. inDataPtr The pointer to the parameter data.
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.
Result: An operating system result code.
Name Description inEvent The event in question. inTime The new time.
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.
Result: An operating system result code.
Name Description inPort The 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. outPt On exit, this parameter receives the mouse location from the last mouse event that caused this function to exit. outResult On exit, this parameter receives a value representing what kind of event was received that cause the function to exit, such as kMouseTrackingMouseReleased.
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.
Result: An operating system result code.
Name Description inPort The grafport to consider for mouse coordinates. You can pass NULL for this parameter to indicate the current port. inRegion The region to consider. This should be in the coordinates of the port you passed to inPort. ioWasInRgn On 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. outResult On exit, this parameter receives a value representing what kind of event was received that cause the function to exit, such as kMouseTrackingMouseEntered.
© 2000 Apple Computer, Inc. — (Last Updated 7/7/2000)