14 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:
14.1 About 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 must add the appropriate help code to your application code.
14.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 5.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.
14.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.
14.4 Using CSHManager to Implement Context-Sensitive Help
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
14.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 14-1.
14.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 enables you to call the
addComponent() method without entering the
Table 14-2 setDefaultBook() Constructors
Sets the specified
If you have more than one
Book, the default
Book is only 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.
14.4.3 Associating Topic IDs with User Interface Components
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 14-3 addComponent() Constructors
Registers a component with the help manager.The default
Registers a component with the help manager. The provided book is used for looking up the topicId.
For components registered using this method,
Registers a component with the help manager. The provided book is used for looking up the
14.4.4 Explicitly Showing Help for Components
showHelpForComponent() method on the
CSHManager when you explicitly want to display the help topic associated with a component. For example, 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.