HandleEvents performs a number of important functions that affect the user's experience. It examines the system event queue, as well as FutureBasic's internal event queues, to see whether any recent events have occurred for your program, that have not yet been handled. If any such events are found,
HandleEvents removes them from the queue and responds to them.
HandleEvents also performs the important function of turning over control to the Process Manager. The Process Manager oversees the execution of all processes on your Macintosh; once it has control, the Process Manager may allow another application to run for a short time before returning control to your application.
HandleEvents responds to some kinds of user actions by calling functions that you have designated in your program. It responds to other kinds of user actions in predetermined, "automatic" ways.
"Automatic" responses by
NOTE: You can inhibit and/or alter these responses by trapping low-level events (especially the
- Allows the Process Manager to bring another process to the front, if the user has selected it in the Applications menu or clicked in one of its windows.
- Opens menus and tracks selection, if user has clicked on the menu bar.
- Activates an inactive window, if the user has clicked on the window's structure region (e.g. its title bar). (This action is inhibited if the window's
_keepInBack attribute is set.)
- Handles dragging & resizing of the active window.
- Performs "standard" handling of mouseclicks and keystrokes in the currently active edit field (if any).
- Highlights & tracks various objects when they're clicked (e.g. buttons, window close box, etc.)
- For any window that requires updating: redraws all buttons, scrollbars, edit fields and picture fields (unless the window's
_noAutoClip feature is set). Also redraws certain parts of the window's structure region.
- If the user presses cmd-period, and no
on break fn function has been identified, then
HandleEvents displays a dialog asking whether the user wants to stop or to continue. If the user elects to stop, FutureBasic then calls your designated
on stop fn function (if any), and then halts the program.
_mButDwnEvt event) in a system event-handling function. See below for more details.
"Programmed" responses by
There are many kinds of common user actions, such as button clicks and menu selections, which you will want to explicitly handle with program statements. When you write a function that is to handle events of a certain type, you designate it as an event-handling function by executing statements like
on dialog fn <functionName>, or
on menu fn <functionName>. Once you've designated your event-handling function(s) this way,
HandleEvents will examine recent user actions to determine whether any of them are of the kind that your function(s) can handle. If any such events are found,
HandleEvents calls the appropriate event-handling function once for each such event. See the descriptions of the various
on <eventType> statements, to learn what types of user actions can be handled.
If you haven't identified a function to handle a certain class of user actions, then
HANDLEVENTS just ignores actions of that class. For example, if you have not identified any function with the
on dialog statement, then
HANDLEVENTS will ignore button clicks and other similar actions.
HandleEvents will still perform the "automatic" responses listed above, however.
Intercepting system events
There may be times when you need greater control over how
HandleEvents responds to certain events. For example, you may want to inhibit or alter some of the "automatic" responses that
HandleEvents normally performs. To do this, you should designate one of your functions as a "system event-handling function," by using the
on event statement. Once you've designated such a function,
HandleEvents calls that function first , before it executes any of its "automatic" responses and before it calls any of the other event-handling functions you may have designated.
HANDLEVENTS either passes a system event to your function (if there's an event in the queue), or it passes a "null event" to your function (if there are no events in the queue).
After your system event-handling function returns,
HandleEvents continues to handle that same event, unless it was a null event. Depending on what the event was,
HandleEvents may perform some of its "automatic" responses, or it may call another one of your event-handling functions. If you don't want
HandleEvents to continue handling the event after your system event-handling function exits, then you need to "trick" FutureBasic into thinking that the event was a null event. You do this by executing a line like the following, in your system event-handling function, after you've handled the event:
theEvent&.evtNum% = _nullEvt
theEvent& is a pointer to the event record.
In order to provide the user with snappy response to actions, and to share execution time with other processes, your program should call
HandleEvents as often as possible. Most well-designed programs contain a "main event loop" which calls
HandleEvents repeatedly for as long as the program is executing, allowing
HandleEvents to call the various event-handling functions as events occur.
Flush the event queue using:
call FlushEvents( _everyEvent, 0 )
The default behaviour of HandleEvents is now to block (i.e. not return) until an event is dispatched.
In FutureBasic version 4, the default behaviour was to return after every 2 ticks (1 tick = 1/60 s) even when no events occurred. In effect a steam of null events was generated 30 times a second, allowing polling but wasting CPU time.
This (typically unwanted) activity could be suppressed by:
poke long event - 8, 0xFFFFFFFF // no null events, thanks
In FutureBasic version 5 onwards, it is no longer necessary to suppress null events in this way. The old FutureBasic version 4 behaviour, if required, can be restored as shown:
poke long event - 8, 2 // null events every 2 ticks, like FutureBasic version 4
on <eventType> statements; dialog statement/function; menu function; mouse; event function; tekey statement/function