xcall AUI, AUI_EVENTWAIT, parentid, ctlid, exitcode {,opflags, timer}
This function has both a subroutine and a print tab implementation.
Parameters
Parameter |
Type |
I/O |
Description |
in |
Specifies a parent control to which the button controls of interest are children to. Leave zero if not applicable. |
||
in/out |
ID of the control which should start with the focus. If zero, the first control within the group specified by parentid will start with the focus. |
||
in/out |
(Signed Num) Returns a code indicating the event received. |
||
B,4 |
in |
Flags affecting operation. |
|
timer |
in |
Optional numeric argument which can be set to the number of milliseconds to wait for an event before the eventwait times out with exitcode 11. |
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.
Comments
When converting from a traditional procedural program to an event-driven one, you will probably encounter situations where used to have an input prompt to wait for the user to select among many choices or confirm/cancel an operation. In the GUI model, such an input prompt may seem silly, since the layout of the screen (buttons, other things to click on) makes it obvious what the user needs to do without being prompted to type something. This EVENTWAIT class is perfect for such situations. Examples include:
| • | Menus, where in the text version you might have a prompt like "Enter Selection:" but now you have buttons. |
| • | At the bottom of an input form, where in the text version you might have had an "Any Change?" prompt, but now you have buttons such as "OK" and "Cancel", with the implicit understanding that the user can just click on a field to edit it. |
| • | Dialogs, especially those containing checkboxes and radio buttons (which do not require any special procedural coding and can instead just be queried upon exiting the dialog). |
Although you do not need to specify a parent group, this concept is generally much clearer if you do group the relevant buttons within a parent. The best way to do this is with a Groupbox Control. Note that the group box need not take up any extra space or even be visible. (You can set its initial state to MBST_HIDE and its size to one row high, and place the buttons right on top of it.)
The BTNMNU.SBX routine encapsulates this logic in a wrapper making it easy to create and use (i.e. wait on) groups of buttons.
The sample program TSTEVW in EXLIB:[908,20] provides detailed examples of using EVENTWAIT, both via BTNMNU and via AUI.
EVENTWAIT only allows the focus to be moved amongst controls that have the MBF_TABSTOP property. This property is automatic for regular buttons, and may be applied manually to check boxes and radio buttons. No other control type currently supports the MBF_TABSTOP property, although the EVW_INFLD flag will cause EVENTWAIT to act as if all INFLD controls had the MBF_TABSTOP property.
See Also
History
2011 February, A-Shell 5.1.1205: Support alphanumeric as well as numeric control IDs for parentid and ctlid.
