Updated September 2018; see History

When this option is set, AUI_EVENTWAIT gives preference to the incoming EXITCODE value in deciding which control to initially set the focus on, using the following rules:

•   If EXITCODE < 0 and not -35 through -42 (often used for Shift+Tab and Shift+Arrows) then it is interpreted as if the CTLID parameter had been set to the control whose click-string generates the specified EXITCODE. Provided that the control is of a type that is normally allowed to retain the focus by EVENTWAIT. If, for example, you define both a static text label and an INFLD field with the same EXITCODE click string, EVENTWAIT will skip over the label and activate the INFLD field.

•   Else if EXITCODE is 2, 3, -35, -36, -37, -40 or -42 (Left-arrow, Up-arrow, Shift+Left-arrow, Shift+Up-arrow, Shift+Tab and shifted XTREE up/left) then the EVW_PREV flag is automatically set.

•   Else if EXITCODE is 5, 7, 12, -38, -39 or -41 (Down-Arrow, Tab, Right-Arrow, Shift+Right, Shift+Down, Shift+Right in XTREE) then the EVW_NEXT flag is automatically set.

•   Else it acts as if the EVW_EXCDFOCUS flag had not been set.

An example will make it clear why this is handy. Imagine a dialog containing some buttons and also several INFLD fields, where you are going to use AUI_EVENTWAIT. Previously, to start you might have set CTLID to the ID of a particular button. You can still do that, but since the logic of your application is probably built on the EXITCODE values rather than the control IDs, it will be easier to just set EXITCODE to the value corresponding to the desired control and use EVW_EXCDFOCUS. That's a minor improvement. But consider if you wanted to start on one of the INFLD fields. You would not call AUI_EVENTWAIT at all, rather you'd call INFLD. But this complicates your logic. If you just set EXITCODE to the value corresponding to the desired field (and specify EVW_EDIT) then AUI_EVENTWAIT will immediately return to you with the desired exitcode—which accomplishes nothing but simplifies your code since you do not have to have special logic for handling the initial focus.

The main improvement comes as you return to the AUI_EVENTWAIT after calling INFLD (or XTREE). If the user exits from the INFLD operation by hitting Up-arrow (returning EXITCODE 3), previously you would have had to figure out what the control ID was for the control prior to that INFLD control (or at the very least, have logic to set the EVW_NEXT or EVW_PREV flags). Now, with the EVW_EXCDFOCUS flag, you can just go right back to the AUI_EVENTWAIT operation and let it decide what the next control to get the focus should be.

In other words, your dialog loop can probably now be simplified down to something like:

do

   xcall AUI,AUI_EVENTWAIT, CTLID, PARENTID, EXITCODE, OPFLAGS

   if <exitcode to exit dialog>

      exit

   else

      call <field handler based on exitcode>

loop

History

2018 September, A-Shell 6.5.1647:  AUI_EVENTWAIT refinement: static 'buttons'—i.e. static controls with the MBF_KBD flag set so they act like clickable buttons—are now compatible with the EVW_EXCDFOCUS flag if the MBF_TABSTOP flag is also set.