AWT

Debug Tips for AWT

This section describes helpful tips to debug issues related to AWT.

To dump the AWT component hierarchy, press Control+Shift+F1.

If the application hangs, get a stack trace by pressing Control+Break on Windows (which sends the SIGBREAK signal) or Control+\ on the Linux operating system (which sends the SIGQUIT signal).

To trace X11 errors on the Linux operating system, set the sun.awt.noisyerrorhandler system property to true.

Loggers can produce helpful output when debugging AWT problems. See java.util.logging package description.

The following loggers are available:

java.awt
java.awt.focus
java.awt.event
java.awt.mixing
sun.awt
sun.awt.windows
sun.awt.X11

Layout Manager Issues

This section describes possible problems with layout managers and provides workarounds when available.

The following problems occur with layout managers and workarounds:

Call to invalidate() and validate() increases component size
Cause: Due to some specifics of the GridBagLayout layout manager, if ipadx or ipady is set, and invalidate() and validate() are called, then the size of the component increases to the value of ipadx or ipady. This happens because the GridBagLayout layout manager iteratively calculates the amount of space needed to store the component within the container.

Workaround: The JDK does not provide a reliable and simple way to detect if the layout manager should rearrange components or not in such a case, but there is a simple workaround. Use components with the overridden method getPreferredSize(), which returns the current size needed, as shown in the following example.
```
public Dimension getPreferredSize(){
   return new Dimension(size+xpad*2+1, size+ypad*2+1); 
}
```
Infinite recursion with validate() from any Container.doLayout() method

Cause: Invoking validate() from any Container.doLayout() method can lead to infinite recursion because AWT itself invokes doLayout() from validate().

Key Events

Some issues related to handling key events do not have a solution in the current release.

The following keyboard issues are currently unresolved:

On some non-English keyboards, certain accented keys are engraved on the key and therefore are primary layer characters. Nevertheless, they cannot be used for mnemonics because there is no corresponding Java keycode.
Changing the default locale at runtime does not change the text that is displayed for the menu accelerator keys.
On a standard 109-key Japanese keyboard, the yen key and the backslash key both generate a backslash, because they have the same character code for the WM_CHAR message. AWT should distinguish them.

Modality Issues

This section provides information about issues related to using modality.

The section addresses the following issues.

UNIX window managers:

Many of the modality improvements are unavailable in some Linux environments, for example, when using Common Desktop Environment (CDE) window managers. To see if a modality type or modal exclusion type is supported in a particular configuration, use the following methods:
- Toolkit.isModalityTypeSupported()
- Toolkit.isModalExclusionTypeSupported()
When a modal dialog box appears on the screen, the window manager might hide some of the Java top-level windows in the same application from the taskbar. This can confuse end users, but it does not affect their work much, because all the hidden windows are modal blocked and cannot be operated.
Other modality problems:

For more information about modality-related features and how to use them, see the AWT Modality specification.

One of the sections in that specification describes some AWT features that might be related to or affected by modal dialog boxes: always-on-top property, focus handling, window states, and so on. Application behavior in such cases is usually unspecified or depends on the platform; therefore, do not rely on any particular behavior.

AWT Crashes

This section shows you how to identify and troubleshoot crashes related to AWT.

Distinguish an AWT crash:

When a crash occurs, an error log is created with information and the state obtained at the time of the crash. See Fatal Error Log.

A line near the top of the file indicates the library where the error occurred. The following example shows part of the error log file in the case when the crash was related to the AWT library.

...
# Java VM: Java HotSpot(TM) Client VM (1.6.0-beta2-b76 mixed mode, sharing)
# Problematic frame:
# C  [awt.dll+0x123456]
...

However, the crash can happen somewhere deep in the system libraries, although still caused by AWT. In such cases, the indication awt.dll does not appear as a problematic frame, and you need to look further in the file, in the section Stack: Native frames: Java frames as shown in the following example.

