If you prefer to sort list items in different ways, you can assign a java.util.Comparator instance to the sortAscending and/or sortDescending property. Once assigned, the list items can be sorted in the ascending and/or descending order with the comparator you assigned.

The invocation of the sort property with auto actually assign two comparators to the sortAsceding and sortDescending automatically. You can override any of them by assigning another comparator to it.

For example, assume you want to sort based on the value of list items, rather than list cell's label, then you assign an instance of ListitemComparator to these properties as follows.

<zscript>
    Comparator asc = new ListitemComarator(-1, true, true);    
    Comparator dsc = new ListitemComarator(-1, false, true);    
</zscript>
<listbox>
    <listhead>    
        <listheader sortAscending="${asc}" sortDescending="${dsc}"/>        
...

The sortDirection property controls whether to show an icon at the client to indicate the order of the particular column. If list items are sorted before adding to the list box, you shall set this property explicitly.

<listheader sortDirection="ascending"/>

Then, it is maintained automatically by list boxes as long as you assign the comparator to the corresponding list header.

When you assign at least one comparator to a list header, an onSort event is sent to the server if user clicks on it. The list header implements a listener to handle the sorting automatically.

If you prefer to handle it manually, you can add your listener to the list header for the onSort event. To prevent the default listener to invoke the sort method, you have to call the stopPropagation method against the event being received. Alternatively, you can override the sort method, see below.

The sort method is the underlying implementation of the default onSort event listener. It is also useful if you wan to sort the list items by Java codes. For example, you might have to call this method after adding items (assuming not in the proper order).

new Listem("New Stuff").setParent(listbox);
if (!"natural".header.getSortDirection())
    header.sort("ascending".equals(header.getSortDirection()));    

The default sorting algorithm is quick-sort (by use of the sort method from the org.zkoss.zk.ui.Components class). You might override it with your own implementation, or listen to the onSort event as described in the previous section.

Tip: Sorting huge number of live data might degrade the performance significantly. It is better to intercept the onSort event or the sort method to handle it effectively. Refer to the Sort Live Data section below.