FutureBasic Logo

<<    Index    >> FutureBasic 5

on event   statement

on event {fn userFunction|gosub{lineNumber|"stmtLabel"}}

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 event function for more information.
After a system event occurs, FutureBasic 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, FutureBasic 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, FutureBasic 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), FutureBasic 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 FutureBasic has a chance to interpret them and report them to your other event handling routines. (When a system event occurs, FutureBasic 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 FutureBasic from further interpreting the event by setting the _evtNum field in the event record to _nullEvt before returning from your routine, as illustrated here:
local fn DoEvent
 evtPtr& = event
 select case evtPtr&.evtNum%
  '[handle the event as desired in here]
 end select
 '"Hide" the event from further handling by FutureBasic:
 evtPtr&.evtNum% = _nullEvt
end fn

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.

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.

See Also: