[cp-patches] FYI: BasicComboBoxUI API doc updates

[David Gilbert]

I committed this patch:

2005-09-18  David Gilbert  <address@hidden>

        * javax/swing/plaf/basic/BasicComboBoxUI.java:
        Updated API docs all over.

Regards,

Dave

Index: javax/swing/plaf/basic/BasicComboBoxUI.java
===================================================================
RCS file: 
/cvsroot/classpath/classpath/javax/swing/plaf/basic/BasicComboBoxUI.java,v
retrieving revision 1.12
diff -u -r1.12 BasicComboBoxUI.java
--- javax/swing/plaf/basic/BasicComboBoxUI.java 15 Sep 2005 19:58:43 -0000      
1.12
+++ javax/swing/plaf/basic/BasicComboBoxUI.java 18 Sep 2005 10:37:13 -0000
@@ -78,7 +78,7 @@
 import javax.swing.plaf.UIResource;
 
 /**
- * UI Delegate for JComboBox
+ * A UI delegate for the address@hidden JComboBox} component.
  *
  * @author Olga Rodimina
  * @author Robert Schuster
@@ -86,52 +86,54 @@
 public class BasicComboBoxUI extends ComboBoxUI
 {
   /**
-   * This arrow button that is displayed in the rigth side of JComboBox. This
-   * button is used to hide and show combo box's list of items
+   * The arrow button that is displayed in the right side of JComboBox. This
+   * button is used to hide and show combo box's list of items.
    */
   protected JButton arrowButton;
 
   /**
-   * The combo box for which this UI delegate is for
+   * The combo box represented by this UI delegate.
    */
   protected JComboBox comboBox;
 
   /**
-   * Component that is responsible for displaying/editting  selected item of
-   * the combo box. By default JTextField is used as an editor for the
-   * JComboBox
+   * The component that is responsible for displaying/editing the selected 
+   * item of the combo box. 
+   * 
+   * @see BasicComboBoxEditor#getEditorComponent()
    */
   protected Component editor;
 
   /**
-   * Listener listening to focus events occuring in the JComboBox
+   * A listener listening to focus events occurring in the address@hidden 
JComboBox}.
    */
   protected FocusListener focusListener;
 
   /**
-   * tells whether JComboBox currently has focus
+   * A flag indicating whether JComboBox currently has the focus.
    */
   protected boolean hasFocus;
 
   /**
-   * Listener listening to item events fired by the JComboBox
+   * A listener listening to item events fired by the address@hidden 
JComboBox}.
    */
   protected ItemListener itemListener;
 
   /**
-   * KeyListener listening to key events that occur while JComboBox has focus
+   * A listener listening to key events that occur while address@hidden 
JComboBox} has
+   * the focus.
    */
   protected KeyListener keyListener;
 
   /**
-   * MouseListener listening to mouse events occuring in the combo box
+   * A listener listening to mouse events occuring in the address@hidden 
JComboBox}.
    */
   private MouseListener mouseListener;
 
   /**
    * List used when rendering selected item of the combo box. The selection
-   * and foreground colors for combo box renderer  are configured from this
-   * list
+   * and foreground colors for combo box renderer are configured from this
+   * list.
    */
   protected JList listBox;
 
@@ -141,7 +143,7 @@
   protected ListDataListener listDataListener;
 
   /**
-   * Popup list containing combo box's menu items
+   * Popup list containing the combo box's menu items.
    */
   protected ComboPopup popup;
   protected KeyListener popupKeyListener;
