| # AWT Enhancements in the JavaTM 2 Platform Standard Edition 5.0 | Documentation Contents

> > 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:
> > > - GraphicsDevice getDevice()
> > > - Point getLocation()

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

> > > - PointerInfo getPointerInfo()
> > > - int getNumberOfButtons

> > > 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:
> > > - isAlwaysOnTop()
> > > - setAlwaysOnTop(boolean)
> > > - addPropertyChangeListener(PropertyChangeListener)
> > > - addPropertyChangeListener(String, PropertyChangeListener)

> > >   > The `addXXX` methods have been modified to support setting a property change listener on the window's `alwaysOnTop` state.

> > > - java.awt.Permission

> > >   > The new `setWindowAlwaysOnTop` permission has been added.

> > > 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:
> > > - Window.setLocationByPlatform(boolean)
> > > - Window.isLocationByPlatform
> > > - Window.isLocationByPlatform (a property)
> > > 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:
> > > - addFlavorListener(FlavorListener)
> > > - removeFlavorListener(FlavorListener)
> > > - getFlavorListeners()

> > ### 4287795: New methods for querying information in a Clipboard

> > > Three new methods have been added:
> > > - DataFlavor[] getAvailableDataFlavors() returns the `DataFlavor`s currently available on the clipboard.
> > > - boolean isDataFlavorAvailable(DataFlavor) returns true if the specified data flavor is available.
> > > - Object getData(DataFlavor) returns the data in the specified data flavor.

> > ### 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:
> > > - java.awt.dnd.DragSource.getDragThreshold()
> > > - java.awt.dnd.drag.threshold (a property)
> > > - java.awt.dnd.MouseDragGestureRecognizer (updated class spec)

> > ### 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:
> > > - dragEnter(DropTargetDragEvent)
> > > - dragOver(DropTargetDragEvent)
> > > - dropActionChanged(DropTargetDragEvent)
> > > - drop(DropTargetDropEvent)
> > > - dragExit(DropTargetEvent)

> > ### 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:
> > > - DragSourceDragEvent(DragSourceContext, int int, int)
> > > - DragSourceDragEvent(DragSourceContext, int int, int, int, int)
> > > - DragSourceDropEvent(DragSourceContext)
> > > - DragSourceDropEvent(DragSourceContext, int, boolean)
> > > - DragSourceDropEvent(DragSourceContext, int, boolean, int, int)

> ## 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:
> > > - Component getLayoutComponent(Object)
> > > - Component getLayoutComponent(Container, Object)
> > > - Object getConstraints(Component)

> > ### 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:
> > > - getComponentZOrder(Component, int)
> > > - setComponentZOrder(Component, int)

> > ### 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:
> > > - deselect(int)
> > > - setMultipleMode(boolean)
> > > - select(int)

> > ### 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:
> > > - FileDialog(Dialog)
> > > - FileDialog(Dialog, String)
> > > - FileDialog(Dialog, String, int)

> > ### 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:
> > > - 4907493: Input focus not working with multiple applets
> > > - 4902616: The characters of a text field can't delete when doing Java Plug-in test
> > > - 4877530: Unable to input text into JTextField in 1.4.1_02
> > > - 4806274: The requestFocus method doesn't bring focus to the component on Netscape 7 on Solaris
> > > - 4816394: Can't input anything to SpreadSheet
> > > - 4837794: Can't input charact to login AnswerCenter with Java applet
> > > - 4902609: Tab key can't work when doing Java test case
> > > To solve this problem, the client side of the XEmbed protocol was implemented:
> > > - 4849238: Add XEmbed support to AWT
> > > - 4907325: XEmbed should be implemented for the Motif toolkit
> > > However, the browser should support the server side of XEmbed in order for it to work. We recommend using the following browsers with Java:
> > > - On Linux, Mozilla community edition at least version 1.5 or higher.
> > > - On Solaris, Sun Mozilla at least version 1.4 or higher.

> > ###

> Copyright © 2004 Sun Microsystems, Inc. All Rights Reserved. Please send comments to: java-awt@java.sun.com |