XTREE vs. PCKLST, Text vs. GUI

XTREE is an upward-compatible variation of the older routine PCKLST. XTREE and PCKLST are actually the same subroutine, so it does not really matter what name you use. We split it into two different names simply to make it easier to document and understand, since the uses of XTREE may diverge considerably from those of PCKLST, and also to avoid the potential confusion of people trying to use XTREE features that are not available in a text environment. Our recommendation is for you to use PCKLST if you need text mode compatibility and are (therefore) going to stick with the PCKLST features and semantics (as documented under PCKLST). Otherwise, if you are committed to the GUI environment and want to take advantage of the maximum feature set, use XTREE.

Depending on how you call it and the operating environment, the subroutine chooses one of two internal implementations. For text environments, it uses the INMEMO menu mode to display the list and allow you to choose an item. (This will only be successful though if you limit yourself to the PCKLST feature set and argument semantics.) For GUI environments, it uses a third-party tree control, which is licensed for A-Shell distribution. It resides in an external module, SftTree_IX86_A_##.DLL, which must be in the same directory where ashw32.exe resides. Samples of XTREE usage in A-Shell are shown below.

Note: The changes listed below are the ones that have NOT integrated into the main body of the documentation. The documenter-in-chief doesn't know where to put them, but didn't want to not include them.

1203 – 02 February 2011

XTREE refinement: Adjust type-ahead logic introduced in 5.1.1197. The new rule is: On calling XTREE, if there is a pending event from clicking on the tree while it was inactive, then any unprocessed keyboard characters are stripped and ignored. In addition, if the XTF2_CLRDEFER flag is set and there is a virtual exitcode sequence pending, it is also stripped. Previously, the virtual exitcode sequence stripping was not dependent on the XTF2_CLRDEFER flag, which made it impossible to use XTREE as a kind of Eventwait handler for click events that had already happened (but which hadn't been detected by the application yet.)

970.0.3 - 31 Oct 06

The XTREE backslash \ character now marks the start of hidden text within a column in array mode, just as it does in file mode. Note that to treat backslash as a normal character, you need to add the \ code to a column definition (any column will do). (WARNING: This may break existing XTREEs that contain backslashes in the array data since previously the \ column code was not necessary for arrays; talk to Herman if you don't like this, or just add \ to your column definitions.)