Futurebasic/Language/Reference/on event

Description
This statement designates a particular function or subroutine as a system-event handling routine. A system-event handling routine is called in response to any event which the MacOS puts into the event queue designated for your program. This includes various kinds of low-level events such as mouseclicks and keypresses, as well as high-level events such as Apple Events. See the  function for more information.

After a system event occurs, FB does not call your designated routine immediately. Instead, your program continues executing until a  statement is reached. At that time,  will call your designated routine once for each system event that occurred; your designated routine should examine the   function to get information about the event.

If there are no events in the system queue when your program executes, FB calls your designated routine once, passing it a "null" event in the   record.

Even if you don't designate a system-event handling routine, FB often uses system events to determine whether other kinds of interesting events have occurred. For example, if the queue contains a system event of type  (indicating that the user has pressed the mouse button), FB checks whether the mouse was clicked inside a button, or in the menu bar, or in the "close box" of a window, etc., and may generate an event such as a dialog event or a menu event that your program can detect in other event handling routines.

By designating a system-event handling routine, your program can "intercept" events like, before FB has a chance to interpret them and report them to your other event handling routines. (When a system event occurs, FB always calls your system-event handling routine first, before any of your other designated event handling routines.) This allows your program to customize the way it responds to system events, in case FutureBasic's "standard" responses don't meet your needs. If you handle an event within your system-event handling routine, you can inhibit FB from further interpreting the event by setting the  field in the event record to  before returning from your routine, as illustrated here:

Another good reason to designate a system-event handling routine is so that your program can respond to high-level events such as Apple Events. See the Manager&quot; chapter in Inside Macintosh  Macintosh Toolbox Essentials, for a discussion of high-level events.

Note: If you use the  syntax, then   must refer to a function which was defined or prototyped at an earlier location in the source code. Your system-event handling function should not take any parameters, nor return a result.