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 select a column header of the table (mouse click on desktop, tap of mobile).
Selecting 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 convert a visual index
to/from the program array index, use the visualToArrayIndex()
/arrayToVisualIndex()
dialog methods.
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 data used to sort rows is the raw data in the program array. When using a
COMBOBOX
with ITEMS
defining key/label pairs, the runtime system uses the key values to
sort the table rows.
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 DIALOG.arrayToVisualIndex()
. With a page-mode DISPLAY
ARRAY
using ON FILL BUFFER
, the build-in sort is disabled. Use the
ON SORT
trigger to re-sort the result providing rows in ON FILL
BUFFER
. For more details, see Populating a DISPLAY ARRAY.
When an application window is closed, the selected sort column and order is saved. 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.