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:
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.
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.
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.
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.
Clients should unregister each Window instance they registered with the