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 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.
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.
See Also:
event