tecgraf.javautils.gui.table

Class TecDefaultRowSorter<M,I>

java.lang.Object

javax.swing.RowSorter<M>

tecgraf.javautils.gui.table.TecDefaultRowSorter<M,I>

Type Parameters:

M - the type of the model

I - the type of the identifier passed to the RowFilter

Direct Known Subclasses:

TecTableRowSorter

public abstract class TecDefaultRowSorter<M,I>
extends RowSorter<M>

An implementation of RowSorter that provides sorting and filtering around a grid-based data model. Beyond creating and installing a RowSorter, you very rarely need to interact with one directly. Refer to TableRowSorter for a concrete implementation of RowSorter for JTable.

Sorting is done based on the current SortKeys, in order. If two objects are equal (the Comparator for the column returns 0) the next SortKey is used. If no SortKeys remain or the order is UNSORTED, then the order of the rows in the model is used.

Sorting of each column is done by way of a Comparator that you can specify using the setComparator method. If a Comparator has not been specified, the Comparator returned by Collator.getInstance() is used on the results of calling toString on the underlying objects. The Comparator is never passed null. A null value is treated as occuring before a non-null value, and two null values are considered equal.

If you specify a Comparator that casts its argument to a type other than that provided by the model, a ClassCastException will be thrown when the data is sorted.

In addition to sorting, DefaultRowSorter provides the ability to filter rows. Filtering is done by way of a RowFilter that is specified using the setRowFilter method. If no filter has been specified all rows are included.

By default, rows are in unsorted order (the same as the model) and every column is sortable. The default Comparators are documented in the subclasses (for example, TableRowSorter).

If the underlying model structure changes (the modelStructureChanged method is invoked) the following are reset to their default values: Comparators by column, current sort order, and whether each column is sortable. To find the default Comparators, see the concrete implementation (for example, TableRowSorter). The default sort order is unsorted (the same as the model), and columns are sortable by default.

If the underlying model structure changes (the modelStructureChanged method is invoked) the following are reset to their default values: Comparators by column, current sort order and whether a column is sortable.

DefaultRowSorter is an abstract class. Concrete subclasses must provide access to the underlying data by invoking setModelWrapper. The setModelWrapper method must be invoked soon after the constructor is called, ideally from within the subclass's constructor. Undefined behavior will result if you use a DefaultRowSorter without specifying a ModelWrapper.

DefaultRowSorter has two formal type parameters. The first type parameter corresponds to the class of the model, for example DefaultTableModel. The second type parameter corresponds to the class of the identifier passed to the RowFilter. Refer to TableRowSorter and RowFilter for more details on the type parameters.

Since:

1.6

Version:

1.20 06/23/06

See Also:

TableRowSorter, DefaultTableModel, Collator

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	TecDefaultRowSorter.ModelWrapper<M,I> DefaultRowSorter.ModelWrapper is responsible for providing the data that gets sorted by DefaultRowSorter.

Nested classes/interfaces inherited from class javax.swing.RowSorter

RowSorter.SortKey

Constructor Summary

Constructors

Constructor and Description
TecDefaultRowSorter() Creates an empty TecDefaultRowSorter.

Method Summary

Methods

Modifier and Type	Method and Description
void	allRowsChanged()
int	convertRowIndexToModel(int index)
int	convertRowIndexToView(int index)
Comparator<?>	getComparator(int column) Returns the Comparator for the specified column.
int	getMaxSortKeys() Returns the maximum number of sort keys.
M	getModel() Returns the underlying model.
int	getModelRowCount()
protected TecDefaultRowSorter.ModelWrapper<M,I>	getModelWrapper() Returns the model wrapper providing the data that is being sorted and filtered.
boolean	getNoSortEnabled() Indica se o estado "não-ordenado" está ou não habilitado.
RowFilter<? super M,? super I>	getRowFilter() Returns the filter that determines which rows, if any, should be hidden from view.
List<? extends RowSorter.SortKey>	getSortKeys() Returns the current sort keys.
boolean	getSortsOnUpdates() Returns true if a sort should happen when the underlying model is updated; otherwise, returns false.
int	getViewRowCount()
boolean	isSortable(int column) Returns true if the specified column is sortable; otherwise, false.
void	modelStructureChanged()
void	rowsDeleted(int firstRow, int endRow)
void	rowsInserted(int firstRow, int endRow)
void	rowsUpdated(int firstRow, int endRow)
void	rowsUpdated(int firstRow, int endRow, int column)
void	setComparator(int column, Comparator<?> comparator) Sets the Comparator to use when sorting the specified column.
void	setMaxSortKeys(int max) Sets the maximum number of sort keys.
protected void	setModelWrapper(TecDefaultRowSorter.ModelWrapper<M,I> modelWrapper) Sets the model wrapper providing the data that is being sorted and filtered.
void	setNoSortEnabled(boolean enable) Habilita / desabilita o estado "não-ordenado" da tabela.
void	setNullComparison(boolean enable)
void	setRowFilter(RowFilter<? super M,? super I> filter) Sets the filter that determines which rows, if any, should be hidden from the view.
void	setSortable(int column, boolean sortable) Sets whether or not the specified column is sortable.
void	setSortKeys(List<? extends RowSorter.SortKey> sortKeys) Sets the sort keys.
void	setSortsOnUpdates(boolean sortsOnUpdates) If true, specifies that a sort should happen when the underlying model is updated (rowsUpdated is invoked).
void	sort() Sorts and filters the rows in the view based on the sort keys of the columns currently being sorted and the filter, if any, associated with this sorter.
void	toggleSortOrder(int column) Reverses the sort order from ascending to descending (or descending to ascending) if the specified column is already the primary sorted column; otherwise, makes the specified column the primary sorted column, with an ascending sort order.
protected boolean	useToString(int column) Returns whether or not to convert the value to a string before doing comparisons when sorting.

