Added January 2011

When the user clicks on an inactive XTREE, it creates potential complications for the application. Typically, the XTR.KBDSTR parameter of the inactive XTREE will be used to generate an exitcode indicating which control was clicked, and the control currently with the focus will exit with that exitcode. The application would then typically call XTREE for the clicked-on tree. The complications arise when the click event has (or should have) more consequences than simply putting the focus on that XTREE.

For example, if the target tree uses SelChgExit or ClickExit, the click event might logically need to trigger one or both of those exitcodes. In the case of a right-click, if there was a context menu defined, the user would expect it to appear (in addition to the tree getting the focus).

The act of clicking on the inactive tree might also have ramifications for the control that previously had the focus, perhaps INFLD or even another XTREE. For example, in either of those cases, exit validation may be needed, which could potentially put the application the position of having to ignore the original click on the inactive tree, in order to enforce some data entry rules in the previously active tree or field.

The general procedure for dealing with these complications is (and has been) as follows:

•   The click on the inactive tree generates the exitcode associated with the XTR.KBDSTR field for that tree.

•   The currently active control (presumably being handled by a subroutine) exits with that exitcode.

•   The application performs any exit validation or cleanup necessary for the field/control just exited.

•   Assuming no problems so far, it then calls XTREE (probably with XTROP_RESELECT) to activate the tree just clicked on.

•   Once activated, that tree should try to proceed with processing the secondary events associated with the click that occurred when the tree was inactive. For example, if it was a right-click on a column that had a PopupMenu, it should then display the context menu. Or if the click caused the selection to be moved to another row and SelChgExit was defined, then the tree should exit with the exitcode defined for the SelChgExit. If the inactive click was on a checkbox cell, the contents of the checkbox should now be toggled, and if validating, the tree should exit with exitcode -48. Etc.

•   The XTF2_CLRDEFER flag may be specified to disable the post-reentry processing described in the previous paragraph. This would be useful in the case where the operation interrupted by the click on the inactive XTREE wasn't properly completed, causing the application to effectively ignore the inactive XTREE click. But at some point later, the application may decide to call that XTREE again for other reasons, in which case we don't want the tree to then attempt to respond to the deferred events associated with the original click. Note that this is effectively automatic after about 2-3 seconds have elapsed since the inactive click event, so the XTF2_CLRDEFER flag is only really needed when you are calling the inactively-clicked XTREE without much delay.

History

2013 March, A-Shell 6.1.1345:  The inactive click may now generate row/column/cell-specific exitcodes (see XTR.KBDSTR)

2010 November, A-Shell 5.1.1196:  Added Xinfo parameter added to allow tree to return multiple exitcodes