List ordering

List controllers implement a built-in sort. This feature can be disabled if not required.

When a DISPLAY ARRAY or INPUT ARRAY block is combined with a TABLE container, the row sorting feature is implicitly available. Row sorting is supported on TREE containers with DISPLAY ARRAY dialogs only.

To sort rows in a list, the user must click on a column header of the table. Clicking on a table column header triggers a GUI event that instructs the runtime system to reorder the rows displayed in the list container.

In fact, the rows are only sorted from a visual point of view; the data rows in the program array (the model) are left untouched. Therefore, when rows are sorted, the visual position of the current row might be different from the current row index in the program array.

To sort rows, the runtime system uses the standard collation order of the system, following the current locale settings. As a result, the rows might be ordered a bit differently than when using the database server sort (with an ORDER BY clause of the SELECT statement), since database servers can define their own collation sequences to sort character data.

The built-in sort is enabled by default. To prevent sorting in TABLE or TREE containers, define the UNSORTABLECOLUNMS attribute at the list container level, or set the UNSORTABLE attribute at the column/field level. As rows can be created and modified during an INPUT ARRAY instruction, you may want to use the UNSORTABLECOLUMNS attribute for tables controlled by INPUT ARRAY.

To execute code after a sort was performed, use the ON SORT interaction block in the dialog, for example to display the current row position with ui.Dialog.arrayToVisualIndex.

The sorting feature is disabled when using the paged mode of DISPLAY ARRAY, because not all result set rows are known by the runtime system in this mode. However, it is possible to detect a sort request from the user with the ON SORT trigger. You can then re-execute the SQL query with a new sort order. For more details, see Populating a DISPLAY ARRAY.

When an application window is closed, the selected sort column and order is stored by the front-end in the user settings database of the system (for example, on Windows® platforms it's the registry database). The sort will be automatically re-applied the next time the window is created. This way, the rows will appear sorted when the program restarts. The saved sort column and order is specific to each list container.