XTREE supports both user-controlled and application-controlled sorting.

User-controlled sorting: To enable user-controlled sorting, specify the XTF_SORT flag. When specified, the user can click on a column header to sort the list based on the data in that column. On the first click, a small up-arrow will appear in the column header, indicating that the column has been sorted with the lowest value items at the top (which is actually descending order). Clicking it again will reverse the order. Multiple-column sorts can be achieved by holding down the Control key while clicking on the column headers. For example, in a tree containing columns for Countries, States, and Cities, you can sort by cities within states by clicking first on the Cities column header, then while holding the Control key down, click on the States column header.

Application-controlled sorting: The application can determine the initial display order of the rows by setting the fields XTR'COLUMNSORT and XTR'SORTORDER. This does not require that the XTF_SORT flag be set. If it is set, then the user can proceed to override the original sort order by the method described above. If the user changes the sort order, the XTR'COLUMNSORT and XTR'SORTORDER will be updated on return, giving the application the ability to later re-display the tree data in the order last specified by the user (or not).

Note the following:

• Whether user- or application-controlled, sorting only affects the display order. It has no effect on the internal order of the data. Any row index indicators passed into or returned from the routine will continue to be relative to the original, physical order of the source data. (For example, if sorting causes the first item of the source data to be repositioned to the end, selecting it will still return answer set to 1.)

• When sorting multi-level trees, the child rows are always kept with their original parents. In other words, the top level rows are sorted, then the children within each parent item are sorted, and so on.

• The sort algorithm is affected by the following codes:

XTF_SORT (enable user-controlled sorting)

XTF_TOTALS (declare last row as a total row so it does not get sorted)

Cformat codes: # (Num), S (String), D (date format), d (another date format), n (empty cells to bottom), ^ (fold)

History

2010 June, A-Shell 5.1.1185:  Sorting a column by clicking on the header now cycles between ascending, descending, and original (physical array) order.