Important: The information in this document is obsolete and should not be used for new development.
Writing an Idle Function
This section describes how to write an idle function for use with theAESend
orAEInteractWithUser
function.When your application sends an Apple event, you can set one of three flags in the
sendMode
parameter toAESend
that specify how you want to deal with the reply:kAENoReply
if you don't want your application to receive a reply,kAEQueueReply
if you want it to receive the reply in its event queue, orkAEWaitReply
if you want the reply returned in thereply
parameter ofAESend
and you are willing to give up the processor while your application is waiting for the reply.If you specify
kAENoReply
orkAEQueueReply
, theAESend
function returns immediately after using the Event Manager to send the event. If you specifykAEWaitReply
, theAESend
function does not return until either the server application finishes handling the Apple event or a specified amount of time expires. In this case theAESend
function callsWaitNextEvent
on behalf of your application. This yields the processor to other processes, so that the server has an opportunity to receive and process the Apple event sent by your application. While your application is waiting for a reply, it cannot receive events unless it provides an idle function.If you provide a pointer to an idle function as a parameter to the
AESend
function,AESend
calls your idle function whenever an update event, null event, operating-system event, or activate event is received for your application. To allow your application to process high-level events that it receives while waiting for a reply, provide a reply filter function. See the next section, "Writing a Reply Filter Function," for more information.Your application can yield the processor in a similar manner when it calls the
AEInteractWithUser
function. IfAEInteractWithUser
needs to post a notification request to bring your application to the front, your application yields the processor until the user brings your application to the front. To receive events while waiting for the user to bring your application to the front, you must provide an idle function.If you provide a pointer to an idle function as a parameter to the
AEInteractWithUser
function,AEInteractWithUser
calls your idle function whenever an update event, null event, operating-system event, or activate event is received for your application.An idle function must use this syntax:
FUNCTION MyIdleFunction (VAR event: EventRecord; VAR sleepTime: LongInt; VAR mouseRgn: RgnHandle): Boolean;Theevent
parameter is the event record of the event to process. ThesleepTime
parameter andmouseRgn
parameter are values that your idle function sets the first time it is called; thereafter they contain the values your function set. Your idle function should return a Boolean value that indicates whether your application wishes to continue waiting. Set the function result toTRUE
if your application is no longer willing to wait for a reply from the server or for the user to bring the application to the front. Set the function result toFALSE
if your application is still willing to wait.You use the
sleepTime
andmouseRgn
parameters in the same way as thesleep
andmouseRgn
parameters of theWaitNextEvent
function. Specify in thesleepTime
parameter the amount of time (in ticks) during which your application agrees to relinquish the processor if no events are pending for it.In the
mouseRgn
parameter, you specify a screen region that determines the conditions under which your application is to receive notice of mouse-moved events. Your idle function receives mouse-moved events only if your application is the front application and the cursor strays outside the region you specify.Your idle function receives only update events, null events, operating-system events, and activate events. When your idle function receives a null event, it can use the idle time to update a status dialog box, animate cursors, or perform similar tasks. If your idle function receives any of the other events, it should handle the event as it normally would if received in its event loop.
Listing 5-5 shows an example of an idle function for use with
AESend
orAEInteractWithUser
. The idle function processes update events, null events, operating-system events, and activate events. The first time the function is called it receives a null event. At this time, it sets thesleepTime
andmouseRgn
parameters. The function continues to process events until the server finishes handling the Apple event or the user brings the application to the front.Your application should implement a method of checking whether the user wants to cancel. The
MyCancelInQueue
function in Listing 5-5 checks the event queue for any instances of Command-period and immediately returnsTRUE
as its function result if it finds a request to cancel in the event queue.
FUNCTION MyIdleFunction (VAR event: EventRecord; VAR sleeptime: LongInt; VAR mouseRgn: RgnHandle): Boolean; BEGIN MyIdleFunction := FALSE; {the MyCancelInQueue function checks for Command-period} IF MyCancelInQueue THEN BEGIN MyIdleFunction := TRUE; Exit(MyIdleFunction); END; CASE event.what OF updateEvt, activateEvt, {every idle function should handle } osEvt: { these kinds of events} BEGIN MyAdjustCursor(event.where, gCursorRgn); DoEvent(event); END; nullEvent: BEGIN {set the sleepTime and mouseRgn parameters} mouseRgn := gCursorRgn; sleeptime := 10; {use the correct value for your } { app} DoIdle; {the application's idle handling} END; END; {of CASE} END;