Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle Help
11g Release 2 (11.1.2.3.0)

Part Number E16280-04
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

13 Adding OHJ to Your Application

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::

13.1 About 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

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

Table 13-1 Help() Constructors

Constructor Description

Help()

Creates an instance of the Help object with the ICEBrowser as the HTMLBrowser component used for topic display. This constructor instructs the help system to show all of the views from the added books in one tab panel, and to ignore author defined tab labels in favor of standard tab labels.

Help(boolean combineBooks, boolean useLabelInfo)

Creates an instance of the Help object with the ICEBrowser as the HTMLBrowser component used for topic display.

Parameters:

  • combineBooks – If true, the help system shows all of the views from the books added to the help system in one tab panel. If false, the help system creates a different tab panel for each book and allows the end user to choose which book is displayed.

  • useLabelInfo – If true, the help system uses the author-defined label information for display and view merging. If false, the help system uses default labels.

Help(Class htmlBrowserClass, boolean combineBooks, boolean useLabelInfo)

Creates an instance of the Help object using the specified HTMLBrowser component for topic display. The ICEBrowser is the only HTMLBrowser subclass currently distributed with OHJ.

Parameters:

  • htmlBrowserClass – The HTMLBrowser subclass to use as the topic display component

  • combineBooks – If true, the help system shows all of the views from the books added to the help system in one tab panel. If false, the help system creates a different tab panel for each book and allows the end user to choose which book is displayed.

  • useLabelInfo – If true, the help system uses the author-defined label information for display and view merging. If false, the help system uses default labels.

Help(Class htmlBrowserClass, boolean combineBooks, boolean useLabelInfo, boolean standAloneMode)

Creates an instance of the Help object using the specified HTMLBrowser component for topic display. The ICEBrowser is the only HTMLBrowser subclass currently distributed with OHJ. This constructor contains an extra parameter enabling a standalone mode for running OHJ, where the Help object exits the JVM (through System.exit) after all help windows have closed. The standAloneMode parameter should be set to false if you are launching OHJ from a Java application (otherwise closing help would exit your application!).

Parameters:

  • htmlBrowserClass – The HTMLBrowser subclass to use as the topic display component

  • combineBooks – If true, the help system shows all of the views from the books added to the help system in one tab panel. If false, the help system creates a different tab panel for each book and allows the end user to choose which book is displayed.

  • useLabelInfo – If true, the help system uses the author-defined label information for display and view merging. If false, the help system uses standard default labels.

  • standAloneMode – If true, the help system exits the JVM when all help windows have been closed. Set this to false if you are launching OHJ from your Java application.


13.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:

13.3.1 Constructing a HelpSet

The Table 13-2 lists HelpSet() constructors:

Table 13-2 HelpSet() Constructors

Constructor Description

HelpSet(URL fileURL)

Constructs a HelpSet object using the helpset file at the specified URL location. Use this constructor when you know the exact location of the helpset file.

Parameters:

  • fileURL – A URL specifying the exact location of the helpset file.

HelpSet(Class pathClass, String pathExtension)

Use this constructor when you know only the path to the helpset file relative to your application implementation.

Parameters:

  • pathClass – One of your application classes. The HelpSet object uses the location of this class to determine the location of your helpset file.

  • pathExtension – The path to the helpset file relative to the location of pathClass. The value of this parameter is appended to the absolute path to the directory containing the pathClass. The resulting path should be the path to your helpset file.


For more information, see the API documentation for oracle.help.library.helpset.HelpSet.

13.3.2 Adding Books to Help

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

addBook(Book book)

This method adds a Book instance to the help system. Author-defined views contained in the Book are displayed in the navigator window, and topics from the Book are available to display.

Parameters:

  • book - The Book instance to add to the help system.


13.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:

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

13.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, and so on).

Table 13-4 showNavigatorWindow() Constructors

Constructor Description

showNavigatorWindow()

Shows the navigator window with the first tab of the first book selected.

Parameters:

  • activeBook - The Book object whose associated set of navigators should be initially displayed when the navigator window is shown.

showNavigatorWindow(Book activeBook)

Shows the navigator window with the associated set of navigators from the given book displayed.

Parameters:

  • activeBook - The Book object whose associated set of navigators should be initially displayed when the navigator window is shown.

showNavigatorWindow(Navigator activeNavigator)

Shows the navigator window with a specific navigator tab selected. Use this method to show a specific navigator from a specific book.

Parameters:

  • activeNavigator - The navigator to show when initially selected.


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

Table 13-5 showTopic() Constructors

Constructor Description

showTopic(Book book, String topicID)

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:

  • book - The Book from which to show the topic.

  • topicID - The topic ID for the topic to show (as specified in the map file of the book)

showTopic(Book book, String topicID, boolean alwaysCreate)

Shows the given topic from the given book. If alwaysCreate is true, a new window is always created. If false, a new window is created if no windows currently exist.

Parameters:

  • book - The Book to show the topic from.

  • topicID - The topic ID for the topic to show (as specified in the map file of the book).

  • alwaysCreate - If true, always create a new window. If false, reuse a window if possible

showTopic(Book book, String topicID, boolean alwaysCreate, Point location, Dimension size)

Shows the given topic from the given book. If alwaysCreate is true, a new window is always created; if it is false, a new window is created if no windows currently exist. The topic window is shown using the given location and size.

Parameters:

  • book - The Book to show the topic from.

  • topicID - The topic ID for the topic to show (as specified in the map file of the book).

  • alwaysCreate - If true, always create a new window. If false, reuse a window if possible.

  • location - Location of the topic window in screen coordinates.

  • size - Size of the topic window in pixels.


13.7.1 Catching TopicDisplayExceptions

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"); 
}

13.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:

Table 13-6 dispose() Constructors

Constructor Description

dispose()

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 Help object after calling dispose().


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.