Java

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

 Project Swing

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:

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:

Sections

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:

JButton

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:

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

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:

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 is now supported in JFileChooser, but due to an oversight the javadoc for setMultiSelectionEnabled wasn't updated. The javadoc will be corrected in the next 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 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.

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.

JPopupMenu

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

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

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

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:

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 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 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 BasicComponentUIs 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:

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

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;
    }

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 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 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. 		Sun
Java Software