de.sciss.gui
Class SortedTableModel

java.lang.Object
  javax.swing.table.AbstractTableModel
      de.sciss.gui.SortedTableModel

All Implemented Interfaces:

java.io.Serializable, javax.swing.table.TableModel

public class SortedTableModel
extends javax.swing.table.AbstractTableModel

Original class commentary: SortedTableModel is a decorator for TableModels; adding sorting functionality to a supplied TableModel. SortedTableModel 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 SortedTableModel appears to hold another copy of the table with the rows in a different order.

SortedTableModel 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 SortedTableModel's listeners (typically the JTable). If a change to the model has invalidated the order of SortedTableModel'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 SortedTableModel. 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.

Version:

0.31, 03-Dec-05

Author:

Philip Milne, Brendon McLean, Dan van Enckevort, Parwinder Sekhon, Hanns Holger Rutz

See Also:

Serialized Form

Todo:

row selection should be updated when switching sorting

Field Summary

static int	ASCENDING
protected java.util.List	collSorted
static java.util.Comparator	COMPARABLE_COMPARATOR A comparator which works on objects that implement the Comparable interface
static int	DESCENDING
protected int[]	modelToView
static int	NOT_SORTED
protected java.util.Set	setDisallowedColumns
static java.util.Comparator	STRING_COMPARATOR A comparator which converts the objects to strings
static java.util.Comparator	STRING_COMPARATOR_UPCASE A comparator which converts the objects to strings and converting them to upper case.
protected javax.swing.table.TableModel	tableModel

Fields inherited from class javax.swing.table.AbstractTableModel

listenerList

Constructor Summary

SortedTableModel()
Creates a new sorted table model with no underlying model assigned.

SortedTableModel(javax.swing.table.TableModel tableModel)
Creates a new sorted table model with a given underlying model assigned.

SortedTableModel(javax.swing.table.TableModel tableModel, javax.swing.table.JTableHeader tableHeader)
Creates a new sorted table model with a given underlying model assigned and a table header used for selecting the sorted column.

Method Summary

void	cancelSorting() Reverts view back to unsorted mode.
protected void	clearSortingState()
java.lang.Class	getColumnClass(int column)
int	getColumnCount()
java.lang.String	getColumnName(int column)
protected java.util.Comparator	getComparator(int column)
protected javax.swing.Icon	getHeaderRendererIcon(int column)
int	getModelIndex(int viewIndex) Returns the row index in the model based on a row index in the visual (sorted) representation.
protected int[]	getModelToView()
int	getRowCount()
int	getSortedColumnDirection() Queries the sorted column's direction.
int	getSortedColumnIndex() Queries the index of the sorted column.
boolean	getSortingAllowed(int columnIndex) Defines a column to be sortable or not sortable.
protected int	getSortingStatus(int column)
javax.swing.table.JTableHeader	getTableHeader()
javax.swing.table.TableModel	getTableModel()
java.lang.Object	getValueAt(int row, int column)
int	getViewIndex(int modelIndex) Returns the row index in the view based on a row index in the (non-sorted) model.
boolean	isCellEditable(int row, int column)
boolean	isSorting() Queries whether the table is sorted by some column.
void	setColumnComparator(java.lang.Class type, java.util.Comparator comparator) Provides a custom comparator for a given class of table cell values.
void	setSortedColumn(int columnIndex, int direction) Sets the sorted column.
void	setSortingAllowed(int columnIndex, boolean allowed) Defines a column to be sortable or not sortable.
protected void	setSortingStatus(int column, int status)
void	setTableHeader(javax.swing.table.JTableHeader tableHeader)
void	setTableModel(javax.swing.table.TableModel tableModel)
void	setValueAt(java.lang.Object aValue, int row, int column)

Methods inherited from class javax.swing.table.AbstractTableModel

addTableModelListener, findColumn, fireTableCellUpdated, fireTableChanged, fireTableDataChanged, fireTableRowsDeleted, fireTableRowsInserted, fireTableRowsUpdated, fireTableStructureChanged, getListeners, getTableModelListeners, removeTableModelListener

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

tableModel

protected javax.swing.table.TableModel tableModel

DESCENDING

public static final int DESCENDING

See Also:

Constant Field Values

NOT_SORTED

public static final int NOT_SORTED

See Also:

Constant Field Values

ASCENDING

public static final int ASCENDING

See Also:

Constant Field Values

COMPARABLE_COMPARATOR

public static final java.util.Comparator COMPARABLE_COMPARATOR

A comparator which works on objects that implement the Comparable interface

STRING_COMPARATOR

public static final java.util.Comparator STRING_COMPARATOR

A comparator which converts the objects to strings

STRING_COMPARATOR_UPCASE

public static final java.util.Comparator STRING_COMPARATOR_UPCASE

A comparator which converts the objects to strings and converting them to upper case.

modelToView

protected int[] modelToView

collSorted

protected java.util.List collSorted

setDisallowedColumns

protected java.util.Set setDisallowedColumns

Constructor Detail

SortedTableModel

