Enabling Context Sensitive Help

Context sensitive help launches help topics that are associated with some context in the user interface. Typically, help topics are written to describe user interface controls such as menus and dialog boxes. When a user requests help for a user interface control--for example by selecting a Help button--the appropriate topic for that context (control) is displayed.

The following sections describe how to implement context sensitive help using Oracle Help for Java:

Associating Help Topics with Contexts in the User Interface
Using OHJ's CSHManager Class
The Modal Window Problem

Associating Help Topics with Contexts in the User Interface

Oracle Help for Java provides mechanisms for associating help topics with UI controls, and for launching context sensitive help when the end user presses the F1 key or clicks Help in a right-click context menu. OHJ also provides an API for explicitly requesting that the help topic associated with a component is shown.

Context sensitive help requires that the help content created by the author includes a map file that maps topic IDs to help topics. In a HelpBook a map file is in the OHT file format, in a helpset the map file is in an XML file format discussed in the OHJ File Format Specification.

As the programmer, when calling the Help.showTopic() method or associating help topics with your Java UI controls you must use the topic IDs specified in the author's map file. Thus, you will have to coordinate your efforts with the help author.

If you wish, you may consider defining a set of Java constants in your application code that map to the author defined topic IDs in the map file. When using OHJ methods that require help topic IDs you can use the constant variable names instead of hard-coding an author-defined topic ID. This will allow you to avoid changing your code in several places if the author changes the topic IDs at a later point.

Using OHJ's CSHManager Class

OHJ's CSHManager (Context Sensitive Help Manager) class provides a way of associating help topics with Java UI components and enabling F1 and right-click context sensitive help. The plain Javasoft toolkits (AWT and Swing) do not have a built-in way of associating help topics with components, and thus require an external mechanism like OHJ's CSHManager. The following section will guide you through using the CSHManager to enable context sensitive help.

Constructing the CSHManager

You should create an instance of the CSHManager class before you begin creating your UI components. The CSHManager constructor takes the Help instance for your application.

Constructor Detail

Constructor Detail
CSHManager(Help help) Creates a new instance of the CSHManager class. All the subsequent calls to this manager object will use the specified Help object. Parameters `help` - Help object to be used for displaying help.

CSHManager(Help help)

Creates a new instance of the CSHManager class. All the subsequent calls to this manager object will use the specified Help object.

Parameters: help - Help object to be used for displaying help.

The setDefaultBook() Method

If you only have one Book of help content, you may want to use the CSHManager setDefaultBook() method to define it as the default book for context sensitive help. This allows you to go without entering the book parameter when you call the addComponent() method.

Method Detail

Method Detail
setDefaultBook(Book book) Sets the specified Book as the default Book. This Book will be as used the default Book for components registered without a specified Book. Parameters: `book` - Book to be set.

setDefaultBook(Book book)

Sets the specified Book as the default Book. This Book will be as used the default Book for components registered without a specified Book.

Parameters:: book - Book to be set.

If you have more than one book, the default book will only be used for those components for which you have not assigned a specific book. In a multiple book help system, you should, in general, assign specific books to your components.

Using the addComponent() method

The addComponent() method is used to associate topic IDs (as defined in the map file) with Java UI components. You will have to call one of the versions of this method for each component that requires context sensitive help.

Method Detail

