Javadoc changes to Swing for JDK (TM) Software, v. 1.4

This document contains the javadoc changes for release 1.4. To see the text document that references these changes, click here.

Box

Change class javadoc for javax.swing.BoxLayout to indicate new functionality:

/**
 * A layout manager that allows multiple components to be laid out either
 * vertically or horizontally. The components will not wrap so, for 
 * example, a vertical arrangement of components will stay vertically 
 * arranged when the frame is resized. 
 * 
 * Nesting multiple panels with different combinations of horizontal and 
 * vertical gives an effect similar to GridBagLayout, without the 
 * complexity. The diagram shows two panels arranged horizontally, each 
 * of which contains 3 components arranged vertically.
 *
 * The BoxLayout manager is constructed with an axis parameter that
 * specifies the type of layout that will be done. There are four choices:
 *
 * X_AXIS - Components are laid out horizontally
 * from left to right.
 * 
 * Y_AXIS - Components are laid out vertically
 * from top to bottom.
 * 
 * LINE_AXIS - Components are laid out the way
 * words are laid out in a line, based on the container's
 * ComponentOrientation property. If the container's
 * ComponentOrientation is horizontal then components are laid out
 * horizontally, otherwise they are laid out vertically.  For horizontal
 * orientations, if the container's ComponentOrientation is left to
 * right then components are laid out left to right, otherwise they are laid
 * out right to left. For vertical orientations components are always laid out
 * from top to bottom.
 * 
 * PAGE_AXIS - Components are laid out the way
 * text lines are laid out on a page, based on the container's
 * ComponentOrientation property. If the container's
 * ComponentOrientation is horizontal then components are laid out
 * vertically, otherwise they are laid out horizontally.  For horizontal
 * orientations, if the container's ComponentOrientation is left to
 * right then components are laid out left to right, otherwise they are laid
 * out right to left.  For vertical orientations components are always
 * laid out from top to bottom.
 *
 * For all directions, components are arranged in the same order as they were
 * added to the container.
 * 
 * BoxLayout attempts to arrange components
 * at their preferred widths (for horizontal layout)
 * or heights (for vertical layout).
 * For a horizontal layout,
 * if not all the components are the same height,
 * BoxLayout attempts to make all the components 
 * as high as the highest component.
 * If that's not possible for a particular component, 
 * then BoxLayout aligns that component vertically,
 * according to the component's Y alignment.
 * By default, a component has an Y alignment of 0.5,
 * which means that the vertical center of the component
 * should have the same Y coordinate as 
 * the vertical centers of other components with 0.5 Y alignment.
 *
 * Similarly, for a vertical layout,
 * BoxLayout attempts to make all components in the column
 * as wide as the widest component.
 * If that fails, it aligns them horizontally
 * according to their X alignments.  For PAGE_AXIS layout,
 * horizontal alignment is done based on the leading edge of the component. 
 * In other words, an X alignment value of 0.0 means the left edge of a 
 * component if the container's ComponentOrientation is left to 
 * right and it means the right edge of the component otherwise.
 *
 * Instead of using BoxLayout directly, many programs use the Box class.
 * The Box class is a lightweight container that uses a BoxLayout.
 * It also provides handy methods to help you use BoxLayout well.  
 * Adding components to multiple nested boxes is a powerful way to get
 * the arrangement you want.
 *
 * Warning:
 * Serialized objects of this class will not be compatible with
 * future Swing releases.  The current serialization support is appropriate
 * for short term storage or RMI between applications running the same
 * version of Swing.  A future release of Swing will provide support for
 * long term persistence.
 *
 * @see Box
 * @see java.awt.ComponentOrientation
 * @see Component#getAlignmentX
 * @see Component#getAlignmentY
 *
 * @author   Timothy Prinzing
 * @version %I% %G% 
 */

Define the two new constants in BoxLayout:

    /**
     * Specifies that components should be laid out in the direction of 
     * a line of text as determined by the target container's
     * ComponentOrientation property.  
     */
    public static final int LINE_AXIS = 2;

    /**
     * Specifies that components should be laid out in the direction that
     * lines flow across a page as determined by the target container's
     * ComponentOrientation property.
     */
    public static final int PAGE_AXIS = 3;

Modify the constructor to allow for the new axes:

    /**
     * Creates a layout manager that will lay out components along the
     * given axis.  
     *
     * @param target  the container that needs to be laid out
     * @param axis  the axis to lay out components along. Can be one of:
     *              BoxLayout.X_AXIS,
     *              BoxLayout.Y_AXIS,
     *              BoxLayout.LINE_AXIS or
     *              BoxLayout.PAGE_AXIS
     *
     * @exception AWTError  if the value of axis is invalid 
     */

Modify the class javadoc for SizeRequirements to indicate new functionality:

/**
 * For the convenience of layout managers,
 * calculates information about the size and position of components.
 * All size and position calculation methods are class methods
 * that take arrays of SizeRequirements as arguments.
 * The SizeRequirements class supports two types of layout:
 * 
 *  tiled
 *  The components are placed end-to-end,
 *      starting either at coordinate 0 (the leftmost or topmost position)
 *      or at the coordinate representing the end of the allocated span
 *      (the rightmost or bottommost position).
 *
 *  aligned
 *  The components are aligned as specified
 *      by each component's X or Y alignment value.
 * 
 *
 * Each SizeRequirements object contains information
 * about either the width (and X alignment)
 * or height (and Y alignment)
 * of a single component or a group of components:
 *
 *  minimum
 *  The smallest reasonable width/height of the component
 *  or component group, in pixels.
 *
 *  preferred
 *  The natural width/height of the component
 *  or component group, in pixels.
 *
 *  maximum
 *  The largest reasonable width/height of the component
 *  or component group, in pixels.
 *
 *  alignment
 *  The X/Y alignment of the component
 *  or component group.
 *
 * Warning:
 * Serialized objects of this class will not be compatible with
 * future Swing releases.  The current serialization support is appropriate
 * for short term storage or RMI between applications running the same
 * version of Swing.  A future release of Swing will provide support for
 * long term persistence.
 *
 * @see Component#getMinimumSize
 * @see Component#getPreferredSize
 * @see Component#getMaximumSize
 * @see Component#getAlignmentX
 * @see Component#getAlignmentY
 *
 * @version %I% %G%
 * @author Timothy Prinzing
 */

Update javadoc for following methods:

   /**
     * Creates a set of offset/span pairs representing how to
     * lay out a set of components end-to-end.
     * This method requires that you specify
     * the total amount of space to be allocated,
     * the size requirements for each component to be placed
     * (specified as an array of SizeRequirements), and
     * the total size requirement of the set of components.
     * You can get the total size requirement
     * by invoking the getTiledSizeRequirements method.
     *
     * This method also requires a flag indicating whether components
     * should be tiled in the forward direction (offsets increasing
     * from 0) or reverse direction (offsets decreasing from the end
     * of the allocated space).  The forward direction represents
     * components tiled from left to right or top to bottom.  The
     * reverse direction represents components tiled from right to left
     * or bottom to top.
     *
     * @param allocated the total span to be allocated >= 0
     * @param total     the total of the children requests; this argument
     *  is optional and may be null
     * @param children  the size requirements for each component
     * @param offsets   the offset from 0 for each child where
     *   the spans were allocated (determines placement of the span)
     * @param spans     the span allocated for each child to make the
     *   total target span
     * @param forward   tile with offsets increasing from 0 if true 
     *   and with offsets decreasing from the end of the allocated space
     *   if false
     */
    public static void calculateTiledPositions(int allocated,
                                               SizeRequirements total,
                                               SizeRequirements[] children,
                                               int[] offsets,
                                               int[] spans,
                                               boolean forward);

    /**
     * Creates a set of offset/span pairs representing how to
     * lay out a set of components end-to-end.
     * This method requires that you specify
     * the total amount of space to be allocated,
     * the size requirements for each component to be placed
     * (specified as an array of SizeRequirements), and
     * the total size requirement of the set of components.
     * You can get the total size requirement
     * by invoking the getTiledSizeRequirements method.  The components
     * will be tiled in the forward direction with offsets increasing from 0.
     *
     * @param allocated the total span to be allocated >= 0
     * @param total     the total of the children requests; this argument
     *  is optional and may be null
     * @param children  the size requirements for each component
     * @param offsets   the offset from 0 for each child where
     *   the spans were allocated (determines placement of the span)
     * @param spans     the span allocated for each child to make the
     *   total target span
     */
    public static void calculateTiledPositions(int allocated,
                                               SizeRequirements total,
                                               SizeRequirements[] children,
                                               int[] offsets,
                                               int[] spans);

    /**
     * Creates a set of offset/span pairs specifying how to
     * lay out a set of components with the specified alignments.
     * The resulting span allocations will overlap, with each one
     * fitting as well as possible into the given total allocation.
     * This method requires that you specify
     * the total amount of space to be allocated,
     * the size requirements for each component to be placed
     * (specified as an array of SizeRequirements), and
     * the total size requirements of the set of components
     * (only the alignment field of which is actually used) 
     * You can get the total size requirement by invoking
     * getAlignedSizeRequirements.
     *
     * This method also requires a flag indicating whether normal or
     * reverse alignment should be performed.  With normal alignment
     * the value 0.0f represents the left/top edge of the component
     * to be aligned.  With reverse alignment, 0.0f represents the 
     * right/bottom edge.
     *
     * @param allocated the total span to be allocated >= 0
     * @param total     the total of the children requests
     * @param children  the size requirements for each component
     * @param offsets   the offset from 0 for each child where
     *   the spans were allocated (determines placement of the span)
     * @param spans     the span allocated for each child to make the
     *   total target span
     * @param normal    when true, the alignment value 0.0f means 
     *   left/top; when false, it means right/bottom
     */
    public static void calculateAlignedPositions(int allocated,
                                                 SizeRequirements total,
                                                 SizeRequirements[] children,
                                                 int[] offsets,
                                                 int[] spans,
                                                 boolean normal);

    /**
     * Creates a set of offset/span pairs specifying how to
     * lay out a set of components with the specified alignments.
     * The resulting span allocations will overlap, with each one
     * fitting as well as possible into the given total allocation.
     * This method requires that you specify
     * the total amount of space to be allocated,
     * the size requirements for each component to be placed
     * (specified as an array of SizeRequirements), and
     * the total size requirements of the set of components
     * (only the alignment field of which is actually used).
     * You can get the total size requirement by invoking
     * getAlignedSizeRequirements.
     *
     * Normal alignment will be done with an alignment value of 0.0f
     * representing the left/top edge of a component.
     *
     * @param allocated the total span to be allocated >= 0
     * @param total     the total of the children requests
     * @param children  the size requirements for each component
     * @param offsets   the offset from 0 for each child where
     *   the spans were allocated (determines placement of the span)
     * @param spans     the span allocated for each child to make the
     *   total target span
     */
    public static void calculateAlignedPositions(int allocated,
                                                 SizeRequirements total,
                                                 SizeRequirements[] children,
                                                 int[] offsets,
                                                 int[] spans);

Javadoc changes to javax.swing.AbstractButton for adding the ability to specify space between icon and text in AbstractButton:

    /**
     * Specifies the amount of space between the icon and text. This is
     * only used if both the icon and text have been specified.
     * 

     * The default value of this property is 4 pixels.
     * 

     * This is a JavaBeans bound property.
     * 
     * @since 1.4
     * @see #getIconTextGap
     * @see #setText
     * @see #setIcon
     * @beaninfo
     *        bound: true
     *    attribute: visualUpdate true
     *  description: If both the icon and text properties are set, this
     *               property defines the space between them.
     */
    public void setIconTextGap(int iconTextGap);

    /**
     * Returns the amount of space between the text and the icon
     * displayed in this button.
     *
     * @return an int equal to the number of pixels between the text
     *         and the icon.
     * @since 1.4
     * @see #setIconTextGap
     */
    public int getIconTextGap();
    

JButton