Methods inherited from class javax.swing.RowSorter

addRowSorterListener, fireRowSorterChanged, fireSortOrderChanged, removeRowSorterListener

Methods inherited from class java.lang.Object

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

Constructor Detail

TecDefaultRowSorter

public TecDefaultRowSorter()

Creates an empty TecDefaultRowSorter.

Method Detail

setModelWrapper

protected final void setModelWrapper(TecDefaultRowSorter.ModelWrapper<M,I> modelWrapper)

Sets the model wrapper providing the data that is being sorted and filtered.

Parameters:

modelWrapper - the model wrapper responsible for providing the data that gets sorted and filtered

Throws:

IllegalArgumentException - if modelWrapper is null

getModelWrapper

protected final TecDefaultRowSorter.ModelWrapper<M,I> getModelWrapper()

Returns the model wrapper providing the data that is being sorted and filtered.

Returns:

the model wrapper responsible for providing the data that gets sorted and filtered

getModel

public final M getModel()

Returns the underlying model.

Specified by:

getModel in class RowSorter<M>

Returns:

the underlying model

setSortable

public void setSortable(int column,
               boolean sortable)

Sets whether or not the specified column is sortable. The specified value is only checked when toggleSortOrder is invoked. It is still possible to sort on a column that has been marked as unsortable by directly setting the sort keys. The default is true.

Parameters:

column - the column to enable or disable sorting on, in terms of the underlying model

sortable - whether or not the specified column is sortable

Throws:

IndexOutOfBoundsException - if column is outside the range of the model

See Also:

toggleSortOrder(int), setSortKeys(java.util.List<? extends javax.swing.RowSorter.SortKey>)

isSortable

public boolean isSortable(int column)

Returns true if the specified column is sortable; otherwise, false.

Parameters:

column - the column to check sorting for, in terms of the underlying model

Returns:

true if the column is sortable

Throws:

IndexOutOfBoundsException - if column is outside the range of the underlying model

setSortKeys

public void setSortKeys(List<? extends RowSorter.SortKey> sortKeys)

Sets the sort keys. This creates a copy of the supplied List; subsequent changes to the supplied List do not effect this DefaultRowSorter. If the sort keys have changed this triggers a sort.

Specified by:

setSortKeys in class RowSorter<M>

Parameters:

sortKeys - the new SortKeys; null is a shorthand for specifying an empty list, indicating that the view should be unsorted

Throws:

IllegalArgumentException - if any of the values in sortKeys are null or have a column index outside the range of the model

getSortKeys

public List<? extends RowSorter.SortKey> getSortKeys()

Returns the current sort keys. This returns an unmodifiable non-null List. If you need to change the sort keys, make a copy of the returned List, mutate the copy and invoke setSortKeys with the new list.

Specified by:

getSortKeys in class RowSorter<M>

Returns:

the current sort order

setMaxSortKeys

public void setMaxSortKeys(int max)

Sets the maximum number of sort keys. The number of sort keys determines how equal values are resolved when sorting. For example, assume a table row sorter is created and setMaxSortKeys(2) is invoked on it. The user clicks the header for column 1, causing the table rows to be sorted based on the items in column 1. Next, the user clicks the header for column 2, causing the table to be sorted based on the items in column 2; if any items in column 2 are equal, then those particular rows are ordered based on the items in column 1. In this case, we say that the rows are primarily sorted on column 2, and secondarily on column 1. If the user then clicks the header for column 3, then the items are primarily sorted on column 3 and secondarily sorted on column 2. Because the maximum number of sort keys has been set to 2 with setMaxSortKeys, column 1 no longer has an effect on the order.

The maximum number of sort keys is enforced by toggleSortOrder. You can specify more sort keys by invoking setSortKeys directly and they will all be honored. However if toggleSortOrder is subsequently invoked the maximum number of sort keys will be enforced. The default value is 3.

Parameters:

max - the maximum number of sort keys

Throws:

IllegalArgumentException - if max < 1

getMaxSortKeys

public int getMaxSortKeys()

Returns the maximum number of sort keys.

Returns:

the maximum number of sort keys

setSortsOnUpdates

public void setSortsOnUpdates(boolean sortsOnUpdates)

If true, specifies that a sort should happen when the underlying model is updated (rowsUpdated is invoked). For example, if this is true and the user edits an entry the location of that item in the view may change. The default is false.

