Futurebasic/Language/Reference/handleevents

Syntax
HANDLEEVENTS

Description
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,  removes them from the queue and responds to them. 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.

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  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  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  feature is set). Also redraws certain parts of the window's structure region.

If the user presses cmd-period, and no  function has been identified, then   displays a dialog asking whether the user wants to stop or to continue. If the user elects to stop, FB then calls your designated  function (if any), and then halts the program.



NOTE: You can inhibit and/or alter these responses by trapping low-level events (especially the  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, or. Once you've designated your event-handling function(s) this way,  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,  calls the appropriate event-handling function once for each such event. See the descriptions of the various 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  just ignores actions of that class. For example, if you have not identified any function with the  statement, then   will ignore button clicks and other similar actions. will still perform the "automatic" responses listed above, however.

Intercepting system events There may be times when you need greater control over how  responds to certain events. For example, you may want to inhibit or alter some of the "automatic" responses that  normally performs. To do this, you should designate one of your functions as a "system event-handling function," by using the statement. Once you've designated such a function,  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. 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,  continues to handle that same event, unless it was a null event. Depending on what the event was,  may perform some of its "automatic" responses, or it may call another one of your event-handling functions. If you don't want  to continue handling the event after your system event-handling function exits, then you need to "trick" FB 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:

where  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  as often as possible. Most well-designed programs contain a "main event loop" which calls  repeatedly for as long as the program is executing, allowing   to call the various event-handling functions as events occur.