@@ -183,19 +185,19 @@
   protected boolean isMinimumSizeDirty;
 
   /**
-   * Creates a new BasicComboBoxUI object.
+   * Creates a new <code>BasicComboBoxUI</code> object.
    */
   public BasicComboBoxUI()
   {
   }
 
   /**
-   * Factory method to create a BasicComboBoxUI for the given address@hidden
-   * JComponent}, which should be a address@hidden JComboBox}.
+   * A factory method to create a UI delegate for the given 
+   * address@hidden JComponent}, which should be a address@hidden JComboBox}.
    *
    * @param c The address@hidden JComponent} a UI is being created for.
    *
-   * @return A BasicComboBoxUI for the address@hidden JComponent}.
+   * @return A UI delegate for the address@hidden JComponent}.
    */
   public static ComponentUI createUI(JComponent c)
   {
@@ -203,9 +205,11 @@
   }
 
   /**
-   * This method installs the UI for the given JComponent.
+   * Installs the UI for the given address@hidden JComponent}.
    *
-   * @param c The JComponent to install a UI for.
+   * @param c  the JComponent to install a UI for.
+   * 
+   * @see #uninstallUI(JComponent)
    */
   public void installUI(JComponent c)
   {
@@ -224,9 +228,11 @@
   }
 
   /**
-   * This method uninstalls the UI.
+   * Uninstalls the UI for the given address@hidden JComponent}.
    *
    * @param c The JComponent that is having this UI removed.
+   * 
+   * @see #installUI(JComponent)
    */
   public void uninstallUI(JComponent c)
   {
@@ -238,8 +244,10 @@
   }
 
   /**
-   * This method installs the defaults that are defined in  the Basic look and
-   * feel for this address@hidden JComboBox}.
+   * Installs the defaults that are defined in the address@hidden 
BasicLookAndFeel} 
+   * for this address@hidden JComboBox}.
+   * 
+   * @see #uninstallDefaults()
    */
   protected void installDefaults()
   {
@@ -261,7 +269,9 @@
   }
 
   /**
-   * This method creates and installs the listeners for this UI.
+   * Creates and installs the listeners for this UI.
+   * 
+   * @see #uninstallListeners()
    */
   protected void installListeners()
   {
@@ -289,8 +299,10 @@
   }
 
   /**
-   * This method uninstalls the defaults and sets any objects created during
-   * install to null
+   * Uninstalls the defaults and sets any objects created during
+   * install to <code>null</code>.
+   * 
+   * @see #installDefaults()
    */
   protected void uninstallDefaults()
   {
@@ -310,6 +322,8 @@
 
   /**
    * Detaches all the listeners we attached in address@hidden 
#installListeners}.
+   * 
+   * @see #installListeners()
    */
   protected void uninstallListeners()
   {
@@ -335,7 +349,7 @@
   }
 
   /**
-   * This method creates popup that will contain list of combo box's items
+   * Creates the popup that will contain list of combo box's items.
    *
    * @return popup containing list of combo box's items
    */
@@ -345,7 +359,7 @@
   }
 
   /**
-   * Creates KeyListener to listen to key events.
+   * Creates a address@hidden KeyListener} to listen to key events.
    *
    * @return KeyListener that listens to key events.
    */
@@ -355,8 +369,8 @@
   }
 
   /**
-   * This method create MouseListener that will listen to mouse event occuring
-   * in combo box.
+   * Creates a address@hidden MouseListener} that will listen to mouse events 
occurring
+   * in the combo box.
    *
    * @return the MouseListener
    */
@@ -366,10 +380,10 @@
   }
 
   /**
-   * This method create FocusListener that will listen to changes in this
+   * Creates the address@hidden FocusListener} that will listen to changes in 
this
    * JComboBox's focus.
    *
-   * @return theFocusListener
+   * @return the FocusListener.
    */
   protected FocusListener createFocusListener()
   {
@@ -377,9 +391,9 @@
   }
 
   /**
-   * This method create ListDataListener to listen to ComboBox's  data model
+   * Creates a address@hidden ListDataListener} to listen to the combo box's 
data model.
    *
-   * @return ListDataListener
+   * @return The new listener.
    */
   protected ListDataListener createListDataListener()
   {
@@ -387,10 +401,10 @@
   }
 
   /**
-   * This method creates ItemListener that will listen to to the changes in
+   * Creates an address@hidden ItemListener} that will listen to the changes in
    * the JComboBox's selection.
    *
-   * @return the ItemListener
+   * @return The ItemListener
    */
   protected ItemListener createItemListener()
   {
@@ -398,10 +412,10 @@
   }
 
   /**
-   * This method creates PropertyChangeListener to listen to  the changes in
+   * Creates a address@hidden PropertyChangeListener} to listen to the changes 
in
    * the JComboBox's bound properties.
    *
-   * @return the PropertyChangeListener
+   * @return The PropertyChangeListener
    */
   protected PropertyChangeListener createPropertyChangeListener()
   {
@@ -409,9 +423,10 @@
   }
 
   /**
-   * This method returns layout manager for the combo box.
+   * Creates and returns a layout manager for the combo box.  Subclasses can 
+   * override this method to provide a different layout.
    *
-   * @return layout manager for the combo box
+   * @return a layout manager for the combo box.
    */
   protected LayoutManager createLayoutManager()
   {
@@ -419,10 +434,10 @@
   }
 
   /**
-   * This method creates component that will be responsible for rendering the
+   * Creates a component that will be responsible for rendering the
    * selected component in the combo box.
    *
-   * @return render for the combo box
+   * @return A renderer for the combo box.
    */
   protected ListCellRenderer createRenderer()
   {
@@ -430,12 +445,12 @@
   }
 
   /**
-   * Creates component that will be responsible for displaying/editting
-   * selected item in the combo box. This editor is used only when combo box
-   * is editable.
+   * Creates the component that will be responsible for displaying/editing
+   * the selected item in the combo box. This editor is used only when combo 
+   * box is editable.
    *
-   * @return component that will be responsible for  displaying/editting
-   *         selected item in the combo box.
+   * @return A new component that will be responsible for displaying/editing
+   *         the selected item in the combo box.
    */
   protected ComboBoxEditor createEditor()
   {
@@ -443,8 +458,8 @@
   }
 
   /**
-   * This method installs components for this JComboBox. ArrowButton, main
-   * part of combo box (upper part) and  popup list of items are created and
+   * Installs the components for this JComboBox. ArrowButton, main
+   * part of combo box (upper part) and popup list of items are created and
    * configured here.
    */
   protected void installComponents()