Parameters:

sortsOnUpdates - whether or not to sort on update events

getSortsOnUpdates

public boolean getSortsOnUpdates()

Returns true if a sort should happen when the underlying model is updated; otherwise, returns false.

Returns:

whether or not to sort when the model is updated

setRowFilter

public void setRowFilter(RowFilter<? super M,? super I> filter)

Sets the filter that determines which rows, if any, should be hidden from the view. The filter is applied before sorting. A value of null indicates all values from the model should be included.

RowFilter's include method is passed an Entry that wraps the underlying model. The number of columns in the Entry corresponds to the number of columns in the ModelWrapper. The identifier comes from the ModelWrapper as well.

This method triggers a sort.

Parameters:

filter - the filter used to determine what entries should be included

getRowFilter

public RowFilter<? super M,? super I> getRowFilter()

Returns the filter that determines which rows, if any, should be hidden from view.

Returns:

the filter

toggleSortOrder

public void toggleSortOrder(int column)

Reverses the sort order from ascending to descending (or descending to ascending) if the specified column is already the primary sorted column; otherwise, makes the specified column the primary sorted column, with an ascending sort order. If the specified column is not sortable, this method has no effect.

Specified by:

toggleSortOrder in class RowSorter<M>

Parameters:

column - index of the column to make the primary sorted column, in terms of the underlying model

Throws:

IndexOutOfBoundsException

See Also:

setSortable(int,boolean), setMaxSortKeys(int)

convertRowIndexToView

public int convertRowIndexToView(int index)

Specified by:

convertRowIndexToView in class RowSorter<M>

Throws:

IndexOutOfBoundsException

convertRowIndexToModel

public int convertRowIndexToModel(int index)

Specified by:

convertRowIndexToModel in class RowSorter<M>

Throws:

IndexOutOfBoundsException

sort

public void sort()

Sorts and filters the rows in the view based on the sort keys of the columns currently being sorted and the filter, if any, associated with this sorter. An empty sortKeys list indicates that the view should unsorted, the same as the model.

See Also:

setRowFilter(javax.swing.RowFilter<? super M, ? super I>), setSortKeys(java.util.List<? extends javax.swing.RowSorter.SortKey>)

useToString

protected boolean useToString(int column)

Returns whether or not to convert the value to a string before doing comparisons when sorting. If true ModelWrapper.getStringValueAt will be used, otherwise ModelWrapper.getValueAt will be used. It is up to subclasses, such as TableRowSorter, to honor this value in their ModelWrapper implementation.

Parameters:

column - the index of the column to test, in terms of the underlying model

Throws:

IndexOutOfBoundsException - if column is not valid

setComparator

public void setComparator(int column,
                 Comparator<?> comparator)

Sets the Comparator to use when sorting the specified column. This does not trigger a sort. If you want to sort after setting the comparator you need to explicitly invoke sort.

Parameters:

column - the index of the column the Comparator is to be used for, in terms of the underlying model

comparator - the Comparator to use

Throws:

IndexOutOfBoundsException - if column is outside the range of the underlying model

getComparator

public Comparator<?> getComparator(int column)

Returns the Comparator for the specified column. This will return null if a Comparator has not been specified for the column.

Parameters:

column - the column to fetch the Comparator for, in terms of the underlying model

Returns:

the Comparator for the specified column

Throws:

IndexOutOfBoundsException - if column is outside the range of the underlying model

getViewRowCount

public int getViewRowCount()

Specified by:

getViewRowCount in class RowSorter<M>

getModelRowCount

public int getModelRowCount()

Specified by:

getModelRowCount in class RowSorter<M>

modelStructureChanged

public void modelStructureChanged()

Specified by:

modelStructureChanged in class RowSorter<M>

allRowsChanged

public void allRowsChanged()

Specified by:

allRowsChanged in class RowSorter<M>

rowsInserted

public void rowsInserted(int firstRow,
                int endRow)

Specified by:

rowsInserted in class RowSorter<M>

Throws:

IndexOutOfBoundsException

rowsDeleted

public void rowsDeleted(int firstRow,
               int endRow)

Specified by:

rowsDeleted in class RowSorter<M>

Throws:

IndexOutOfBoundsException

rowsUpdated

public void rowsUpdated(int firstRow,
               int endRow)

Specified by:

rowsUpdated in class RowSorter<M>

Throws:

IndexOutOfBoundsException

rowsUpdated

public void rowsUpdated(int firstRow,
               int endRow,
               int column)

Specified by:

rowsUpdated in class RowSorter<M>

Throws:

IndexOutOfBoundsException

setNullComparison

public void setNullComparison(boolean enable)

getNoSortEnabled

public boolean getNoSortEnabled()

Indica se o estado "não-ordenado" está ou não habilitado.

Returns:

true se o estado "não-ordenado" for permitido, false caso contrário.

setNoSortEnabled

public void setNoSortEnabled(boolean enable)

Habilita / desabilita o estado "não-ordenado" da tabela.

Parameters:

enable - se true, habilita; false caso contrário.