Need more control of highlighted character than setMnemonic offers

    /**
     * Provides a hint to the look and feel as to which character in the
     * text should be decorated to represent the mnemonic. Not all look and
     * feels may support this. A value of -1 indicates either there is no
     * mnemonic, the mnemonic character is not contained in the string, or
     * the developer does not wish the mnemonic to be displayed.
     *
     * The value of this is updated as the properties relating to the
     * mnemonic change (such as the mnemonic itself, the text...).
     * You should only ever have to call this if
     * you do not wish the default character to be underlined. For example, if
     * the text was 'Save As', with a mnemonic of 'a', and you wanted the 'A'
     * to be decorated, as 'Save As', you would have to invoke
     * setDisplayedMnemonicIndex(5) after invoking
     * setMnemonic(KeyEvent.VK_A).
     *
     * @since 1.4
     * @param index index into the String to underline
     * @exception IllegalArgumentException   if index
     *            is >= length of the text, or < -1
     *
     * @beaninfo
     *        bound: true
     *    attribute: visualUpdate true
     *  description: the index into the String at which to draw
     *               the keyboard character mnemonic 
     */
    public void setDisplayedMnemonicIndex(int index)
                                          throws IllegalArgumentException;


    /**
     * Returns an index to the character in the String that the look
     * and feel should decorate to represent the mnemonic character.
     *
     * @since 1.4
     * @return an index representing mnemonic character
     * @see #setDisplayedMnemonicIndex
     */
    public int getDisplayedMnemonicIndex();

And the following to javax.swing.plaf.basic.BasicGraphicsUtils:

    /**
     * Draws a string with the graphics g at location
     * (x, y)
     * just like g.drawString would.
     * The character at index underlinedIndex
     * in text will be underlined. If index is beyond the
     * bounds of text (including < 0), nothing will be
     * underlined.
     *
     * @param g graphics to draw with
     * @param text string to draw
     * @param underlinedIndex index of character in text to underline
     * @param x x coordinate 
     * @param y y coordinate
     * @since 1.4
     */
    public static void drawStringUnderlineCharAt(Graphics g, String text,
                           int underlinedIndex, int x, int y);

JComboBox

Javadoc for adding PopupMenuListener support to JComboBox:

/**
 * Adds a PopupMenu listener which will listen to notification
 * messages from the popup portion of the combo box. 
 *
 * For all standard look and feels shipped with Java 2, the popup list  
 * portion of combo box is implemented as a JPopupMenu.
 * A custom look and feel may not implement it this way and will 
 * therefore not receive the notification.
 *
 * @param l  the PopupMenuListener to add
 * @since 1.4
 */
public void addPopupMenuListener(PopupMenuListener l) 

/**
 * Removes a PopupMenuListener.
 *
 * @param l  the PopupMenuListener to remove
 * @see #addPopupMenuListener
 * @since 1.4
 */
public void removePopupMenuListener(PopupMenuListener l)

/**
 * Notifies PopupMenuListeners that the popup portion of the
 * combo box will become visible.
 * 
 * This method is public but should not be called by anything other than 
 * the UI delegate.
 * @see #addPopupMenuListener
 * @since 1.4
 */
public void firePopupMenuWillBecomeVisible()

/**
 * Notifies PopupMenuListeners that the popup portion of the
 * combo box has become invisible.
 *
 * This method is public but should not be called by anything other than 
 * the UI delegate.
 * @see #addPopupMenuListener
 * @since 1.4
 */
public void firePopupMenuWillBecomeInvisible()

/**
 * Notifies PopupMenuListeners that the popup portion of the 
 * combo box has been canceled.
 *
 * This method is public but should not be called by anything other than 
 * the UI delegate.
 * @see #addPopupMenuListener
 * @since 1.4
 */
public void firePopupMenuCanceled()
    

