diff options
-rw-r--r-- | ChangeLog | 8 | ||||
-rw-r--r-- | javax/swing/event/ChangeEvent.java | 33 | ||||
-rw-r--r-- | javax/swing/event/ChangeListener.java | 32 | ||||
-rw-r--r-- | javax/swing/event/TableColumnModelListener.java | 88 | ||||
-rw-r--r-- | javax/swing/table/DefaultTableColumnModel.java | 222 | ||||
-rw-r--r-- | javax/swing/table/TableColumnModel.java | 95 |
6 files changed, 316 insertions, 162 deletions
@@ -1,3 +1,11 @@ +2006-04-24 David Gilbert <david.gilbert@object-refinery.com> + + * javax/swing/event/ChangeEvent.java: Updated API docs, + * javax/swing/event/ChangeListener.java: Likewise, + * javax/swing/event/TableColumnModelEventListener.java: Likewise, + * javax/swing/table/DefaultTableColumnModel.java: Likewise, + * javax/swing/table/TableColumnModel.java: Likewise. + 2006-04-24 Robert Schuster <robertschuster@fsfe.org> * javax/swing/text/Utilities.java: diff --git a/javax/swing/event/ChangeEvent.java b/javax/swing/event/ChangeEvent.java index f75c15aac..8854282a9 100644 --- a/javax/swing/event/ChangeEvent.java +++ b/javax/swing/event/ChangeEvent.java @@ -1,5 +1,5 @@ /* ChangeEvent.java -- - Copyright (C) 2002 Free Software Foundation, Inc. + Copyright (C) 2002, 2006, Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -37,23 +37,30 @@ exception statement from your version. */ package javax.swing.event; -// Imports import java.util.EventObject; /** - * ChangeEvent + * An event used to signal a state change for an object. + * + * @see ChangeListener + * @see CellEditorListener + * @see TableColumnModelListener + * * @author Andrew Selkirk * @author Ronald Veldema */ -public class ChangeEvent extends EventObject { +public class ChangeEvent + extends EventObject +{ - /** - * ChangeEvent constructor - * @param source Source object - */ - public ChangeEvent(Object source) { - super(source); - } // ChangeEvent() + /** + * Creates a new <code>ChangeEvent</code> instance for the specified source. + * + * @param source the source for the event (<code>null</code> not permitted). + */ + public ChangeEvent(Object source) + { + super(source); + } - -} // ChangeEvent +} diff --git a/javax/swing/event/ChangeListener.java b/javax/swing/event/ChangeListener.java index 1e58b1d82..75809707b 100644 --- a/javax/swing/event/ChangeListener.java +++ b/javax/swing/event/ChangeListener.java @@ -1,5 +1,5 @@ /* ChangeListener.java -- - Copyright (C) 2002 Free Software Foundation, Inc. + Copyright (C) 2002, 2006, Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -37,21 +37,27 @@ exception statement from your version. */ package javax.swing.event; -// Imports import java.util.EventListener; /** - * ChangeListener interface + * A <code>ChangeListener</code> can register with an object to receive + * notification of state changes (for objects that support this mechanism). + * * @author Andrew Selkirk * @author Ronald Veldema */ -public interface ChangeListener extends EventListener { - - /** - * State changed - * @param event Change Event - */ - void stateChanged(ChangeEvent event); - - -} // ChangeListener +public interface ChangeListener + extends EventListener +{ + + /** + * Called by an object to notify the listener that the object's state has + * changed. The incoming <code>event</code> identifies the + * <code>source</code> of the event, allowing the listener to differentiate + * when it is listening for changes in multiple sources. + * + * @param event the change event. + */ + void stateChanged(ChangeEvent event); + +} diff --git a/javax/swing/event/TableColumnModelListener.java b/javax/swing/event/TableColumnModelListener.java index 90e1b29cc..522e0a8c6 100644 --- a/javax/swing/event/TableColumnModelListener.java +++ b/javax/swing/event/TableColumnModelListener.java @@ -1,5 +1,5 @@ /* TableColumnModelListener.java -- - Copyright (C) 2002 Free Software Foundation, Inc. + Copyright (C) 2002, 2006, Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -37,44 +37,58 @@ exception statement from your version. */ package javax.swing.event; -// Imports import java.util.EventListener; +import javax.swing.table.TableColumnModel; + /** - * TableColumnModelListener public interface + * A <code>TableColumnModelListener</code> can register with a + * {@link TableColumnModel} to receive notification of changes to the model. + * * @author Andrew Selkirk */ -public interface TableColumnModelListener extends EventListener { - - /** - * Column added - * @param event Table Column Model Event - */ - void columnAdded(TableColumnModelEvent event); - - /** - * Column margin changed - * @param event Change Event - */ - void columnMarginChanged(ChangeEvent event); - - /** - * Column moved - * @param event Table Column Model Event - */ - void columnMoved(TableColumnModelEvent event); - - /** - * Column removed - * @param event Table Column Model Event - */ - void columnRemoved(TableColumnModelEvent event); - - /** - * Column selection changed - * @param event List Selection Event - */ - void columnSelectionChanged(ListSelectionEvent event); - - -} // TableColumnModelListener +public interface TableColumnModelListener + extends EventListener +{ + + /** + * Called by the {@link TableColumnModel} to indicate that a column has been + * added to the model. + * + * @param event information about the column addition. + */ + void columnAdded(TableColumnModelEvent event); + + /** + * Called by the {@link TableColumnModel} to indicate that the model's + * column margin has changed. + * + * @param event the event (identifies the source). + */ + void columnMarginChanged(ChangeEvent event); + + /** + * Called by the {@link TableColumnModel} to indicate that a column has been + * moved. + * + * @param event information about the column move. + */ + void columnMoved(TableColumnModelEvent event); + + /** + * Called by the {@link TableColumnModel} to indicate that a column has been + * removed from the model. + * + * @param event information about the column removal. + */ + void columnRemoved(TableColumnModelEvent event); + + /** + * Called by the {@link TableColumnModel} to indicate that the column + * selection state has changed. + * + * @param event information about the column selection state. + */ + void columnSelectionChanged(ListSelectionEvent event); + +} diff --git a/javax/swing/table/DefaultTableColumnModel.java b/javax/swing/table/DefaultTableColumnModel.java index 10871770d..32a9b94e7 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,9 @@ import javax.swing.event.TableColumnModelEvent; import javax.swing.event.TableColumnModelListener; /** - * DefaultTableColumnModel + * A model that stores information about the columns used in a {@link JTable}. + * * @author Andrew Selkirk - * @version 1.0 */ public class DefaultTableColumnModel implements TableColumnModel, PropertyChangeListener, ListSelectionListener, @@ -66,12 +67,12 @@ public class DefaultTableColumnModel private static final long serialVersionUID = 6580012493508960512L; /** - * Columns that this model keeps track of. + * Storage for the table columns. */ protected Vector tableColumns; /** - * Selection Model that keeps track of columns selection + * A selection model that keeps track of column selections. */ protected ListSelectionModel selectionModel; @@ -86,8 +87,11 @@ public class DefaultTableColumnModel 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); /** @@ -101,7 +105,11 @@ public class DefaultTableColumnModel 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 defautl value for <code>columnSelectionAllowed</code> is + * <code>false</code>. */ public DefaultTableColumnModel() { @@ -112,10 +120,14 @@ public class DefaultTableColumnModel } /** - * addColumn adds column to the model. This method fires ColumnAdded - * event to model's registered TableColumnModelListeners. + * Adds a column to the model and sends a {@link TableColumnModelEvent} to + * all registered listeners. * - * @param col column to add + * @param col the column (<code>null</code> not permitted). + * + * @throws IllegalArgumentException if <code>col</code> is <code>null</code>. + * + * @see #removeColumn(TableColumn) */ public void addColumn(TableColumn col) { @@ -123,14 +135,18 @@ public class DefaultTableColumnModel throw new IllegalArgumentException("Null 'col' argument."); tableColumns.add(col); 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 and sends a {@link TableColumnModelEvent} + * to all registered listeners. If the specified column is <code>null</code> + * or does not belong to the model, this method does nothing. * - * @param col column to be removed + * @param col the column to be removed (<code>null</code> permitted). + * + * @see #addColumn(TableColumn) */ public void removeColumn(TableColumn col) { @@ -162,18 +178,22 @@ public class DefaultTableColumnModel } /** - * setColumnMargin sets margin of the columns. - * @param m new column margin + * Sets the column margin then calls {@link #fireColumnMarginChanged()}. + * + * @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 +201,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 getColumns() { @@ -214,9 +235,16 @@ 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 i 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) { @@ -224,8 +252,11 @@ public class DefaultTableColumnModel } /** - * getColumnMargin returns column margin - * @return int column margin + * Returns the column margin. + * + * @return The column margin. + * + * @see #setColumnMargin(int) */ public int getColumnMargin() { @@ -233,16 +264,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, + * assuming 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 +293,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 +306,31 @@ 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>. */ public void setSelectionModel(ListSelectionModel model) { if (model == null) throw new IllegalArgumentException(); + // FIXME: we are registered as a listener with the existing model, + // so we should remove that before updating the model... 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 +338,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 +350,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() { @@ -356,8 +407,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 +449,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) { @@ -417,6 +471,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() @@ -435,7 +496,7 @@ public class DefaultTableColumnModel { TableColumnModelListener[] listeners = getColumnModelListeners(); - for (int i=0; i< listeners.length; i++) + for (int i = 0; i < listeners.length; i++) listeners[i].columnAdded(e); } @@ -449,7 +510,7 @@ public class DefaultTableColumnModel { TableColumnModelListener[] listeners = getColumnModelListeners(); - for (int i=0; i< listeners.length; i++) + for (int i = 0; i < listeners.length; i++) listeners[i].columnRemoved(e); } @@ -463,7 +524,7 @@ public class DefaultTableColumnModel { TableColumnModelListener[] listeners = getColumnModelListeners(); - for (int i=0; i< listeners.length; i++) + for (int i = 0; i < listeners.length; i++) listeners[i].columnMoved(e); } @@ -478,26 +539,30 @@ public class DefaultTableColumnModel { EventListener [] listeners = getListeners(TableColumnModelListener.class); for (int i = 0; i < listeners.length; ++i) - ((TableColumnModelListener)listeners[i]).columnSelectionChanged(evt); + ((TableColumnModelListener) listeners[i]).columnSelectionChanged(evt); } /** - * fireColumnMarginChanged fires TableColumnModelEvent to model's - * registered TableColumnModelListeners to indicate that column margin - * was changed. + * Sends a {@link TableColumnModelEvent} to the model's registered + * {@link TableColumnModelListener}s to indicate that the column margin + * was changed. */ 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 EventListener[] getListeners(Class listenerType) { @@ -513,12 +578,17 @@ public class DefaultTableColumnModel public void propertyChange(PropertyChangeEvent evt) { if (evt.getPropertyName().equals(TableColumn.COLUMN_WIDTH_PROPERTY)) - invalidateWidthCache(); + 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 +596,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 +608,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 +620,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() { diff --git a/javax/swing/table/TableColumnModel.java b/javax/swing/table/TableColumnModel.java index b006f9ad4..986c02533 100644 --- a/javax/swing/table/TableColumnModel.java +++ b/javax/swing/table/TableColumnModel.java @@ -1,5 +1,5 @@ /* TableColumnModel.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. @@ -42,6 +42,8 @@ import java.util.Enumeration; import javax.swing.JTable; import javax.swing.ListSelectionModel; +import javax.swing.event.ChangeEvent; +import javax.swing.event.TableColumnModelEvent; import javax.swing.event.TableColumnModelListener; /** @@ -50,7 +52,6 @@ import javax.swing.event.TableColumnModelListener; * * @author Andrew Selkirk */ -// FIXME: The API documentation in this class is incomplete. public interface TableColumnModel { /** @@ -80,21 +81,26 @@ public interface TableColumnModel void moveColumn(int columnIndex, int newIndex); /** - * setColumnMargin - * @param margin Margin of column + * Sets the column margin and sends a {@link ChangeEvent} to all registered + * {@link TableColumnModelListener}s registered with the model. + * + * @param margin the column margin. + * + * @see #getColumnMargin() */ void setColumnMargin(int margin); /** * Returns the number of columns in the model. * - * @return The column count + * @return The column count. */ int getColumnCount(); /** - * getColumns - * @return Enumeration of columns + * Returns an enumeration of the columns in the model. + * + * @return An enumeration of the columns in the model. */ Enumeration getColumns(); @@ -123,30 +129,53 @@ public interface TableColumnModel * Returns the column margin. * * @return The column margin. + * + * @see #setColumnMargin(int) */ int getColumnMargin(); /** - * getColumnIndexAtX - * @return Column index as position x + * Returns the index of the column that contains the specified x-coordinate, + * assuming 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 xPosition the x-position. + * + * @return The column index, or <code>-1</code>. */ int getColumnIndexAtX(int xPosition); /** - * getTotalColumnWidth - * @return Total column width + * Returns total width of all the columns in the model, ignoring the + * column margin (see {@link #getColumnMargin()}). + * + * @return The total width of all the columns. */ int getTotalColumnWidth(); /** - * setColumnSelectionAllowed - * @param value Set column selection + * Sets the flag that indicates whether or not column selection is allowed. + * + * @param allowed the new flag value. + * + * @see #getColumnSelectionAllowed() */ - void setColumnSelectionAllowed(boolean value); + void setColumnSelectionAllowed(boolean allowed); /** - * getColumnSelectionAllowed - * @return true if column selection allowed, false otherwise + * Returns <code>true</code> if column selection is allowed, and + * <code>false</code> if column selection is not allowed. + * + * @return A boolean. + * + * @see #setColumnSelectionAllowed(boolean) */ boolean getColumnSelectionAllowed(); @@ -157,31 +186,47 @@ public interface TableColumnModel int[] getSelectedColumns(); /** - * getSelectedColumnCount - * @return Count of selected columns + * Returns the number of selected columns in the model. + * + * @return The selected column count. + * + * @see #getSelectionModel() */ int getSelectedColumnCount(); /** - * setSelectionModel - * @param model ListSelectionModel + * Sets the selection model that will be used to keep track of the selected + * columns. + * + * @param model the selection model (<code>null</code> not permitted). + * + * @throws IllegalArgumentException if <code>model</code> is + * <code>null</code>. */ void setSelectionModel(ListSelectionModel model); /** - * getSelectionModel + * Returns the selection model used to track table column selections. + * + * @return The selection model. + * + * @see #setSelectionModel(ListSelectionModel) */ ListSelectionModel getSelectionModel(); /** - * addColumnModelListener - * @param listener TableColumnModelListener + * Registers a listener with the model, so that it will receive + * {@link TableColumnModelEvent} notifications. + * + * @param listener the listener (<code>null</code> ignored). */ void addColumnModelListener(TableColumnModelListener listener); /** - * removeColumnModelListener - * @param listener TableColumnModelListener + * Deregisters a listener, so that it will no longer receive + * {@link TableColumnModelEvent} notifications. + * + * @param listener the listener. */ void removeColumnModelListener(TableColumnModelListener listener); } |