| ## Swing Changes and New Features for JavaTM 2 SDK, Standard Edition, v 1.4 | Project Swing

## Changes Specific to releases 1.4.1 and 1.4.2

This document contains information relevant to all 1.4.* releases. For information specific to 1.4.1 and 1.4.2, see Swing Changes Since Java 2 SDK, Standard Edition, v 1.4.

## Major Changes

Certain features, typically ones that have a large impact on Swing, have been extensively written up in separate documents. The following link to these documents:

- Windows XP look and feel
- GTK+ look and feel
- Support for indeterminate progress bars
- `JTabbedPane` with scrollable tabs
- `JSpinner`
- `JFormattedTextField`
- `Popup` and `PopupFactory`
- New Focus Model Specification and Javadoc
- Windows look and feel update.
- The new Drag and Drop architecture.

## Minor Changes

Each section contains changes for a set of related classes. Most of the sections are focused on the classes that are part of a single Swing component like `JEditorPane` or `JTable`. Each API change is associated with a link to a report on the Java Developer Connection (JDC) Bug Parade , where you'll find the original bug or RFE ("request for enhancement") that motivated the change. In this document you'll also find the following information for each API change:

- The method signatures with a link to the Javadoc for new methods or methods whose semantics have changed.
- A brief description of the overall change and how to take advantage of it. You'll probably find this same material in the evaluation section of the bug/rfe report.
- If the API change corrects a long standing bug or provides a missing feature - suggestions about how to migrate typical workarounds or extensions to the new feature.
- Nearly all changes (even bugfixes!) introduce some kind of incompatibility. We've done our best to predict these incompatibilities and provide advice about how to avoid them.

### Sections

- `Box`
- `JButton`
- `JComboBox`
- `JFileChooser`
- `JInternalFrame`
- `JList`
- `JOptionPane`
- `JPopupMenu`
- `JPanel`
- `JRootPane`
- `JScrollBar`
- `JScrollPane`
- `JTabbedPane`
- `JTable`
- `JTextComponent`
- `JTree`
- `RepaintManager`
- `SpringLayout`
- Miscellaneous
- Known Bugs

## Box

> ### Box now descends from JComponent

> > The bugtraq report that corresponds to this change is: 4304100.

> > Historically, the superclass for `Box` has been `Component`. Since `Box` did not descend from `JComponent`, you could not use it like a normal Swing component, for example, you couldn't set the borders, or issue `revalidate`. Not only this, but changing visibility, or other similiar visual properties, on a standard Swing component typically triggers a `repaint` or `revalidate`, but `Box` did not conform to this behavior. As of this release, `Box` and `Box.Filler` now descend from the `JComponent` superclass and therefore behave more like standard Swing components.

> ### BoxLayout Now Supports Right-to-Left and Bottom-to-Top Component Orientations

> > The bugtraq report that corresponds to this change is: 4140833.

> > `BoxLayout` did not consider the `ComponentOrientation` of the `Container` it is laying out. Other AWT layout managers were made to do this when the `ComponentOrientation` feature was added in JDK 1.2. Adding this feature to `BoxLayout` makes it useful for programs that support Middle East locales. Because `BoxLayout` is also used internally by other Swing components, such as `JOptionPane`, `JToolBar` and `JMenuBar`, adding this feature is also necessary for these components to support `ComponentOrientation`.

> > To support this functionality, the constants `LINE_AXIS` and `PAGE_AXIS`, and the constructor, `BoxLayout(Container, int)`, were added to `BoxLayout`.

> > There were also changes to several methods in `SizeRequirements`:

> > - `calculateTiledPositions(int,SizeRequirements,SizeRequirements[],int[],int[],boolean)`
> > - `calculateTiledPositions(int,SizeRequirements,SizeRequirements[],int[],int[])`
> > - `calculateAlignedPositions(int,SizeRequirements,SizeRequirements[],int[],int[],boolean)`
> > - `calculateAlignedPositions(int,SizeRequirements,SizeRequirements[],int[],int[])`

## JButton

> ### Default Button Follows the Focus on Windows LAF

> > The bugtraq report that corresponds to this change is: 4659800.

> > With this bug, introduced in 1.4.0, the default button did not always follow the focus. This has been fixed in 1.4.1.

> ### New Control of Highlighted Characters

> > The bugtraq report that corresponds to this change is: 4138746.

> > `AbstractButton` and `JLabel` both allow the developer to set a character, called the mnemonic, that can be used to perform an action when typed at the keyboard. The javadoc for these methods states that the first case-insensitive occurrence of the character is decorated. While this suits most developers, often times a different occurrence of the character needs to be highlighted. For example: in Notepad, 'a' is the accelerator for Save As, but the second 'a' is decorated. Developers need a way to be able to specify this.

> > This is solved with the new `AbstractButton.setDisplayedMnemonicIndex` and `JLabel.setDisplayedMnemonicIndex` methods. Once you have specified a mnemonic, via the `setMnemonic` or `setDisplayedMnemonic` methods, you can then change the character that is highlighted via the `setDisplayedMnemonicIndex` method. There are also new `AbstractButton.getDisplayedMnemonicIndex` and `JLabel.getDisplayedMnemonicIndex` methods. Finally, `drawStringUnderlineCharAt` has been added to `javax.swing.plaf.basic.BasicGraphicsUtils`.

> ### AbstractButton.configurePropertiesFromAction Now Honors ACTION_COMMAND_KEY Property

> > The bugtraq report that corresponds to this change is: 4457940.

> > Previously, the `AbstractButton` methods `configurePropertiesFromAction(Action)` and `configurePropertiesFromAction(Action, String[])` did not honor the `ACTION_COMMAND_KEY` property. That has now been addressed. This affects the javadoc for the `configurePropertiesFromAction` methods in the following subclasses of `AbstractButton`:

> > - `JButton.configurePropertiesFromAction(Action)`
> > - `JMenu.configurePropertiesFromAction(Action)`
> > - `JCheckBox.configurePropertiesFromAction(Action)`
> > - `JRadioButton.configurePropertiesFromAction(Action)`

## JComboBox

> ### PopupMenuListener Added to JComboBox

> The bugtraq report that corresponds to this change is: 4287690.