public SortedTableModel()

Creates a new sorted table model with no underlying model assigned. Use setTableModel to assign such an underlying model before using the stm.

SortedTableModel

public SortedTableModel(javax.swing.table.TableModel tableModel)

Creates a new sorted table model with a given underlying model assigned. Use setTableHeader to assign a header used for selecting the sorted column.

SortedTableModel

public SortedTableModel(javax.swing.table.TableModel tableModel,
                        javax.swing.table.JTableHeader tableHeader)

Creates a new sorted table model with a given underlying model assigned and a table header used for selecting the sorted column.

Method Detail

getTableModel

public javax.swing.table.TableModel getTableModel()

setTableModel

public void setTableModel(javax.swing.table.TableModel tableModel)

getTableHeader

public javax.swing.table.JTableHeader getTableHeader()

setTableHeader

public void setTableHeader(javax.swing.table.JTableHeader tableHeader)

isSorting

public boolean isSorting()

Queries whether the table is sorted by some column. Initially the table is not sorted. As soon as the user clicks on a column header or if setSortingStatus is called, the table will be sorted.

Returns:

true if the table is sorted by some column

getSortedColumnIndex

public int getSortedColumnIndex()

Queries the index of the sorted column.

Returns:

the sorted column index or -1 if not sorted by any column

getSortedColumnDirection

public int getSortedColumnDirection()

Queries the sorted column's direction.

Returns:

ASCENDING or DESCENDING. If the table is not sorted, returns NOT_SORTED

setSortedColumn

public void setSortedColumn(int columnIndex,
                            int direction)

Sets the sorted column. Clears the previously sorted column. Note that this will not check for allowed/disallowed columns.

Parameters:

columnIndex - index of the column to sort

direction - either of ASCENDING, DESCENDING, or NOT_SORTED (equal to calling cancelSorting())

cancelSorting

public void cancelSorting()

Reverts view back to unsorted mode.

setColumnComparator

public void setColumnComparator(java.lang.Class type,
                                java.util.Comparator comparator)

Provides a custom comparator for a given class of table cell values. Note that this will not alter the currently active sorting state in any way.

Parameters:

type - the class of the values for which to use the custom comparator

comparator - the comparator to use for this class of values, or null to remove a custom comparator

setSortingAllowed

public void setSortingAllowed(int columnIndex,
                              boolean allowed)

Defines a column to be sortable or not sortable. Use this method to exempt certain columns from being sortable. By default all columns are considered sortable. Note that this will not alter the currently active sorting state in any way.

Parameters:

columnIndex - model index of the column to modify

allowed - true to allow this column to be sorted, false to prohibit sorting

getSortingAllowed

public boolean getSortingAllowed(int columnIndex)

Defines a column to be sortable or not sortable. Use this method to exempt certain columns from being sortable. By default all columns are considered sortable. Note that this will not alter the currently active sorting state in any way.

Parameters:

columnIndex - model index of the column to modify

Returns:

true if it's allowed to sort this column, false otherwise

getModelIndex

public int getModelIndex(int viewIndex)

Returns the row index in the model based on a row index in the visual (sorted) representation.

Parameters:

viewIndex - row index in the sorted visible table

Returns:

row index in the underlying (not sorted) model

Throws:

IndexOutOfBoundException - if the viewIndex is out of range

getViewIndex

public int getViewIndex(int modelIndex)

Returns the row index in the view based on a row index in the (non-sorted) model.

Parameters:

modelIndex - row index in the underlying (not sorted) model

Returns:

row index in the sorted visible table

Throws:

IndexOutOfBoundException - if the modelIndex is out of range

getSortingStatus

protected int getSortingStatus(int column)

setSortingStatus

protected void setSortingStatus(int column,
                                int status)

getHeaderRendererIcon

protected javax.swing.Icon getHeaderRendererIcon(int column)

getComparator

protected java.util.Comparator getComparator(int column)

clearSortingState

protected void clearSortingState()

getModelToView

protected int[] getModelToView()

getRowCount

public int getRowCount()

getColumnCount

public int getColumnCount()

getColumnName

public java.lang.String getColumnName(int column)

Specified by:

getColumnName in interface javax.swing.table.TableModel

Overrides:

getColumnName in class javax.swing.table.AbstractTableModel

getColumnClass

public java.lang.Class getColumnClass(int column)

Specified by:

getColumnClass in interface javax.swing.table.TableModel

Overrides:

getColumnClass in class javax.swing.table.AbstractTableModel

isCellEditable

public boolean isCellEditable(int row,
                              int column)

Specified by:

isCellEditable in interface javax.swing.table.TableModel

Overrides:

isCellEditable in class javax.swing.table.AbstractTableModel

getValueAt

public java.lang.Object getValueAt(int row,
                                   int column)

setValueAt

public void setValueAt(java.lang.Object aValue,
                       int row,
                       int column)

Specified by:

setValueAt in interface javax.swing.table.TableModel

Overrides:

setValueAt in class javax.swing.table.AbstractTableModel