< prev index next >
src/java.desktop/share/classes/javax/swing/RowSorter.java
Print this page
*** 27,104 ****
import javax.swing.SortOrder;
import javax.swing.event.*;
import java.util.*;
/**
! * <code>RowSorter</code> provides the basis for sorting and filtering.
! * Beyond creating and installing a <code>RowSorter</code>, you very rarely
* need to interact with one directly. Refer to
* {@link javax.swing.table.TableRowSorter TableRowSorter} for a concrete
! * implementation of <code>RowSorter</code> for <code>JTable</code>.
* <p>
! * <code>RowSorter</code>'s primary role is to provide a mapping between
* two coordinate systems: that of the view (for example a
! * <code>JTable</code>) and that of the underlying data source, typically a
* model.
* <p>
! * The view invokes the following methods on the <code>RowSorter</code>:
* <ul>
! * <li><code>toggleSortOrder</code> — The view invokes this when the
* appropriate user gesture has occurred to trigger a sort. For example,
* the user clicked a column header in a table.
* <li>One of the model change methods — The view invokes a model
* change method when the underlying model
* has changed. There may be order dependencies in how the events are
! * delivered, so a <code>RowSorter</code> should not update its mapping
* until one of these methods is invoked.
* </ul>
* Because the view makes extensive use of the
! * <code>convertRowIndexToModel</code>,
! * <code>convertRowIndexToView</code> and <code>getViewRowCount</code> methods,
* these methods need to be fast.
* <p>
! * <code>RowSorter</code> provides notification of changes by way of
! * <code>RowSorterListener</code>. Two types of notification are sent:
* <ul>
! * <li><code>RowSorterEvent.Type.SORT_ORDER_CHANGED</code> — notifies
* listeners that the sort order has changed. This is typically followed
* by a notification that the sort has changed.
! * <li><code>RowSorterEvent.Type.SORTED</code> — notifies listeners that
! * the mapping maintained by the <code>RowSorter</code> has changed in
* some way.
* </ul>
! * <code>RowSorter</code> implementations typically don't have a one-to-one
* mapping with the underlying model, but they can.
* For example, if a database does the sorting,
! * <code>toggleSortOrder</code> might call through to the database
* (on a background thread), and override the mapping methods to return the
* argument that is passed in.
* <p>
! * Concrete implementations of <code>RowSorter</code>
! * need to reference a model such as <code>TableModel</code> or
! * <code>ListModel</code>. The view classes, such as
! * <code>JTable</code> and <code>JList</code>, will also have a
* reference to the model. To avoid ordering dependencies,
! * <code>RowSorter</code> implementations should not install a
* listener on the model. Instead the view class will call into the
! * <code>RowSorter</code> when the model changes. For
! * example, if a row is updated in a <code>TableModel</code>
! * <code>JTable</code> invokes <code>rowsUpdated</code>.
* When the model changes, the view may call into any of the following methods:
! * <code>modelStructureChanged</code>, <code>allRowsChanged</code>,
! * <code>rowsInserted</code>, <code>rowsDeleted</code> and
! * <code>rowsUpdated</code>.
*
* @param <M> the type of the underlying model
* @see javax.swing.table.TableRowSorter
* @since 1.6
*/
public abstract class RowSorter<M> {
private EventListenerList listenerList = new EventListenerList();
/**
! * Creates a <code>RowSorter</code>.
*/
public RowSorter() {
}
/**
--- 27,104 ----
import javax.swing.SortOrder;
import javax.swing.event.*;
import java.util.*;
/**
! * {@code RowSorter} provides the basis for sorting and filtering.
! * Beyond creating and installing a {@code RowSorter}, you very rarely
* need to interact with one directly. Refer to
* {@link javax.swing.table.TableRowSorter TableRowSorter} for a concrete
! * implementation of {@code RowSorter} for {@code JTable}.
* <p>
! * {@code RowSorter}'s primary role is to provide a mapping between
* two coordinate systems: that of the view (for example a
! * {@code JTable}) and that of the underlying data source, typically a
* model.
* <p>
! * The view invokes the following methods on the {@code RowSorter}:
* <ul>
! * <li>{@code toggleSortOrder} — The view invokes this when the
* appropriate user gesture has occurred to trigger a sort. For example,
* the user clicked a column header in a table.
* <li>One of the model change methods — The view invokes a model
* change method when the underlying model
* has changed. There may be order dependencies in how the events are
! * delivered, so a {@code RowSorter} should not update its mapping
* until one of these methods is invoked.
* </ul>
* Because the view makes extensive use of the
! * {@code convertRowIndexToModel},
! * {@code convertRowIndexToView} and {@code getViewRowCount} methods,
* these methods need to be fast.
* <p>
! * {@code RowSorter} provides notification of changes by way of
! * {@code RowSorterListener}. Two types of notification are sent:
* <ul>
! * <li>{@code RowSorterEvent.Type.SORT_ORDER_CHANGED} — notifies
* listeners that the sort order has changed. This is typically followed
* by a notification that the sort has changed.
! * <li>{@code RowSorterEvent.Type.SORTED} — notifies listeners that
! * the mapping maintained by the {@code RowSorter} has changed in
* some way.
* </ul>
! * {@code RowSorter} implementations typically don't have a one-to-one
* mapping with the underlying model, but they can.
* For example, if a database does the sorting,
! * {@code toggleSortOrder} might call through to the database
* (on a background thread), and override the mapping methods to return the
* argument that is passed in.
* <p>
! * Concrete implementations of {@code RowSorter}
! * need to reference a model such as {@code TableModel} or
! * {@code ListModel}. The view classes, such as
! * {@code JTable} and {@code JList}, will also have a
* reference to the model. To avoid ordering dependencies,
! * {@code RowSorter} implementations should not install a
* listener on the model. Instead the view class will call into the
! * {@code RowSorter} when the model changes. For
! * example, if a row is updated in a {@code TableModel}
! * {@code JTable} invokes {@code rowsUpdated}.
* When the model changes, the view may call into any of the following methods:
! * {@code modelStructureChanged}, {@code allRowsChanged},
! * {@code rowsInserted}, {@code rowsDeleted} and
! * {@code rowsUpdated}.
*
* @param <M> the type of the underlying model
* @see javax.swing.table.TableRowSorter
* @since 1.6
*/
public abstract class RowSorter<M> {
private EventListenerList listenerList = new EventListenerList();
/**
! * Creates a {@code RowSorter}.
*/
public RowSorter() {
}
/**
*** 117,167 ****
* the primary sorted column, with an ascending sort order. If
* the specified column is not sortable, this method has no
* effect.
* <p>
* If this results in changing the sort order and sorting, the
! * appropriate <code>RowSorterListener</code> notification will be
* sent.
*
* @param column the column to toggle the sort ordering of, in
* terms of the underlying model
* @throws IndexOutOfBoundsException if column is outside the range of
* the underlying model
*/
public abstract void toggleSortOrder(int column);
/**
! * Returns the location of <code>index</code> in terms of the
! * underlying model. That is, for the row <code>index</code> in
* the coordinates of the view this returns the row index in terms
* of the underlying model.
*
* @param index the row index in terms of the underlying view
* @return row index in terms of the view
! * @throws IndexOutOfBoundsException if <code>index</code> is outside the
* range of the view
*/
public abstract int convertRowIndexToModel(int index);
/**
! * Returns the location of <code>index</code> in terms of the
! * view. That is, for the row <code>index</code> in the
* coordinates of the underlying model this returns the row index
* in terms of the view.
*
* @param index the row index in terms of the underlying model
* @return row index in terms of the view, or -1 if index has been
* filtered out of the view
! * @throws IndexOutOfBoundsException if <code>index</code> is outside
* the range of the model
*/
public abstract int convertRowIndexToView(int index);
/**
* Sets the current sort keys.
*
! * @param keys the new <code>SortKeys</code>; <code>null</code>
* is a shorthand for specifying an empty list,
* indicating that the view should be unsorted
*/
public abstract void setSortKeys(List<? extends SortKey> keys);
--- 117,167 ----
* the primary sorted column, with an ascending sort order. If
* the specified column is not sortable, this method has no
* effect.
* <p>
* If this results in changing the sort order and sorting, the
! * appropriate {@code RowSorterListener} notification will be
* sent.
*
* @param column the column to toggle the sort ordering of, in
* terms of the underlying model
* @throws IndexOutOfBoundsException if column is outside the range of
* the underlying model
*/
public abstract void toggleSortOrder(int column);
/**
! * Returns the location of {@code index} in terms of the
! * underlying model. That is, for the row {@code index} in
* the coordinates of the view this returns the row index in terms
* of the underlying model.
*
* @param index the row index in terms of the underlying view
* @return row index in terms of the view
! * @throws IndexOutOfBoundsException if {@code index} is outside the
* range of the view
*/
public abstract int convertRowIndexToModel(int index);
/**
! * Returns the location of {@code index} in terms of the
! * view. That is, for the row {@code index} in the
* coordinates of the underlying model this returns the row index
* in terms of the view.
*
* @param index the row index in terms of the underlying model
* @return row index in terms of the view, or -1 if index has been
* filtered out of the view
! * @throws IndexOutOfBoundsException if {@code index} is outside
* the range of the model
*/
public abstract int convertRowIndexToView(int index);
/**
* Sets the current sort keys.
*
! * @param keys the new {@code SortKeys}; {@code null}
* is a shorthand for specifying an empty list,
* indicating that the view should be unsorted
*/
public abstract void setSortKeys(List<? extends SortKey> keys);
*** 195,205 ****
public abstract int getModelRowCount();
/**
* Invoked when the underlying model structure has completely
* changed. For example, if the number of columns in a
! * <code>TableModel</code> changed, this method would be invoked.
* <p>
* You normally do not call this method. This method is public
* to allow view classes to call it.
*/
public abstract void modelStructureChanged();
--- 195,205 ----
public abstract int getModelRowCount();
/**
* Invoked when the underlying model structure has completely
* changed. For example, if the number of columns in a
! * {@code TableModel} changed, this method would be invoked.
* <p>
* You normally do not call this method. This method is public
* to allow view classes to call it.
*/
public abstract void modelStructureChanged();
*** 232,242 ****
* to allow view classes to call it.
*
* @param firstRow the first row
* @param endRow the last row
* @throws IndexOutOfBoundsException if either argument is invalid, or
! * <code>firstRow</code> > <code>endRow</code>
*/
public abstract void rowsInserted(int firstRow, int endRow);
/**
* Invoked when rows have been deleted from the underlying model
--- 232,242 ----
* to allow view classes to call it.
*
* @param firstRow the first row
* @param endRow the last row
* @throws IndexOutOfBoundsException if either argument is invalid, or
! * {@code firstRow > endRow}
*/
public abstract void rowsInserted(int firstRow, int endRow);
/**
* Invoked when rows have been deleted from the underlying model
*** 252,262 ****
*
* @param firstRow the first row
* @param endRow the last row
* @throws IndexOutOfBoundsException if either argument is outside
* the range of the model before the change, or
! * <code>firstRow</code> > <code>endRow</code>
*/
public abstract void rowsDeleted(int firstRow, int endRow);
/**
* Invoked when rows have been changed in the underlying model
--- 252,262 ----
*
* @param firstRow the first row
* @param endRow the last row
* @throws IndexOutOfBoundsException if either argument is outside
* the range of the model before the change, or
! * {@code firstRow > endRow}
*/
public abstract void rowsDeleted(int firstRow, int endRow);
/**
* Invoked when rows have been changed in the underlying model
*** 267,277 ****
*
* @param firstRow the first row, in terms of the underlying model
* @param endRow the last row, in terms of the underlying model
* @throws IndexOutOfBoundsException if either argument is outside
* the range of the underlying model, or
! * <code>firstRow</code> > <code>endRow</code>
*/
public abstract void rowsUpdated(int firstRow, int endRow);
/**
* Invoked when the column in the rows have been updated in
--- 267,277 ----
*
* @param firstRow the first row, in terms of the underlying model
* @param endRow the last row, in terms of the underlying model
* @throws IndexOutOfBoundsException if either argument is outside
* the range of the underlying model, or
! * {@code firstRow > endRow}
*/
public abstract void rowsUpdated(int firstRow, int endRow);
/**
* Invoked when the column in the rows have been updated in
*** 284,317 ****
* @param endRow the last row, in terms of the underlying model
* @param column the column that has changed, in terms of the underlying
* model
* @throws IndexOutOfBoundsException if either argument is outside
* the range of the underlying model after the change,
! * <code>firstRow</code> > <code>endRow</code>, or
! * <code>column</code> is outside the range of the underlying
* model
*/
public abstract void rowsUpdated(int firstRow, int endRow, int column);
/**
! * Adds a <code>RowSorterListener</code> to receive notification
! * about this <code>RowSorter</code>. If the same
* listener is added more than once it will receive multiple
! * notifications. If <code>l</code> is <code>null</code> nothing
* is done.
*
! * @param l the <code>RowSorterListener</code>
*/
public void addRowSorterListener(RowSorterListener l) {
listenerList.add(RowSorterListener.class, l);
}
/**
! * Removes a <code>RowSorterListener</code>. If
! * <code>l</code> is <code>null</code> nothing is done.
*
! * @param l the <code>RowSorterListener</code>
*/
public void removeRowSorterListener(RowSorterListener l) {
listenerList.remove(RowSorterListener.class, l);
}
--- 284,317 ----
* @param endRow the last row, in terms of the underlying model
* @param column the column that has changed, in terms of the underlying
* model
* @throws IndexOutOfBoundsException if either argument is outside
* the range of the underlying model after the change,
! * {@code firstRow > endRow}, or
! * {@code column} is outside the range of the underlying
* model
*/
public abstract void rowsUpdated(int firstRow, int endRow, int column);
/**
! * Adds a {@code RowSorterListener} to receive notification
! * about this {@code RowSorter}. If the same
* listener is added more than once it will receive multiple
! * notifications. If {@code l} is {@code null} nothing
* is done.
*
! * @param l the {@code RowSorterListener}
*/
public void addRowSorterListener(RowSorterListener l) {
listenerList.add(RowSorterListener.class, l);
}
/**
! * Removes a {@code RowSorterListener}. If
! * {@code l} is {@code null} nothing is done.
*
! * @param l the {@code RowSorterListener}
*/
public void removeRowSorterListener(RowSorterListener l) {
listenerList.remove(RowSorterListener.class, l);
}
*** 324,334 ****
/**
* Notifies listener that the mapping has changed.
*
* @param lastRowIndexToModel the mapping from model indices to
! * view indices prior to the sort, may be <code>null</code>
*/
protected void fireRowSorterChanged(int[] lastRowIndexToModel) {
fireRowSorterChanged(new RowSorterEvent(this,
RowSorterEvent.Type.SORTED, lastRowIndexToModel));
}
--- 324,334 ----
/**
* Notifies listener that the mapping has changed.
*
* @param lastRowIndexToModel the mapping from model indices to
! * view indices prior to the sort, may be {@code null}
*/
protected void fireRowSorterChanged(int[] lastRowIndexToModel) {
fireRowSorterChanged(new RowSorterEvent(this,
RowSorterEvent.Type.SORTED, lastRowIndexToModel));
}
*** 353,369 ****
public static class SortKey {
private int column;
private SortOrder sortOrder;
/**
! * Creates a <code>SortKey</code> for the specified column with
* the specified sort order.
*
* @param column index of the column, in terms of the model
* @param sortOrder the sorter order
! * @throws IllegalArgumentException if <code>sortOrder</code> is
! * <code>null</code>
*/
public SortKey(int column, SortOrder sortOrder) {
if (sortOrder == null) {
throw new IllegalArgumentException(
"sort order must be non-null");
--- 353,369 ----
public static class SortKey {
private int column;
private SortOrder sortOrder;
/**
! * Creates a {@code SortKey} for the specified column with
* the specified sort order.
*
* @param column index of the column, in terms of the model
* @param sortOrder the sorter order
! * @throws IllegalArgumentException if {@code sortOrder} is
! * {@code null}
*/
public SortKey(int column, SortOrder sortOrder) {
if (sortOrder == null) {
throw new IllegalArgumentException(
"sort order must be non-null");
*** 389,399 ****
public final SortOrder getSortOrder() {
return sortOrder;
}
/**
! * Returns the hash code for this <code>SortKey</code>.
*
* @return hash code
*/
public int hashCode() {
int result = 17;
--- 389,399 ----
public final SortOrder getSortOrder() {
return sortOrder;
}
/**
! * Returns the hash code for this {@code SortKey}.
*
* @return hash code
*/
public int hashCode() {
int result = 17;
*** 402,417 ****
return result;
}
/**
* Returns true if this object equals the specified object.
! * If the specified object is a <code>SortKey</code> and
* references the same column and sort order, the two objects
* are equal.
*
* @param o the object to compare to
! * @return true if <code>o</code> is equal to this <code>SortKey</code>
*/
public boolean equals(Object o) {
if (o == this) {
return true;
}
--- 402,417 ----
return result;
}
/**
* Returns true if this object equals the specified object.
! * If the specified object is a {@code SortKey} and
* references the same column and sort order, the two objects
* are equal.
*
* @param o the object to compare to
! * @return true if {@code o} is equal to this {@code SortKey}
*/
public boolean equals(Object o) {
if (o == this) {
return true;
}
< prev index next >