> Many developers have requested support for listeners to be notified when a combo box's drop down menu is popped up, dismissed, or canceled. Applications could use these listeners to lazily populate the combo box's model with items.

> This feature wasn't provided in earlier versions of Swing because there was some, probably academic, concern about supporting a listener for a feature (the drop down menu) that some look and feel implementations might not provide. All of the look and feels that are shipped with Java, and all of the ones we've come across, do use a drop down menu to show all of the combo box items. Some developers have resorted to non-portable hacks to get the menu state change notifications.

> For this release, we added a `PopupMenuListener` to `JComboBox`. So long as the underlying look and feel supports an item menu, this listener can be used to perform actions before and after the combo box menu appears. Several new `JComboBox` methods were required to support this feature:

>         public void addPopupMenuListener(PopupMenuListener l)
>         public void removePopupMenuListener(PopupMenuListener l)
>         public void firePopupMenuWillBecomeVisible()
>         public void firePopupMenuWillBecomeInvisible()
>         public void firePopupMenuCanceled()

### JComboBox Now Supports Prototype Cell for Lists

> The bugtraq report that corresponds to this change is: 4231298.

> `JComboBox` previously configured a renderer for every item it displayed. For large lists this could take quite a while. Instead, developers needed the ability to specify a prototype that all cells match, so that the prototype is only checked once instead of every cell. For this release, `getPrototypeDisplayValue` and `setPrototypeDisplayValue` have been added to `JComboBox`.

### Javadoc for JComboBox and Related Classes Has Improved Documentation

> The bugtraq report that corresponds to this change is 4394300.

> Previously, public API for `JComboBox` and its UI delegates contained javadoc which described the details of its implementation. Refactoring and bug fixing over the course of its history had made this javadoc out of date. The javadoc has been checked and revised so that it describes the behavior of the method rather than the implementation details. Also, some of the javadoc for "protected" methods and fields which should really have been private have been removed so that overriding or calling these methods are not encouraged.

> The doc has been changed for `JComboBox`, `ComboBoxModel`, `MutableComboBoxModel`, `javax.swing.plaf.basic.BasicComboBoxUI`, `javax.swing.plaf.basic.ComboPopup`, and `javax.swing.plaf.basic.BasicComboPopup`.

## JFileChooser

> ### JFileChooser Windows Look and Feel Improved

> > The bugtraq report that corresponds to this change is 4290709.

> > Although Swing's `JFileChooser` closely resembles the Microsoft Windows common file dialog under the Windows look and feel, there are several deficiencies for which we have received complaints. In particular, the Microsoft Windows aesthetics guide mentions the following:

> > If you cannot use the [common] Open and Save As dialog boxes, you should incorporate the following features into your open and save dialog boxes to ensure that they are consistent with the shell, the Windows accessories, and other applications:

> > - Support the same namespace hierarchy as the shell; that is, Desktop should be at the root of the hierarchy, followed by all folders and objects on the desktop, including My Computer, My Network, and so on. [...]
> > - Support shortcuts (also known as shell links). [...]
> > - Display filenames with the corresponding icons and filename extensions removed, as the shell does.
> > - Allow the user to browse the network hierarchy directly.
> > - Make sure that all of your dialog boxes (not just your open and save dialog boxes) use only nonbold fonts. [...]

> > The first four points are not possible in Swing without additional API support from the AWT. The AWT common file dialog is also currently an unacceptable solution for the following reasons:

> > - It cannot be embedded into a frame or dialog like JFileChooser.
> > - Filename filter is not implemented and is difficult to implement on Windows.

> > The new functionality is accomplished by adding the following public methods to the `javax.swing.filechooser.FileSystemView` class, providing file and directory information beyond the scope of the `File` class:

> >         public boolean isTraversable(File f)
> >         public String getSystemDisplayName(File f)
> >         public String getSystemTypeDescription
> >         public Icon getSystemIcon(File f)
> >         public boolean isParent(File folder, File file)
> >         public File getChild(File parent, String filename)
> >         public boolean isFileSystem(File f)
> >         public boolean isFileSystemRoot(File dir)
> >         public boolean isDrive(File dir)
> >         public boolean isFloppyDrive(File dir)
> >         public boolean isComputerNode(File dir)
> >         public File createFileSystemRoot(File f)
> >         public File[] getRoots()

> > The `isTraversable` method has been removed from `javax.swing.plaf.basic.BasicFileChooserUI.BasicFileView` so that the superclass's implementation is used.

> > `createListSelectionListener` has been added to `javax.swing.plaf.metal.MetalFileChooserUI`.

> > Also, `javax.swing.plaf.basic.BasicDirectoryModel` has the following changes:

> >         public void intervalAdded(ListDataEvent e)
> >         public void intervalRemoved(ListDataEvent e)
> >         public void renameFile(File oldFile, File newFile)

> ### New Ability to Specify Characteristics of Open Directory Button in JFileChooser

> > The bugtraq report that corresponds to this change is 4318785.

> > Look and feels need the ability to specify the text, tooltip text, and mnemonic for the button used to open a directory in `JFileChooser`.

> > To support this, several constants and methods were added to `plaf.basic.BasicFileChooserUI`:

> >         protected int directoryOpenButtonMnemonic = 0;
> >         protected String directoryOpenButtonText = null
> >         protected String directoryOpenButtonToolTipText = null
> >         protected boolean isDirectorySelected()
> >         protected void setDirectorySelected(boolean b)
> >         protected File getDirectory()
> >         protected void setDirectory(File f)

> ### Multiple File Selection Supported

> > The bugtraq report that corresponds to this change is 4218431.

> > Multiple file selection was added to `JFileChooser` in the 1.4 release, but the javadoc for `setMultiSelectionEnabled` wasn't updated until the 1.4.1 release.

## JInternalFrame

> ### JInternalFrame Now Truncates Titles That are Too Long

> > The bugtraq report that corresponds to this change is 4134077.

> > Previously, the title of an internal frame would not be clipped if it was too long. This would lead to the title displaying over parts of the icons, as well no visual feedback to the user that the title had been clipped. To solve this, `BasicInternalFrameTitlePane.getTitle` was added.

> ### JInternalFrame Titles in Windows Look and Feel May Now be Rendered with a Gradient

> > The bugtraq report that corresponds to this change is: 4389209.

