Oracle® Fusion Middleware Developer's Guide for Oracle Help 11g Release 1 (11.1.1.5.0) E14149-03 |
|
![]() Previous |
![]() Next |
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:
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.2, "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.
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.
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
:
You should create an instance of the CSHManager
class before creating user interface components. The CSHManager
constructor is summarized in Table 15-1.
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 |
---|---|
|
Sets the specified Parameters:
|
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.
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 |
---|---|
|
Registers a component with the help manager.The default Parameters:
|
|
Registers a component with the help manager. The provided book is used for looking up the topicId. For components registered using this method, Parameters:
|
|
The default Parameters:
|
|
Registers a component with the help manager. The provided book is used for looking up the Parameters:
|
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.