This chapter describes how to integrate OHJ with your product application, how to contruct and create the Help object, add help data, how to add tabs, and how to show a topic.
This chapter contains the following sections::
The basic steps for adding OHJ to an application are:
Construct the Help object.
Populate the Help object with help content, as follows:
Create Book objects that represent your help data.
Add the Book objects to the Help object.
Implement methods for showing the OHJ navigator window and for showing help topics.
Dispose of the Help object at the end of your product's lifecycle
The Help object is the main entry point for Oracle Help for Java. It includes methods for adding help content, showing the OHJ navigator window, and displaying specific topics. There are several options that can only be set at the time the Help object is constructed.
The boolean combineBooks parameter in the Help object constructor determines how OHJ displays multiple Books, or HelpSets. If the boolean combineBooks parameter is set to true, OHJ merges all author-defined views that have the same type and label. For example, if multiple books include a Keyword Index view with the same label, OHJ displays one keyword index navigator tab with a merged, sorted list of keywords. If the combineBooks parameter is set to false, the views from each book are displayed separately, and the end user can select which book to display using a drop-down list in the OHJ navigator window.
The versions of the Help object constructor are summarized below. For more information on API documentation of oracle.help.Help , see Section 12.3.2, "Contents of an OHJDK Release".
Table 13-1 Help() Constructors
| Constructor | Description |
|---|---|
|
|
Creates an instance of the |
|
|
Creates an instance of the Parameters:
|
|
|
Creates an instance of the Parameters:
|
|
|
Creates an instance of the Help object using the specified Parameters:
|
After creating a Help object, you must add one or more Book objects to it. A Book object encapsulates a collection, or "book," of help content.
The HelpSet book implementation handles the preferred Oracle Help file formats, as documented in Oracle Help File Formats. These files include the helpset file, which defines the characteristics of the help system.
The following sections describe how to add the help sets, and other optional features:
The Table 13-2 lists HelpSet() constructors:
Table 13-2 HelpSet() Constructors
| Constructor | Description |
|---|---|
|
|
Constructs a Parameters:
|
|
|
Use this constructor when you know only the path to the helpset file relative to your application implementation. Parameters:
|
For more information, see the API documentation for oracle.help.library.helpset.HelpSet.
After you have constructed a Book instance using the HelpSet constructors, you must add the Book to your Help instance. This is accomplished by calling the following method on the Help instance:
Table 13-3 addBook() Constructors
| Constructor | Description |
|---|---|
|
|
This method adds a Parameters:
|
You have the option of adding a Favorites tab or a custom tab after the help object is constructed and before the Navigator window is displayed:
To add a Favorites tab to the navigator window, use the function enableFavoritesNavigator(URL). For more information on API documentation of oracle.help.Help.enableFavoritesNavigator(URL), see Section 12.3.2, "Contents of an OHJDK Release", or find this code in PreviewHelpSet.java for an example:
if (!"".equals(_favoritesPath))
{
try
{
File file = new File(_favoritesPath);
_help.enableFavoritesNavigator(file.toURL());
}
catch (MalformedURLException e)
{
e.printStackTrace();
}
}
To add a custom tab, see the API documentation for oracle.help.navigator.Navigator in Section 12.3.2, "Contents of an OHJDK Release".
A single instance of the Help object should be created and help data should be added at application startup. You should use this single instance of the Help object throughout the application session. It is not efficient to create unique Help objects each time the user requests help in your application.
Instruct your Help instance to show the OHJ navigator window by calling the showNavigatorWindow() method. Some versions of this method take additional parameters to show the navigator window with a specified navigator tab selected (for example, Contents, Index, Search, and so on).
Table 13-4 showNavigatorWindow() Constructors
| Constructor | Description |
|---|---|
|
|
Shows the navigator window with the first tab of the first book selected. Parameters:
|
|
|
Shows the navigator window with the associated set of navigators from the given book displayed. Parameters:
|
|
|
Shows the navigator window with a specific navigator tab selected. Use this method to show a specific navigator from a specific book. Parameters:
|
Instruct your Help instance to show a specific help topic by calling the showTopic() method and providing the topic ID and the Book instance for that topic. Some versions of this method take additional parameters to specify how the topic should be displayed.
Table 13-5 showTopic() Constructors
| Constructor | Description |
|---|---|
|
|
Shows the given topic from the given book in a currently existing topic window. If no topic windows currently exist, a new topic window is created with the default size and position. Parameters:
|
|
|
Shows the given topic from the given book. If Parameters:
|
|
|
Shows the given topic from the given book. If Parameters:
|
Exceptions are thrown by the showTopic() method when an error is encountered when trying to display a topic. For example, if you attempt to display a topic ID which is not in the map file, a TopicDisplayException is thrown. By catching the TopicDisplayException, you have the opportunity to act when an error occurs. In the following example, an author-defined error topic is displayed when TopicDisplayException is thrown.
For example:
try
{
myHelp.showTopic(myhelpset, "nonExistingTopic");
}
catch (TopicDisplayException e)
{
//An error has occurred, try to show an error topic
myHelp.showTopic(myhelpset, "onErrorTopic");
}
Disposing of the Help object frees OHJ resources. You should dispose of the Help object when you no longer need the help engine. Typically, this would be done at end of the user's application session. Disposing closes all files and frees memory used by the Help object. To dispose of the Help object, call the dispose() method:
Table 13-6 dispose() Constructors
| Constructor | Description |
|---|---|
|
|
Dispose of the help system. This method frees up all resources used by the help system. Applications should call this method when they do not need help anymore. You should not call any methods on the |
The dispose() method eliminates any references to objects held by the OHJ classes, but not other references that you have created from your application to Help objects.
Therefore, after you call dispose() you should eliminate any references to OHJ objects (Help or Book objects) in your application code. This allows the Java garbage collection process to free the OHJ objects.