This field provides a means of rearranging the display order of the first (up to) 31 columns. As background, if the XTF_REORD flag is specified (and the cformat K is not specified on the columns in question), XTREE allows users to re-order the columns by dragging and dropping the column headers. This, combined with the horizontal scroll capability, may lead to a situation where, in order to satisfy different user desires, an application loads an XTREE with many more columns than can be seen at once, figuring that users can always scroll, or even drag the columns around as desired. But after the initial thrill wears off, the users tire of this routine and would be much happier if they could preserve their own preferred column order. The XTR'COLORDER array, along with the XTR'USECOLORDER field/option, makes this nearly trivial to support. Just set XTR'USECOLORDER to 1 and XTREE automatically saves the updated column arrangement in the XTR'COLORDER() array. All the application needs to do then is to save those 31 bytes in a user preferences file so that it can be recalled the next time the user wants to see this particular XTREE.
Notes
XTR'COLORDER(1) specifies the "real" column which is displayed in the first position; XTR'COLORDER(2) specifies the "real" column displayed in the second position, etc. If the user shrinks a visible column to zero width, effectively making it hidden, this will be noted in the array by adding +128 to the column number.
If you are manually using XTR'COLORDER to set a column order, you do not have to specify all the columns. For example, if there were 10 columns defined, you could determine which of the 10 displayed in the first three positions as follows:
xtr'colorder(1) = 5 ! real column #5 will be displayed first
xtr'colorder(2) = 8+128 ! real column #8 will be second (but will be invisible)
xtr'colorder(3) = 2 ! real column #2 will be displayed third
xtr'colorder(4) = 0 ! remaining columns will retain their natural
! order, i.e. 1,3,4,6,7,9,10
(The first zero in the XTR'COLORDER array effectively terminates the forced part of the ordering, with the remaining columns using "natural" ordering.)
Unless you set the XTF_REORD bit in the flags parameter, the user will not be able to reorder the columns by drag-and-drop, but that would not stop the application from using XTR'USECOLORDER and XTR'COLORDER to override the natural (or "real") column ordering.
Changing the display order of the columns does not affect the way columns are numbered in any of the other parameters (such as XTR'COLUMNSORT, XTR'COLUMNACTIVE, etc.) In other words, the application does not need to be "aware" of how the columns are ordered.
See Also
Update: A-Shell 958.3.1 - 27 June 06
XTREE now allows you to hide a column by using the mouse to shrink its width to 0. (Actually, you could always have done this, but now, if XTR'USECOLORDER=1, XTREE sets the corresponding entry in the XTR'COLORDER array to <position>+128, which effectively causes the column to remain hidden on subsequent calls to reselect from the tree.
This can be demonstrated easily in the XTRA3 sample program: use opcode 0 and set the modeless option to create/display the tree; then manually shrink one or more of the columns to become invisible. Then exit the tree and re-enter it with opcode 0 or 1 to verify that the column remains hidden. (Use the popup menu option to unhide them.)