FutureBasic Logo

<<    Index    >> FutureBasic 5

HandleEvents   statement



Syntax:
HandleEvents

Description:
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 HandleEvents
NOTE: You can inhibit and/or alter these responses by trapping low-level events (especially the _mButDwnEvt event) in a system event-handling function. See below for more details.

"Programmed" responses by HandleEvents
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
where 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.

Flushing events
Flush the event queue using: call FlushEvents( _everyEvent, 0 )

Events trapping
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
do
  fn PollRegularlyForSomething
  HandleEvents
until gFBQuit


See Also:
on <eventType> statements; dialog statement/function; menu function; mouse; event function; tekey statement/function