Peter wrote:
> Observation:
> What is HANDLEEVENTS? Is it a queue or is it an interrupt?
> The manual is not clear.
> 
> After looking into Inside Mac I am assured that getNextEvent is a queue.
> It appears that HANDLEEVENTS has some some similarity to getNextEvent.
> 
> I _assumed_ that HANDLEEVENTS was an _interrupt_ that was handled by say an
> ON MOUSE ... routine. Hence I _assumed_ that I could set a global variable
> and have a FN react accordingly.

Every tick (approx. 1/60th second), the Mac does an interrupt, at which
time it checks to see whether anything's going on which could be
considered an "event" and, if so, stores it into a queue.  These are
pretty low-level events: mouse-down, mouse-up, key-down, key-up, etc. 
Besides these events, which are queued automatically, an app can also
store a "high-level" event on the queue programmatically (such as an
Apple Event).  The once-per-tick interrupt and event queue update is
strictly a Mac OS thing; it's done independently of FB.

HANDLEEVENTS _reads_ the event queue.  It doesn't do any interrupting. 
You can think of HANDLEEVENTS as a special LOCAL FN, which in turn (may)
call other LOCAL FN's such as your FN doDialog or FN doMenu.  As far as
I can tell, each time you call HANDLEEVENTS, _something_ like the
following occurs.

DO
  Read one event from queue (call GetNextEvent);
  [note GetNextEvent returns a "null event" if queue is empty]

  If ON EVENT FN doEvent is defined, then
    Call FN doEvent;
    [Note: you can "nullify" a non-null event by setting the
     event type to zero within FN doEvent, if you don't want
     the event to be seen by other event handlers.]
  End if

  If event is non-null, then
    If it's a click on an (FB) window's title bar, then
      Make the window active
      Handle window dragging until mouse up
    Else if it's a click on the menu bar, then
      Track menu item selection until mouse up
    Else if it's a click on an (FB) window's "size box," then
      Handle window resizing until mouse up
    Else if (a few other possibilities), then
      (do a few other special things)
    End if

    If event is a Cmd-period keypress, then
      If ON BREAK FN doBreak is defined, then
        call FN doBreak
      Else
        do "end program" processing, then stop
      End if
    Else if event is keypress and an edit field is active, then
      If ON EDIT FN doEdit is defined, then
        fill the TEKEY$ register;
        call FN doEdit
      Else
        do "default" TextEdit processing with the keystroke;
      End if
    Else if event falls into the DIALOG category, then
      push an "FB event" into the DIALOG() queues;
      If ON DIALOG FN doDialog is defined, then call FN doDialog;
    Else if event falls into the MENU category, then
      push an "FB event" into the MENU() queues;
      If ON MENU FN doMenu is defined, then call FN doMenu;
    Else if event falls into the (etc., etc.) category, then
      (etc., etc.)
      :
    End if

  Else if user has previously pushed a "_userEvent" onto the
          DIALOG() queues (via the "DIALOG=" statement), then
    If ON DIALOG FN doDialog is defined, then call FN doDialog;
  End if
UNTIL event queue is empty

Note that HANDLEEVENTS calls "GetNextEvent" (or is it "WaitNextEvent"?)
which, in addition to getting an event from the queue, also handles
"context switching," which allows other app's to execute for a while,
and/or allows the user to switch your app to the background.  Therefore,
in support of good multitasking, it's a real good idea to call
HANDLEEVENTS periodically even while you're not expecting any incoming
events for your program.

- Rick