8 AWT

How to Trace Focus Events

To troubleshoot a problem with focus, you can trace focus events. You can do it 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 that 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 that events of losing focus or activation should come first.

Native Focus System

Sometimes a problem may be caused by the native platform. To check this, investigate the native events that are related to focus. Make sure that the window you want to be focused gets activated and 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 has been 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. Prior to JDK7 a focus proxy component was a dedicated hidden child component inside a frame/dialog. In the latest JDK releases a frame/dialog itself 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 focus proxy of its owner. This mechanism is transparent for a user but should be taken into account when debugging.

On Oracle Solaris and Linux operating systems, 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 that X server and some window managers may nevertheless send focus events to a window. However all such 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 itself does not get any native focus event. On the Oracle Solaris and Linux platforms, 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 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. Since the major processing of focus occurs at the Java level, debugging focus with XToolkit is simpler than with WToolkit.

Focus System in the Java Plug-in

An applet is embedded in a browser as a child (though not a direct child) of an EmbeddedFrame. This is a special Frame that has the ability to communicate with the plugin. From the applet's perspective the EmbeddedFrame is a full top-level Frame.

Managing focus for an EmbeddedFrame requires special additional actions. When an applet first starts, the EmbeddedFrame does not get activated by default by the native system. The activation is performed by the plugin that triggers a special API provided by the EmbeddedFrame. When focus leaves the applet, the EmbeddedFrame is also deactivated in a synthesized manner.

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.

The focus-follows-mouse model is not detected in XAWT in Java SE 7, and this causes problems for simple windows (objects of java.awt.Window class). Such windows have the override-redirect property, which means that they can be focused only when the mouse button is pressed, and not by hovering over the window. As a workaround, set MouseListener on the window and request focus on it when mouse crosses the window borders.

Tray Icon Issues

With the Java SE 6 release on Windows 98, the method TrayIcon.displayMessage() is not supported because the native service to display a balloon is not supported on Windows 98.

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

Popup Menu Issues

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

The solution is to set the popup's invoker to itself.

Background/Foreground Color Inheritance

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

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.

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

AWT Panel Size Restriction

The AWT container has a size limitation. On most platforms, this limit is 32767 pixels. This means that, for example, if the canvas objects are 25 pixels high, 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 a widget size. For example, the Windows 2000/XP operating system and the Linux X operating system use 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.

For more information, refer to 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 when debugging popup menus and similar components on X11

Certain graphical user interface (GUI) actions require grabbing all the input events in order to determine when the action should terminate (for example, navigating popup 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 has been active, 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 simply 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 effectively turns off setting the grab, and as such does not hang the system. However, with this option set, in some cases this may lead to inability to terminate a GUI actions that would normally be terminated. For example, popup 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 always 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 ultimately wants to bring a window to 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.

Swing Painting Optimizations

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

Disabling the Default HW/LW Mixing Feature Implementation

In the past, some developers have implemented their own support for cases when HW and LW components must be mixed together. The built-in implementation of the feature available since JDK 6 and JDK 7 may cause problems with custom workarounds. In order to disable the built-in feature the application must be started with the following system property:

-Dsun.awt.disableMixing=true