Stack: [0x0aeb0000,0x0aef0000),  sp=0x0aeefa44,  free space=254k
Native frames: (J=compiled Java code, j=interpreted, Vv=VM code, C=native code)
C  0x00abc751
C  [USER32.dll+0x3a5f]
C  [USER32.dll+0x3b2e]
C  [USER32.dll+0x5874]
C  [USER32.dll+0x58a4]
C  [ntdll.dll+0x108f]
C  [USER32.dll+0x5e7e]
C  [awt.dll+0xec889]
C  [awt.dll+0xf877d]
j  sun.awt.windows.WToolkit.eventLoop()V+0
j  sun.awt.windows.WToolkit.run()V+69
j  java.lang.Thread.run()V+11
v  ~StubRoutines::call_stub
V  [jvm.dll+0x83c86]
V  [jvm.dll+0xd870f]
V  [jvm.dll+0x83b48]
V  [jvm.dll+0x838a5]
V  [jvm.dll+0x9ebc8]
V  [jvm.dll+0x108ba1]
V  [jvm.dll+0x108b6f]
C  [MSVCRT.dll+0x27fb8]
C  [kernel32.dll+0x202ed]

Java frames: (J=compiled Java code, j=interpreted, Vv=VM code)
j  sun.awt.windows.WToolkit.eventLoop()V+0
j  sun.awt.windows.WToolkit.run()V+69
j  java.lang.Thread.run()V+11
v  ~StubRoutines::call_stub

If the text awt.dll appears somewhere in the native frames, then the crash might be related to AWT.

Troubleshoot an AWT crash:

One of the possible causes of crashes is that many AWT operations are asynchronous. For example, if you show a frame with a call to frame.setVisible(true), then you cannot be sure that it will be the active window after the return from this call.

Another example concerns native file dialogs. It takes some time for the operating system to initialize and show these dialogs, and if you dispose of them immediately after the call to setVisible(true), then a crash might occur. Therefore, if your application contains some AWT calls running simultaneously or immediately one after another, it is a good idea to insert some delays between them or add some synchronization.

Focus Events

The following sections discuss the troubleshooting issues related to focus events:

How to Trace Focus Events

You can trace focus events by adding a focus listener to the toolkit, as shown in the following example.

Toolkit.getDefaultToolkit().addAWTEventListener(new AWTEventListener(
   public void eventDispatched(AWTEvent e) {
      System.err.println(e);
   }
), FocusEvent.FOCUS_EVENT_MASK | WindowEvent.WINDOW_FOCUS_EVENT_MASK |
   WindowEvent.WINDOW_EVENT_MASK);

The System.err stream is used here because it does not buffer the output.

Remember:

The correct order of focus events is the following:

FOCUS_LOST on component losing focus
WINDOW_LOST_FOCUS on top-level losing focus
WINDOW_DEACTIVATED on top-level losing activation
WINDOW_ACTIVATED on top-level becoming active widow
WINDOW_GAINED_FOCUS on top-level becoming focused window
FOCUS_GAINED on component gaining focus

When focus is transferred between components inside the focused window, only FOCUS_LOST and FOCUS_GAINED events should be generated. When focus is transferred between owned windows of the same owner or between an owned window and its owner, then the following events should be generated:

FOCUS_LOST
WINDOW_LOST_FOCUS
WINDOW_GAINED_FOCUS
FOCUS_GAINED

Note:

The events losing focus or activation should come first.

Native Focus System

Sometimes, a problem can be caused by the native platform. To check this, investigate the native events that are related to focus.

Ensure that the window you want to be focused gets activated and that the component you want to focus receives the native focus event.

On the Windows platform, the native focus events are the following:

WM_ACTIVATE for a top-level. WPARAM is WA_ACTIVE when activating and WA_INACTIVE when deactivating.
WM_SETFOCUS and WM_KILLFOCUS for a component.

On the Windows platform, a concept of synthetic focus was implemented. It means that a focus owner component only emulates its focusable state, whereas real native focus is set to a focus proxy component. This component receives key and input method native messages and dispatches them to a focus owner. In the latest JDK releases a frame or dialog box serves as a focus proxy. Now, it proxies focus not only for components in an owned window but for all child components as well. A simple window never receives native focus and relies on the focus proxy of its owner. This mechanism is transparent for a user but should be taken into account when debugging.

On the Linux operating system, XToolkit uses a focus model that allows AWT to manage focus itself. With this model the window manager does not directly set input focus on a top-level window, but instead it sends only the WM_TAKE_FOCUS client message to indicate that focus should be set. AWT then explicitly sets focus on the top-level window if it is allowed.