JComboBox needs prototype cell for lists

    /**
     * Returns the "prototypical display" value - an Object used
     * for the calculation of the display height and width.
     *
     * @return the value of the prototypeDisplayValue property
     * @see #setPrototypeDisplayValue
     * @since 1.4
     */
    public Object getPrototypeDisplayValue()

    /**
     * Sets the prototype display value used to calculate the size of the 
     * display for the UI portion. 
     * 
     * If a prototype display value is specified, the preferred size of
     * the combo box is calculated by configuring the renderer with the
     * prototype display value and obtaining its preferred size. Specifying
     * the preferred display value is often useful when the combo box will be
     * displaying large amounts of data. If no prototype display value has
     * been specified, the renderer must be configured for each value from
     * the model and its preferred size obtained, which can be
     * relatively expensive.
     * 
     * @param prototypeDisplayValue 
     * @see #getPrototypeDisplayValue
     * @since 1.4
     * @beaninfo
     *       bound: true
     *   attribute: visualUpdate true
     * description: The display prototype value, used to compute display width and height.
     */
    public void setPrototypeDisplayValue(Object prototypeDisplayValue) {

Updated javadoc for javax.swing.JComboBox:

/**
 * A component that combines a button or editable field and a drop-down list.
 * The user can select a value from the drop-down list, which appears at the 
 * user's request. If you make the combo box editable, then the combo box
 * includes an editable field into which the user can type a value.
 * 
 * For the keyboard keys used by this component in the standard Look and
 * Feel (L&F) renditions, see the
 * <a href="doc-files/Key-Index.html#JComboBox">JComboBox key assignments</a>.
 *
 * Warning:
 * Serialized objects of this class will not be compatible with 
 * future Swing releases.  The current serialization support is appropriate
 * for short term storage or RMI between applications running the same
 * version of Swing.  A future release of Swing will provide support for
 * long term persistence.
 *
 * See <a href="http://java.sun.com/docs/books/tutorial/uiswing/components/combobox.html">How to Use Combo Boxes</a>
 * in <a href="http://java.sun.com/Series/Tutorial/index.html">The Java Tutorial</a>
 * for further information.
 *
 * @see ComboBoxModel
 * @see DefaultComboBoxModel
 *
 * @beaninfo
 *   attribute: isContainer false
 * description: A combination of a button or editable field and a drop-down list.
 *
 * @version %I% %G%
 * @author Arnaud Weber
 * @author Mark Davidson
 */
public class JComboBox {

    /**
     * This protected field is implementation specific. Do not access directly
     * or override. Use the accessor methods instead.
     *
     * @see #getModel
     * @see #setModel
     */
    protected ComboBoxModel    dataModel;

    /**
     * This protected field is implementation specific. Do not access directly
     * or override. Use the accessor methods instead.
     *
     * @see #getRenderer
     * @see #setRenderer
     */
    protected ListCellRenderer renderer;

    /**
     * This protected field is implementation specific. Do not access directly
     * or override. Use the accessor methods instead.
     *
     * @see #getEditor
     * @see #setEditor
     */
    protected ComboBoxEditor       editor;


    /**
     * This protected field is implementation specific. Do not access directly
     * or override. Use the accessor methods instead.
     *
     * @see #getMaximumRowCount
     * @see #setMaximumRowCount
     */
    protected int maximumRowCount = 8;

    /**
     * This protected field is implementation specific. Do not access directly
     * or override. Use the accessor methods instead.
     *
     * @see #isEditable
     * @see #setEditable
     */
    protected boolean isEditable  = false;


    /**
     * This protected field is implementation specific. Do not access directly
     * or override. Use the accessor methods instead.
     *
     * @see #setKeySelectionManager
     * @see #getKeySelectionManager
     */
    protected KeySelectionManager keySelectionManager = null;

    /**
     * This protected field is implementation specific. Do not access directly
     * or override. Use the accessor methods instead.
     *
     * @see #setActionCommand
     * @see #getActionCommand
     */
    protected String actionCommand = "comboBoxChanged";

    /**
     * This protected field is implementation specific. Do not access directly
     * or override. Use the accessor methods instead.
     *
     * @see #setLightWeightPopupEnabled
     * @see #isLightWeightPopupEnabled
     */
    protected boolean lightWeightPopupEnabled;
     
    /**
     * When displaying the popup, JComboBox will choose a
     * light weight popup if it fits. Light weight popups may need to be
     * disabled if the application mixes light and heavy weight components.
     *
     * See the article <a href="http://webmirror.eng/products/jfc/tsc/articles/mixing/index.html">Mixing Heavy and Light Components</a> 
     * on <a href="http://java.sun.com/products/jfc/tsc">
     * The Swing Connection</a>
     *
     * @beaninfo
     *        bound: true
     *       expert: true
     *  description: When set, disables using light weight popups.
     */
    public void setLightWeightPopupEnabled(boolean aFlag);

    /** 
     * Sets the selected item in the combo box display area to the object in 
     * the argument.
     * If anObject is in the list, the display area shows 
     * anObject selected.
     *
     * If anObject is not in the list and the combo box is
     * uneditable, it will not change the current selection. For editable 
     * combo boxes, the selection will change to anObject.
     *
     * If this constitutes a change in the selected item, 
     * ItemListeners added to the combo box will be notified with
     * one or two ItemEvents.
     * If there is a current selected item, an ItemEvent will be
     * fired and the state change will be ItemEvent.DESELECTED. 
     * If anObject is in the list and is not currently selected
     * then an ItemEvent will be fired and the state change will 
     * be ItemEvent.SELECTED.
     *
     * ActionListeners added to the combo box will be notified
     * with an ActionEvent when this method is called.
     *
     * @param anObject  the list object to select; use null to
                        clear the selection
     * @beaninfo
     *    preferred:   true
     *    description: Sets the selected item in the JComboBox.
     */
    public void setSelectedItem(Object anObject);

    /**
     * Returns the current selected item.
     *
     * If the combo box is editable, then this value may not have been added
     * to the combo box with addItem, insertItemAt 
     * or the data constructors.
     * 
     * @return the current selected Object
     * @see #setSelectedItem
     */
    public Object getSelectedItem();

    /** 
     * Adds an ItemListener.
     * 
     * aListener will receive one or two ItemEvents when
     * the selected item changes.
     *
     * @param aListener the ItemListener that is to be notified
     * @see #setSelectedItem
     */
    public void addItemListener(ItemListener aListener);

    /** 
     * Adds an ActionListener. 
     *
     * The ActionListener will receive an ActionEvent
     * when a selection has been made. If the combo box is editable, then
     * an ActionEvent will be fired when editing has stopped.
     *
     * @param l  the ActionListener that is to be notified
     * @see #setSelectedItem
     */
    public void addActionListener(ActionListener l);
}

/**
 * A data model for a combo box. This interface extends ListDataModel
 * and adds the concept of a selected item. The selected item is generally
 * the item which is visible in the combo box display area.
 *
 * The selected item may not necessarily be managed by the underlying 
 * ListModel. This disjoint behavior allows for the temporary 
 * storage and retrieval of a selected item in the model.
 *
 * @version 1.11 03/03/00
 * @author Arnaud Weber
 */
public interface ComboBoxModel extends ListModel {

  /** 
   * Set the selected item. The implementation of this  method should notify 
   * all registered ListDataListeners that the contents 
   * have changed. 
   * 
   * @param anItem the list object to select or null 
   *        to clear the selection
   */
  void setSelectedItem(Object anItem);
}

/**
 * A mutable version of ComboBoxModel.
 *
 * @version 1.8 02/02/00
 * @author Tom Santos
 */
public interface MutableComboBoxModel extends ComboBoxModel {

    /**
     * Adds an item at the end of the model. The implementation of this method
     * should notify all registered ListDataListeners that the 
     * item has been added.
     * 
     * @param obj the Object to be added
     */
    public void addElement(Object obj);

    /**
     * Removes an item from the model. The implementation of this method should
     * should notify all registered ListDataListeners that the 
     * item has been removed.
     *
     * @param obj the Object to be removed
     */
    public void removeElement(Object obj);


    /**
     * Adds an item at a specific index.  The implementation of this method
     * should notify all registered ListDataListeners that the 
     * item has been added.
     *
     * @param obj  the Object to be added
     * @param index  location to add the object
     */
    public void insertElementAt(Object obj, int index);

    /**
     * Removes an item at a specific index. The implementation of this method 
     * should notify all registered ListDataListeners that the 
     * item has been removed.
     *
     * @param index  location of object to be removed
     */
    public void removeElementAt(int index);
}

/**
 * Basic UI implementation for JComboBox. 
 *
 * The combo box is a compound component which means that it is an agregate of
 * many simpler components. This class creates and manages the listeners
 * on the combo box and the combo box model. These listeners update the user 
 * interface in response to changes in the properties and state of the combo box.
 *
 * All event handling is handled by listener classes created with the 
 * createxxxListener() methods and internal classes.
 * You can change the behavior of this class by overriding the
 * createxxxListener() methods and supplying your own
 * event listeners or subclassing from the ones supplied in this class.
 *
 * For adding specific actions, 
 * overide installKeyboardActions to add actions in response to
 * KeyStroke bindings. See the article <a href="http://java.sun.com/products/jfc/tsc/special_report/kestrel/keybindings.html">Keyboard Bindings in Swing</a>
 * at <a href="http://java.sun.com/products/jfc/tsc">The Swing Connection</a>.
 *
 * @version %I% %G%
 * @author Arnaud Weber
 * @author Tom Santos
 * @author Mark Davidson
 */
public class BasicComboBoxUI {

    /**
     * This protected field is implementation specific. Do not access directly
     * or override. 
     */
    protected boolean hasFocus;

    /**
     * This protected field is implementation specific. Do not access directly
     * or override. Override the listener construction method instead.
     *
     * @see #createKeyListener
     */
    protected KeyListener keyListener;

    /**
     * This protected field is implementation specific. Do not access directly
     * or override. Override the listener construction method instead.
     *
     * @see #createFocusLisener
     */
    protected FocusListener focusListener;


    /**
     * This protected field is implementation specific. Do not access directly
     * or override. Override the listener construction method instead.
     *
     * @see #createPropertyChangeListener
     */
    protected PropertyChangeListener propertyChangeListener;

    /**
     * This protected field is implementation specific. Do not access directly
     * or override. Override the listener construction method instead.
     *
     * @see #createItemListener
     */
    protected ItemListener itemListener;

    /**
     * This protected field is implementation specific. Do not access directly
     * or override. Override the listener construction method instead.
     *
     * @see #createListDataListener
     */
    protected ListDataListener listDataListener;

    /**
     * Create and install the listeners for the combo box and its model.
     * This method is called when the UI is installed.
     */
    protected void installListeners();

    /**
     * Remove the installed listeners from the combo box and its model.
     * The number and types of listeners removed and in this method should be
     * the same that was added in installListeners
     */
    protected void uninstallListeners();

    /**
     * Creates the popup portion of the combo box.
     *
     * @return an instance of ComboPopup
     * @see ComboPopup
     */
    protected ComboPopup createPopup();

    /**
     * Creates a KeyListener which will be added to the
     * combo box. If this method returns null then it will not be added
     * to the combo box.
     * 
     * @return an instance KeyListener or null
     */
    protected KeyListener createKeyListener();

    /**
     * Creates a FocusListener which will be added to the combo box.
     * If this method returns null then it will not be added to the combo box.
     *
     * @return an instance of a FocusListener or null
     */
    protected FocusListener createFocusListener();

    /**
     * Creates a list data listener which will be added to the
     * ComboBoxModel. If this method returns null then
     * it will not be added to the combo box model.
     *
     * @return an instance of a ListDataListener or null
     */
    protected ListDataListener createListDataListener();
	
    /**
     * Creates an ItemListener which will be added to the 
     * combo box. If this method returns null then it will not 
     * be added to the combo box.
     *
     * Subclasses may override this method to return instances of their own
     * ItemEvent handlers.
     *
     * @return an instance of an ItemListener or null
     */
    protected ItemListener createItemListener();
    
    /**
     * Creates a PropertyChangeListener which will be added to
     * the combo box. If this method returns null then it will not
     * be added to the combo box.
     * 
     * @return an instance of a PropertyChangeListener or null
     */
    protected PropertyChangeListener createPropertyChangeListener();

    /**
     * Creates a layout manager for managing the components which make up the 
     * combo box.
     * 
     * @return an instance of a layout manager
     */
    protected LayoutManager createLayoutManager();

    /**
     * Creates the default renderer that will be used in a non-editiable combo 
     * box. A default renderer will used only if a renderer has not been 
     * explicitly set with setRenderer.
     * 
     * @return a ListCellRender used for the combo box
     * @see javax.swing.JComboBox#setRenderer
     */
    protected ListCellRenderer createRenderer();

    /**
     * Creates the default editor that will be used in editable combo boxes.  
     * A default editor will be used only if an editor has not been 
     * explicitly set with setEditor.
     *
     * @return a ComboBoxEditor used for the combo box
     * @see javax.swing.JComboBox#setEditor
     */
    protected ComboBoxEditor createEditor();

    //
    // Inner classes
    //

    /**
     * This listener watches for changes in the 
     * ComboBoxModel.
     *
     * This public inner class should be treated as protected. 
     * Instantiate it only within subclasses of 
     * BasicComboBoxUI.
     *
     * @see createListDataListener
     */
    public class ListDataHandler implements ListDataListener {}

    /**
     * This listener watches for changes to the selection in the 
     * combo box.
     *
     * This public inner class should be treated as protected. 
     * Instantiate it only within subclasses of 
     * BasicComboBoxUI.
     *
     * @see createItemListener
     */
    public class ItemHandler implements ItemListener {}

    /**
     * This listener watches for bound properties that have changed in the
     * combo box. 
     *
     * Subclasses which wish to listen to combo box property changes should
     * call the superclass methods to ensure that the combo box ui correctly 
     * handles property changes.
     *
     * This public inner class should be treated as protected. 
     * Instantiate it only within subclasses of 
     * BasicComboBoxUI.
     * 
     * @see createPropertyChangeListener
     */
    public class PropertyChangeHandler implements PropertyChangeListener {}

    //
    // end Inner classes
    //====================


    //===============================
    // begin Sub-Component Management
    //

    /**
     * Creates and initializes the components which make up the
     * aggregate combo box. This method is called as part of the UI
     * installation process.
     */
    protected void installComponents();

    /**
     * The aggregate components which compise the combo box are 
     * unregistered and uninitialized. This method is called as part of the
     * UI uninstallation process.
     */
    protected void uninstallComponents();

    /**
     * This public method is implementation specific and should be private.
     * do not call or override. To implement a specific editor create a
     * custom ComboBoxEditor
     *
     * @see createEditor
     * @see javax.swing.JComboBox#setEditor
     * @see javax.swing.ComboBoxEditor
     */
    public void addEditor();

    /**
     * This public method is implementation specific and should be private.
     * do not call or override. 
     *
     * @see addEditor
     */
    public void removeEditor();

    /**
     * This protected method is implementation specific and should be private.
     * do not call or override.
     * 
     * @see addEditor
     */
    protected void configureEditor();

    /**
     * This protected method is implementation specific and should be private.
     * Do not call or override.
     * 
     * @see addEditor
     */
    protected void unconfigureEditor();

    /**
     * This public method is implementation specific and should be private. Do
     * not call or override.
     *
     * @see createArrowButton
     */
    public void configureArrowButton();

    /**
     * This public method is implementation specific and should be private. Do
     * not call or override.
     *
     * @see createArrowButton
     */
    public void unconfigureArrowButton();

    /**
     * Creates an button which will be used as the control to show or hide
     * the popup portion of the combo box.
     *
     * @return a button which represents the popup control
     */
    protected JButton createArrowButton();

    /** 
     * Return the default size of an empty display area of the combo box using
     * the current renderer and font.
     *
     * @return the size of an empty display area
     * @see getDisplaySize
     */
    protected Dimension getDefaultSize();

    /** 
     * Returns the calculated size of the display area. The display area is the
     * portion of the combo box in which the selected item is displayed. This 
     * method will use the prototype display value if it has been set. 
     *
     * For combo boxes with a non trivial number of items, it is recommended to
     * use a prototype display value to significantly speed up the display 
     * size calculation.
     * 
     * @return the size of the display area calculated from the combo box items
     * @see javax.swing.JComboBox#setPrototypeDisplayValue
     */
    protected Dimension getDisplaySize();

}

/**
 * The interface which defines the methods required for the implementation of the popup
 * portion of a combo box.
 *
 * Warning:
 * Serialized objects of this class will not be compatible with
 * future Swing releases.  The current serialization support is appropriate
 * for short term storage or RMI between applications running the same
 * version of Swing.  A future release of Swing will provide support for
 * long term persistence.
 *
 * @version 1.9 02/02/00
 * @author Tom Santos
 */
public interface ComboPopup {

    /**
     * Returns true if the popup is visible (currently being displayed).
     * 
     * @return true if the component is visible; false otherwise.
     */
    public boolean isVisible();

    /**
     * Returns the list that is being used to draw the items in the JComboBox.
     */
    public JList getList();

    /**
     * Returns a mouse listener that will be added to the combo box.
     *
     * @see ComboPopup#getMouseListener
     */
    public MouseListener getMouseListener();

    /**
     * Returns a mouse motion listener that will be added to the combo box or null.
     *
     * @see ComboPopup#getMouseMotionListener
     */
    public MouseMotionListener getMouseMotionListener();

    /**
     * Returns a key listener that shows and hides the popup.
     *
     * @param a KeyListener or null
     */
    public KeyListener getKeyListener();
}

/**
 * This is a basic implementation of the ComboPopup interface.
 * 
 * This class represents the ui for the popup portion of the combo box.
 *
 * All event handling is handled by listener classes created with the 
 * createxxxListener() methods and internal classes.
 * You can change the behavior of this class by overriding the
 * createxxxListener() methods and supplying your own
 * event listeners or subclassing from the ones supplied in this class.
 *
 * Warning:
 * Serialized objects of this class will not be compatible with
 * future Swing releases.  The current serialization support is appropriate
 * for short term storage or RMI between applications running the same
 * version of Swing.  A future release of Swing will provide support for
 * long term persistence.
 *
 * @version %I% %G%
 * @author Tom Santos
 */
public class BasicComboPopup extends JPopupMenu implements ComboPopup {

    /**
     * This protected field is implementation specific. Do not access directly
     * or override. Use the accessor methods instead.
     *
     * @see #getList
     * @see #createList
     */
    protected JList                    list;

    /**
     * This protected field is implementation specific. Do not access directly
     * or override. Use the create method instead
     *
     * @see #createScroller
     */
    protected JScrollPane              scroller;

    /**
     * As of Java 2 platform v1.4 this previously undocumented field is no
     * longer used. Do not use or override.
     */
    protected boolean                  valueIsAdjusting = false;

    /**
     * This protected field is implementation specific. Do not access directly
     * or override. Use the accessor or create methods instead.
     *
     * @see #getMouseMotionListener
     * @see #createMouseMotionListener
     */
    protected MouseMotionListener      mouseMotionListener;

    /**
     * This protected field is implementation specific. Do not access directly
     * or override. Use the accessor or create methods instead.
     *
     * @see #getMouseListener
     * @see #createMouseListener
     */
    protected MouseListener            mouseListener;

    /**
     * This protected field is implementation specific. Do not access directly
     * or override. Use the accessor or create methods instead.
     *
     * @see #getKeyListener
     * @see #createKeyListener
     */
    protected KeyListener              keyListener;

    /**
     * This protected field is implementation specific. Do not access directly
     * or override. Use the create method instead.
     *
     * @see #createListSelectionListener
     */
    protected ListSelectionListener    listSelectionListener;

    /**
     * This protected field is implementation specific. Do not access directly
     * or override. Use the create method instead
     *
     * @see #createListMouseListener
     */
    protected MouseListener            listMouseListener;

    /**
     * This protected field is implementation specific. Do not access directly
     * or override. Use the create method instead
     *
     * @see #createListMouseMotionListener
     */
    protected MouseMotionListener      listMouseMotionListener;

    /**
     * This protected field is implementation specific. Do not access directly
     * or override. Use the create method instead
     *
     * @see #createPropertyChangeListener
     */
    protected PropertyChangeListener   propertyChangeListener;

    /**
     * This protected field is implementation specific. Do not access directly
     * or override. Use the create method instead
     *
     * @see #createListDataListener
     */
    protected ListDataListener         listDataListener;

    /**
     * This protected field is implementation specific. Do not access directly
     * or override. Use the create method instead
     *
     * @see #createItemListener
     */
    protected ItemListener             itemListener;

    /**
     * This protected field is implementation specific. Do not access directly
     * or override. 
     */
    protected Timer                    autoscrollTimer;

    /**
     * Implementation of ComboPopup.getMouseListener().
     * 
     * @param a MouseListener or null
     * @see ComboPopup#getMouseListener
     */
    public MouseListener getMouseListener();

    /**
     * Implementation of ComboPopup.getMouseMotionListener().
     *
     * @param a MouseMotionListener or null
     * @see ComboPopup#getMouseMotionListener
     */
    public MouseMotionListener getMouseMotionListener();

    /**
     * Implementation of ComboPopup.getKeyListener(). 
     * 
     * @param a KeyListener or null
     * @see ComboPopup#getKeyLisener
     */
    public KeyListener getKeyListener();

    /** 
     * Installs the listeners on the combo box model. Any listeners installed
     * on the combo box model should be removed in 
     * uninstallComboBoxModelListeners.
     *
     * @param model The combo box model to install listeners
     * @see uninstallComboBoxModelListeners
     */
    protected void installComboBoxModelListeners( ComboBoxModel model ) {

    /** 
     * Removes the listeners from the combo box model
     *
     * @param model The combo box model to install listeners
     * @see installComboBoxModelListeners
     */
    protected void uninstallComboBoxModelListeners( ComboBoxModel model );

    /**
     * Creates the mouse listener which will be added to the combo box
     * that watches for mouse clicks and releases. 
     * 
     * Warning:
     * When overriding this method, make sure to maintain the existing
     * behavior.
     *
     * @return a MouseListener which will be added to 
     * the combo box or null
     */
    protected MouseListener createMouseListener();

    /**
     * Creates the mouse motion listener which will be added to the combo
     * box.
     *
     * Warning:
     * When overriding this method, make sure to maintain the existing
     * behavior.
     *
     * @return a MouseMotionListener which will be added to
     *         the combo box or null
     */
    protected MouseMotionListener createMouseMotionListener();

    /**
     * Creates the key listener that will be added to the combo box. If 
     * this method returns null then it will not be added to the combo box.
     *
     * @return a KeyListener or null
     */
    protected KeyListener createKeyListener();

    /**
     * Creates a list selection listener that watches for selection changes in
     * the popup's list.  If this method returns null then it will not
     * be added to the popup list.
     *
     * @return an instance of a ListSelectionListener or null
     */
    protected ListSelectionListener createListSelectionListener() {

    /**
     * Creates a list data listener which will be added to the
     * ComboBoxModel. If this method returns null then
     * it will not be added to the combo box model.
     *
     * @return an instance of a ListDataListener or null
     */
    protected ListDataListener createListDataListener();

    /**
     * Creates a mouse listener that watches for mouse events in
     * the popup's list. If this method returns null then it will
     * not be added to the combo box.
     *
     * @return an instance of a MouseListener or null
     */
    protected MouseListener createListMouseListener();

    /**
     * Creates a mouse motion listener that watches for mouse motion 
     * events in the popup's list. If this method returns null then it will
     * not be added to the combo box.
     *
     * @return an instance of a MouseMotionListener or null
     */
    protected MouseMotionListener createListMouseMotionListener();

    /**
     * Creates a PropertyChangeListener which will be added to
     * the combo box. If this method returns null then it will not
     * be added to the combo box.
     * 
     * @return an instance of a PropertyChangeListener or null
     */
    protected PropertyChangeListener createPropertyChangeListener();

    /**
     * Creates an ItemListener which will be added to the 
     * combo box. If this method returns null then it will not 
     * be added to the combo box.
     *
     * Subclasses may override this method to return instances of their own
     * ItemEvent handlers.
     *
     * @return an instance of an ItemListener or null
     */
    protected ItemListener createItemListener();

    /**
     * Creates the JList used in the popup to display 
     * the items in the combo box model. This method is called when the UI class
     * is created.
     *
     * @return a JList used to display the combo box items
     */
    protected JList createList();

    /**
     * Configures the list which is used to hold the combo box items in the
     * popup. This method is called when the UI class
     * is created.
     *
     * @see createList
     */
    protected void configureList();

    /**
     * Adds the listeners to the list control
     */
    protected void installListListeners();
    // NOTE: The uninstallListListeners() is package private so overloaded
    // methods should be responsible for thier own listener de-registration.

    /**
     * Configures the scrollable portion which holds the list within 
     * the combo box popup. This method is called when the UI class
     * is created.
     */
    protected void configureScroller();

    /**
     * Configures the popup portion of the combo box. This method is called
     * when the UI class is created.
     */
    protected void configurePopup();


    /**
     * As of JDK 1.4, this class is now obsolete and is only included for
     * backwards API compatibility. Do not instantiate or subclass.
     *
     * All the functionality of this class has been included in 
     * BasicComboBoxUI ActionMap/InputMap methods.
     */
    public class InvocationKeyHandler extends KeyAdapter {}

    /**
     * As of JDK 1.4, this class is now obsolete and doesn't do anything and
     * is only included for backwards API compatibility. Do not call or 
     * override.
     */
    protected class ListSelectionHandler implements ListSelectionListener {}


    /**
     * As of JDK 1.4, this class is now obsolete and doesn't do anything and
     * is only included for backwards API compatibility. Do not call or 
     * override. 
     *
     * The functionality has been migrated into ItemHandler.
     *
     * @see createItemListener
     */
    public class ListDataHandler implements ListDataListener;

    /**
     * This listener watches for changes to the selection in the 
     * combo box.
     */
    protected class ItemHandler implements ItemListener;


    /**
     * This listener watches for bound properties that have changed in the
     * combo box. 
     *
     * Subclasses which wish to listen to combo box property changes should
     * call the superclass methods to ensure that the combo popup correctly 
     * handles property changes.
     * 
     * @see createPropertyChangeListener
     */
    protected class PropertyChangeHandler implements PropertyChangeListener;


    /**
     * This protected method is implementation specific and should be private.
     * do not call or override.
     */
    protected void startAutoScrolling( int direction );

    /**
     * This protected method is implementation specific and should be private.
     * do not call or override.
     */
    protected void stopAutoScrolling();

    /**
     * This protected method is implementation specific and should be private.
     * do not call or override.
     */
    protected void autoScrollUp();

    /**
     * This protected method is implementation specific and should be private.
     * do not call or override.
     */
    protected void autoScrollDown();
}

JFileChooser

Add following to javax.swing.plaf.metal.MetalFileChooserUI

    /**
     * Creates a selection listener for the list of files and directories.
     *
     * @param fc a JFileChooser
     * @return a ListSelectionListener
     */
    public ListSelectionListener createListSelectionListener(JFileChooser fc)

Add the following to javax.swing.filechooser.FileSystemView:

    /**
     * Returns true if the file (directory) can be visited.
     * Returns false if the directory cannot be traversed.
     *
     * @param f the File
     * @return true if the file/directory can be traversed, otherwise false
     * @see JFileChooser#isTraversable
     * @see FileView#isTraversable
     * @since 1.4
     */
    public Boolean isTraversable(File f);

    /**
     * Name of a file, directory, or folder as it would be displayed in
     * a system file browser. Example from Windows: the "M:\" directory
     * displays as "CD-ROM (M:)"
     *
     * The default implementation gets information from the ShellFolder class.
     *
     * @param f a File object
     * @return the file name as it would be displayed by a native file chooser
     * @see JFileChooser#getName
     * @since 1.4
     */
    public String getSystemDisplayName(File f);

    /**
     * Type description for a file, directory, or folder as it would be displayed in
     * a system file browser. Example from Windows: the "Desktop" folder
     * is desribed as "Desktop".
     *
     * Override for platforms with native ShellFolder implementations.
     *
     * @param f a File object
     * @return the file type description as it would be displayed by a native file chooser
     * or null if no native information is available.
     * @see JFileChooser#getTypeDescription
     * @since 1.4
     */
    public String getSystemTypeDescription(File f);

    /**
     * Icon for a file, directory, or folder as it would be displayed in
     * a system file browser. Example from Windows: the "M:\" directory
     * displays a CD-ROM icon.
     *
     * The default implementation gets information from the ShellFolder class.
     *
     * @param f a File object
     * @return an icon as it would be displayed by a native file chooser
     * @see JFileChooser#getIcon
     * @since 1.4
     */
    public Icon getSystemIcon(File f);

    /**
     * On Windows, a file can appear in multiple folders, other than its
     * parent directory in the filesystem. Folder could for example be the
     * "Desktop" folder which is not the same as file.getParentFile().
     *
     * @param folder a File object repesenting a directory or special folder
     * @param file a File object
     * @return true if folder is a directory or special folder and contains file.
     * @since 1.4
     */
    public boolean isParent(File folder, File file);

    /**
     *
     * @param parent a File object repesenting a directory or special folder
     * @param fileName a name of a file or folder which exists in parent
     * @return a File object. This is normally constructed with new
     * File(parent, fileName) except when parent and child are both
     * special folders, in which case the File is a wrapper containing
     * a ShellFolder object.
     * @since 1.4
     */
    public File getChild(File parent, String fileName);

    /*
     * Checks if f represents a real directory or file as opposed to a
     * special folder such as "Desktop". Used by UI classes to decide if
     * a folder is selectable when doing directory choosing.
     *
     * @param f a File object
     * @return true if f is a real file or directory.
     * @since 1.4
     */
    public boolean isFileSystem(File f);

    /*
     * Is dir the root of a tree in the file system, such as a drive
     * or partition. Example: Returns true for "C:\" on Windows 98.
     * 
     * @See also isRoot
     * @since 1.4
     */
    public boolean isFileSystemRoot(File dir);

    /*
     * Used by UI classes to decide whether to display a special icon
     * for drives or partitions, e.g. a "hard disk" icon.
     *
     * The default implementation has no way of knowing, so always returns false.
     *
     * @param dir a directory
     * @return false always
     * @since 1.4
     */
    public boolean isDrive(File dir);

    /*
     * Used by UI classes to decide whether to display a special icon
     * for a floppy disk. Implies isDrive(dir).
     *
     * The default implementation has no way of knowing, so always returns false.
     *
     * @param dir a directory
     * @return false always
     * @since 1.4
     */
    public boolean isFloppyDrive(File dir);

    /*
     * Used by UI classes to decide whether to display a special icon
     * for a computer node, e.g. "My Computer" or a network server.
     *
     * The default implementation has no way of knowing, so always returns false.
     *
     * @param dir a directory
     * @return false always
     * @since 1.4
     */
    public boolean isComputerNode(File dir);

    /**
     * Creates a new File object for f with correct
     * behavior for a file system root directory.
     *
     * @param f a File object
     * @return a new File object
     * @see #FileSystemRoot
     * @since 1.4
     */
    protected File createFileSystemRoot(File f) {

Also, the method getRoots has been changed to be concrete.

Updated javdoc of following methods in javax.swing.plaf.basic.BasicDirectoryModel:

    /**
     * Obsolete - not used.
     */
    public void intervalAdded(ListDataEvent e);

    /**
     * Obsolete - not used.
     */
    public void intervalRemoved(ListDataEvent e);

Add following to javax.swing.plaf.basic.BasicDirectoryModel:

    /**
     * Renames a file in the underlying file system.
     *
     * @param oldFile a File object representing the existing file.
     * @param newFile a File object representing the desired new file name.
     * @return true if rename succeeded, otherwise false
     */
    public boolean renameFile(File oldFile, File newFile) {

Javadoc for specifying characteristics of open directory button in JFileChooser:

    /**
     * Mnemonic to use for the open directory button. The value of
     * this is initialized when installed in a JFileChooser from the
     * UI defaults table value
     * FileChooser.directoryOpenButtonMnemonic
     * @since 1.4
     */
    protected int directoryOpenButtonMnemonic = 0;
    /**
     * Text for the open directory button. The value of
     * this is initialized when installed in a JFileChooser from the
     * UI defaults table value
     * FileChooser.directoryOpenButtonText
     * @since 1.4
     */
    protected String directoryOpenButtonText = null;

    /**
     * Tooltip text for the open directory button. The value of
     * this is initialized when installed in a JFileChooser from the
     * UI defaults table value
     * FileChooser.directoryOpenButtonText
     * @since 1.4
     */
    protected String directoryOpenButtonToolTipText = null;

    /**
     * Returns true if the user has currently selected a directory.
     *
     * @return true if a directory is selected
     * @since 1.4
     */
    protected boolean isDirectorySelected()

    /**
     * Set when the user changes the selection. If the user has selected a
     * directory, true will be passed in.
     *
     * @param b indicates if a directory has been selected
     * @since 1.4
     */
    protected void setDirectorySelected(boolean b);

    /**
     * Directory the user has selected.
     *
     * @return the directory the user has selected
     * @since 1.4
     */
    protected File getDirectory()

    /**
     * Sets the directory the user has selected. If the user has selected a
     * file null will be passed in.
     *
     * @param f selected directory
     * @since 1.4
     */
    protected void setDirectory(File f)

JInternalFrame

JInternalFrame should truncate titles that are too long

Add the following to BasicInternalFrameTitlePane:

    /**
     * Returns the text that should be displayed as the title of the
     * JInternalFrame. If text does not fit
     * in the available space this will truncate the String until the
     * truncated String plus '...' will fit in the available
     * space.
     * 
     * If text is null, this will return an empty string.
     *
     * @param text Current title of the JInternalFrame
     * @param fm FontMetrics associated with the Font that will be used to
     *           render the text.
     * @param availTextWidth Width available for the string.
     * @return String to display for the text.
     * @since 1.4
     */
    protected String getTitle(String text, FontMetrics fm, int availTextWidth);

JInternalFrame Titles in Windows Look and Feel should be rendered with a gradient

   /**
    * Invoked from paintComponent.
    * Paints the background of the titlepane.  All text and icons will
    * then be rendered on top of this background.
    * @param g the graphics to use to render the background
    * @since 1.4
    */
    protected void paintTitleBackground(Graphics g) 

JTextComponent

Tooltips for Images in JEditorPane

To make it possible for Views to effect the tooltip text, a number of methods were needed. First, TextUI needed a method to get the tooltip text for a particular location:

Added getToolTipText Method to javax.swing.plaf.TextUI

/**
 * Returns the string to be used as the tooltip at the passed in location.
 *
 * @see javax.swing.text.JTextComponent#getToolTipText
 * @since 1.4
 */
public String getToolTipText(JTextComponent t, Point pt)
    

JTextComponent's getToolTipText method then forwards to the TextUI, assuming a tooltip was not set on the JTextComponent.

Second, the Views needed a way to be able to specify tooltip text:

Added getToolTipText Method to javax.swing.text.View

/**
 * Returns the tooltip text at the specified location. The default
 * implementation returns the value from the child View identified by
 * the passed in location.
 *
 * @since 1.4
 * @see JTextComponent#getToolTipText
 */
public String getToolTipText(float x, float y, Shape allocation)

    

The default implementation of View.getToolTipText will forward the request to the Views child at the given location. To make it easy to determine the child at a particular location, the following method was added:

Added getViewIndex Method to javax.swing.text.View

/**
 * Returns the child view index representing the given position in
 * the view. This iterates over all the children returning the
 * first with a bounds that contains x, y.
 *
 * @param x the x coordinate
 * @param y the y coordinate
 * @param allocation current allocation of the View
 * @return  index of the view representing the given location, or 
 *   -1 if no view represents that position
 * @since 1.4
 */
public int getViewIndex(float x, float y, Shape allocation)
    

The View implementation invokes getViewIndex and then getToolTipText on the child View. ImageView then overrides getToolTipText and returns the value from the ALT attribute of its AttributeSet.

Class text.html.ImageView should be public

/**
 * View of an Image, intended to support the HTML <IMG> tag.
 * Supports scaling via the HEIGHT and WIDTH attributes of the tag.
 * If the image is unable to be loaded any text specified via the
 * ALT attribute will be rendered.
 *
 * While this class has been part of swing for a while now, it is 
 * public as of 1.4.
 *  
 * @since 1.4
 */
    

New HyperlinkEvent Read-Only elementOffset Property

Changes to javax.swing.event.HyperlinkEvent

    /**
     * Creates a new object representing a hypertext link event.
     *
     * @param source the object responsible for the event
     * @param type the event type
     * @param u the affected URL.  This may be null if a valid URL
     *   could not be created.
     * @param desc the description of the link.  This may be useful
     *   when attempting to form a URL resulted in a MalformedURLException.
     *   The description provides the text used when attempting to form the
     *   URL.
     * @param sourceElement Element in the Document representing the
     *   anchor
     * @since 1.4
     */
    public HyperlinkEvent(Object source, EventType type, URL u, String desc,
                          Element sourceElement);

    /**
     * Returns the Element that corresponds to the source of the
     * event. This will typically be an Element representing
     * an anchor. If a constructur that is used that does not specify a source
     * Element, or null was specified as the source
     * Element, this will return null.
     *
     * @return Element indicating source of event, or null
     * @since 1.4
     */
    public Element getSourceElement();

HTMLFrameHyperlinkEvent extends HyperlinkEvent. It already defines the method getSourceElement. As the superclass will now define this method, the following javadoc will be removed from HTMLFrameHyperlinkEvent (the method will now be inherited):

     /**
      * Returns the element that corresponds to the source of the
      * event.  This would always be the leaf element whose
      * tag is HTML.Tag.FRAME.
      */
     public Element getSourceElement();

Changes to javax.swing.text.html.HTMLFrameHyperlinkEvent

/**
 * Creates a new object representing a hypertext link event.
 *
 * @param source the object responsible for the event
 * @param type the event type
 * @param targetURL the affected URL
 * @param desc a description
 * @param targetFrame the Frame in which to display the document 
 * @param offset Start of the Element in the Document representing the
 *   anchor
 * @since 1.4
 */
public HTMLFrameHyperlinkEvent(Object source, EventType type, URL targetURL, String desc,  
			       String targetFrame, int offset)
    

Static DefaultPainter in javax.swing.text.DefaultHighlighter now Final

/**
 * Default implementation of LayeredHighlighter.LayerPainter
 * that can be used for painting highlights.
 * 
 * As of 1.4 this is final.
 */
public static final LayeredHighlighter.LayerPainter DefaultPainter = xxx;
    

Document.getText should allow for partial returns

Changes to javax.swing.text.Segment:

  /**
   * Flag to indicate that partial returns are valid.  If the flag is true,
   * an implementation of the interface method Document.getText(position,length,Segment)
   * should return as much text as possible without making a copy.  The default
   * state of the flag is false which will cause Document.getText(position,length,Segment)
   * to provide the same return behavior it currently does, which may or may not
   * make a copy of the text depending upon the request.
   *
   * @param p whether or not partial returns are valid.
   * @since 1.4
   */
  public void setPartialReturn(boolean b) {
  }

  /**
   * Flag to indicate that partial returns are valid.
   *
   * @return whether or not partial returns are valid.
   * @since 1.4
   */
  public boolean isPartialReturn() {
  }

JEditorPane should provide HTML accessibility support

The following will be added to javax.swing.text.html.HTMLEditorKit:

    /**
     * Returns the AccessibleContext associated with this
     * editor kit.
     *
     * @return the AccessibleContext associated with this
     * editor kit.
     * @since 1.4
     */
    public AccessibleContext getAccessibleContext();

JOptionPane

New showInputDialog methods

/**
 * Shows a question-message dialog requesting input from the user, with
 * the input value initialized to initialSelectionValue. The 
 * dialog uses the default frame, which usually means it is centered on 
 * the screen. 
 *
 * @param message the Object to display
 * @param initialSelectionValue the value used to initialize the input field
 */
public static String showInputDialog(Object message, 
				     Object initialSelectionValue)

/**
 * Shows a question-message dialog requesting input from the user and
 * parented to parentComponent. The input value will be
 * initialized to initialSelectionValue.
 * The dialog is displayed on top of the Component's
 * frame, and is usually positioned below the Component.  
 *
 * @param parentComponent  the parent Component for the dialog
 * @param message the Object to display
 * @param initialSelectionValue the value used to initialize the input field
 */
public static String showInputDialog(Component parentComponent, 
				     Object message, 
				     Object initialSelectionValue) 
    	                                 
    

JOptionPane should support ComponentOrientation

 * The basic appearance of one of these dialog boxes is generally
 * similar to the picture at the right, although the various
 * look-and-feels are
 * ultimately responsible for the final result.  In particular, the
 * look-and-feels will adjust the layout to accomodate the option pane's
 * ComponentOrientation property.

Update javadoc for javax.swing.plaf.BasicOptionPaneUI

/**
 * Provides the basic look and feel for a JOptionPane.
 * BasicMessagePaneUI provides a means to place an icon,
 * message and buttons into a Container.
 * Generally, the layout will look like:

 * 
 *        ------------------
 *        | i | message    |
 *        | c | message    |
 *        | o | message    |
 *        | n | message    |
 *        ------------------
 *        |     buttons    |
 *        |________________|
 *
 * icon is an instance of Icon that is wrapped inside a
 * JLabel.  The message is an opaque object and is tested
 * for the following: if the message is a Component it is
 * added to the Container, if it is an Icon
 * it is wrapped inside a JLabel and added to the 
 * Container otherwise it is wrapped inside a JLabel.
 *
 * The above layout is used when the option pane's 
 * ComponentOrientation property is horizontal, left-to-right.
 * The layout will be adjusted appropriately for other orientations.
 *

JPanel

Added setUI, getUI Methods

    /**
     * Returns the look and feel (L&F) object that renders this component.
     *
     * @return the PanelUI object that renders this component
     * @since 1.4
     */
    public PanelUI getUI()

    /**
     * Sets the look and feel (L&F) object that renders this component.
     *
     * @param ui  the PanelUI L&F object
     * @see UIDefaults#getUI
     * @since 1.4
     */
    public void setUI(PanelUI ui)
    

JTabbedPane

Added indexAtLocation Method to JTabbedPane

/**
 * Returns the tab index corresponding to the tab whose bounds 
 * intersect the specified location.  Returns -1 if no tab
 * intersects the location.
 *
 * @param x the x location relative to this tabbedpane
 * @param y the y location relative to this tabbedpane
 * @return the tab index which intersects the location, or
 *         -1 if no tab intersects the location
 * @since 1.4
 */
public int indexAtLocation(int x, int y)
    

Need mnemonic support for accessing tabs in a JTabbedPane

Add the following to javax.swing.JTabbedPane

    /**
     * Returns the index of the character that is underlined in the
     * mnemonic string for the specified tab index.
     * The mnemonic is the key which when combined with the look&feel's
     * mouseless modifier (usually Alt) will cause the tab at the
     * specified index to become selected if focus is contained
     * somewhere within this tabbed pane's ancestor window.
     *
     * A mnemonic corresponds to a single key on the keyboard
     * and is specified using one of the VK_XXX
     * keycodes defined in java.awt.event.KeyEvent.
     * Mnemonics are case-insensitive, therefore a key event
     * with the corresponding keycode would cause the tab to be
     * selected whether or not the Shift modifier was pressed.
     *
     * @param index the tab index
     * @return  the index of the character that is underlined in the
     * mnemonic string for the specified tab index if the mnemonic
     * exists.  Otherwise, returns -1.
     * @exception IllegalArgumentException if index is out of bounds
     * @see java.awt.event.KeyEvent
     */
    public int getDisplayedMnemonicAt(int index);

    /**
     * Sets the index of the character that is underlined in the
     * mnemonic string for the specified tab index.
     * The mnemonic is the key which when combined with the look&feel's
     * mouseless modifier (usually Alt) will cause the tab at the
     * specified index to become selected if focus is contained
     * somewhere within this tabbed pane's ancestor window.
     *
     * A mnemonic must correspond to a single key on the keyboard
     * and should be specified using one of the VK_XXX
     * keycodes defined in java.awt.event.KeyEvent.
     * Mnemonics are case-insensitive, therefore a key event
     * with the corresponding keycode would cause the tab to be
     * selected whether or not the Shift modifier was pressed.
     *
     * If the character defined by the mnemonic is found within
     * the tab's label string, the first occurrence of it
     * will be underlined to indicate the mnemonic to the user.
     *
     * @param index the tab index for the mnemonic
     * @param mnemonicIndex index of the character that is underlined in the
     * mnemonic string for the specified tab index
     * @exception IllegalArgumentException if either index is out of bounds
     * @see java.awt.event.KeyEvent
     *
     * @beaninfo
     *        bound: true
     *    attribute: visualUpdate true
     *  description: the keyboard character mnemonic
     */
    public void setDisplayedMnemonicAt(int index, int mnemonicIndex);

Exceptions thrown by JTabbedPane are inconsistent.

Any method which takes an index that must be in the valid range from 0 to tabCount-1 will document that it throws an IndexOutOfBoundsException (note: the underlying code will continue to throw ArrayIndexOutOfBoundsException for compatibility reasons).

The following doc change:

       * @exception IndexOutOfBoundsException if index is out of range 
       *            (index < 0 || index >= tab count)

Will be applied to the following javax.swing.JTabbedPane methods (which currently incorrectly documents throwing IllegalParameterException):

    public String getTitleAt(int index) 
    public Icon getIconAt(int index) 
    public Icon getDisabledIconAt(int index)
    public String getToolTipTextAt(int index)
    public int getBackgroundAt(int index)
    public Color getForegroundAt(int index)
    public boolean isEnabledAt(int index)
    public Component getComponentAt(int index)
    public int getDisplayedMnemonicIndexAt(int tabIndex)
    public Rectangle getBoundsAt(int index)
    public void setTitleAt(int index, String title)
    public void setIconAt(int index, Icon icon) 
    public void setDisabledIconAt(int index, Icon disabledIcon)
    public void setToolTipTextAt(int index, String toolTipText)
    public void setForegroundAt(int index, Color foreground)
    public void setBackgroundAt(int index, Color background)
    public void setEnabledAt(int index, boolean enabled)
    public void setComponentAt(int index, Component component)
    public void setDisplayedMnemonicIndexAt(int tabIndex, int mnemonicIndex)

Additionally, we will add the same exception handling to the following methods which do nothing currently:

    public void setSelectedIndex(int index)
    public void removeTabAt(int index)
    public void remove(int index)

JTable

DefaultTableModel.moveRow Specification Clarified

Here is the javadoc for moveRow in release 1.3:

/**
 *  Moves one or more rows starting at startIndex to endIndex
 *  in the model to the toIndex.    This method will send a
 *  tableChanged notification message to all the listeners. 

 *
 *  Examples of moves:

 *  1. moveRow(1,3,5);

 *          a|B|C|D|e|f|g|h|i|j|k   - before
 *          a|e|f|B|C|D|g|h|i|j|k   - after
 *  2. moveRow(6,7,1);

 *          a|b|c|d|e|f|G|H|i|j|k   - before
 *          a|G|H|b|c|d|e|f|i|j|k   - after
 *
 * @param   startIndex       the starting row index to be moved
 * @param   endIndex         the ending row index to be moved
 * @param   toIndex          the destination of the rows to be moved
 * @exception  ArrayIndexOutOfBoundsException  if any of the indices are out of
 *                           range; or if endIndex is less than startIndex
 */
public void moveRow(int startIndex, int endIndex, int toIndex)
    

Here is the new javadoc for moveRow in release 1.4:

/**
 *  Moves one or more rows from the inclusive rangestart to 
 *  end to the to position in the model. 
 *  After the move, the row that was at index start 
 *  will be at index to. 
 *  This method will send a tableChanged notification
 *  message to all the listeners. 

 *
 *  Examples of moves:
 *  1. moveRow(1,3,5);
 *          a|B|C|D|e|f|g|h|i|j|k   - before
 *          a|e|f|g|h|B|C|D|i|j|k   - after
 *  2. moveRow(6,7,1);
 *          a|b|c|d|e|f|G|H|i|j|k   - before
 *          a|G|H|b|c|d|e|f|i|j|k   - after
 *
 * @param   start       the starting row index to be moved
 * @param   end         the ending row index to be moved
 * @param   to          the destination of the rows to be moved
 * @exception  ArrayIndexOutOfBoundsException  if any of the elements 
 * would be moved out of the table's range 
 * 
 */
public void moveRow(int start, int end, int to)
  

Typing into a JTable fails to tranfer focus to the cell

Add the following to javax.swing.JTable

    /** 
     * Sets whether editors in this JTable get the keyboard focus
     * when an editor is activated as a result of the JTable
     * forwarding keyboard events for a cell.
     * By default, this property is false, and the JTable
     * retains the focus unless the cell is clicked.
     *
     * @param b true if the editor should get the focus
     *          when keystrokes cause the editor to be
     *          activated
     * 
     *
     * @see #getSurrendersFocusOnKeystroke
     */ 
    public void setSurrendersFocusOnKeystroke(boolean b);
    
    /**
     * Returns true if the editor should get the focus
     * when keystrokes cause the editor to be activated
     * 
     * @return  true if the editor should get the focus
     *          when keystrokes cause the editor to be
     *          activated
     *
     * @see #setSurrendersFocusOnKeystroke
     */ 
    public boolean getSurrendersFocusOnKeystroke();

JTree

DefaultTreeModel Now Allows a Null Root

The old DefaultTreeModel.setRoot javadoc was:

/**
 * Sets the root to root. This will throw an
 * IllegalArgumentException if root is
 * null.
 */
public void setRoot(TreeNode root)
    

The new DefaultTreeModel.setRoot javadoc is:

/**
 * Sets the root to root. A null
 * root implies
 * the tree is to display nothing, and is legal.
 */
public void setRoot(TreeNode root)
    

Add first letter navigation to JTree

Add the following to javax.swing.JTree:

    /**
     * Returns the TreePath to the next tree element that 
     * begins with a prefix. To handle the conversion of a
     * TreePath into a String, convertValueToText
     * is used.
     *
     * @param prefix the string to test for a match
     * @param startingRow the row for starting the search
     * @param bias the search direction, either 
     * Position.Bias.Forward or Position.Bias.Backward.
     * @return the TreePath of the next tree element that
     * starts with the prefix; otherwise null
     * @exception IllegalArgumentException if prefix is null
     * or startingRow is out of bounds 
     * @since 1.4
     */
    public TreePath getNextMatch(String prefix, int startingRow,
				 Position.Bias bias) {

JList

ListDataEvent.toString does not provide any useful information

  /**
   * Returns a string representation of this ListDataEvent.
   * This method is intended to be used only for debugging purposes, and the
   * content and format of the returned string may vary between
   * implementations. The returned string may be empty but may not
   * be null.
   *
   * @since 1.4
   * @return  a string representation of this ListDataEvent
   */
   public String toString()

JList should support first letter key navigation

Add the following to javax.swing.JList:

    /**
     * Returns the next list element that starts with 
     * a prefix.
     *
     * @param prefix the string to test for a match
     * @param startIndex the index for starting the search
     * @param bias the search direction, either 
     * Position.Bias.Forward or Position.Bias.Backward.
     * @return the index of the next list element that
     * starts with the prefix; otherwise -1
     * @exception IllegalArgumentException if prefix is null
     * or startIndex is out of bounds
     * @since 1.4
     */
    public int getNextMatch(String prefix, int startIndex, Position.Bias bias) {

BasicListUI will then install a KeyListener that will invoke this method as keys are typed to update the selection.

Allow JList items to be arranged horizontally

Add the following to javax.swing.JList:

    /** 
     * Indicates the default layout: one column of cells.
     * @see #setLayoutOrientation.
     * @since 1.4
     */
    public static final int VERTICAL = SwingConstants.VERTICAL;

    /** 
     * Indicates "newspaper style" layout: fixed number of rows with
     * and arbitrary number of columns.
     * @see #setLayoutOrientation.
     * @since 1.4
     */
    public static final int HORIZONTAL = SwingConstants.HORIZONTAL;

    /**
     * Returns JList.VERTICAL if the layout is a single
     * column of cells, or JList.HORIZONTAL if the layout
     * is "newspaper style", that's a fixed number of rows and an 
     * arbitrary number of columns.
     * 
     * @return the value of the layoutOrientation property
     * @see #setLayoutOrientation
     * @since 1.4
     */
    public int getLayoutOrientation();

    /**
     * Defines the way list cells are layed out.  If the value of
     * layoutOrientation is JList.VERTICAL then list cells are
     * arranged in a single column, one cell per row.  The widest cell
     * defines the preferred width of the list
     * and the preferred height of the list is the sum of the preferred heights
     * of the cells (rows).  If the value of layoutOrientation is 
     * JList.HORIZONTAL then visibleRowCount rows
     * will be displayed and as many columns as needed.  This layout is
     * similar to the way lines of text are packed into newspaper columns.
     * For example if there were 11 cells and visibleRowCount
     * was 3, the cells would be arranged in four columns like this:
     * <pre>
     *     0    3    6    9
     *     1    4    7    10   
     *     2    5    8
     * </pre>
     * If the visibleRowCount is less than zero, than the
     * number of rows per column will be determined by the height of the
     * JList. This is often useful when the JList
     * is contained within a JScrollPane and you wish to
     * only have horizontal scrollbars.
     *
     * The default value of this property is JList.VERTICAL.
     *
     * This will throw an IllegalArgumentException if 
     * layoutOrientation is not one of
     * JList.HORIZONTAL or JList.VERTICAL.
     *
     * @param layoutOrientation New orientation, one of
     *        JList.HORIZONTAL or JList.VERTICAL.
     * @see #getLayoutOrientation
     * @see #setVisibleRowCount
     * @see #getScrollableTracksViewportWidth
     * @since 1.4
     * @beaninfo
     *       bound: true
     *   attribute: visualUpdate true
     * description: Defines the way list cells are layed out.
     *        enum: VERTICAL JList.VERTICAL 
     *              HORIZONTAL JList.HORIZONTAL
     */
    public void setLayoutOrientation(int layoutOrientation);

Update the following javadoc in javax.swing.JList:

    /**
     * Returns true if this JList is displayed in a 
     * JViewport and the viewport is taller than
     * JList's preferred height, or if the layout orientation is
     * horizontal and the number of visible rows is <= 0; otherwise returns
     * false.
     * If false, then don't track the viewport's height. This allows vertical
     * scrolling if the JViewport is itself embedded in a
     * JScrollPane.
     *
     * @return true if viewport is taller than Jlist's
     *				preferred height, otherwise false
     * @see Scrollable#getScrollableTracksViewportHeight
     */
    public boolean getScrollableTracksViewportHeight();

    /**
     * Computes the size of the viewport needed to display 
     * visibleRowCount
     * rows.  This is trivial if 
     * fixedCellWidth and fixedCellHeight
     * were specified.  Note that they can be specified implicitly with
     * the prototypeCellValue property.  
     * If fixedCellWidth wasn't specified,
     * it's computed by finding the widest list element.  
     * If fixedCellHeight
     * wasn't specified then we resort to heuristics:
     * 
     * 
     * If the model isn't empty we just multiply the height of the first row
     * by visibleRowCount.
     * 
     * If the model is empty, (JList.getModel().getSize() == 0),
     * then we just allocate 16 pixels per visible row, and 256 pixels
     * for the width (unless fixedCellWidth was set),
     * and hope for the best.
     *
     * If the layout orientation is HORIZONTAL, than this will
     * return the value from getPreferredSize. The current
     * ListUI is expected to override
     * getPreferredSize to return an appropriate value.
     *
     * @return a dimension containing the size of the viewport needed
     *		to display visibleRowCount rows
     * @see #getPreferredScrollableViewportSize
     * @see #setPrototypeCellValue
     */
    public Dimension getPreferredScrollableViewportSize();

Update the following javadoc in javax.swing.plaf.basic.BasicListUI:

    /**
     * The preferredSize of the list depends upon the layout orientation.
     * <table><tr><td>Layout Orientation</td><td>Preferred Size</td></tr>
     * <tr>
     *   <td>JList.VERTICAL
     *   <td>The preferredSize of the list is total height of the rows
     *       and the maximum width of the cells.  If JList.fixedCellHeight
     *       is specified then the total height of the rows is just
     *       (cellVerticalMargins + fixedCellHeight) * model.getSize() where
     *       rowVerticalMargins is the space we allocate for drawing
     *       the yellow focus outline.  Similarly if JListfixedCellWidth is
     *       specified then we just use that.
     *   </td>
     * <tr>
     *   <td>JList.HORIZONTAL
     *   <td>If the visible row count is greater than zero, the preferredHeight
     *       is the maximum cell height * visibleRowCount. If the visible row
     *       count is <= 0, the preferred height is either the current height
     *       of the list, or the maximum cell height, whichever is
     *       bigger. The preferred width is than the maximum cell width *
     *       number of columns needed. Where the number of columns needs is
     *       list.height / max cell height. Max cell height is either the fixed
     *       cell height, or is determined by iterating through all the cells
     *       to find the maximum height from the ListCellRenderer.
     * </table>
     * The above specifies the raw preferred width and height. The resulting
     * preferred width is the above width + insets.left + insets.right and
     * the resulting preferred height is the above height + insets.top +
     * insets.bottom. Where the Insets are determined from
     * list.getInsets().
     *
     * @param c the JList component
     * @return The total size of the list
     */
    public Dimension getPreferredSize(JComponent c);

Miscellaneous

SwingConstants should define next and previous

    /**
     * Identifies the next direction in a sequence.
     *
     * @since 1.4
     */
     public static final int NEXT = 12;

    /**
     * Identifies the previous direction in a sequence.
     *
     * @since 1.4
     */
     public static final int PREVIOUS = 13;
    

No way to process bindings for Swing Components from a non-Swing Component

    /**
     * Processes the key bindings for the Component associated with
     * event. This method is only useful if
     * event.getComponent does not descend from
     * JComponent, or you are not invoking
     * super.processKeyEvent from within your
     * JComponent subclass. JComponent
     * automatically processes bindings from within its
     * processKeyEvent method, hence you rarely need
     * to directly invoke this method.
     *
     * @param event KeyEvent used to identify which bindings
     *              to process, as well as which Component
     *              has focus
     * @return true if a binding has found and processed
     * @since 1.4
     */
    public static boolean processKeyBindings(KeyEvent event);

Auditory Feedback for Swing components

Add the following to javax.swing.plaf.basic.BasicLookAndFeel

/**
 * Returns an ActionMap.
 *
 * This ActionMap contains Actions that
 * embody the ability to render an auditory cue. These auditory
 * cues map onto user and system activities that may be useful
 * for an end user to know about (such as a dialog box appearing).
 *
 * At the appropriate time in a JComponent UI's lifecycle,
 * the ComponentUI is responsible for getting the appropriate
 * Action out of the ActionMap and passing
 * it on to playSound.
 *
 * The Actions in this ActionMap are
 * created by the createAudioAction method.
 *
 * @return      an ActionMap containing Actions
 *              responsible for rendering auditory cues
 * @see #createActionMap(Object)
 * @see #playSound(Action)
 * @since 1.4
 */
protected ActionMap getAudioActionMap();


/**
 * Returns an Action.
 *
 * This Action contains the information and logic to render an
 * auditory cue. The Object that is passed to this
 * method contains the information needed to render the auditory
 * cue. Normally, this Object is a String
 * that points to an audio file relative to the current package.
 * This Action's actionPerformed method
 * is fired by the playSound method.
 *
 * @return      an Action which knows how to render the auditory
 *              cue for one particular system or user activity
 * @see #playSound(Action)
 * @since 1.4
 */
protected Action createAudioAction(Object key);


/**
 * Decides whether to fire the Action that is passed into
 * it and, if needed, fires the Action's
 * actionPerformed method. This has the effect
 * of rendering the audio appropriate for the situation.
 *
 * The set of possible cues to be played are stored in the default
 * table value "AuditoryCues.cueList". The cues that will be played
 * are stored in "AuditoryCues.playList".
 *
 * @param audioAction an Action that knows how to render the audio
 *                    associated with the system or user activity
 *                    that is occurring
 * @since 1.4
 */
protected void playSound(Action audioAction);

Add the following to javax.swing.plaf.basic.BasicMenuItemUI

/**
 * Call this method when a menu item is to be activated.
 * This method handles some of the details of menu item activation
 * such as clearing the selected path and messaging the
 * JMenuItem's doClick() method.
 *
 * @param msm  A MenuSelectionManager. The visual feedback and
 *             internal bookkeeping tasks are delegated to
 *             this MenuSelectionManager. If null is
 *             passed as this argument, the
 *             MenuSelectionManager.defaultManager is
 *             used.
 * @see MenuSelectionManager
 * @see JMenuItem#doClick(int)
 * @since 1.4
 */
protected void doClick(MenuSelectionManager msm);

JMenu should be updated to work with new focus architecture

Have JComponent override requestFocusInWindow(boolean) and requestFocus(boolean) making them public:

    /**
     * JComponent overrides requestFocus solely
     * to make the method public so that UI implementations can cause
     * temporary focus changes. This method is not meant for general use,
     * instead developers are urged to call the noarg requestFocus
     * or requestFocusInWindow methods.
     *
     * Refer to {@link java.awt.Component#requestFocus(boolean)
     * Component.requestFocus(boolean)} for a complete description
     * of this method.
     *
     * @param temporary boolean indicating if the focus change is temporary
     * @return false if the focus change request is guaranteed to
     *         fail; true if it is likely to succeed
     * @see java.awt.Component#requestFocus()
     * @see java.awt.Component#requestFocusInWindow()
     * @see java.awt.Component#requestFocus(boolean)
     * @see java.awt.Component#requestFocusInWindow(boolean)
     * @since 1.4
     */
    public boolean requestFocus(boolean temporary);

    /**
     * JComponent overrides requestFocusInWindow
     * solely to make the method public so that UI implementations can cause
     * temporary focus changes. This method is not meant for general use,
     * instead developers are urged to call the noarg requestFocus
     * or requestFocusInWindow methods.
     *
     * Refer to {@link java.awt.Component#requestFocusInWindow(boolean)
     * Component.requestFocusInWindow(boolean)} for a complete description of
     * this method.
     *
     * @param temporary boolean indicating if the focus change is temporary
     * @return false if the focus change request is guaranteed to
     *         fail; true if it is likely to succeed
     * @see java.awt.Component#requestFocus()
     * @see java.awt.Component#requestFocusInWindow()
     * @see java.awt.Component#requestFocus(boolean)
     * @see java.awt.Component#requestFocusInWindow(boolean)
     * @since 1.4
     */
    public boolean requestFocusInWindow(boolean temporary);

Need ability to change ComponentOrientation of tree of Components

Add the following method to the javax.swing.SwingUtilities class

    /**
     * Sets the ComponentOrientation property of each component
     * in the tree rooted at c to the value o.
     * 
     * @param c  the root of the component tree 
     * @param o  the new ComponentOrientation value
     * @see java.awt.ComponentOrientation
     * @since 1.4
     * 
     */
    public static void applyComponentOrientation(Component c,
                                                 ComponentOrientation o);

Need access to desktop properties

    /**
     * Returns the value of the specified system desktop property by
     * invoking Toolkit.getDefaultToolkit().getDesktopProperty().
     * If the current value of the specified property is null, the
     * fallbackValue is returned.
     * @param systemPropertyName the name of the system desktop property being
     *        queried
     * @param fallbackValue the object to be returned as the value if the system
     *        value is null
     * @return the current value of the desktop property
     *
     * @see java.awt.Toolkit#getDesktopProperty
     * @since 1.4
     */
    public static Object getDesktopPropertyValue(String systemPropertyName,
                                                 Object fallbackValue);

Add method to offset Rectangle by Component insets

/**
 * Stores the position and size of
 * the inner painting area of the specified component
 * in r and returns r.
 * The position and size specify the bounds of the component,
 * adjusted so as not to include the border area (the insets).
 * This method is useful for classes 
 * that implement painting code.
 *
 * @param c  the Component in question; if null, this method returns null
 * @param r  the Rectangle instance to be modified;
 *           may be null
 * @return null if the Component is null;
 *         otherwise, returns the passed-in rectangle (if non-null)
 *         or a new rectangle specifying position and size information
 *
 * @since 1.4
 */
public static Rectangle calculateInnerArea(Component c, Rectangle r):

Need API for mouse wheels

New interface java.awt.event.MouseWheelListener

New class java.awt.event.MouseWheelEvent.

Add the following to java.awt.AWTEvent

    /**
     * The event mask for selecting mouse wheel events.
     * @since 1.4
     */
    public final static long MOUSE_WHEEL_EVENT_MASK = 0x20000;

Add the following to java.awt.AWTEventMulticaster

    /**
     * Handles the mouseWheelMoved event by invoking the
     * mouseWheelMoved methods on listener-a and listener-b.
     * @param e the mouse event
     * @since 1.4
     */
    public void mouseWheelMoved(MouseWheelEvent e);

    /**
     * Adds mouse-wheel-listener-a with mouse-wheel-listener-b and
     * returns the resulting multicast listener.
     * @param a mouse-wheel-listener-a
     * @param b mouse-wheel-listener-b
     * @since 1.4
     */
    public static MouseWheelListener add(MouseWheelListener a,
                                         MouseWheelListener b);

    /**
     * Removes the old mouse-wheel-listener from mouse-wheel-listener-l 
     * and returns the resulting multicast listener.
     * @param l mouse-wheel-listener-l
     * @param oldl the mouse-wheel-listener being removed
     * @since 1.4
     */
    public static MouseWheelListener remove(MouseWheelListener l,
                                            MouseWheelListener oldl);

Add the following to java.awt.Component

    /**
     * Adds the specified mouse wheel listener to receive mouse wheel events
     * from this component.  Containers also receive mouse wheel events from
     * sub-components.
     * If l is null, no exception is thrown and no action is performed.
     *
     * @param    l   the mouse wheel listener.
     * @see      java.awt.event.MouseWheelEvent
     * @see      java.awt.event.MouseWheelListener
     * @see      #removeMouseWheelListener
     * @see      #getMouseWheelListeners
     * @since    1.4
     */
    public synchronized void addMouseWheelListener(MouseWheelListener l);

    /**
     * Removes the specified mouse wheel listener so that it no longer
     * receives mouse wheel events from this component. This method performs 
     * no function, nor does it throw an exception, if the listener 
     * specified by the argument was not previously added to this component.
     * If l is null, no exception is thrown and no action is performed.
     *
     * @param    l   the mouse wheel listener.
     * @see      java.awt.event.MouseWheelEvent
     * @see      java.awt.event.MouseWheelListener
     * @see      #addMouseWheelListener
     * @see      #getMouseWheelListeners
     * @since    1.4
     */
    public synchronized void removeMouseWheelListener(MouseWheelListener l);

Add the following to java.awt.ScrollPane

    /**
     * Enables/disables scrolling in response to movement of the mouse wheel.
     * Wheel scrolling is enabled by default.
     *
     * @param handleWheel   true if scrolling should be done
     *                      automatically for a MouseWheelEvent,
     *                      false otherwise.
     * @see #isWheelScrollingEnabled
     * @see java.awt.event.MouseWheelEvent
     * @see java.awt.event.MouseWheelListener
     * @since 1.4
     */
    public void setWheelScrollingEnabled(boolean handleWheel);

    /**
     * Indicates whether or not scrolling will take place in response to
     * the mouse wheel.  Wheel scrolling is enabled by default.
     *
     * @see #setWheelScrollingEnabled(boolean)
     * @since 1.4
     */
    public boolean isWheelScrollingEnabled();

Add the following to java.awt.Robot

    /**
     * wheelAmt: number of "clicks" to move the mouse wheel
     * negative values indicate movement up/away
     * positive values indicate movement down/towards
     * @since 1.4
     */
     public void mouseWheelMoved(int wheelAmt);

JRootPane

Ability for look and feels to provide window decorations

Add the following to javax.swing.JRootPane:

    /**
     * Constant used for the windowDecorationStyle property. Indicates that
     * the JRootPane should not provide any sort of
     * Window decorations.
     *
     * @since 1.4
     */
    public static final int NONE;
    /**
     * Constant used for the windowDecorationStyle property. Indicates that
     * the JRootPane should provide decorations appropriate for
     * a Frame.
     *
     * @since 1.4
     */
    public static final int FRAME;
    /**
     * Constant used for the windowDecorationStyle property. Indicates that
     * the JRootPane should provide decorations appropriate for
     * a Dialog.
     *
     * @since 1.4
     */
    public static final int PLAIN_DIALOG;
    /**
     * Constant used for the windowDecorationStyle property. Indicates that
     * the JRootPane should provide decorations appropriate for
     * a Dialog used to display an informational message.
     *
     * @since 1.4
     */
    public static final int INFORMATION_DIALOG;
    /**
     * Constant used for the windowDecorationStyle property. Indicates that
     * the JRootPane should provide decorations appropriate for
     * a Dialog used to display an error message.
     *
     * @since 1.4
     */
    public static final int ERROR_DIALOG;
    /**
     * Constant used for the windowDecorationStyle property. Indicates that
     * the JRootPane should provide decorations appropriate for
     * a Dialog used to display a JColorChooser.
     *
     * @since 1.4
     */
    public static final int COLOR_CHOOSER_DIALOG;
    /**
     * Constant used for the windowDecorationStyle property. Indicates that
     * the JRootPane should provide decorations appropriate for
     * a Dialog used to display a JFileChooser.
     *
     * @since 1.4
     */
    public static final int FILE_CHOOSER_DIALOG;
    /**
     * Constant used for the windowDecorationStyle property. Indicates that
     * the JRootPane should provide decorations appropriate for
     * a Dialog used to present a question to the user.
     *
     * @since 1.4
     */
    public static final int QUESTION_DIALOG;
    /**
     * Constant used for the windowDecorationStyle property. Indicates that
     * the JRootPane should provide decorations appropriate for
     * a Dialog used to display a warning message.
     *
     * @since 1.4
     */
    public static final int WARNING_DIALOG;


    /**
     * Sets the type of Window decorations (such as borders, widgets for
     * closing a Window, title ...) the JRootPane should
     * provide. The default is to provide no Window decorations, 
     * NONE.
     *
     * This is only a hint, and some look and feels may not support
     * this.
     *
     * This will throw an IllegalArgumentException 
     *
     * This is a bound property.
     *
     * @param style Constant identifying Window decorations to provide
     * @see JDialog#setDefaultLookAndFeelDecorated
     * @see JFrame#setDefaultLookAndFeelDecorated
     * @see LookAndFeel#getSupportsWindowDecorations
     * @throws IllegalArgumentException if style is
     *        not one of: NONE, FRAME,
     *        PLAIN_DIALOG, INFORMATION_DIALOG,
     *        ERROR_DIALOG, COLOR_CHOOSER_DIALOG,
     *        FILE_CHOOSER_DIALOG, QUESTION_DIALOG or
     *         WARNING_DIALOG.
     * @since 1.4
     * @beaninfo
     *        bound: true
     *         enum: NONE                   JRootPane.NONE
     *               FRAME                  JRootPane.FRAME
     *               PLAIN_DIALOG           JRootPane.PLAIN_DIALOG
     *               INFORMATION_DIALOG     JRootPane.INFORMATION_DIALOG
     *               ERROR_DIALOG           JRootPane.ERROR_DIALOG
     *               COLOR_CHOOSER_DIALOG   JRootPane.COLOR_CHOOSER_DIALOG
     *               FILE_CHOOSER_DIALOG    JRootPane.FILE_CHOOSER_DIALOG
     *               QUESTION_DIALOG        JRootPane.QUESTION_DIALOG
     *               WARNING_DIALOG         JRootPane.WARNING_DIALOG
     *       expert: true
     *    attribute: visualUpdate true
     *  description: Identifies the type of Window decorations to provide
     */
    public void setWindowDecorationStyle(int style);

    /**
     * Returns a constant identifying the type of Window decorations the
     * JRootPane is providing.
     *
     * @return One of NONE, FRAME,
     *        PLAIN_DIALOG, INFORMATION_DIALOG,
     *        ERROR_DIALOG, COLOR_CHOOSER_DIALOG,
     *        FILE_CHOOSER_DIALOG, QUESTION_DIALOG or
     *        WARNING_DIALOG.
     * @see #setWindowDecorationStyle
     * @since 1.4
     */
    public int getWindowDecorationStyle();

The metal look and feel previously did not provide an implementation of RootPaneUI, it will now provide one.

Create the new class javax.swing.plaf.metal.MetalRootPaneUI

Not all LookAndFeels will support the window decoration style, the following will be added to javax.swing.LookAndFeel to provide a way for look and feels to indicate they support this behavior.

    /**
     * Returns true if the LookAndFeel returned
     * RootPaneUI instances support providing Window decorations
     * in a JRootPane.
     *
     * The default implementation returns false, sublclasses that support
     * Window decorations should override this and return true.
     *
     * @return True if the RootPaneUI instances created support client side
     *              decorations
     * @see JDialog#setDefaultLookAndFeelDecorated
     * @see JFrame#setDefaultLookAndFeelDecorated
     * @see JRootPane#setWindowDecorationStyle
     * @since 1.4
     */
    public boolean getSupportsWindowDecorations();

Add the following to javax.swing.JFrame

    /**
     * Provides a hint as to whether or not newly created JFrames
     * should have their Window decorations (such as borders, widgets to
     * close the window, title...) provided by the current look
     * and feel. If defaultLookAndFeelDecorated is true,
     * the current LookAndFeel supports providing window
     * decorations, and the current window manager supports undecorated
     * windows, then newly created JFrames will have their
     * Window decorations provided by the current LookAndFeel.
     * Otherwise, newly created JFrames will have their
     * Window decorations provided by the current window manager.
     *
     * You can get the same effect on a single JFrame by doing the following:
     * <pre>
     *    JFrame frame = new JFrame();
     *    frame.setUndecorated(true);
     *    frame.getRootPane().setWindowDecorationStyle(JRootPane.FRAME);
     * </pre>
     *
     * @param defaultLookAndFeelDecorated A hint as to whether or not current
     *        look and feel should provide window decorations
     * @see javax.swing.LookAndFeel.getSupportsWindowDecorations
     * @since 1.4
     */
    public static void setDefaultLookAndFeelDecorated(boolean defaultLookAndFeelDecorated);

    /**
     * Returns true if newly created JFrames should have their
     * Window decorations provided by the current look and feel. This is only
     * a hint, as certain look and feels may not support this feature.
     *
     * @return true if look and feel should provide Window decorations.
     * @since 1.4
     */
    public static boolean isDefaultLookAndFeelDecorated();

Add the following to javax.swing.JDialog

    /**
     * Provides a hint as to whether or not newly created JDialogs
     * should have their Window decorations (such as borders, widgets to
     * close the window, title...) provided by the current look
     * and feel. If defaultLookAndFeelDecorated is true,
     * the current LookAndFeel supports providing window
     * decorations, and the current window manager supports undecorated
     * windows, then newly created JDialogs will have their
     * Window decorations provided by the current LookAndFeel.
     * Otherwise, newly created JDialogs will have their
     * Window decorations provided by the current window manager.
     *
     * You can get the same effect on a single JDialog by doing the following:
     * <pre>
     *    JDialog dialog = new JDialog();
     *    dialog.setUndecorated(true);
     *    dialog.getRootPane().setWindowDecorationStyle(JRootPane.PLAIN_DIALOG);
     * </pre>
     *
     * @param defaultLookAndFeelDecorated A hint as to whether or not current
     *        look and feel should provide window decorations
     * @see javax.swing.LookAndFeel.getSupportsWindowDecorations
     * @since 1.4
     */
    public static void setDefaultLookAndFeelDecorated(boolean defaultLookAndFeelDecorated);

    /**
     * Returns true if newly created JDialogs should have their
     * Window decorations provided by the current look and feel. This is only
     * a hint, as certain look and feels may not support this feature.
     *
     * @return true if look and feel should provide Window decorations.
     * @since 1.4
     */
    public static boolean isDefaultLookAndFeelDecorated();

JScrollBar

JScrollBar does not override setUI as other JComponent subclasses do

Add the following to javax.swing.JScrollBar:

    /**
     * Sets the L&F object that renders this component.
     *
     * @param ui  the ScrollBarUI L&F object
     * @see UIDefaults#getUI
     * @since 1.4
     * @beaninfo
     *        bound: true
     *       hidden: true
     *    attribute: visualUpdate true
     *  description: The UI object that implements the Component's LookAndFeel
     */
    public void setUI(ScrollBarUI ui);

JScrollPane

JScrollPane should support the new MouseWheelListener

Add the following to javax.swing.JScrollPane

    /**
     * Indicates whether or not scrolling will take place in response to the
     * mouse wheel.  Wheel scrolling is enabled by default.
     * 
     * @see #setWheelScrollingEnabled
     * @since 1.4
     * @beaninfo
     *       bound: true
     * description: Flag for enabling/disabling mouse wheel scrolling
     */
    public boolean isWheelScrollingEnabled();

    /**
     * Enables/disables scrolling in response to movement of the mouse wheel.
     * Wheel scrolling is enabled by default.
     *
     * @param handleWheel   true if scrolling should be done
     *                      automatically for a MouseWheelEvent,
     *                      false otherwise.
     * @see #isWheelScrollingEnabled
     * @see java.awt.event.MouseWheelEvent
     * @see java.awt.event.MouseWheelListener
     * @since 1.4
     * @beaninfo
     *       bound: true
     * description: Flag for enabling/disabling mouse wheel scrolling
     */
    public void setWheelScrollingEnabled(boolean handleWheel);

Add the following to javax.swing.plaf.basic.ScrollScrollPaneUI

    /**
     * MouseWheelHandler is an inner class which implements the 
     * MouseWheelListener interface.  MouseWheelHandler responds to 
     * MouseWheelEvents by scrolling the JScrollPane appropriately.
     * If isWheelScrollEnabled() is false, no scrolling occurs.
     * 
     * @see #isWheelScrollingEnabled
     * @see #createMouseWheelListener
     * @see java.awt.event.MouseWheelListener
     * @see java.awt.event.MouseWheelEvent
     * @since 1.4
     */
    protected class MouseWheelHandler implements MouseWheelListener {
        /**
         * Called when the mouse wheel is rotated while over a
         * JScrollPane.
         *
         * @param e     MouseWheelEvent to be handled
         * @since 1.4
         */
        public void mouseWheelMoved(MouseWheelEvent e);
    }

    /**
     * Creates an instance of MouseWheelListener, which is added to the
     * JScrollPane by installUI().  The returned MouseWheelListener is used
     * to handle mouse wheel-driven scrolling.
     *
     * @return      MouseWheelListener which implements wheel-driven scrolling
     * @see #installUI
     * @see MouseWheelHandler
     * @since 1.4
     */
    protected MouseWheelListener createMouseWheelListener();

RepaintManager

  /**
   * Returns a volatile offscreen buffer that should be used as a
   * double buffer with the specified component c.
   * The image returned will be an instance of VolatileImage, or
   * null if a VolatileImage object could
   * not be instantiated. This buffer might be smaller than
   * (proposedWidth,proposedHeight).
   * This happens when the maximum double buffer size has been set for this
   * repaint manager.
   *
   * @see java.awt.image.VolatileImage
   * @since 1.4
   */
    public Image getVolatileOffscreenBuffer(Component c, 
    					    int proposedWidth, 
    					    int proposedHeight)