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 Bug Database ,
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.

Box now descends from JComponent

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

New Control of Highlighted Characters

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.

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:

PopupMenuListener Added to JComboBox

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:

JComboBox Now Supports Prototype Cell for Lists

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

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.

JFileChooser Windows Look and Feel Improved

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:

JInternalFrame Now Truncates Titles That are Too Long

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

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.

New
Support for Tooltips for Images in JEditorPane

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

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 semantics of the HTML parser ( javax.swing.text.html.parser.Parser)
have slightly changed to better match that of the browser
(Netscape 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 HTML support provided in the JDK 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

PlainDocument Constructor is Now Public

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.

Document.getText Method Now Allows for Partial Returns

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

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.

Further Support for New AbstractDocument.replace Method

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.

New showInputDialog Methods

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.

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.

As of this release, showing a JPopupMenu causes
focus to transfer to the parent JRootPane. This was
done so that JPopupMenus 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

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

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.

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

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

Exceptions Thrown by JTabbedPane Now Consistent

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

DefaultTableModel.moveRow Specification Clarified

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

DefaultTreeModel Now Allows a Null Root

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

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.

ListDataEvent.toString Now Provides Useful Information

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

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.

JFrame.setDefaultCloseOperation Can Now Throw
SecurityException

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.

Document Which Properties a Look and Feel May Ignore

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.

SwingConstants Now Define NEXT and PREVIOUS

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

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.

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
Actions 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
Runnables by way of Toolkit.getDefaultToolkit().getDesktopProperty(),
to provide integration with the sounds provided by Windows.

The sounds used by all Components 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:

JMenu Updated to Work with New Focus Architecture

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

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

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.

JFrame, JDialog, and JApplet No Longer Override
processKeyEvent

Swing supports the option of registering key bindings on
JComponents. 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.

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.

New Multi Implementation of RootPaneUI

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.

Support for Look and Feels to Provide Window Decorations

AWT recently provided API such that Windows 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 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.

New VolatileImage Support

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.