Note:

The X server and some window managers may send focus events to a window. However, these events are discarded by AWT.

AWT does not generate the hierarchical chains of focus events when a component inside a top-level gains focus. Moreover, the native window mapped to the component does not get a native focus event. On the Linux platform, as well as on the Windows platform, AWT uses the focus proxy mechanism. Therefore, focus on the component is set by synthesizing a focus event, whereas the invisible focus proxy has native focus.

A native window that is mapped to a Window object (not a Frame or Dialog object) has the override-redirect flag set. Thus, the window manager does not notify the window about the focus change. Focus is requested on the window only in response to a mouse click. This window will not receive native focus events at all. Therefore, you can trace only FocusIn or FocusOut events on a frame or dialog box. Because the major processing of focus occurs at the Java level, debugging focus with XToolkit is simpler than with WToolkit.

Focus Models Supported by X Window Managers

The following focus models are supported by X window managers:

Click-to-focus is a commonly used focus model. (For example, Microsoft Windows uses this model.)
Focus-follows-mouse is a focus model in which focus goes to the window that the mouse hovers over.

Miscellaneous Problems with Focus

This section discusses issues related to focus in AWT that can occur and suggested solutions.

Linux + KDE, XToolkit cannot be switched between two frames when a frame's title is clicked.

Clicking a component inside a frame causes the focus to change.

Solution: Check the version of your window manager and upgrade it to 3.0 or greater.
You want to manage focus using KeyListener to transfer the focus in response to Tab/Shift+Tab, but the key event doesn’t appear.

Solution: To catch traversal key events, you must enable them by calling Component.setFocusTraversalKeysEnabled(true).
A window is set to modal excluded with Window.setModalExclusionType(ModalExclusionType).

The frame, its owner, is modal blocked. In this case, the window will also remain modal blocked.

Solution: A window cannot become the focused window when its owner is not allowed to get focus. The solution is to exclude the owner from modality.
On Windows, a component requests focus and is concurrently removed from its container.

Sometimes java.lang.NullPointerException: null pData is thrown.

Solution: The easiest way to avoid throwing the exception is to do the removal along with requesting focus on EDT. Another, more complicated approach is to synchronize the requesting focus and removal if you need to perform these actions on different threads.
When focus is requested on a component and the focus owner is immediately removed, focus goes to the component after the removed component.

For example, Component A is the focus owner. Focus is requested on Component B, and immediately after this Component A is removed from its container. Eventually, focus goes to Component C, which is located after Component A in the container, but not to Component B.

Solution: In this case, ensure that the requesting focus is executed after Component A is removed, not before.
On Windows, when a window is set to alwaysOnTop in an inactive frame, the window cannot receive key events.

For example, a frame is displayed with a window that it owns. The frame is inactive, so the window is not focused. Then, the window is set to alwaysOnTop. The window gains focus, but its owner remains inactive. Therefore, the window cannot receive key events.

Solution: Bring the frame to the front (the Frame.toFront() method) before setting the window to alwaysOnTop.
When a splash screen is shown and a frame is shown after the splash screen window closes, the frame does not get activated.

Solution: Bring the frame to the front (the Frame.toFront() method) after showing it (the Frame.setVisible(true) method).
The WindowFocusListener.windowGainedFocus(WindowEvent) method does not return the frame's most-recent focus owner.

For example, a frame is the focused window, and one of its components is the focus owner. Another window is clicked, and then the frame is clicked again. WINDOW_GAINED_FOCUS comes to the frame and the WindowFocusListener.windowGainedFocus(WindowEvent) method is called. However, inside of this callback, you cannot determine the frame's most-recent focus owner, because Frame.getMostRecentFocusOwner() returns null.

Solution: You can get the frame's most recent focus owner inside the WindowListener.windowActivated(WindowEvent) callback. However, by this time, the frame will have become the focused window only if it does not have owned windows.

Note:

This approach does not work for the window, only for the frame or dialog box.
A window is disabled with Component.setEnabled(false), but is not get completely unfocusable.

Solution: Do not assume that the condition set by calling Component.setEnabled(false) or Component.setFocusable(false) will be maintained unfocusable along with all its content. Instead, use the Window.setFocusableWindowState(boolean) method.

