TableSorter is a decorator for TableModels; adding sorting functionality to a supplied
TableModel. TableSorter does not store or copy the data in its TableModel; instead it maintains a
map from the row indexes of the view to the row indexes of the model. As requests are made of the
sorter (like getValueAt(row, col)) they are passed to the underlying model after the row numbers
have been translated via the internal mapping array. This way, the TableSorter appears to hold
another copy of the table with the rows in a different order.
TableSorter registers itself
as a listener to the underlying model, just as the JTable itself would. Events recieved from the
model are examined, sometimes manipulated (typically widened), and then passed on to the
TableSorter's listeners (typically the JTable). If a change to the model has invalidated the
order of TableSorter's rows, a note of this is made and the sorter will resort the rows the next
time a value is requested.
When the tableHeader property is set, either by using the
setTableHeader() method or the two argument constructor, the table header may be used as a
complete UI for TableSorter. The default renderer of the tableHeader is decorated with a renderer
that indicates the sorting status of each column. In addition, a mouse listener is installed with
the following behavior:
- Mouse-click: Clears the sorting status of all other columns and advances the sorting status
of that column through three values: {NOT_SORTED, ASCENDING, DESCENDING} (then back to NOT_SORTED
again).
- SHIFT-mouse-click: Clears the sorting status of all other columns and cycles the sorting
status of the column through the same three values, in the opposite order: {NOT_SORTED,
DESCENDING, ASCENDING}.
- CONTROL-mouse-click and CONTROL-SHIFT-mouse-click: as above except that the changes to the
column do not cancel the statuses of columns that are already sorting - giving a way to initiate
a compound sort.
This is a long overdue rewrite of a class of the same name that first appeared in the swing
table demos in 1997.