B Working Around the Java Modal Window Problem

This appendix describes how Java handles modal windows that 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.

This appendix includes the following sections:

Section B.1, "About the Java Modal Window Problem"
Section B.2, "Registering a Window"
Section B.3, "Unregistering a Window"

B.1 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. 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.

B.2 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.

Table B-1 registerClientWindow() Method

Constructor Description

Constructor	Description
`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.

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.

B.3 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.

Table B-2 unregisterClientWindow() Method

Method Description

Method	Description
`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 register.

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