Data Transfer

The following sections discuss possible problems with data transfer features, which allow you to add drag-and-drop (DnD) and cut, copy, and paste (CCP) operations to the application.

Debug Drag-and-Drop Applications

It is difficult to use a debugger to troubleshoot DnD features, because during the drag-and-drop operation all input is grabbed. Therefore, if you place a breakpoint during DnD, you might need to restart your X server. Try to use remote debugging instead.

Two simple methods can be used to troubleshoot most issues with DnD:

Printing all DataFlavor instances
Printing received data
An alternative to remote debugging is the System.err.println() function, which prints output without delay.

Frequent Issues with Data Transfer

This section describes issues that frequently occur with data transfer operations in AWT and suggests troubleshooting solutions.

Pasting a large amount of data from the clipboard takes too much time.
Using the Clipboard.getContents() function for a paste operation sometimes causes the application to hang for a while, especially if a rich application provides the data to paste.

The Clipboard.getContents() function fetches clipboard data in all available types (for example, some text and image types), and this can be expensive and unnecessary.

Solution: Use the Clipboard.getData() method to get only specific data from the clipboard. If data in only one or a few types are needed, then use one of the following Clipboard methods instead of getContents():
- DataFlavor[] getAvailableDataFlavors()
- boolean isDataFlavorAvailable(DataFlavor flavor)
- Object getData(DataFlavor flavor)
When a Java application uses Transferable.getTransferData() for DnD operations, the drag seems to take a long time.

In order to initialize transferred data only if it is needed, the initialization code was put in Transferable.getTransferData().

Transferable data is expensive to generate, and during a DnD operation Transferable.getTransferData() is invoked more than once, causing a slowdown.

Solution: Cache the Transferable data so that it is generated only once.
Files cannot be transferred between a Java application and the GNOME/KDE desktop and file browser.

On Windows and some window managers, transferred file lists can be represented as the DataFlavor.javaFileListFlavor data type. But, not all window managers represent lists of files in this format. For example, the GNOME window manager represents a file list as a list of URIs.

Workaround: To get files, request data of type String, and then translate the string to a list of files according to the text/uri-list format described in RFC 2483. To enable dropping files from a Java application to GNOME/KDE desktop and file browser, export data in the text/uri-list format. For an example, see the Work Around section from the RFE.
An image is passed to one of the startDrag() methods of DragGestureEvent or DragSource, but the image is not displayed during the subsequent DnD operation.

Solution: Move a window with an image rendered on it as the mouse cursor moves during a DnD operation. See the code example in the Work Around section from the RFE.
There is no way to transfer an array using DnD.
The DataFlavor class has no constructor that handles arrays. The mime type for an array contains characters that escapes. The code in the following example throws an IllegalArgumentException.
```
new DataFlavor(DataFlavor.javaJVMLocalObjectMimeType + 
"; class=" + 
(new String[0]).getClass().getName())
```
Solution: “Quote” the value of the representation class parameter, as shown in the following example, where the quotation marks escape:
```
new DataFlavor(DataFlavor.javaJVMLocalObjectMimeType + 
"; class=" + 
"\"" + 
(new String[0]).getClass().getName() + 
"\"")
```
See bug report.
There are problems using AWT DnD support with Swing components.

Various problems can happen, for example, odd events are fired during a DnD operation, multiple items cannot be dragged and dropped, an InvalidDnDOperationException is thrown.

Solution: Use Swing's DnD support with Swing components. Although the Swing DnD implementation is based on the AWT DnD implementation, you cannot mix Swing and AWT DnD. See Lesson: Drag and Drop and Data Transfer in the Java Tutorials.
There is no way to change the state of the source to depend on the target.
In order to change the state of the source to depend on the target, you must have references to the source and target components in the same area of code, but this is not currently implemented in the DnD API.

Workaround: One workaround is to add flags to the transferable object that allow you to determine the context of the event.

For the transfer of data within one Java VM, the following workaround is proposed:
- Implement your target component as DragSourceListener.
- In DragGestureRecognizer.dragGestureRecognized(), add the target at the drag source listener, as shown in the following example.
```
public void dragGestureRecognized(DragGestureEvent dge) {
             dge.startDrag(null, new StringSelection("SomeTransferedText"));
             dge.getDragSource().addDragSourceListener(target);             
        }
```
- Now you can get the target and the source in the dragEnter(), dragOver(), dropActionChanged(), and dragDropEnd() methods of DragSourceListener().
Transferring objects in an application takes a long time.

