15 Enabling Context-Sensitive Help in Your Application

This chapter describes how to enable context-sensitive help in your application and how to map topic IDs with the help topics.

This chapter includes the following sections:

• Section 15.1, "Overview of Context-Sensitive Help"

• Section 15.2, "Mapping Topic IDs to Help Topics"

• Section 15.3, "Programming Your Application to Support Context-Sensitive Help"

• Section 15.4, "Using CSHManager to Implement Context-Sensitive Help"

15.1 Overview of Context-Sensitive Help

A context-sensitive help topic is one that is associated with a context in a product's user interface and which can be launched from that context. For example, a context-sensitive help system may contain topics that describe the product's menus and dialog boxes. When a user requests help for one of those controls, the appropriate topic for that control is displayed.

Oracle Help for Java provides mechanisms for associating help topics with user interface controls and for launching context-sensitive help when the user presses the F1 key or selects Help from a right-click context menu. OHJ also provides an API for explicitly displaying the help topic associated with a component.

To provide context-sensitive help for an application, the help system source must include one or more map files and you have to add the appropriate help code to your application code, as described in these sections:

15.2 Mapping Topic IDs to Help Topics

A context-sensitive help system must include one or more map files that map topic IDs to help topics. Ideally, the map file is created by the help author, not the programmer. OHJ supports two kinds of map files:

When an OHJ system is implemented using a HelpSet, the map file must use the XML file format, also the recommended format for Oracle Help systems. For more information about the map file, see Section 6.3, "Map Files".

You may want to define a set of Java constants in your application code that map to topic IDs in the map file. When using OHJ methods that require topic IDs (such as Help.showTopic()), you can use the constant variable names instead of using explicit topic IDs from the map file. This helps you avoid changing code in several places if topic IDs in the map file are changed later. This is particularly useful when help authors are responsible for maintaining map files.

15.3 Programming Your Application to Support Context-Sensitive Help

The standard Java toolkits (AWT and Swing) do not include built-in mechanisms for associating help topics with components. However, OHJ provides a generic way to implement context-sensitive help in Java applications, using the OHJ CSHManager class. This help manager provides a way to associate help topics with user interface components and to enable F1 and right-click context-sensitive help.

15.4 Using CSHManager to Implement Context-Sensitive Help

OHJ's CSHManager class provides a generic way to associate help topics with user interface controls and to launch context-sensitive help when the end user presses the F1 key or selects Help from a right-click context menu. OHJ also provides an API for explicitly displaying the help topic associated with a component.

The following sections provide an introduction to using CSHManager:

• Section 15.4.1, "CSHManager Constructors"

• Section 15.4.2, "Setting the Default Book"

• Section 15.4.3, "Associating Topic IDs with User Interface Components"

• Section 15.4.4, "Explicitly Showing Help for Components"

15.4.1 CSHManager Constructors

You should create an instance of the CSHManager class before creating user interface components. The CSHManager constructor is summarized in Table 15-1.

Table 15-1 CSHManager() Constructors

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

15.4.2 Setting the Default Book

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

Table 15-2 setDefaultBook() Constructors

Constructor	Description
setDefaultBook(Book book)	Sets the specified Book as the default Book. This will be as used the default Book for components registered without a specified Book. Parameters: book – The 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.

15.4.3 Associating Topic IDs with User Interface Components

Use the addComponent() method to associate topic IDs, as defined in the map file, with Java user interface components. You can call one of the versions of this method for each component that requires context-sensitive help.

Table 15-3 addComponent() Constructors

Constructor	Description
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 topic ID 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 topic ID 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, 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 topic ID 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 pop-up menu 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. topicId – The topic ID 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 pop-up menu upon right mouse click and launches context-sensitive help if the Help menu item is selected. needF1Help – If true, displays help for this component in response to F1 key press events. needPopupHelp – If true, displays a Help pop-up menu upon right mouse click and launches context-sensitive help if the Help menu item is selected.

15.4.4 Explicitly Showing Help for Components

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

Table 15-4 showHelpForComponent() Method

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