@@ -481,7 +496,9 @@
   }
 
   /**
-   * This method uninstalls components from this JComboBox
+   * Uninstalls components from this address@hidden JComboBox}.
+   * 
+   * @see #installComponents()
    */
   protected void uninstallComponents()
   {
@@ -500,7 +517,7 @@
   }
 
   /**
-   * This method adds editor to the combo box
+   * Adds the current editor to the combo box.
    */
   public void addEditor()
   {
@@ -508,7 +525,7 @@
   }
 
   /**
-   * This method removes editor from the combo box
+   * Removes the current editor from the combo box.
    */
   public void removeEditor()
   {
@@ -516,7 +533,7 @@
   }
 
   /**
-   * This method configures editor for this combo box.
+   * Configures the editor for this combo box.
    */
   protected void configureEditor()
   {
@@ -524,7 +541,7 @@
   }
 
   /**
-   * This method removes all the listeners for the editor.
+   * Unconfigures the editor for this combo nox.  This method is not 
implemented.
    */
   protected void unconfigureEditor()
   {
@@ -532,7 +549,9 @@
   }
 
   /**
-   * This method adds listeners to the arrow button part of the combo box.
+   * Configures the arrow button.
+   * 
+   * @see #configureArrowButton()
    */
   public void configureArrowButton()
   {
@@ -540,8 +559,9 @@
   }
 
   /**
-   * This method removes listeners from the arrow button part of the combo
-   * box.
+   * Unconfigures the arrow button.
+   * 
+   * @see #configureArrowButton()
    */
   public void unconfigureArrowButton()
   {
@@ -549,11 +569,11 @@
   }
 
   /**
-   * This method create arrow button for this JComboBox. Arrow button is
-   * responsible for displaying / hiding drop down list of items  when it is
-   * clicked.
+   * Creates an arrow button for this address@hidden JComboBox}.  The arrow 
button is
+   * displayed at the right end of the combo box and is used to display/hide
+   * the drop down list of items.
    *
-   * @return JButton arrow button for this JComboBox.
+   * @return A new button.
    */
   protected JButton createArrowButton()
   {
@@ -561,13 +581,13 @@
   }
 
   /**
-   * This method checks if popup part of the combo box is visible on the
-   * screen
+   * Returns <code>true</code> if the popup is visible, and <code>false</code>
+   * otherwise.
    *
    * @param c The JComboBox to check
    *
-   * @return true if popup part of the JComboBox is visible and false
-   *         otherwise.
+   * @return <code>true</code> if popup part of the JComboBox is visible and 
+   *         <code>false</code> otherwise.
    */
   public boolean isPopupVisible(JComboBox c)
   {
@@ -575,7 +595,7 @@
   }
 
   /**
-   * Displays/Hides JComboBox's list of items on the screen.
+   * Displays/hides the address@hidden JComboBox}'s list of items on the 
screen.
    *
    * @param c The combo box, for which list of items should be
    *        displayed/hidden
@@ -647,11 +667,11 @@
   }
 
   /**
-   * Returns preferred size for the given menu item.
+   * Returns preferred size for the combo box.
    *
    * @param c comboBox for which to get preferred size
    *
-   * @return $Dimension$ preferred size for the given combo box
+   * @return The preferred size for the given combo box
    */
   public Dimension getPreferredSize(JComponent c)
   {
@@ -661,7 +681,7 @@
   }
 
   /**
-   * This method returns the minimum size for this address@hidden JComboBox} 
for this
+   * Returns the minimum size for this address@hidden JComboBox} for this
    * look and feel.
    *
    * @param c The address@hidden JComponent} to find the minimum size for.
@@ -674,7 +694,7 @@
   }
 
   /**
-   * This method returns the maximum size for this address@hidden JComboBox} 
for this
+   * Returns the maximum size for this address@hidden JComboBox} for this
    * look and feel.
    *
    * @param c The address@hidden JComponent} to find the maximum size for
@@ -712,7 +732,7 @@
   }
 
   /**
-   * This method selects next possible item relative to the current selection
+   * Selects next possible item relative to the current selection
    * to be next selected item in the combo box.
    */
   protected void selectNextPossibleValue()