> > To implement this correctly, we needed to create a class, `com.sun.java.swing.plaf.windows.WindowsInternalFrameTitlePane`, which extended `javax.swing.plaf.basic.BasicInternalFrameTitlePane`, but overrode the paint routine to render the gradient when appropriate. The best way to get code-reuse was to break out the portion of the paint method which paints just the background and override just that in `WindowsInternalFrameTitlePane`. The method `paintTitleBackground` was added to `javax.swing.plaf.basic.BasicInternalFrameTitlePane`.

## JTextComponent

> ### New Support for Tooltips for Images in JEditorPane

> > The bugtraq report that corresponds to this change is: 4252169.

> > In previous releases it was not possible for `ImageView` (the `View` responsible for rendering images in a `JEditorPane`) to show tooltip text because there was no way for a `View` to influence the tooltip text that is displayed for a `JTextComponent`. In this release, if the the `JTextComponent` doesn't have a tooltip, then the view under the mouse is asked to provide one. If that `View` corresponds to an HTML element with an ALT attribute, then the tooltip text is the value of that attribute.

> > To make it possible for `View`s to affect the tooltip text, a number of methods were needed. `getToolTipText` was added to `javax.swing.plaf.TextUI` so that it is possible to get the tooltip text for a particular location. `JTextComponent`'s `getToolTipText` method then forwards to the `TextUI`, assuming a tooltip was not set on the `JTextComponent`.

> > `getToolTipText` was also added to `javax.swing.text.View`. The default implementation of `View.getToolTipText` will forward the request to the `View`'s child at the given location. To make it easy to determine the child at a particular location, `getViewIndex` was added to `View`.

