AWT Enhancements in the Java 2 Platform Standard Edition 5.0

Major Changes
Window Bugfixes and Enhancements
DnD and Data Transfer Bugfixes and Enhancements
Layout Bugfixes
Miscellaneous Bugfixes
Known Bugs and Issues

Major Changes

4615479: XToolkit on Solaris and Linux

In this release, AWT has been reimplemented on the Solaris and Linux platforms. It is possible to force the Motif toolkit on Linux or XAWT on Solaris. This is done either by setting the AWT_TOOLKIT variable or using the -Dawt.toolkit command line parameter. The value for XAWT is sun.awt.X11.XToolkit and the value for Motif is sun.awt.motif.MToolkit. For more information, see the XToolkit on Solaris/Linux note.

4638443: XDnD Support

As of this release, the XDnD Protocol support has been implemented as part of the data transfer system. Prior to this release, only the Motif DnD protocol was supported on X11.

4009555: Obtaining the mouse location on the desktop

API has been added to obtain the mouse location on the desktop. The new PointerInfo class describes the pointer coordinates and the associated GraphicsDevice object at the moment the PointerInfo instance is created. PointerInfo has the following methods:

The new MouseInfo class has information about the current location of the mouse pointer. MouseInfo has two methods:

Other new methods:

java.awt.Component.getMousePosition()
java.awt.Container.getMousePosition(boolean)
java.awt.Toolkit.getMouseInfoPeer

Window Bugfixes and Enhancements

4632143: Window, Frame or Dialog Always on Top

New API has been added to ensure that a particular Window, Frame or Dialog is always on top of the desktop. This is useful when implementing certain GUI elements, such as tool boxes, notification or information applets, and other desktop-enhancing features. The new and modified API includes:

Depending on the system setup, always-on-top Windows, Frames or Dialogs may not be supported. They are supported on Microsoft Windows, Linux and Solaris running GNOME2/Metacity, as well as Linux running KDE/kwin. They are not supported on Solaris running CDE/dtwm. It is possible that always-on-top windows do not work on Linux or Solaris running session and window managers other than those mentioned above.

4102292: New API to Specify Default Window Location by Platform

Two new methods and one new property allow the user to specify the default location for a new Window, appropriate to the platform. This is especially important for X11. The new api includes: Note that the locationByPlatform property must be set to true for the underlying window manager to tile the window according to its own logic. Otherwise, AWT won't know whether the window was put at 0,0 intentionally or was just unspecified and the window will be placed at the upper-left-hand corner of the screen.

4101435: Window/Dialog/Frame.setLocation doesn't always work as expected

The location and size of Windows, Dialogs and Frames, is under the control of the desktop's window management system, not the application or the toolkit. The window manager is free to ignore or modify a window placement request. Therefore, when calling Window.setLocation(x, y), you can't rely on the Window being moved to location (x, y). The same situation exists for Window.setSize and Window.setBounds. The Window documentation has been clarified to explain this.

4401846: New _JAVA_AWT_WM_STATIC_GRAVITY Environment Variable

Certain window managers position AWT windows incorrectly. For example, a window that is requested to be moved to (0,0) will, under some window managers, be positioned so that the window's title and left border are off-screen. This is because there are two schools of window managers that disagree on the interpretation of the ICCCM specification for the ConfigureRequest requests that X11 programs make to position their windows.

To address this issue, the _JAVA_AWT_VM_STATIC_GRAVITY environment variable has been added so that a power user can indicate that his window manager implements the StaticGravity behavior.

DnD and Data Transfer Bugfixes and Enhancements

4378091: New DropTarget.getTransferable method

The new java.awt.dnd.DropTargetDragEvent.getTransferable method enables the drop target to access transfer data during a drag operation.

This also fixes bug 4248542: DropTargetListener can't access the transferable in dragOver and dragEnter.

4259272: Notification of Clipboard contents changes is now supported

Previously, the Java clipboard API didn't allow an efficient way to track changes to the set of DataFlavors available on the clipboard or notify interested parties about those changes. API has been added for this purpose:

4287795: New methods for querying information in a Clipboard

Three new methods have been added:

4790833: Memory Usage No Longer Shoots Up using Clipboard.getContents

