XTREE supports the following kinds of sorting.
User-Controlled Sorting
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, and a third click will restore the original (physical) 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. 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.
Depending on the column type, XTREE uses one of the following sort algorithms:
| • | ASCII Sort cformat code A) |
| • | Natural Sort (S) |
| • | Numeric Value Sort (# or Z). |
| • | Date (D or d) - Supports variations of mm/dd/{cc}yy and dd/mm{cc}yy depending on the locale, or dd-mon-yr |
| • | Time (h) - mm:hh{:ss} {AM/PM} |
| • | Checkboxes and radio buttons (T, t, tt, R, r) |
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:
| • | To override the built-in sort logic, use the HdrClickExit Advanced Coldef Option to trap the user's click on the header. The application can then resort the data rows any way it likes and reload the tree using XTROP_REPLACE. |
| • | 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.) |
| • | Use the Advanced Coldef Options HdrLines and TotalLines directives (and/or XTF_TOTALS flag) to prevent the headers and/or totals from being sorted with the other rows. |
Context Menu Sorting
The application can also provide the user with pre-configured multi-level sort options on the context menu via the PopupMenu $Sort directive.
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.
