Added November 2010

When one control has the focus (whether an XTREE, INFLD, or some other), and the user clicks on another XTREE, the event is signaled by processing the XTR.KBDSTR parameter associated with the clicked-on tree. This will cause the current control-handling routing (XTREE, INFLD, AUI_EVENTWAIT, etc.) to exit with the corresponding exitcode. The application would then typically invoke an XCALL XTREE operation for the clicked-on tree (as determined by the exitcode) to allow the user to work with that tree.

Obviously in order to be able to identify the clicked-on tree, each tree should have a unique exitcode (i.e. a unique XTR.KBDSTR). While this generally applies to any control for which a click event should result in the application giving the control focus, clicking on an inactive XTREE has additional complications in that it may matter exactly where on the tree the click occurred (i.e. the row and column). For example, if the user clicks on an editable cell at location (3,5), there would be a reasonable expectation that the application would respond by putting the focus on the tree and specifically on that cell, putting it in editing mode. But the click event returns the same exitcode regardless of where the tree was clicked. How can the application identify the specific cell in order to respond as the user expects?

There are two solutions to this problem. the first is that the XTR.TARGETROW/COL fields will be set according to the clicked-on tree (i.e. the previously inactive one), while the XTR.XROW/XCOL fields will indicate the last context of the tree that was active. (This solution only applies when the control which initially had the focus was XTREE.)

A more general solution is that each XTREE control remembers any click events that occur while the tree is not active. The remembered click event can then be automatically processed when the application calls that tree to activate it. In the example just given, the application responds to the click on a particular tree by calling XTREE to activate it (typically in XTROP_RESELECT mode). As soon as it becomes active, that control can then respond to the saved click event (in this case putting the focus on cell (3,5) and going into editing mode. This scheme is particularly useful for events that aren't completely described by the XTR.TARGETROW/COL information (such as a SelChgExit triggered by the fact that the click on the inactive tree moved the selection bar of that tree).

Another example of where the saved/recalled click mechanism comes in handy would be in the case of a right-click on an inactive tree which has a context menu defined (see PopupMenu). Initially, rather than displaying the context menu, the click information is saved and instead the exitcode associated with the clicked-on tree is generated, causing the current control-handling routine to exit. When the application calls XTREE to process the clicked-on tree, XTREE will start by processing the deferred right-click information, causing the context menu to appear. (Assuming no undue delays in the application, this behind-the-scenes processing will be invisible to the user, who will simply see the context menu appear in response to the right-click.)

Both of these mechanisms are automatic. But there may be cases where the application decides it does not want to proceed with the user's intent, i.e. does not want the deferred click action to take place. For example, if the click on the inactive XTREE control occurs while the user was editing a text field (in INFLD, or perhaps in another XTREE), the typical plan would be for the current subroutine to return with the clicked-on XTREE's exitcode, so the application could call XTREE to process that event. But maybe the current value of the field violates some application rule, in which case the application may decide to just ignore the XTREE click and instead display a data-entry error message and return to editing the field. At some later point, the application may decide to activate the previously-clicked XTREE, but by then you would no longer want to process the deferred click event. XTREE uses a timer to attempt to determine whether the deferred click event is still relevant, but as of 5.1.1195, a new flag was added, XTF2_CLRDEFER, to force it to ignore (clear) deferred click event information (eliminating any question about the whether the timer expired).