Futurebasic/Language/Reference/handleevents

HANDLEEVENTS

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

• 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, FB then calls your designated ON STOP FN function (if any), and then halts the program.

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" 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:

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.

See Also

ON DIALOG; MENU; MOUSE; TEKEY