The transferring of a big bundle of data or the creation of transferred objects takes too long. The user must wait a long time for the data transfer to complete.

This expensive operation makes transferring too long because you must wait until Transferable.getTransferData() finishes.

Solution: This solution is valid only for transferring data within one Java VM. Create or get expensive resources before the drag operation. For example, get the file content when you create a transferable data, so that Transferable.getTransferData() will not be too long.

Other Issues

The following subsections discuss troubleshooting tips for other issues:

Splash Screen Issues

Issues that can happen with splash screen AWT and solutions.

This section describes some issues that can happen with the splash screen in AWT:

The user specified a JAR file with an appropriate MANIFEST.MF in -classpath, but the splash screen does not work.
Solution: See the solution for the next issue.
It is not clear which of several JAR files in an application should contain the splash screen image.
Solution: The splash screen image will be picked from a JAR file only if the file is used with the -jar command-line option. This JAR file should contain both the SplashScreen-Image manifest option and the image file. JAR files in -classpath will never be checked for splash screens in MANIFEST.MF. If you do not use -jar, you can still use -splash to specify the splash screen image in the command line.
Translucent PNG splash screens do not work on the Linux operating system.
Solution: This is a native limitation of X11. On the Linux operating system, the alpha channel of a translucent image will be compared with the 50% threshold. Alpha values above 0.5 will make opaque pixels, and pixels with alpha values below 0.5 will be completely transparent.

Tray Icon Issues

If a SecurityManager is installed, then the value of AWTPermission must be set to accessSystemTray in order to create a TrayIcon object.

Pop-up Menu Issues

In the JPopupMenu.setInvoker() method, the invoker is the component in which the pop-up menu is to be displayed. If this property is set to null, then the pop-up menu does not function correctly.

The solution is to set the pop-up menu's invoker to itself.

Background or Foreground Color Inheritance

To ensure the consistency of your application on every platform, use explicit color assignment (both foreground and background) for every component or container.

Many AWT components use their own defaults for background and foreground colors instead of using parent colors.

This behavior is platform-dependent; the same component can behave differently on different platforms. In addition, some components use the default value for one of the background or foreground colors, but take the value from the parent for another color.

AWT Panel Size Restriction

The AWT container has a size limitation. On most platforms, this limit is 32,767 pixels.

This means that, for example, if the canvas objects are 25 pixels high, then a Java AWT panel cannot display more than 1310 objects.

Unfortunately, there is no way to change this limit, neither with Java code nor with native code. The limit depends on what data type the operating system uses to store the widget size. For example, the Linux X windows system use the integer type, and are therefore limited to the maximum size of an integer. Other operating systems might use different types, such as long, and in this case, the limit could be higher.

See the documentation for your platform.

The following are examples of workarounds for this limit that might be helpful:

Display components, page by page.
Use tabs to display a few components at a time.

Hangs During Debugging of Pop-up Menus and Similar Components on X11

Set the -Dsun.awt.disablegrab=true system property during the debugging of certain graphical user interface (GUI) components.

Certain graphical user interface (GUI) actions require grabbing all the input events in order to determine when the action should terminate (for example, navigating pop-up menus). While the grab is active, no other applications receive input events. If a Java application is being debugged, and a breakpoint is reached while the grab is active, then the operating system appears to hang. This happens because the Java application holding the grab is stopped by the debugger and cannot process any input events, and other applications do not receive the events due to the installed grab. In order to allow debugging such applications, the following system property should be set when running the application from the debugger:

-Dsun.awt.disablegrab=true

This property effectively turns off setting the grab, and does not hang the system. However, with this option set, in some cases, this can lead to the inability to terminate a GUI actions that would normally be terminated. For example, pop-up menus may not be dismissed when clicking a window's title bar.

Window.toFront()/toBack() Behavior on X11

Due to restrictions enforced by third-party software (in particular, by window managers such as the Metacity), the toFront()/toBack() methods may not work as expected and cause the window to not change its stacking order in relation to other top-level windows.

