diff options
Diffstat (limited to 'javax/swing/table/DefaultTableColumnModel.java')
| -rw-r--r-- | javax/swing/table/DefaultTableColumnModel.java | 346 |
1 files changed, 226 insertions, 120 deletions
diff --git a/javax/swing/table/DefaultTableColumnModel.java b/javax/swing/table/DefaultTableColumnModel.java index cd04a6979..6ed6331c2 100644 --- a/javax/swing/table/DefaultTableColumnModel.java +++ b/javax/swing/table/DefaultTableColumnModel.java @@ -1,5 +1,5 @@ /* DefaultTableColumnModel.java -- - Copyright (C) 2002, 2004, 2005 Free Software Foundation, Inc. + Copyright (C) 2002, 2004, 2005, 2006, Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -46,6 +46,7 @@ import java.util.EventListener; import java.util.Vector; import javax.swing.DefaultListSelectionModel; +import javax.swing.JTable; import javax.swing.ListSelectionModel; import javax.swing.event.ChangeEvent; import javax.swing.event.EventListenerList; @@ -55,9 +56,11 @@ import javax.swing.event.TableColumnModelEvent; import javax.swing.event.TableColumnModelListener; /** - * DefaultTableColumnModel + * A model that stores information about the columns used in a {@link JTable}. + * + * @see JTable#setColumnModel(TableColumnModel) + * * @author Andrew Selkirk - * @version 1.0 */ public class DefaultTableColumnModel implements TableColumnModel, PropertyChangeListener, ListSelectionListener, @@ -66,88 +69,116 @@ public class DefaultTableColumnModel private static final long serialVersionUID = 6580012493508960512L; /** - * Columns that this model keeps track of. + * Storage for the table columns. */ protected Vector<TableColumn> tableColumns; /** - * Selection Model that keeps track of columns selection + * A selection model that keeps track of column selections. */ protected ListSelectionModel selectionModel; /** - * Space between two columns. By default it is set to 1 + * The space between the columns (the default value is <code>1</code>). */ protected int columnMargin; /** - * listenerList keeps track of all listeners registered with this model + * Storage for the listeners registered with the model. */ protected EventListenerList listenerList = new EventListenerList(); /** - * changeEvent is fired when change occurs in one of the columns properties + * A change event used when notifying listeners of a change to the + * <code>columnMargin</code> field. This single event is reused for all + * notifications. */ + // FIXME: use lazy instantiation protected transient ChangeEvent changeEvent = new ChangeEvent(this); /** - * Indicates whether columns can be selected + * A flag that indicates whether or not columns can be selected. */ protected boolean columnSelectionAllowed; /** - * Total width of all the columns in this model + * The total width of all the columns in this model. */ protected int totalColumnWidth; /** - * Constructor DefaultTableColumnModel + * Creates a new table column model with zero columns. A default column + * selection model is created by calling {@link #createSelectionModel()}. + * The default value for <code>columnMargin</code> is <code>1</code> and + * the default value for <code>columnSelectionAllowed</code> is + * <code>false</code>. */ public DefaultTableColumnModel() { tableColumns = new Vector(); - setSelectionModel(createSelectionModel()); + selectionModel = createSelectionModel(); + selectionModel.addListSelectionListener(this); columnMargin = 1; columnSelectionAllowed = false; } /** - * addColumn adds column to the model. This method fires ColumnAdded - * event to model's registered TableColumnModelListeners. + * Adds a column to the model then calls + * {@link #fireColumnAdded(TableColumnModelEvent)} to notify the registered + * listeners. The model registers itself with the column as a + * {@link PropertyChangeListener} so that changes to the column width will + * invalidate the cached {@link #totalColumnWidth} value. * - * @param col column to add + * @param column the column (<code>null</code> not permitted). + * + * @throws IllegalArgumentException if <code>column</code> is + * <code>null</code>. + * + * @see #removeColumn(TableColumn) */ - public void addColumn(TableColumn col) + public void addColumn(TableColumn column) { - if (col == null) + if (column == null) throw new IllegalArgumentException("Null 'col' argument."); - tableColumns.add(col); + tableColumns.add(column); + column.addPropertyChangeListener(this); invalidateWidthCache(); - fireColumnAdded(new TableColumnModelEvent(this, 0, tableColumns.size() - 1)); + fireColumnAdded(new TableColumnModelEvent(this, 0, + tableColumns.size() - 1)); } /** - * removeColumn removes table column from the model. This method fires - * ColumnRemoved event to model's registered TableColumnModelListeners. + * Removes a column from the model then calls + * {@link #fireColumnRemoved(TableColumnModelEvent)} to notify the registered + * listeners. If the specified column does not belong to the model, or is + * <code>null</code>, this method does nothing. * - * @param col column to be removed + * @param column the column to be removed (<code>null</code> permitted). + * + * @see #addColumn(TableColumn) */ - public void removeColumn(TableColumn col) + public void removeColumn(TableColumn column) { - int index = this.tableColumns.indexOf(col); + int index = this.tableColumns.indexOf(column); if (index < 0) return; + tableColumns.remove(column); fireColumnRemoved(new TableColumnModelEvent(this, index, 0)); - tableColumns.remove(col); + column.removePropertyChangeListener(this); invalidateWidthCache(); } /** - * moveColumn moves column at index i to index j. This method fires - * ColumnMoved event to model's registered TableColumnModelListeners. + * Moves the column at index i to the position specified by index j, then + * calls {@link #fireColumnMoved(TableColumnModelEvent)} to notify registered + * listeners. * - * @param i index of the column that will be moved - * @param j index of column's new location + * @param i index of the column that will be moved. + * @param j index of the column's new location. + * + * @throws IllegalArgumentException if <code>i</code> or <code>j</code> are + * outside the range <code>0</code> to <code>N-1</code>, where + * <code>N</code> is the column count. */ public void moveColumn(int i, int j) { @@ -158,22 +189,27 @@ public class DefaultTableColumnModel throw new IllegalArgumentException("Index 'j' out of range."); TableColumn column = tableColumns.remove(i); tableColumns.add(j, column); - fireColumnAdded(new TableColumnModelEvent(this, i, j)); + fireColumnMoved(new TableColumnModelEvent(this, i, j)); } /** - * setColumnMargin sets margin of the columns. - * @param m new column margin + * Sets the column margin then calls {@link #fireColumnMarginChanged()} to + * notify the registered listeners. + * + * @param margin the column margin. + * + * @see #getColumnMargin() */ - public void setColumnMargin(int m) + public void setColumnMargin(int margin) { - columnMargin = m; + columnMargin = margin; fireColumnMarginChanged(); } /** - * getColumnCount returns number of columns in the model - * @return int number of columns in the model + * Returns the number of columns in the model. + * + * @return The column count. */ public int getColumnCount() { @@ -181,8 +217,9 @@ public class DefaultTableColumnModel } /** - * getColumns - * @return Enumeration + * Returns an enumeration of the columns in the model. + * + * @return An enumeration of the columns in the model. */ public Enumeration<TableColumn> getColumns() { @@ -214,18 +251,28 @@ public class DefaultTableColumnModel } /** - * getColumn returns column at the specified index - * @param i index of the column - * @return TableColumn column at the specified index + * Returns the column at the specified index. + * + * @param columnIndex the column index (in the range from <code>0</code> to + * <code>N-1</code>, where <code>N</code> is the number of columns in + * the model). + * + * @return The column at the specified index. + * + * @throws ArrayIndexOutOfBoundsException if <code>i</code> is not within + * the specified range. */ - public TableColumn getColumn(int i) + public TableColumn getColumn(int columnIndex) { - return (TableColumn) tableColumns.get(i); + return (TableColumn) tableColumns.get(columnIndex); } /** - * getColumnMargin returns column margin - * @return int column margin + * Returns the column margin. + * + * @return The column margin. + * + * @see #setColumnMargin(int) */ public int getColumnMargin() { @@ -233,16 +280,26 @@ public class DefaultTableColumnModel } /** - * getColumnIndexAtX returns column that contains specified x-coordinate. - * @param x x-coordinate that column should contain - * @return int index of the column that contains specified x-coordinate relative - * to this column model + * Returns the index of the column that contains the specified x-coordinate. + * This method assumes that: + * <ul> + * <li>column zero begins at position zero;</li> + * <li>all columns appear in order;</li> + * <li>individual column widths are taken into account, but the column margin + * is ignored.</li> + * </ul> + * If no column contains the specified position, this method returns + * <code>-1</code>. + * + * @param x the x-position. + * + * @return The column index, or <code>-1</code>. */ public int getColumnIndexAtX(int x) { for (int i = 0; i < tableColumns.size(); ++i) { - int w = ((TableColumn)tableColumns.get(i)).getWidth(); + int w = ((TableColumn) tableColumns.get(i)).getWidth(); if (0 <= x && x < w) return i; else @@ -252,10 +309,10 @@ public class DefaultTableColumnModel } /** - * getTotalColumnWidth returns total width of all the columns including - * column's margins. + * Returns total width of all the columns in the model, ignoring the + * {@link #columnMargin}. * - * @return total width of all the columns + * @return The total width of all the columns. */ public int getTotalColumnWidth() { @@ -265,24 +322,32 @@ public class DefaultTableColumnModel } /** - * setSelectionModel sets selection model that will be used by this ColumnTableModel - * to keep track of currently selected columns + * Sets the selection model that will be used to keep track of the selected + * columns. * - * @param model new selection model - * @exception IllegalArgumentException if model is null + * @param model the selection model (<code>null</code> not permitted). + * + * @throws IllegalArgumentException if <code>model</code> is + * <code>null</code>. + * + * @see #getSelectionModel() */ public void setSelectionModel(ListSelectionModel model) { if (model == null) throw new IllegalArgumentException(); + selectionModel.removeListSelectionListener(this); selectionModel = model; selectionModel.addListSelectionListener(this); } /** - * getSelectionModel returns selection model - * @return ListSelectionModel selection model + * Returns the selection model used to track table column selections. + * + * @return The selection model. + * + * @see #setSelectionModel(ListSelectionModel) */ public ListSelectionModel getSelectionModel() { @@ -290,10 +355,11 @@ public class DefaultTableColumnModel } /** - * setColumnSelectionAllowed sets whether column selection is allowed - * or not. + * Sets the flag that indicates whether or not column selection is allowed. * - * @param flag true if column selection is allowed and false otherwise + * @param flag the new flag value. + * + * @see #getColumnSelectionAllowed() */ public void setColumnSelectionAllowed(boolean flag) { @@ -301,10 +367,12 @@ public class DefaultTableColumnModel } /** - * getColumnSelectionAllowed indicates whether column selection is - * allowed or not. + * Returns <code>true</code> if column selection is allowed, and + * <code>false</code> if column selection is not allowed. * - * @return boolean true if column selection is allowed and false otherwise. + * @return A boolean. + * + * @see #setColumnSelectionAllowed(boolean) */ public boolean getColumnSelectionAllowed() { @@ -312,10 +380,9 @@ public class DefaultTableColumnModel } /** - * getSelectedColumns returns array containing indexes of currently - * selected columns + * Returns an array containing the indices of the selected columns. * - * @return int[] array containing indexes of currently selected columns + * @return An array containing the indices of the selected columns. */ public int[] getSelectedColumns() { @@ -356,8 +423,11 @@ public class DefaultTableColumnModel } /** - * getSelectedColumnCount returns number of currently selected columns - * @return int number of currently selected columns + * Returns the number of selected columns in the model. + * + * @return The selected column count. + * + * @see #getSelectionModel() */ public int getSelectedColumnCount() { @@ -395,10 +465,10 @@ public class DefaultTableColumnModel } /** - * addColumnModelListener adds specified listener to the model's - * listener list + * Registers a listener with the model, so that it will receive + * {@link TableColumnModelEvent} notifications. * - * @param listener the listener to add + * @param listener the listener (<code>null</code> ignored). */ public void addColumnModelListener(TableColumnModelListener listener) { @@ -406,10 +476,10 @@ public class DefaultTableColumnModel } /** - * removeColumnModelListener removes specified listener from the model's - * listener list. + * Deregisters a listener so that it no longer receives notification of + * changes to this model. * - * @param listener the listener to remove + * @param listener the listener to remove */ public void removeColumnModelListener(TableColumnModelListener listener) { @@ -417,6 +487,13 @@ public class DefaultTableColumnModel } /** + * Returns an array containing the listeners that are registered with the + * model. If there are no listeners, an empty array is returned. + * + * @return An array containing the listeners that are registered with the + * model. + * + * @see #addColumnModelListener(TableColumnModelListener) * @since 1.4 */ public TableColumnModelListener[] getColumnModelListeners() @@ -426,78 +503,97 @@ public class DefaultTableColumnModel } /** - * fireColumnAdded fires TableColumnModelEvent to registered - * TableColumnModelListeners to indicate that column was added - * - * @param e TableColumnModelEvent + * Sends the specified {@link TableColumnModelEvent} to all registered + * listeners, to indicate that a column has been added to the model. The + * event's <code>toIndex</code> attribute should contain the index of the + * added column. + * + * @param e the event. + * + * @see #addColumn(TableColumn) */ protected void fireColumnAdded(TableColumnModelEvent e) { TableColumnModelListener[] listeners = getColumnModelListeners(); - for (int i=0; i< listeners.length; i++) + for (int i = 0; i < listeners.length; i++) listeners[i].columnAdded(e); } /** - * fireColumnAdded fires TableColumnModelEvent to registered - * TableColumnModelListeners to indicate that column was removed - * - * @param e TableColumnModelEvent + * Sends the specified {@link TableColumnModelEvent} to all registered + * listeners, to indicate that a column has been removed from the model. The + * event's <code>fromIndex</code> attribute should contain the index of the + * removed column. + * + * @param e the event. + * + * @see #removeColumn(TableColumn) */ protected void fireColumnRemoved(TableColumnModelEvent e) { TableColumnModelListener[] listeners = getColumnModelListeners(); - for (int i=0; i< listeners.length; i++) + for (int i = 0; i < listeners.length; i++) listeners[i].columnRemoved(e); } /** - * fireColumnAdded fires TableColumnModelEvent to registered - * TableColumnModelListeners to indicate that column was moved - * - * @param e TableColumnModelEvent + * Sends the specified {@link TableColumnModelEvent} to all registered + * listeners, to indicate that a column in the model has been moved. The + * event's <code>fromIndex</code> attribute should contain the old column + * index, and the <code>toIndex</code> attribute should contain the new + * column index. + * + * @param e the event. + * + * @see #moveColumn(int, int) */ protected void fireColumnMoved(TableColumnModelEvent e) { TableColumnModelListener[] listeners = getColumnModelListeners(); - for (int i=0; i< listeners.length; i++) + for (int i = 0; i < listeners.length; i++) listeners[i].columnMoved(e); } /** - * fireColumnSelectionChanged fires TableColumnModelEvent to model's - * registered TableColumnModelListeners to indicate that different column - * was selected. + * Sends the specified {@link ListSelectionEvent} to all registered listeners, + * to indicate that the column selections have changed. * - * @param evt ListSelectionEvent + * @param e the event. + * + * @see #valueChanged(ListSelectionEvent) */ - protected void fireColumnSelectionChanged(ListSelectionEvent evt) + protected void fireColumnSelectionChanged(ListSelectionEvent e) { EventListener [] listeners = getListeners(TableColumnModelListener.class); for (int i = 0; i < listeners.length; ++i) - ((TableColumnModelListener)listeners[i]).columnSelectionChanged(evt); + ((TableColumnModelListener) listeners[i]).columnSelectionChanged(e); } /** - * fireColumnMarginChanged fires TableColumnModelEvent to model's - * registered TableColumnModelListeners to indicate that column margin - * was changed. + * Sends a {@link ChangeEvent} to the model's registered listeners to + * indicate that the column margin was changed. + * + * @see #setColumnMargin(int) */ protected void fireColumnMarginChanged() { EventListener [] listeners = getListeners(TableColumnModelListener.class); for (int i = 0; i < listeners.length; ++i) - ((TableColumnModelListener)listeners[i]).columnMarginChanged(changeEvent); + ((TableColumnModelListener) listeners[i]).columnMarginChanged(changeEvent); } /** - * getListeners returns currently registered listeners with this model. - * @param listenerType type of listeners to return + * Returns an array containing the listeners (of the specified type) that + * are registered with this model. + * + * @param listenerType the listener type (must indicate a subclass of + * {@link EventListener}, <code>null</code> not permitted). * - * @return EventListener[] array of model's listeners of the specified type + * @return An array containing the listeners (of the specified type) that + * are registered with this model. */ public <T extends EventListener> T[] getListeners(Class<T> listenerType) { @@ -505,20 +601,26 @@ public class DefaultTableColumnModel } /** - * propertyChange handles changes occuring in the properties of the - * model's columns. + * Receives notification of property changes for the columns in the model. + * If the <code>width</code> property for any column changes, we invalidate + * the {@link #totalColumnWidth} value here. * - * @param evt PropertyChangeEvent + * @param event the event. */ - public void propertyChange(PropertyChangeEvent evt) + public void propertyChange(PropertyChangeEvent event) { - if (evt.getPropertyName().equals(TableColumn.COLUMN_WIDTH_PROPERTY)) - invalidateWidthCache(); + if (event.getPropertyName().equals("width")) + invalidateWidthCache(); } /** - * valueChanged handles changes in the selectionModel. - * @param e ListSelectionEvent + * Receives notification of the change to the list selection model, and + * responds by calling + * {@link #fireColumnSelectionChanged(ListSelectionEvent)}. + * + * @param e the list selection event. + * + * @see #getSelectionModel() */ public void valueChanged(ListSelectionEvent e) { @@ -526,10 +628,11 @@ public class DefaultTableColumnModel } /** - * createSelectionModel creates selection model that will keep track - * of currently selected column(s) + * Creates a default selection model to track the currently selected + * column(s). This method is called by the constructor and returns a new + * instance of {@link DefaultListSelectionModel}. * - * @return ListSelectionModel selection model of the columns + * @return A new default column selection model. */ protected ListSelectionModel createSelectionModel() { @@ -537,9 +640,10 @@ public class DefaultTableColumnModel } /** - * recalcWidthCache calculates total width of the columns. - * If the current cache of the total width is in invalidated state, - * then width is recalculated. Otherwise nothing is done. + * Recalculates the total width of the columns, if the cached value is + * <code>-1</code>. Otherwise this method does nothing. + * + * @see #getTotalColumnWidth() */ protected void recalcWidthCache() { @@ -548,13 +652,15 @@ public class DefaultTableColumnModel totalColumnWidth = 0; for (int i = 0; i < tableColumns.size(); ++i) { - totalColumnWidth += ((TableColumn)tableColumns.get(i)).getWidth(); + totalColumnWidth += ((TableColumn) tableColumns.get(i)).getWidth(); } } } /** - * invalidateWidthCache + * Sets the {@link #totalColumnWidth} field to <code>-1</code>. + * + * @see #recalcWidthCache() */ private void invalidateWidthCache() { |