@@ -723,7 +743,7 @@
   }
 
   /**
-   * This method selects previous item relative to current selection to be
+   * Selects previous item relative to current selection to be
    * next selected item.
    */
   protected void selectPreviousPossibleValue()
@@ -734,8 +754,8 @@
   }
 
   /**
-   * This method displays combo box popup if the popup is not currently shown
-   * on the screen and hides it if it is  currently shown
+   * Displays combo box popup if the popup is not currently shown
+   * on the screen and hides it if it is currently shown
    */
   protected void toggleOpenClose()
   {
@@ -743,8 +763,8 @@
   }
 
   /**
-   * This method returns bounds in which comboBox's selected Item will be
-   * displayed
+   * Returns the bounds in which comboBox's selected item will be
+   * displayed.
    *
    * @return rectangle bounds in which comboBox's selected Item will be
    *         displayed
@@ -770,7 +790,7 @@
   }
 
   /**
-   * This method returns insets of the current border.
+   * Returns the insets of the current border.
    *
    * @return Insets representing space between combo box and its border
    */
@@ -780,7 +800,7 @@
   }
 
   /**
-   * This method paints currently selected value in the main part of the combo
+   * Paints currently selected value in the main part of the combo
    * box (part without popup).
    *
    * @param g graphics context
@@ -820,7 +840,7 @@
   }
 
   /**
-   * This method paints background of part of the combo box, where currently
+   * Paints the background of part of the combo box, where currently
    * selected value is displayed. If the combo box has focus this method
    * should also paint focus rectangle around the combo box.
    *
@@ -889,7 +909,7 @@
   }
 
   /**
-   * This method installs the keyboard actions for the JComboBox as specified
+   * Installs the keyboard actions for the address@hidden JComboBox} as 
specified
    * by the look and feel.
    */
   protected void installKeyboardActions()
@@ -898,7 +918,7 @@
   }
 
   /**
-   * This method uninstalls the keyboard actions for the JComboBox there were
+   * Uninstalls the keyboard actions for the address@hidden JComboBox} there 
were
    * installed by in address@hidden #installListeners}.
    */
   protected void uninstallKeyboardActions()