More details are available in the CR 6472274.

If an application wants to bring a window to the top, it can try to workaround the issue by calling Window.setAlwaysOnTop(true) to temporarily make the window always stay on top and then calling setAlwaysOnTop(false) to reset the "always on top" state.

Note:

This workaround is not guaranteed to work because window managers can enforce more restrictions. Also, setting a window to "always on top" is available to trusted applications only.

However, native applications experience similar issues, and this peculiarity makes Java applications behave similar to native applications.

Heavyweight or Lightweight Components Mix

The following issues are addressed in the heavyweight or lightweight (HW/LW) component mixing feature:

Validate the component hierarchy:
Changing any layout-related properties of a component, such as its size, location, or font, invalidates the component as well as its ancestors. In order for the HW/LW Mixing feature to function correctly, the component hierarchy must be validated after making such changes. By default, invalidation stops on the top-most container of the hierarchy (for example, a Frame object). Therefore, to restore the validity of the hierarchy, the application should call the Frame.validate() method. For example:
```
component.setFont(myFont);
frame.validate();
```
frame refers to a frame that contains component.
Note:
Swing applications and the Swing library often use the following pattern:
```
component.setFont(myFont);
component.revalidate();
```
The revalidate() call is not sufficient because it validates the hierarchy starting from the nearest validate root of the component only, thus leaving the upper containers invalid. In that case, the HW/LW feature may not calculate correct shapes for the HW components, and visual artifacts may be seen on the screen.

To verify the validity of the whole component hierarchy, a user can use the key combination Control+Shift+F1, as described in Debug Tips for AWT. A component marked invalid may indicate a missing validate() call somewhere.
Validate roots:
The concept of validate roots mentioned in Validate the component hierarchy was introduced in Swing in order to speed up the process of validating component hierarchies because it may take a significant amount of time. While such optimization leaves upper parts of hierarchies invalid, this did not create any issues because the layout of components inside a validate root does not affect the layout of the outside component hierarchy (that is, the siblings of the validate root). However, when HW and LW components are mixed together in a hierarchy, this statement is no longer true. That is why the feature requires the whole component hierarchy to be valid.

Calling frame.validate() may be inefficient, and AWT supports an alternative, optimized way of handling invalidation/validation of component hierarchies. This feature is enabled with a system property:
```
-Djava.awt.smartInvalidate=true
```
Once this property is specified, the invalidate() method will stop invalidation of the hierarchy when it reaches the nearest validate root of a component on which the invalidate() method has been invoked. Afterward, to restore the validity of the component hierarchy, the application should simply call:
```
component.revalidate();
```
Note:
In this case, calling frame.validate() would be effectively a no-op (a statement that does nothing) because frame is still valid. Since some applications rely on calling validate() directly on a component upper than the validate root of the hierarchy (for example, a frame), this new optimized behavior may cause incompatibility issues, and hence it is available only when specifying the system property.

If an application experiences any difficulties running in this new optimized mode, a user can use the key combination Control+Shift+F1 as described in Debug Tips for AWT to investigate what parts of the component hierarchy are left invalid, and thus possibly cause the problems.
Swing painting optimization:

By default, the Swing library assumes that there are no HW components in the component hierarchy, and therefore uses optimized drawing techniques to boost performance of the Swing GUI. If a component hierarchy contains HW components, the optimizations must be turned off. This is relevant for Swing JScrollPanes in the first place. You can change the scrolling mode by using the JViewPort.setScrollMode(int) method.
Non-opaque LW components:

Non-opaque LW components are not supported by the HW/LW mixing feature implementation by default. In order to enable mixing non-rectangular LW components with HW components, the application must use the com.sun.awt.AWTUtilities.setComponentMixingCutoutShape() non-public API.

Note:
The non-rectangular LW components should still paint themselves using either opaque (alpha = 1.0) or transparent (alpha = 0.0) colors. Using translucent colors (with 0.0 < alpha < 1.0) is not supported.
Disable the default HW/LW mix feature:
In the past, some developers have implemented their own support for cases when HW and LW components must be mixed together. In order to disable the built-in feature the application must be started with the following system property:
```
-Dsun.awt.disableMixing=true
```