Prior to this release, Clipboard.getContents fetched clipboard data in all provided formats for which a mapping to the corresponding data flavor in the default flavor map exists. If there were a lot of formats and the data were large, a lot of memory was consumed with the fetched data in different formats. Thanks to the new methods introduced with bug fix 4287795, this problem has been fixed.

4415175: New API to Globally Change the DnD Gesture Motion Threshold

The drag motion gesture threshold represents the number of pixels the cursor is dragged before the data transfer system initiates a drag operation. Prior to this release, this was hard-coded to 5 pixels. As of release 5.0, there is support for picking up the desktop properties for drag sensitivity and mapping it to the threshold, and new API that allows users to get and change this threshold. The new API includes:

4712068: DnD Usability Issue for Dragging Text

Prior to this release, the hotspot of the drop icons used on X platforms was located at the middle of the icon. When dragging text, the text cursor moves to indicate the current drop location, but this was obscurbed by the drop icon itself. For this release, the drop cursors used on X platforms have been changed to point to the upper-left corner of the drop icon. The corresponding hotspots have been changed accordingly.

4191708: Clarification in spec for several java.awt.dnd.DropTarget methods

The doc has been clarified with respect to passing in a null parameter for the following java.awt.dnd.DropTarget methods:

4819437: DragSourceListener.dragExit is now called in a consistent way

The class specification for the DragSourceAdapter and DragSourceAdapter classes, and the documentation for the DragSourceAdapter.dragExit and DragSourceListener.dragExit methods have been updated to clarify the notion that the drop site is associated with the previous call to dragEnter.

4654688: SystemFlavorMap Methods Now Consistent with Documentation

The SystemFlavorMap class is used to store mappings between native formats and Java data flavors in order to support data transfer between native and Java applications. The documentation for the SystemFlavorMap.getNativesForFlavor(DataFlavor) method has been clarified to say that a DataFlavor (or a native format) is known if and only if it has at least one static mapping associated with it.

4123385: Documentation Clarification for Drag Source Events Constructors Constructors

The documentation has been clarified with respect to passing in invalid parameters for the following constructors of drag source events:

Layout Bugfixes

GridBagLayout Bugfixes

GridBagLayout: Several bugfixes have been implemented for GridBagLayout. Note that two of these bugs listed apply to the documentation only. The most significant bugfixes include:

4254022: More than 512 horizontal or vertical components are now possible in a GridBagLayout

Previously, GridBagLayout had been implemented with a hard-coded width and height limit of 512. This is now allocated dynamically and the MAXGRIDSIZE constant is no longer used.

4532201: GridBagLayout.lookupConstraints doc is clarified

Documentation was added to clarify what happens when the specified Component is not in the grid bag layout.

4618355: Doc for GridBagLayout.gridwidth/gridheight is clarified

The class spec for GridBagLayout.gridwidth/gridheight was confusing in its description of REMAINDER and RELATIVE. This has been corrected.

FlowLayout Bugfixes

FlowLayout: Several documentation bugs have been fixed for FlowLayout

4586806: FlowLayout spec is corrected regarding alignment

Previously, the class spec stated that components are centered on the line. Actually, the align property determines how the components are laid out. The doc has been corrected.

4881919: FlowLayout class spec no longer implies that components are always left to right

The FlowLayout class spec was written before the ability to go right to left was added. Therefore it assumed that left to right was the only possible orientation. The doc has been corrected.

4587456: Corrected spec for FlowLayout constructor

Previously, the doc for the FlowLayout constructor neglected to mention that the hgap and vap were applied to the spacing between the components and the container border as well as between the components. The documentation has been corrected.

4172932: New methods to get constraints for children in BorderLayout