Method Detail
addComponent(Component component, String topicId) Registers a component with the help manager. The default Book is used for looking up the topicId. If no default Book is registered at the time of calling this method, then the component is not registered with the help manager, and help will not be shown if `showHelpForComponent()` is later called for this component. For components registered using this method, CSHManager will not display help in response to an F1 key press or a right mouse click event. Parameters: `component` - The component to be added. `topicId` - The author-defined topic ID you wish to associate with this component
addComponent(Component component, Book book, String topicId) Registers a component with the help manager. The provided book is used for looking up the `topicId`. For components registered using this method, CSHManager will not display help in response to an F1 key press or right mouse click event. Parameters: `component` - The component to be added `book` - The Book containing the help topic. `topicId` - The author-defined topic ID you wish to associate with this component
addComponent(Component component, String topicId, boolean needF1Help, boolean needPopupHelp) The default Book is used for looking up the topicId. If no default Book is registered at the time of calling this method, then the component is not registered with the help manager, and help will not be shown if `showHelpForComponent()` is later called for this component. Parameters: `component` - The component to be added. `topicId` - The author-defined topic ID you wish to associate with this component `needF1Help` - if true, displays help for this component in response to F1 key press events `needPopupHelp` - if true, displays a "Help" PopupMenu upon right mouse click and launches context sensitive help if the "Help" menu item is selected
addComponent(Component component, Book book, String topicId, boolean needF1Help, boolean needPopupHelp) Registers a component with the help manager. The provided `book` is used for looking up the `topicId`. Parameters: `component` - The component to be added `book` - The Book containing the help topic. `topicId` - The author-defined topic ID you wish to associate with this component `needF1Help` - if true, displays help for this component in response to F1 key press events `needPopupHelp` - if true, displays a "Help" PopupMenu upon right mouse click and launches context sensitive help if the "Help" menu item is selected

addComponent(Component component, String topicId)

Registers a component with the help manager.

The default Book is used for looking up the topicId. If no default Book is registered at the time of calling this method, then the component is not registered with the help manager, and help will not be shown if showHelpForComponent() is later called for this component.

For components registered using this method, CSHManager will not display help in response to an F1 key press or a right mouse click event.

Parameters:: component - The component to be added.; topicId - The author-defined topic ID you wish to associate with this component

addComponent(Component component, Book book, String topicId)

Registers a component with the help manager. The provided book is used for looking up the topicId.

For components registered using this method, CSHManager will not display help in response to an F1 key press or right mouse click event.

Parameters:: component - The component to be added; book - The Book containing the help topic.; topicId - The author-defined topic ID you wish to associate with this component

addComponent(Component component, String topicId, boolean needF1Help, boolean needPopupHelp)

Parameters:: component - The component to be added.; topicId - The author-defined topic ID you wish to associate with this component; needF1Help - if true, displays help for this component in response to F1 key press events; needPopupHelp - if true, displays a "Help" PopupMenu upon right mouse click and launches context sensitive help if the "Help" menu item is selected

addComponent(Component component, Book book, String topicId, boolean needF1Help, boolean needPopupHelp)

Registers a component with the help manager. The provided book is used for looking up the topicId.

Parameters:: component - The component to be added; book - The Book containing the help topic.; topicId - The author-defined topic ID you wish to associate with this component; needF1Help - if true, displays help for this component in response to F1 key press events; needPopupHelp - if true, displays a "Help" PopupMenu upon right mouse click and launches context sensitive help if the "Help" menu item is selected

Explicitly Showing Help for Components

Call the showHelpForComponent() method on the CSHManager when you explicitly want to display the help topic associated with a given component. For example, if you want to launch context-sensitive help in response to a button press, you could call this method in the button's event handler.

Method Detail

Method Detail
showHelpForComponent(Component component) Shows help for the specified `component`. If the specified `component` was not registered via `addComponent()`, then no help will be shown.

showHelpForComponent(Component component)

Shows help for the specified component. If the specified component was not registered via addComponent(), then no help will be shown.

The Modal Window Problem

If the user requests help from a non-modal window, the user may switch back and forth between the help requesting window and the displayed help topic (as you would expect).

Unfortunately, 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.

The OHJ Workaround

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.

Help.registerClientWindow()

In order for the OHJ workaround for the modal window problem to work, OHJ must be able to track the currently active window. To facilitate this process, you must register each window (Frame or Dialog) that you create with the Help object using the registerClientWindow() method.

Method Detail

Method Detail
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

Help.unregisterClientWindow()

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.

Method Detail

Method Detail
unregisterClientWindow(Window aWindow) Clients should unregister each Window instance that 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

unregisterClientWindow(Window aWindow)

Clients should unregister each Window instance that 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