14 Adding OHJ to Your Application

14.1 Overview of Adding OHJ to an Application

The basic steps for adding OHJ to an application are:

1. Construct the Help object.

2. 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.

3. Implement methods for showing the OHJ navigator window and for showing help topics.

4. Dispose of the Help object at the end of your product's lifecycle

14.2 Constructing the Help Object

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 13.2.2, "Contents of an OHJDK Release".

14.3 Adding the Help Data

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:

• Section 14.3.1, "Constructing a HelpSet"

• Section 14.3.2, "Adding Books to Help"

14.4 Adding the Favorites Tab or Custom Tab

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 13.2.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 13.2.2, "Contents of an OHJDK Release".

14.5 When to Create the Help object

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.

14.6 Showing the Navigator Window

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, etc.).

14.7 Showing a Topic

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.

try
{
  myHelp.showTopic(myhelpset, "nonExistingTopic"); 
}
catch (TopicDisplayException e)
{
  //An error has occurred, try to show an error topic 
  myHelp.showTopic(myhelpset, "onErrorTopic"); 
}

14.8 Disposing of the Help Object

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:

The dispose() method will eliminate 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.