Updated April 2014
This field may be used to specify a click string (see Virtual Key Symbolic Names) to generate an exitcode when the XTREE control is clicked while inactive, e.g. "VK_xrF401". Since the field is only ten characters long, to allow for longer forms of the click string to be used, the initial "VK" may be omitted, e.g. "_xrF401".
For standard click strings, although the exitcode does not capture information about the specific location of the click within the control (i.e. row and col), this information is made available internally to the target control so that when the application activates it, the control has the possibility of responding to the location, for example, to select the row clicked on. For single-selection trees, in order for this to work, you must set the answer parameter to 0, otherwise the specified answer value will override the clicked row to determine the new selection. For multi-selection trees, the clicked row will be added to the existing selections. An extended from of the click string (described below) allows the exitcode to be customized to indicate the row and/or column where the click occurred.
Coordinates on Inactive Trees
You may also use XTR.KBDSTR to retrieve row and/or column coordinates of click events on inactive trees, by coding the XTR.KBDSTR field as follows:
_x{r}{d}F##{R..R}{C..C}
In other words, using the standard Virtual Key Symbolic Name syntax, except with the leading "VK" removed, and with some of the numeric digits at the end replaced with a string of zero or more "R" characters (representing row digits) and zero or more "C" characters (representing column digits). For example:
_xF1RRRC
The above format would return exitcodes in the range of -10000 thru -19999 where the last digit represented the column clicked on (1-9) and the next three digits to the left represent row clicked on (1-999). So -10493 would indicate that the user clicked on row 49, column 3. -10000 would indicate some kind of click event that wasn't specifically on a particular cell.
_xrF2RRRR
The above would be useful in cases where you just wanted the row number, and would return exitcodes from -20001 to -29999 for rows 1 thru 9999. As with standard extended virtual key codes, the "r" in between the "_x" and "F" indicates that right clicks will be distinguished by returning a positive exitcode value rather than negative.
_xF5CC
The above example returns exitcodes -501 thru -599, representing clicked columns 1 thru 99.
See Also
• Sample program XTRA4.BP in EXLIB:[908,21].
History
2013 October, A-Shell 6.1.1383: An inactive right-click on a tree now always sends the standard left-click exitcode, regardless of whether the XTR.KBDSTR field contains an "r". Normally an "r" is required, e.g. "VK_xrF101", to support right click, and in that case the exitcode is positive rather than negative. But in this case, the only logical application response is to XCALL XTREE in either case, so making a distinction was just leading to application bugs.
2013 March, A-Shell 6.1.1345: Add ability to retrieve row and/or column coordinates of click events on inactive trees. Eliminated 16-bit bottleneck that limited exit codes to the range of +/- 32K. If using ATE, both the server and client must be at least 6.1.1345.0 in order for XTREE to handle an inactive click exitcode from another XTREE, outside the +/- 32K range.