Statement

Syntax

ON EVENT {FN userFunction|GOSUB{lineNumber|"stmtLabel"}}

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 <a href="event.html">EVENT</a> function for more information.

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

If there are no events in the system queue when your program executes HANDLEEVENTS, FB calls your designated routine once, passing it a "null" event in the EVENT 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 _mButDwnEvt (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 _mButDwnEvt, 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 _evtNum field in the event record to _nullEvt before returning from your routine, as illustrated here:

<code><b>LOCAL FN</b> DoEvent<br>
evtPtr& = <b>EVENT</b><br>
<b>SELECT CASE</b> evtPtr&.evtNum%<br>
'[handle the event as desired in here]<br>
<b>END SELECT</b><br>
'"Hide" the event from further handling by FB:<br>
evtPtr&.evtNum% = _nullEvt<br>
<b>END FN</b></code>

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 ">"Event Manager" chapter in " Inside Macintosh Macintosh Toolbox Essentials, for a discussion of high-level events.

Note:
If you use the ON EVENT FN userFunction syntax, then userFunction 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.