< 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> &gt; <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> &gt; <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> &gt; <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> &gt; <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 >