Oracle Help for Java Developer's Guide	Contents	Previous	Next

Working Around the Java Modal Window Problem

A characteristic of how Java handles modal windows causes a problem when trying to display a context-sensitive help topic for a modal window. (A modal window is one that does not allow focus to be shifted away from it. A nonmodal window is one that allows focus to be switched to another window.)

OHJ provides a workaround for this problem, as discussed in the following sections:

About the Java Modal Window Problem
Registering a Window
Unregistering a Window

About the Java Modal Window Problem

If a user requests help from a nonmodal window, it is possible to switch back and forth between the help window and the window requesting help (as you would expect). However, this is not possible when requesting help from a modal window. In Java, a modal window blocks access to all other windows created by the Java Virtual Machine (except yet another modal window). Thus, if help is requested from a modal window, OHJ must display help in a modal help window. Then, because OHJ is itself shown in a modal window, the user must close the help window to return to the application.

When help is requested, OHJ determines whether the active window is modal. If it is, then it re-parents the normal OHJ topic windows and the OHJ navigator window into a new modal window. That new window appears in the foreground of the user's display, and the user can interact with it; in fact, they must interact with it if only to close the (modal) help window. Given the coarse implementation of modality in Java, this is the only solution that will work for all of the Java Virtual Machines currently supported by OHJ.

Registering a Window

In order for the OHJ workaround to work, OHJ must be able to track the currently active window. Use the registerClientWindow() method to register each window (Frame or Dialog) you create with the Help object.

`registerClientWindow()` Method
`registerClientWindow(Window aWindow)` Window instances registered with the `Help` object are tracked. If the active window is a modal dialog and help is requested, the `Help` object will take special action so that the help windows are not blocked by the active modal dialog. Parameters: `aWindow` - The `Window` instance to register

For more information, see the API documentation for Help.registerClientWindow()

Unregistering a Window

If you registered your Window objects using Help.registerClientWindow(), you must also unregister them. When you know that a Window will no longer be active, you should unregister the window with the Help object using the unregisterClientWindow() method. It is important to note that failure to unregister Window instances may result in the window not being garbage collected.

`unregisterClientWindow()` Method
`unregisterClientWindow(Window aWindow)` Clients should unregister each `Window` instance they registered with the `registerClientWindow()` method once the window will no longer be active. Failure to unregister `Window` instances may result in the window not being garbage collected. Parameters: `aWindow` - The `Window` instance to unregister

For more information, see the API documentation for Help.unregisterClientWindow()