Updated August 2011

XTREE provides two built-in methods for preserving display adjustments (column sizing, ordering, sorting, etc.) between calls. The first involves the use of the XTR'COLORDER array to return the size and position of the columns to the application so that it may save it and recall it later. The second method is somewhat more powerful and requires no application involvement other than the following changes to the code calling each XTREE:

• Use the new advanced coldef directive TreeID to give the tree a unique identity, so that any user-directed modifications can be associated with just that one tree. See notes below.

• Assign the XTR'USRCFG field (in xtrctl) to one of the following, based on which user-configuration options should be allowed to override the application-supplied values:

    *from XTREE.DEF

The TreeID may consist of an alphanumeric name, with an optional :# suffix where # is the version of the tree (an integer value). The idea of the version is so that if you modify the tree layout during an application update, XTREE will know not to apply previously saved configuration details to the new tree layout.

The TreeID (maximum 32 chars) may also contain "%p" which will be replaced at runtime by the name of the current program. The feature is mainly useful for XTREEs that are implemented within SBX routines that might be called by multiple programs, where you want to allow the user to maintain a separate configuration in each case. So for example, you might use

TreeID=SelCus-%p:1

For ATE, see History notes below.

User configuration adjustments are saved in the Registry automatically, provided that TreeID is defined. (If XTR'USRCFG is zero, the settings will be saved on exit, but not restored on entrance, which is one way to force the configuration back to application-specified settings.)

Another way to deal with the possibility that the user accidentally makes a disastrous change to the configuration (like resizing a column to zero width, thus making it disappear entirely), is to define a Popup Menu and add to it the new special command $RESETCFG. For example:

COLDEF=COLDEF+"0~0~x~H~PopupMenu=Misc,VK_xF666;Reset Columns,$RESETCFG~~"

Selecting this option from the menu will cause the tree configuration to be immediately reset back to the way the application had originally intended.

The configuration information is saved in the Registry as:

HKCU\Software\MicroSabio\A-Shell\XTREE\treeid

where treeid is the value specified in the TreeID= coldef clause, but with the version stripped. (The version is saved as a sub-field rather than part of the key, to reduce the proliferation of Registry entries.)

History

2016 October, A-Shell 6.3.1530:  Number of columns whose reordering can be maintained between sessions expanded from 31 to the maximum number of columns supported by XTREE (currently 100).

2011 August, A-Shell 5.1.1229:  Prior to ATE 5.1.1229, the "%p" code (for program name) did not work at all, and in fact, rendered the TreeID inoperable. As of ATE 5.1.1229, it does work, although subject to the server version. For server versions prior to 5.1.1217, "%p" is translated to "ATE". As of edit 1217, A-Shell on the server began transmitting the program name to ATE, allowing "%p" to be translated to the proper application program name.

2008 October, A-Shell 5.1.1126:  Ability for users to save/restore their own adjustments added to A-Shell.

2008 October, A-Shell 5.1.1127:  Column configuration now saved even when tree is exited with Escape (since this is a common exit not necessarily considered as "cancel"). The only way to exit without saving is now Ctrl+C.