Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 5 - Creating and Sending Apple Events / Sending an Apple Event

Writing an Idle Function

This section describes how to write an idle function for use with the AESend or AEInteractWithUser function.

When your application sends an Apple event, you can set one of three flags in the sendMode parameter to AESend 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, or kAEWaitReply if you want the reply returned in the reply parameter of AESend and you are willing to give up the processor while your application is waiting for the reply.

If you specify kAENoReply or kAEQueueReply, the AESend function returns immediately after using the Event Manager to send the event. If you specify kAEWaitReply, the AESend function does not return until either the server application finishes handling the Apple event or a specified amount of time expires. In this case the AESend function calls WaitNextEvent 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. If AEInteractWithUser 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;

The event parameter is the event record of the event to process. The sleepTime parameter and mouseRgn 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 to TRUE 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 to FALSE if your application is still willing to wait.

You use the sleepTime and mouseRgn parameters in the same way as the sleep and mouseRgn parameters of the WaitNextEvent function. Specify in the sleepTime 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 or AEInteractWithUser. 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 the sleepTime and mouseRgn 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 returns TRUE as its function result if it finds a request to cancel in the event queue.

Listing 5-5 An idle function

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;