Three public methods have been added to BorderLayout, one to get the constraints for a component, and two different ways to get the component for a given constraint (one takes component orientation into account and the other doesn't). The new methods are:

4515041: Clarified spec for GridLayout.layoutContainer regarding vgap and hgap params

Previously, the spec for layoutContainer stated that the vgap and hgap was added between each cell and between the first/last cell and the border. In reality, the gaps are applied between the components only. This has been corrected in the doc.

Miscellaneous Bugfixes

4533021: New API to Change the Z-ordering of Children

New API has been added to specify the z-ordering of children in a Container. The two new Container methods include:

4370733: AWTKeyStroke.getAWTKeyStroke(String) and toString are now symmetric

Previously it was not possible to take the output from AWTKeyStroke.toString and pass it to the getAWTKeyStroke method. This has been changed so the methods

4341785: Clarify spec for several List methods

The spec for the following List methods has been clarified to state that unspecified behavior results when the range is out of bounds:

4368570: Clarify List spec regarding behavior of clicking on a selected item

Previously, the class spec for List stated that clicking on an unselected item selects it and clicking on a selected item de-selects it. This is true only if the list is in multiple-selection mode. In single-selection mode, any click on a list's item selects the clicked item. The spec has been clarified.

4082708: Clarified spec for the ContainerEvent.getContainer method

The ContainerEvent.getContainer method assumes that source is of type Container. Previously, it casted the source to type Container without first checking which could result in ClassCastException. The method has been changed to return a value of null if the source isn't a Container.

4620715: New KeyEvent codes for two standard Microsoft Windows keys.

Two keys on a standard Microsoft Windows keyboard don't have Java keycodes — the windows key and the context menu key. This impedes the ability to meet 508 requirements. Therefore, the java.awt.event.KeyEvent.VK_WINDOWS and java.awt.event.KeyEvent.VK_CONTEXT_MENU keycodes have been added.

4829063: Scrollbar now specifies that Scrollbar thumb may not be visible

Previously, the doc for Scrollbar.getVisibleAmount and setVisibleAmount did not say that sometimes the thumb might not be visible or accurately describe what the scrollbar's range is used for. The specification has been cleaned up. This is a doc-only change.

4840172: Behavior of KeyEvent.getKeyChar is clarified

Use of KeyEvent.getKeyChar is explained in the KeyEvent class documentation, but the doc for the method itself was brief. The doc for getKeyChar has been improved for this release.

4233061: Clarify spec that ENTER doesn't fire an ActionEvent

There is confusion among some developers that when the focus is on a Button, pressing the ENTER key doesn't fire an ActionEvent. This is correct behavior. The SPACE bar fires an ActionEvent. The ActionEvent class specification was updated to clarify this fact.

4221123: New FileDialog constructors

Three new FileDialog constructors have been added that can specify a Dialog as the owner:

4691481: Updated spec for Robot.createScreenCapture

Previously, the documentation for Robot.createScreenCapture didn't mention that the mouse cursor is not included in the captured image. This has always been true of Solaris, Linux, Windows and Mac OS X. The documentation has been updated to reflect this information.

4704042: New method for setting Insets

A single method to set Insets has been added: set(int, int, int, int).

4492739: Clarify InputEvent.ALT_MASK/BUTTON2_MASK and META_MASK/BUTTON3_MASK doc

There is an overlap in the values for some of the InputEvent constants. This is confusing because when calling KeyEvent.getModifiersExText(int) and MouseEvent.getMouseEventModifiersText(int) the string returned for KeyEvent.BUTTON2_MASK is "Alt" and the string returned for KeyEvent.BUTTON3_MASK is "Meta". For this release, documentation was added to the InputEvent, KeyEvent and MouseEvent classes to clarify this.

Known Bugs and Issues

Here is a list of known problems you may encounter in release 5.0.

Metacity versioning

We recommend using the latest build of Metacity (which is currently 2.6.2). There were some bugs that occurred with versions prior to 2.4.34 (problems with programmatic iconification, and non-resizable frames, for example) that have since been fixed.

5051557: Applet focus incompatibility

We have received reports that, in some applets, pressing a key on the keyboard doesn't have the expected result. This usually happens because the applet doesn't get the focus automatically when there are no child components in the applet. To ensure that such an applet works across all platforms, it is recommended that you request the focus at startup (via requestFocus) and on mouse press. If you don't want the focus, call setFocusable(false).

5050387: JVM may crash when JOptionPane is invoked from drop()

On Solaris/Linus running MToolKit, displaying a JOptionpane from the drop method may cause the JVM to crash. This bug will be addressed in a future release.

Focus bugs when running applets

There were focus-related bugs noticeable when running applets in Mozilla in release 1.4.2 and earlier. This includes: To solve this problem, the client side of the XEmbed protocol was implemented: However, the browser should support the server side of XEmbed in order for it to work. We recommend using the following browsers with Java:
Copyright © 1993, 2011, Oracle and/or its affiliates. All rights reserved.