xcall AUI, AUI_EVENTWAIT, parentid, ctlid, exitcode {,opflags, timer}

The AUI_EVENTWAIT class is really less of an independent "class" than a method relating to the CONTROL class, but is separated out for parameter organization convenience. Its purpose is simply to wait for an event, allowing the user to shift the focus among a range of buttons (plus some other control types) until something is clicked which triggers an event. It could be implemented using an invisible INFLD call in a loop, but this is much simpler to program.

The basic concept is analogous to the dialog manager in Windows or forms manager in VB, which allows the user to move around the form or dialog until some event is triggered that requires the dialog or forms manager to exit (temporarily or permanently) back to the application. In Windows/VB this is done by calling special event handler routines in the application. In A-Shell, this is done by returning from the routine with an exitcode and control ID and leaving it to the application to perform whatever action it deems suitable, after which the application can return to the eventwait (or not).

Aside from simplifying the coding of event-driven programs, AUI_EVENTWAIT can often be useful for converting legacy programs which prompt the user to enter a field number to edit, or to choose among a handful of commands that might otherwise be represented as buttons. In the legacy case, the program would be waiting for only one kind of event (the entry of a field number or menu command.) With AUI_EVENTWAIT, the program logic is nearly the same, except that instead of keying in a command, the user can select a field to edit or operation to perform by either clicking on something that generates an exitcode, or by using the Arrows and Tab and Shift+Tab keys to move the focus around a collection of buttons or other controls and hitting Enter to generate the equivalent of a click.

There are several options relating to managing which control gets the focus to start with, which controls can get the focus, and what kinds of events generate exitcodes.

Although AUI_EVENTWAIT will exit on any click event that generates an INFLD-style exitcode, it only allows the focus to be moved (via Arrows and Tab and Shift+Tab) to a limited subset of controls that can take the MBF_TABSTOP style. Standard pushbuttons automatically get this style, while it can be manually added to checkboxes and radio buttons when they are created. In the case of INFLD controls, there is no way to specify the MBF_TABSTOP style when creating them, but you can pass the EVW_INFLD flag to AUI_EVENTWAIT to temporarily confer that style on all INFLD controls in the scope.

Note that this function was originally designated as MX_EVENTWAIT and MX_BTNIDLE.