> > 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`.

> ### ImageView Class is Now Public

> > The bugtraq report that corresponds to this change is: 4233811.

> > The package private class `javax.swing.text.html.ImageView` is now public so that it can be extended.

> ### New HyperlinkEvent Read-Only elementOffset Property

> > The bugtraq report that corresponds to this change is: 4182124.

> > The HTML package exposes a way for developers to determine when the mouse moves over a link via the `HyperlinkEvent` and `HyperlinkListener` classes. Often times developers need a way to extract information from the document when the `HyperlinkListener` is notified. There was previously no way for a developer to determine the position in the document a `HyperlinkEvent` represents. To remedy this the constructor `HyperlinkEvent(Object, EventType, URL, String, Element)` and the method `getSourceElement` were added to `HyperlinkEvent`.

> > `HTMLFrameHyperlinkEvent` extends `HyperlinkEvent`, which already defines the method `getSourceElement`. Since the superclass now defines this method, the `getSourceElement` javadoc was removed from `HTMLFrameHyperlinkEvent` (the method is now inherited):

> ### HTML Parser Change: Whitespace Reporting

> > The bugtraq report that corresponds to this change is: 4241788.

> > The semantics of the HTML parser ( `javax.swing.text.html.parser.Parser`) have slightly changed to better match that of the browser (NetscapeTM and Internet Explorer). While no API was changed, those using the parser may notice a slight difference in the reporting of whitespace. Here is how things have changed: if `strict` (an instance variable of `javax.swing.text.html.parser.Parser`) == `false` (the default) an instance variable is used to try and mimic the behavior of Netscape and Explorer.

> > The problematic scenarios are:

> >     '<b>blah <i> <strike> foo'

> > which can be treated as:

> >     '<b>blah <i><strike>foo'

> > as well as:

> >     '<p><a href="xx"> <em>Using</em></a></p>'

> > which appears to be treated as:

> >     '<p><a href="xx"><em>Using</em></a></p>'

> > When a tag that breaks flow, or trailing whitespace is encountered an instance variable is set to true. From then on, all whitespace is ignored. The instance variable is set back to false the first time a non whitespace character is encountered.

> ### Improved Support for Writing HTML Forms

> > The bugtraq report that corresponds to this change is: 4200439.

> > The HTML support provided in the J2SETM has never correctly supported writing out form elements. This was due, in large part, to the way that forms were modeled. To better match the document object model (see DOM at www.w3.org) we have changed how the forms are modeled internally. Previously, any attributes of a form would be stored in the `attributeSet` of all of the children character elements. As of this release, an element is created to represent the form, better matching that of the HTML file itself. This allows for better modeling of the form, as well as consistent writing of the form.

> > This affects developers that relied on forms being handled loosely. As an example, we would previously treat the following invalid HTML:

> >     <table>
> >     <form>
> >     </table>
> >     </form>

> > as:

> >     <form>
> >     <table>
> >     </table>
> >     </form>

> > With this release, we instead treat it as:

> >     <table>
> >     <form>
> >     </form>
> >     </table>

> ### Static DefaultPainter in `javax.swing.text.DefaultHighlighter` Class is Now `Final`

> > The bugtraq report that corresponds to this change is: 4328938.

> > Prior to this release, the static field `DefaultPainter` of `javax.swing.text.DefaultHighlighter` was not final. This was a potential security problem. For this release, it is now `Final`.

> ### PlainDocument Constructor is Now Public

> > The bugtraq report that corresponds to this change is: 4220001.

> > Prior to this release, the `PlainDocument(AbstractDocument.Content)` constructor was protected. This meant that developers wishing to use the constructor had to subclass. This constructor was intended to be public, and is now public in this release.

> ### JEditorPane.scrollToReference Method is Now Public

> > The bugtraq report that corresponds to this change is: 4304676.

> > `JEditorPane.scrollToReference` was protected for no good reason. This method is intended to be useful without having to subclass, as such it has been made public in this release.

> ### Document.getText Method Now Allows for Partial Returns

> > The bugtraq report that corresponds to this change is: 4156650.

> > For efficiently accessing the content of a text document, `Document` defines the method `getText(int, int, Segment)`. Unfortunately, there has been no way for the caller to determine if the receiver could efficiently satisfy the request. For example, `GapContent` could efficiently implement the request as long as the request didn't span the last edited spot of the document (the gap). To facilitate efficient access of the content, the methods `setPartialReturn` and `isPartialReturn` have been added to `Segment`. The current semantics of `Document.getText` still hold, but for more efficient use callers should invoke `segment.setPartialReturn(true)` and be prepared to get back a portion of the document at a time.

> ### JEditorPane Now Provides HTML Accessibility Support

> > The bugtraq report that corresponds to this change is: 4303259.

> > Assistive technologies for people with disabilities require programmatic access to the contents of `JEditorPane` using the Accessibility API. Previously, the only access was to hypertext links. This API change provided accessibility to all HTML components using the Accessibility API.

> > `javax.swing.text.html.HTMLEditorKit` now implements `javax.accessibility.Accessible`.

> > `JEditorPane` now implements `getAccessibleContext()`.

> ### Further Support for New AbstractDocument.replace Method

> > The bugtraq report that corresponds to this change is: 4458513.

> > As part of RFE 4431047, a `replace` method was added to `AbstractDocument`. In order to allow this method to call `remove` and `insertString` (the only methods defined in the interface for mutating a `Document`), the restrictions on when `writeLock` may be invoked have been relaxed. This allows `replace` to be compatible with old versions of `AbstractDocument` that only override `remove` and `insertString`.

## JOptionPane

> ### New showInputDialog Methods

> > The bugtraq report that corresponds to this change is: 4226644.

> > Prior to this release, if programs wished to display a simple input dialog containing a textfield with a default string, they had to invoke the complex `JOptionPane.showInputDialog` method which requires seven parameters. Two new methods, `showInputDialog(Object, Object)`, and `showInputDialog(Component, Object, Object)`, make it more convenient to create and display simple input dialogs.

> ### JOptionPane Now Supports ComponentOrientation

> > The bugtraq report that corresponds to this change is: 4265463.

> > `JOptionPane` needed to support right-to-left layout. This was a bug fix and no actual API was required, however, the class spec for `JOptionPane` and `javax.swing.plaf.basic.BasicOptionPane` have been updated.

> ### JOptionPane now uses Non-Resizable Dialogs

> > The bugtraq report that corresponds to this change is: 4829588.

> > As of release 1.4.0, `JOptionPane` is changed to use non-resizable dialogs. As a result, the dialogs displayed by many `JOptionPane` methods have slightly changed. The first two changes are desirable:

> > - The dialogs are, obviously, no longer resizable.

> > - The dialogs no longer show the system menu icon (that typically appears in the upper-left corner of the dialog on a left-to-right system).
> > A side effect of this change appears in the handling of extra-long text. Previously, long text was clipped, showing "..." at the end, as the dialog was restricted to the size of the screen. Now, extra-long text can cause the dialog to be sized larger than the screen in order to accomodate all of the text. Keep watching bug 4829588 to see how this undesirable behavior is resolved.

## JPopupMenu

> ### JPopupMenu and Focus

> > As of this release, showing a `JPopupMenu` causes focus to transfer to the parent `JRootPane`. This was done so that `JPopupMenu`s would support keyboard traversal ( 4212563). This may cause problems for applications that are doing validation on focus lost. If this affects you, it is recommended that in the `focusLost` notification you check the temporary property of the `FocusEvent` and, if `true`, do nothing. In situations where you don't want `JPopupMenu` to grab focus, there is unfortunately no way to disable this in the current release. In release 1.4.1 the decision to transfer focus is based on the focusability of the `JPopupMenu`. Refer to bug 4632782 for details.

> ### JPopupMenu Now Supports Key Bindings

> > The bugtraq report that corresponds to this change is: 4212563.

> > Previously, `JPopupMenu` didn't support key bindings. The arrow keys, mnemonics, the enter key, and escape did not work with a `JPopupMenu` unless it was used as part of a compound component (like a `JMenu` or a `JComboBox`).

> > This behavior can be traced to the fact that `JPopupMenu` did not always gain focus, and could therefore not get `KeyEvents`. It was previously not possible for light weight toolkits, such as Swing, to request focus and indicate that the focus change was temporary. The new focus architecture solved this problem, and Swing can now request a temporary focus change. Fixing this bug required making the `JPopupMenu` get focus so that the key bindings can be processed. Consumers that had previously not expected focus changes need to update their code to check the temporary property of the `FocusEvent`s.

> ### JPopupMenu.setVisible(true) Now Throws HeadlessException in Headless Mode

> > The bugtraq report that corresponds to this change is: 4401222.

> > When the new headless mode was introduced, `JPopupMenu.setVisible(true)` was implemented to throw `NullPointerException` when called in headless mode. It has now been fixed to throw `HeadlessException` instead, to indicate that this operation cannot be performed in headless mode.

## JPanel

> ### New setUI, getUI Methods

> > The bugtraq report that corresponds to this change is: 4226238.

> > The `setUI`/`getUI` methods were not implemented for `JPanel`, even though its look and feel is defined by pluggable look and feel (plaf). See `javax.swing.plaf.basic.BasicPanelUI.java`, for example.

## JTabbedPane

> ### JTabbedPane and Focus

> > The new focus specification states that focus requests on components that are not showing will fail. This can have subtle side effects. One such side effect is that requesting focus from a `ChangeListener` associated with a `JTabbedPane` may fail. At the same time, the `ChangeListener` is notified that the component is not currently visible and therefore the focus request fails in the same situation that it probably worked under the previous release. If you are running into this situation with `JTabbedPane` it is suggested you make the component visible before requesting focus. Other situations may require different approaches.

> ### New indexAtLocation Method in JTabbedPane

> > The bugtraq report that corresponds to this change is: 4241787.

> > Prior to this change, there was no way for client programs to convert a coordinate location to a particular tab in a tabbedpane. This made it difficult to implement special event handling on a `JTabbedPane` (like popping up a menu over a tab).

> > The method indexAtLocation has been added to `JTabbedPane`.

> ### New Mnemonic Support for Accessing Tabs in JTabbedPane

> > The bugtraq report that corresponds to this change is: 4284674.

> > The panes of a `JTabbedPane` did not previously allow for mnemonics. To facilitate this, the methods `getDisplayedMnemonicIndexAt` and `setDisplayedMnemonicIndexAt` have been added.

> ### Exceptions Thrown by JTabbedPane Now Consistent

> > The bugtraq report that corresponds to this change is: 4287053.

> > The `JTabbedPane` class is a container that has many methods which take an integer index as a parameter. Unfortunately, these methods weren't inconsistent with their approach to throwing exceptions (some methods check/throw, some don't). Additionally, the javadoc was in error - it stated that an `IllegalParameterException` was thrown when in fact an `ArrayIndexOutOfBoundsException` was thrown (by the underlying `Vector`).

> > Any method which takes an index that must be in the valid range from 0 to tabCount-1 now documents that it throws an `IndexOutOfBoundsException` (note: the underlying code continues 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 `JTabbedPane` methods:

> >         public String getTitleAt(int index)
> >         public Icon getIconAt(int index)
> >         public Icon getDisabledIconAt(int index)
> >         public String getToolTipTextAt(int index)
> >         public Color getBackgroundAt(int index)
> >         public Color getForegroundAt(int index)
> >         public boolean isEnabledAt(int index)
> >         public Component getComponentAt(int index)
> >         public int getDisplayedMnemonicIndexAt(int index)
> >         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 icon)
> >         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)

> > The same exception handling will be added to the following methods which previously did nothing:

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

## JTable

> ### DefaultTableModel.moveRow Specification Clarified

> > The bugtraq report that corresponds to this change is: 4144295.

> > In JDK 1.3, the `moveRow` method in `DefaultTableModel` was documented in such a way that it did not clearly define whether the row at `startIndex` or the row at `endIndex` row would end up at `toIndex`. By inference from the examples, it appears that the `startIndex` should end up at `toIndex` when moving rows downward and the `endIndex` should end up at `toIndex` when moving rows upward.

> > That said, the implementation of `moveRow` had a bug such that whenever the number of rows being moved was more than one - the rows would end up in somewhat arbitrary positions and would not even be contiguous after the move. Bug 4144295 noted that the implementation did not even perform the example in its specification: the `moveRow(1, 3, 5)` example in practice left the vector in the following state:

> >     a|C|e|B|D|f|g|h|i|j|k

> > The new implementation makes the observation that this operation is a simple rotation of elements between bounds that can be calculated from the inputs.

> > Since the previous implementation did not work we have taken the opportunity to simplify the definition to one where the `startIndex` is always moved to the `toIndex`, with all other elements appearing after `toIndex` in the same order that they were originally. Note that this performs the same operation as the previous implementation in the only case where it worked - when a single row was being moved.

> > The new implementation does not throw an exception when `endIndex` is less than `startIndex` - it does nothing instead having satisfied the implied contract to move all rows, `r`, where `startIndex <= r <= endIndex`.

> ### Typing into a JTable Now Transfers Focus to the Cell

> > The bugtraq report that corresponds to this change is: 4274963.

> > The Excel application automatically gives focus to underlying editors when a user presses an alphanumeric key. We have received over 200 JDC votes requesting that we offer this behavior in `JTable`. While we can't change the default behavior for reasons of backwards compatibility, in this release we have added the new property, `surrendersFocusOnKeystroke`, to address this request. The new methods `setSurrendersFocusOnKeystroke` and `getSurrendersFocusOnKeystrok` support this feature. The default behavior remains unchanged.

> ### DefaultTableModel Now Allows a Null For Name Argument

> > The bugtraq report that corresponds to this change is: 4474094.

> > The methods `DefaultTableModel.addColumn(Object)` and `DefaultTableModel.addColumn(Object, Vector)` did not previously allow `null` for the `name` argument - they threw an `IllegalArgumentException`. As it is possible to set the column name to `null` via other means (using constructors, or directly manipulating the field), the `addColumn` methods now also allows a `null` value.

## JTree

> ### DefaultTreeModel Now Allows a Null Root

> > The bugtraq report that corresponds to this change is: 4264897.

> > `DefaultTreeModel` now allows a `null` root node . Previously, the javadoc for `TreeModel` specified that a `null` root was valid, but `DefaultTreeModel` would not allow one. `DefaultTreeModel` now allows setting a `null` root, as well as a `null` root in the constructor. The javadoc for `setRoot` has been revised to reflect the change.

> ### Added First Letter Navigation to JTree

> > The bugtraq report that corresponds to this change is: 4284709.

> > Often times users wish to navigate to cells in a `JTree` using alphanumeric keys. To facilitate this, a method named `getNextMatch` has been added to `JTree`. `BasicTreeUI` installs a `KeyListener` that invokes this method as keys are typed on the keyboard.

## JList

> ### ListDataEvent.toString Now Provides Useful Information

> > The bugtraq report that corresponds to this change is: 4134085.

> > Developers often rely on the `toString` method for useful debugging information. Unfortunately `ListDataEvent`'s `toString` method did not really provide anything useful. For this release, it has been changed to return something useful.

> ### JList Now Supports First Letter Key Navigation

> > The bugtraq report that corresponds to this change is: 4284709.

> > Often times users wish to navigate to cells in a `JList` using alphanumeric keys. To facilitate this, `getNextMatch` was added to `JList`. `BasicListUI` will then install a `KeyListener` that will invoke this method as keys are typed to update the selection.

> ### JList Items May Now be Arranged Horizontally

> > The bugtraq report that corresponds to this change is: 4460016.

> > `JList` previously only allowed laying out its cells vertically, that is:

> >     1
> >     2
> >     3
> >     4

> > Numerous users have asked for the ability to lay out the list horizontally, something like:

> >     1  3
> >     2  4

> > or

> >     1  2
> >     3  4

> > To achieve this, three constants are added to `JList`, `VERTICAL`, `VERTICAL_WRAP`, and `HORIZONTAL_WRAP`. The methods `getLayoutOrientation` and `setLayoutOrientation` are also added to `JList`. The javadoc for the `JList` methods `getScrollableTracksViewportHeight`, `getScrollableTracksViewportWidth`, `getScrollableBlockIncrement`, and `getPreferredScrollableViewportSize` are updated accordingly. Likewise, the javadoc for `getPreferredSize` in `javax.swing.plaf.basic.BasicListUI` is updated.

## Miscellaneous

> ### Two default settings in Metal look and feel have changed

> > Two default settings have changed in the Metal look and feel:

> > - The foreground color for `JLabel` has changed from dark blue to black.

> > - The font for `DefaultListCellRenderer` has changed from normal to bold.

> ### JColorChooser.setPreviewPanel doesn't remove the old one

> > The bugtraq report that corresponds to this change is: 4759306.

> > When calling this method the default PreviewPanel was not removed from the colorChooser, though the new panel was added. This resulted in strange artifacts. This has been fixed in release 1.4.2.

> ### Deadlock in JColorChooser Fixed

> > The bugtraq report that corresponds to this change is: 4668511.

> > This bug when encountered in 1.4.0, caused a deadlock that would hang the entire application. This has been fixed in 1.4.1.

> ### JFrame.setDefaultCloseOperation Can Now Throw SecurityException

> > As of release 1.4.1, the `setDefaultCloseOperation` method in `JFrame` may now throw `SecurityException`.

> ### Metal Can Now Pick up Font Sizes from the Desktop on Microsoft Windows

> > The bugtraq reports that correspond to this change are: 4419964 and 4668963.

> > Prior to this release, the `DefaultMetalTheme` ignored the font size information from the Windows desktop. As of release 1.4.1, `DefaultMetalTheme` can use the font sizes specified in the Windows desktop. This can be disabled using the system property `swing.useSystemFontSettings`. An additional part of this bug is that our Windows look and feel was picking up the wrong fonts for a handful of components; this has been fixed.

> ### Some Locales Will Honor Font Size Only from the Desktop on Windows

> > The bugtraq report that corresponds to this change is: 4615396.

> > On Microsoft Windows, with the `WindowsLookAndFeel`, in certain locales we only honor font size from the desktop. This has been addressed in 1.4.1.

> ### Document Which Properties a Look and Feel May Ignore

> > The bugtraq report that corresponds to this change is: 4420209.

> > Some look and feel implementations may ignore certain properties which affect the look and feel. With this release, the documentation for certain methods has been modified to indicate that these properties may be ignored by some look and feels. Also, the class spec for `UIManager` and the documentation for the `javax.swing.plaf.metal` package were modified to specify that the Java look and feel is the default look and feel. This modification affects only documentation.

> > The affected methods are:

> > - `javax.swing.AbstractButton`
> >   - `public boolean isFocusPainted()`
> >   - `public void setFocusPainted(boolean b)`
> >   - `public boolean isRolloverEnabled()`
> >   - `public void setRolloverEnabled(boolean b)`
> > - `javax.swing.JButton`
> >   - `public boolean isDefaultButton()`
> >   - `public boolean isDefaultCapable()`
> >   - `public void setDefaultCapable(boolean defaultCapable)`
> > - `javax.swing.JCheckBox`
> >   - `public boolean isBorderPaintedFlat()`
> >   - `public void setBorderPaintedFlat(boolean b)`
> > - `javax.swing.JColorChooser`
> >   - `public boolean getDragEnabled()`
> >   - `public void setDragEnabled(boolean b)`
> > - `javax.swing.JComboBox`
> >   - `public boolean isLightWeightPopupEnabled()`
> >   - `public void setLightWeightPopupEnabled(boolean aFlag)`
> > - `javax.swing.JFileChooser`
> >   - `public boolean getDragEnabled()`
> >   - `public void setDragEnabled(boolean b)`
> >   - `public boolean getControlButtonsAreShown()`
> >   - `public void setControlButtonsAreShown(boolean b)`
> > - `javax.swing.JInternalFrame`
> >   - `public boolean isIconifiable()`
> >   - `public void setIconifiable(boolean b)`
> > - `javax.swing.JList`
> >   - `public boolean getDragEnabled()`
> >   - `public void setDragEnabled(boolean b)`
> > - `javax.swing.JPopupMenu`
> >   - `public boolean isLightWeightPopupEnabled()`
> >   - `public void setLightWeightPopupEnabled(boolean aFlag)`
> > - `javax.swing.JProgressBar`
> >   - `public boolean isStringPainted()`
> >   - `public void setStringPainted(boolean b)`
> >   - `public boolean isIndeterminate()`
> >   - `public void setIndeterminate(boolean newValue)`
> > - `javax.swing.JSplitPane`
> >   - `public boolean isOneTouchExpandable()`
> >   - `public void setOneTouchExpandable(boolean newValue)`
> >   - `public boolean isContinuousLayout()`
> >   - `public void setContinuousLayout(boolean newContinuousLayout)`
> > - `javax.swing.JTable`
> >   - `public boolean getDragEnabled()`
> >   - `public void setDragEnabled(boolean b)`
> > - `javax.swing.text.JTextComponent`
> >   - `public boolean getDragEnabled()`
> >   - `public void setDragEnabled(boolean b)`
> > - `javax.swing.JToolBar`
> >   - `public boolean isFloatable()`
> >   - `public void setFloatable(boolean b)`
> > - `javax.swing.JTree`
> >   - `public boolean getDragEnabled()`
> >   - `public void setDragEnabled(boolean b)`
> >   - `public boolean getShowsRootHandles()`
> >   - `public void setShowsRootHandles(boolean newValue)`
> >   - `public boolean getScrollsOnExpand()`
> >   - `public void setScrollsOnExpand(boolean newValue)`

> ### SwingConstants Now Define NEXT and PREVIOUS

> > The bugtraq report that corresponds to this change is: 4175466.

> > `SwingConstants` defines constants that are used throughout Swing. A common UI operation is to locate the next/previous item in a sequence; as such, `SwingConstants` now defines constants for `NEXT` and `PREVIOUS`.

> ### New Way to Process Bindings for Swing Components from a non-Swing Component

> > The bugtraq report that corresponds to this change is: 4344900.

> > Swing has an elaborate infrastructure to support associating actions with particular key strokes. This means that when the user types a character the action executes. The processing of these events is triggered from within `JComponent.processKeyEvent` (`processKeyEvent` is overridden from `java.awt.Component`). As the processing of these actions occurs within `JComponent`, there was previously no way for developers to process bindings from within non-`JComponent` subclasses that get focus. To facilitate this, a `processKeyBindings` method was added to `SwingUtilities`.

> ### Auditory Feedback for Swing Components

> > The bugtraq report that corresponds to this change is: 4290988.

> > Note: Due to a handful of bugs in the sound package we default to playing no sounds. If you would like to turn on sounds, you can do the following:

> >         UIManager.put("AuditoryCues.playList",
> >             UIManager.get("AuditoryCues.allAuditoryCues"));

> > Previously, Swing components did not provide the same auditory feedback as native components on many platforms. MALF2, a set of modifications to Swing's PLAFs, is primarily intended for use as an output-only, non-speech audio user feedback mechanism. The MALF2 project is important from the perspective of Swing/JFC and the Java platform's goal of tight user interface integration with the underlying platform. The MALF2 project ensures that a user's experience with a native application and a Swing/JFC application is identical with regard to the auditory user feedback.

> > The implementation centers around adding API to `BasicLookAndFeel` to support loading an `ActionMap` containing `Action`s that play sounds. Various `BasicComponentUI` implementations then invoke `actionPerformed` on the `Action` at the appropriate time to play the sound. For example, `BasicMenuItemUI` uses `doClick` to perform the action. While `BasicLookAndFeel` plays sounds using the Java Sound API, subclasses can use an alternative method. For example, `WindowsLookAndFeel` maps the Strings to `Runnable`s by way of `Toolkit.getDefaultToolkit().getDesktopProperty()`, to provide integration with the sounds provided by Windows.

> > The `ActionMap` containing the sounds can be accessed via `BasicLookAndFeel.getAudioActionMap`. When `getAudioActionMap` is first invoked, it performs the following:

> > 1. The default entry `auditoryCues.cueList` (an `Object[]`) is used to determine a list of sounds to load.
> > 2. Each entry in the array is passed to `createAudioAction` to obtain the `Action` responsible for playing the sound.
> > 3. The `Object` passed into `BasicLookAndFeel.createAudioAction` is used to look up a path to a sound file from the defaults table that can be loaded by Java Sound.
> > 4. When one of the `BasicComponentUI`s classes wishes to play a sound, it invokes `BasicLookAndFeel.playSound`, passing in the `Action`.
> > 5. `BasicLookAndFeel.playSound` invokes `actionPerformed` on the `Action` if the name of the `Action` is contained in the defaults entry `AuditoryCues.playList`.

> > This architecture allows the developer numerous ways to customize the sounds that are played:

> > - The sounds associated with a particular `JComponent` can be manipulated by changing the `Action` in the `ActionMap` associated with the `JComponent`, eg:

> >       ActionMap map = menuItem.getActionMap();
> >       map.put("MenuItem.commandSound", differentActionToPlaySound);

> > - The sounds used by all `Component`s of a particular type can be changed by manipulating the defaults table, eg:

> >       UIManager.put("MenuItem.commandSound", "pathToNewSoundFild");

> > - Developers creating a custom look and feel may override one of the `BasicLookAndFeel` methods to load the sounds in an alternative manner, or perhaps play the sounds in a different way.

> > Alternatively, the set of sounds to be played can be manipulated by way of the defaults entry `AuditoryCues.playList`. This `Object` array contains the keys in the defaults table indicating which sounds to play. `MetalLookAndFeel` defines this to be:

> >     new Object[]  {"OptionPane.errorSound",
> >     	  "OptionPane.informationSound",
> >     	  "OptionPane.questionSound",
> >     	  "OptionPane.warningSound" }

> > This has the effect of turning on only the sounds that `JOptionPane` supports.

> ### JMenu Updated to Work with New Focus Architecture

> > The bugtraq report that corresponds to this change is: 4371580.

> > The new focus architecture introduced via RFE 4290675 allows for developers to request a temporary focus change. The request is done through the protected `Component` methods `requestFocus(boolean)` or `requestFocusInWindow(boolean)`. These two methods are protected as they are not meant for general use, but only for implementors of lightweight toolkits, such as Swing. Swing is architected in such a way that code in different packages needs to temporarily request focus; as such, the parent class of all Swing Components, `JComponent`, needs to expose `requestFocus(boolean)` and `requestFocusInWindow` as public.

> ### New Support for Changing ComponentOrientation in Tree of Components

> > The bugtraq report that corresponds to this change is: 4337186.

> > With the bulk of the Swing components paying attention to their `ComponentOrientation` property, we now need two features to make it easier to manage the `ComponentOrientation` settings of an entire hierarchy of components. It should be easy to set entire hierarchies of components to a consistent `ComponentOrientation` setting using the new `SwingUtilities` method `applyComponentOrientation(Component c, ComponentOrientation o)`.

> ### New Access to Desktop Properties

> > The bugtraq report that corresponds to this change is: 4290973.

> > As part of the Windows look and feel update, a method was added to `LookAndFeel`, `getDesktopPropertyValue`, to facilitate accessing desktop properties.

> ### New Method to Offset Rectangle by Component's Insets

> > This was actually added as part of the update to `JProgressBar` to support an indeterminate state. The bugtraq report that corresponds to this change is: 4290717.

> > The new method is `calculateInnerArea(Component, Rectangle)` has been added to `SwingUtilities`.

> ### New API for Mouse Wheels

> > The bugtraq report that corresponds to this change is: 4356268.

> > Wheel mice, with a scroll wheel as a middle mouse button, are increasingly popular. This proposal provides for built-in Java support for scrolling via the mouse wheel, as well as a new wheel event listener so developers can customize mouse wheel behavior.

> > A new class, `MouseWheelListener`, and a new interface, `MouseWheelEvent`, have been added. The constant, `MOUSE_WHEEL_EVENT_MASK` has been added to `AWTEvent`. `AWTEventMulticaster` has three new methods: `mouseWheelMoved`, `add`, and `remove`. `Component` has two new methods: `addMouseWheelListener`, and `removeMouseWheelListener`. `ScrollPane` also has two new methods: `setWheelScrollingEnabled` and `isWheelScrollingEnabled`. Finally, `Robot` has the new method `mouseWheel`.

> ### JFrame, JDialog, and JApplet No Longer Override processKeyEvent

> > The bugtraq report that corresponds to this change is: 4462408.

> > Swing supports the option of registering key bindings on `JComponent`s. In previous releases it was necessary for Swing top level components ( `JFrame`, `JDialog`, and `JApplet`) to override `processKeyEvent` (defined in `java.awt.Component`) to activate these bindings if the focus was ever on one of these top level components. With the addition of `java.awt.KeyEventPostProcessor` and Swing taking advantage of this ( RFE 4389332), it is no longer necessary for these methods to be overridden in the Swing top level components. As of this release, these methods have been removed at the top level and are now inherited.

> ### Document Headless Exceptions for JWindow Constructors

> > The bugtraq report that corresponds to this change is: 4483258.

> > Though the headless mode was added to this release, two `JWindow` constructors did not indicate that `HeadlessException` may be thrown. This has been fixed in the doc for `Window(Window, GraphicsConfiguration)` and `JWindow(GraphicsConfiguration)`.

> ### Known Input Verifier Bug

> > The bugtraq report that corresponds to this change is: 4532517.

> > We've recently found an input verifier bug that has been causing problems for some of our users. Under 1.4, the `shouldYieldFocus` method does not allow side-effects such as popping up an `OptionPane`.

> > We do have the following workaround:

> >         public boolean shouldYieldFocus(JComponent input) {
> >           if (verify(input)) {
> >             return true;
> >           }

> >           // According to the documentation, should yield focus is allowed to cause
> >           // side effects.  So temporarily remove the input verifier on the text
> >           // field.
> >           input.setInputVerifier(null);
> >           System.out.println("Removed input verifier");

> >           // Pop up the message dialog.
> >           String message = "Roll over the 'JButton1' with mouse pointer "
> >             + "after closing this dialog.\nIt sometimes behaves correctly "
> >             + "for the first time\n but repeating action brings incorrect "
> >             + "behaviour of button.";
> >           JOptionPane.showMessageDialog(null, message , "invalid value",
> >             JOptionPane.WARNING_MESSAGE);
> >           System.out.println("Showed message.");

> >           // Reinstall the input verifier.
> >           input.setInputVerifier(this);
> >           System.out.println("Reinstalled input verifier");

> >           // Tell whomever called us that we don't want to yield focus.
> >           return false;
> >         }

## Known Bugs

> ### Focus Bug When Simultaneously Running Windows and a Remote Display Application

> > In certain circumstances showing a heavy weight Window that is not focusable causes focus to be lost. This specifically happens when running flavors of Windows and a remote display application, such as Reflection-X, at the same time. Note that this bug was filed against release 1.4, but is fixed in 1.4.1. Refer to bug 4628933 for details.

## JRootPane

> ### New Multi Implementation of RootPaneUI

> > The bugtraq report that corresponds to this change is: 4338458.

> > The classes in `javax.swing.plaf.multi` are used to multiplex between multiple look and feels. This is typically used by assistive technologies that use an auxiliary look and feel to provide additional information, such as auditory information. There is currently no implementation in multi for `RootPaneUI` which makes using an auxiliary look and feel problematic.

> > The new class `javax.swing.plaf.multi.MultiRootPaneUI` has been added.

> ### Support for Look and Feels to Provide Window Decorations

> > The bugtraq report that corresponds to this change is: 4290471.

> > AWT recently provided API such that `Window`s may be undecorated. That is, when undecorated is true, the `Window` will not render any widgets for closing, moving, or resizing. As such, Swing has made it possible for the look and feel to render decorations for Windows.

> > This feature is primarily supported in `javax.swing.JRootPane`, but we encourage developers to use the switches provided in `javax.swing.JFrame` and `javax.swing.JDialog`.

> > The following changes were made to `JRootPane`:

> >         public static final int NONE;
> >         public static final int FRAME;
> >         public static final int PLAIN_DIALOG;
> >         public static final int INFORMATION_DIALOG;
> >         public static final int ERROR_DIALOG;
> >         public static final int COLOR_CHOOSER_DIALOG;
> >         public static final int FILE_CHOOSER_DIALOG;
> >         public static final int QUESTION_DIALOG;
> >         public static final int WARNING_DIALOG;

> >         public void setWindowDecorationStyle(int style)
> >         public int getWindowDecorationStyle()

> > Not all look and feels support the window decoration style; the method `getSupportsWindowDecorations` has been added to `javax.swing.LookAndFeel` to provide a way for look and feels to indicate whether they support this behavior.

> > The methods, `isDefaultLookAndFeelDecorated()`, and setDefaultLookAndFeelDecorated have been added to `JFrame`.

> > The methods, `isDefaultLookAndFeelDecorated()`, and setDefaultLookAndFeelDecorated have also been added to `JDialog`.

## JScrollBar

> ### JScrollBar Now Overrides setUI

> > The bugtraq report that corresponds to this change is: 4213298.

> > `JScrollBar` did not previously override the `setUI` method. For this release, it has been changed to conform to this behavior.

## JScrollPane

> ### JScrollPane Supports New MouseWheelListener

> > This was implemented as part of the mouse wheel support. This section only documents the changes to `JScrollPane`, for details of the other changes refer to this section. The bugtraq report that corresponds to this change is: 4356268.

> > The methods `isWheelScrollingEnabled` and `setWheelScrollingEnabled` were added to `JScrollPane`.

> > A new protected inner class, `MouseWheelHandler`, was added to `javax.swing.plaf.basic.BasicScrollPaneUI`. The relevant method in this inner class is `mouseWheelMoved`. Finally, the new method `createMouseWheelListener` has been added to `BasicScrollPaneUI`.

## RepaintManager

> ### New VolatileImage Support

> > The bugtraq report that corresponds to this change is: 4363288.

> > The Java 2D team has implemented a new `VolatileImage` mechanism that has the ability to take advantage of hardware acceleration for `Image` graphics and blit-to-screen operations.

> > By default, Swing uses double-buffering to paint the contents of GUI components (by rendering into an offscreen image and then copying that image to the screen) and has been changed to take advantage of the new `VolatileImage` support.

> > The double buffer that Swing uses to do painting is obtained from the `RepaintManager` by using the method `getOffscreenBuffer`. Since a `VolatileImage` object requires special handling (to test for failure conditions), we could not simply change this method to return a `VolatileImage` since there may be existing code out there that invokes this method and does not implement this additional handling. Therefore, we have added a method, `getVolatileOffscreenBuffer`, to `javax.swing.RepaintManager` to specifically return a `VolatileImage` object.

## SpringLayout

> ### New SpringLayout Class

> > The bugtraq report that corresponds to this change is: 4290203.

> > This release introduces the new layout manager, `SpringLayout`.

> > See How to Use SpringLayout in The Java Tutorial for examples of using `SpringLayout`.

Copyright © 2002 Sun Microsystems, Inc. All Rights Reserved. Please send comments to: swing-feedback@java.sun.com. This is not a subscription list. | Java Software