@@ -907,7 +927,10 @@
   }
 
   /**
-   * This class is Layout Manager for this combo box.
+   * A address@hidden LayoutManager} used to position the sub-components of the
+   * address@hidden JComboBox}.
+   * 
+   * @see BasicComboBoxUI#createLayoutManager()
    */
   public class ComboBoxLayoutManager extends Object implements LayoutManager
   {
@@ -918,11 +941,24 @@
     {
     }
 
+    /**
+     * Adds a component to the layout.  This method does nothing, since the
+     * layout manager doesn't need to track the components.
+     * 
+     * @param name  the name to associate the component with (ignored).
+     * @param comp  the component (ignored).
+     */
     public void addLayoutComponent(String name, Component comp)
     {
       // Do nothing
     }
 
+    /**
+     * Removes a component from the layout.  This method does nothing, since
+     * the layout manager doesn't need to track the components.
+     * 
+     * @param comp  the component.
+     */
     public void removeLayoutComponent(Component comp)
     {
       // Do nothing
@@ -931,9 +967,10 @@
     /**
      * Returns preferred layout size of the JComboBox.
      *
-     * @param parent Container for which preferred size should be calculated
+     * @param parent  the Container for which the preferred size should be 
+     *                calculated.
      *
-     * @return preferred size for the given container
+     * @return The preferred size for the given container
      */
     public Dimension preferredLayoutSize(Container parent)
     {
@@ -961,6 +998,13 @@
       return d;
     }
 
+    /**
+     * Returns the minimum layout size.
+     * 
+     * @param parent  the container.
+     * 
+     * @return The minimum size.
+     */
     public Dimension minimumLayoutSize(Container parent)
     {
       Dimension minSize = getDefaultSize();
@@ -986,7 +1030,7 @@
     }
 
     /**
-     * This method layouts out the components in the container.  It puts arrow
+     * Arranges the components in the container.  It puts arrow
      * button right end part of the comboBox. If the comboBox is editable
      * then editor is placed to the left of arrow  button, starting from the
      * beginning.
@@ -1011,7 +1055,7 @@
   }
 
   /**
-   * This class handles focus changes occuring in the combo box. This class is
+   * Handles focus changes occuring in the combo box. This class is
    * responsible for repainting combo box whenever focus is gained or lost
    * and also for hiding popup list of items whenever combo box loses its
    * focus.
@@ -1026,8 +1070,8 @@
     }
 
     /**
-     * This mehtod is invoked when combo box gains focus. It repaints main
-     * part of combo box  accordingally.
+     * Invoked when combo box gains focus. It repaints main
+     * part of combo box accordingly.
      *
      * @param e the FocusEvent
      */
@@ -1038,8 +1082,8 @@
     }
 
     /**
-     * This method is invoked when combo box loses focus It repaint main part
-     * of combo box accordingally and  hides popup list of items.
+     * Invoked when the combo box loses focus.  It repaints the main part
+     * of the combo box accordingly and hides the popup list of items.
      *
      * @param e the FocusEvent
      */
@@ -1051,8 +1095,8 @@
   }
 
   /**
-   * This class handles ItemEvent fired by the JComboBox when its selected
-   * item changes.
+   * Handles address@hidden ItemEvent}s fired by the address@hidden JComboBox} 
when its 
+   * selected item changes.
    */
   public class ItemHandler extends Object implements ItemListener
   {
@@ -1064,7 +1108,7 @@
     }
 
     /**
-     * This method is invoked when selected item becomes deselected or when
+     * Invoked when selected item becomes deselected or when
      * new item becomes selected.
      *
      * @param e the ItemEvent representing item's state change.
@@ -1084,9 +1128,8 @@
     {
     }
 
-    /*
-     * This method is invoked whenever key is pressed while JComboBox is in
-     * focus.
+    /**
+     * Invoked whenever key is pressed while JComboBox is in focus.
      */
     public void keyPressed(KeyEvent e)
     {
@@ -1096,7 +1139,7 @@
   }
 
   /**
-   * This class handles to the changes occuring in the JComboBox's data model
+   * Handles the changes occurring in the JComboBox's data model.
    */
   public class ListDataHandler extends Object implements ListDataListener
   {
@@ -1108,7 +1151,7 @@
     }
 
     /**
-     * This method is invoked content's of JComboBox's data model  are changed
+     * Invoked if the content's of JComboBox's data model are changed.
      *
      * @param e ListDataEvent describing the change.
      */
@@ -1118,8 +1161,7 @@
     }
 
     /**
-     * This method is invoked when items were added to the JComboBox's data
-     * model.
+     * Invoked when items are added to the JComboBox's data model.
      *
      * @param e ListDataEvent describing the change.
      */
@@ -1139,7 +1181,7 @@
     }
 
     /**
-     * This method is invoked when items were removed from the JComboBox's
+     * Invoked when items are removed from the JComboBox's
      * data model.
      *
      * @param e ListDataEvent describing the change.
@@ -1153,17 +1195,22 @@
   }
 
   /**
-   * This class handles PropertyChangeEvents fired by JComboBox.
+   * Handles address@hidden PropertyChangeEvent}s fired by the address@hidden 
JComboBox}.
    */
   public class PropertyChangeHandler extends Object
     implements PropertyChangeListener
   {
+    /**
+     * Creates a new instance.
+     */
     public PropertyChangeHandler()
     {
     }
 
     /**
-     * This method is invoked whenever bound property of JComboBox changes.
+     * Invoked whenever bound property of JComboBox changes.
+     * 
+     * @param e  the event.
      */
     public void propertyChange(PropertyChangeEvent e)
     {
@@ -1207,17 +1254,16 @@
   }
 
   /**
-   * MouseHandler listens to mouse events occuring in the combo box. This
-   * class is responsible for repainting this JComboBox whenever the mouse is
-   * being pressed or released over it.
+   * A handler for mouse events occurring in the combo box.  An instance of 
+   * this class is returned by the <code>createMouseListener()</code> method.
    */
   private class MouseHandler extends MouseAdapter
   {
     /**
-     * This method is invoked when mouse is pressed over the combo box. It
-     * repaints the combo box accordinglly
+     * Invoked when mouse is pressed over the combo box. It toggles the 
+     * visibility of the popup list.
      *
-     * @param e the MouseEvent
+     * @param e  the event
      */
     public void mousePressed(MouseEvent e)
     {