Adding Oracle Help For Java To Your Application

This section guides you through the process of integrating Oracle Help for Java with your product application. The first step is constructing the Help object, which is the main entry point for Oracle Help for Java. You will then need to populate the Help object with your product's help content. This is accomplished by creating Book objects (HelpBooks or helpsets) that represent your help data, and adding those Book objects to the Help object. Methods for showing the OHJ Navigator Window and showing particular help topics are discussed. Finally, information is provided on how to dispose of the Help object at the end of your product's lifecycle.

This chapter contains the following sections:

Constructing the Help Object
Adding the Help Data
When to Create the Help Object
Showing the Navigator Window
Showing a Topic
Disposing of The Help Object

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 help navigator window, and displaying specific topics. There are several options that can only be set at the time the Help object is constructed.

One option set in the Help object constructor determines how OHJ will handle displaying multiple Help books (HelpBook/helpsets). If the boolean combineBooks parameter is set to true, OHJ will merge all of the 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 will display 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 will be displayed separately, and the end user will be able to select which book is currently displayed using a drop-down list in the OHJ navigator window. The help author should be able to tell you whether or not their help content should be merged with other books or displayed separately.

The various versions of the Help object constructor and their parameters are summarized below (see the oracle.help.Help JavaDoc documentation for more detail):

Constructor Detail

Constructor Detail
Help() Creates an instance of the Help object with the ICEBrowser as the HTMLBrowser component used for topic display. This constructor will instruct 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 will show all of the views from the books added to the help system in one tab panel, if false the help system will create a different tab panel for each book and allow 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 navigator labels
Help(Class htmlBrowserClass, boolean combineBooks, boolean useLabelInfo) Creates an instance of the Help object using the specified HTMLBrowser component for topic display (Note: 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 will show all of the views from the books added to the help system in one tab panel, if false the help system will create a different tab panel for each book and allow 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 navigator 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 (Note: The ICEBrowser is the only HTMLBrowser subclass currently distributed with OHJ). This constructor contains an extra parameter enabling a "stand-alone" mode for running OHJ, where the Help object will exit the JVM (via System.exit) once all help windows have been 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 will show all of the views from the books added to the help system in one tab panel, if false the help system will create a different tab panel for each book and allow 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 navigator labels `standAloneMode` - if true the help system will exit the JVM when all help windows have been closed. This should be set to false if you are launching OHJ from your Java application.

Help()

Creates an instance of the Help object with the ICEBrowser as the HTMLBrowser component used for topic display. This constructor will instruct 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 will show all of the views from the books added to the help system in one tab panel, if false the help system will create a different tab panel for each book and allow 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 navigator labels

Help(Class htmlBrowserClass, boolean combineBooks, boolean useLabelInfo)

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

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

Creates an instance of the Help object using the specified HTMLBrowser component for topic display (Note: The ICEBrowser is the only HTMLBrowser subclass currently distributed with OHJ). This constructor contains an extra parameter enabling a "stand-alone" mode for running OHJ, where the Help object will exit the JVM (via System.exit) once all help windows have been 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!).

Adding the Help Data

The difference between HelpBook and helpset

An OHJ Book object encapsulates a book of help content. There are two implementations of the Book interface included with Oracle Help for Java that handle different file formats.

helpset. This Book implementation handles the new and preferred file format for Oracle Help for Java (as described in the OHJ File Format Specification). If the help author has created a helpset file (.hs is the typical extension), you will construct a helpset object using that file.

HelpBook. This Book implementation handles the legacy OHJ format. The HelpBook class examines a directory, identifies files with known extensions, and adds them to the help system.

The help author should be able to tell you which format is used for their help content.

Constructing HelpBooks/helpsets

The HelpBook and helpset constructors and their parameters are described below:

helpset

Constructor Detail

Constructor Detail
helpset(URL fileURL) Construct a helpset object using the author's helpset file at the specified URL location. Use this constructor when you know the exact location of the author's helpset file. Parameters: `fileURL` - a URL specifying the exact location of the author's helpset file.
helpset(Class pathClass, String pathExtension) Use this constructor when you know only the path to the author's 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` - is 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.

helpset(URL fileURL)

Construct a helpset object using the author's helpset file at the specified URL location. Use this constructor when you know the exact location of the author's helpset file.

Parameters:: fileURL - a URL specifying the exact location of the author's helpset file.

helpset(Class pathClass, String pathExtension)

Use this constructor when you know only the path to the author's 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 - is 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.

See the oracle.help.library.helpset.helpset section of the OHJDK JavaDoc for further information.

HelpBook

The HelpBook format is directory based; thus you will use its constructors to specify the location of the directory containing the author's help content.

Constructor Detail

Constructor Detail
HelpBook(String baseURL, String baseName, String bookTitle) Create a HelpBook with the specified title, loading the data from the directory location specified by `baseURL`. The HelpBook object examines the directory to identify known control files (TOC, TOK, HHC, HHK, OHT, and IDX) named with the given `baseName`. Use this constructor when you know the exact location of the help content directory. Parameters: `baseURL` - a String specifying the exact location of the author's helpset file in URL format. `baseName` - is base name of all the control files found in the specified directory (i.e. if your control files are named discoverer.hhc, discoverer.hhk, etc., the `baseName` would be "discoverer"). `bookTitle` - is the book name desired by the help author. The book name appears in the book selection pull down menu in multiple book help systems.
HelpBook(Class baseClass, String dirPathExt, String baseName, String bookTitle) Create a HelpBook with the specified title, loading the data from the directory location specified by `baseClass` and `dirPathExt`. The HelpBook object examines the directory to identify known control files (TOC, TOK, HHC, HHK, OHT, and IDX) named with the given `baseName`. Use this constructor when you know only the path to the help content directory relative to your application implementation. Parameters: `baseClass` - one of your application classes. The HelpBook object uses the location of this class to determine the location of your help content directory. `dirPathExt` - is the path to the help content directory relative to the location of `baseClass`. The value of this parameter is appended to the absolute path to the directory containing the `baseClass`>. The resulting path should be the path to your help content directory. `baseName` - is base name of all the control files found in the specified directory (i.e. if your control files are named discoverer.hhc, discoverer.hhk, etc., the `baseName` would be "discoverer") `bookTitle` - is the book name desired by the help author. The book name appears in the book selection pull down menu in multiple book help systems.

HelpBook(String baseURL, String baseName, String bookTitle)

Create a HelpBook with the specified title, loading the data from the directory location specified by baseURL. The HelpBook object examines the directory to identify known control files (TOC, TOK, HHC, HHK, OHT, and IDX) named with the given baseName. Use this constructor when you know the exact location of the help content directory.

Parameters:: baseURL - a String specifying the exact location of the author's helpset file in URL format.; baseName - is base name of all the control files found in the specified directory (i.e. if your control files are named discoverer.hhc, discoverer.hhk, etc., the baseName would be "discoverer").; bookTitle - is the book name desired by the help author. The book name appears in the book selection pull down menu in multiple book help systems.

HelpBook(Class baseClass, String dirPathExt, String baseName, String bookTitle)

Create a HelpBook with the specified title, loading the data from the directory location specified by baseClass and dirPathExt. The HelpBook object examines the directory to identify known control files (TOC, TOK, HHC, HHK, OHT, and IDX) named with the given baseName. Use this constructor when you know only the path to the help content directory relative to your application implementation.

Parameters:: baseClass - one of your application classes. The HelpBook object uses the location of this class to determine the location of your help content directory.; dirPathExt - is the path to the help content directory relative to the location of baseClass. The value of this parameter is appended to the absolute path to the directory containing the baseClass>. The resulting path should be the path to your help content directory.; baseName - is base name of all the control files found in the specified directory (i.e. if your control files are named discoverer.hhc, discoverer.hhk, etc., the baseName would be "discoverer"); bookTitle - is the book name desired by the help author. The book name appears in the book selection pull down menu in multiple book help systems.

See the oracle.help.library.helpbook.HelpBook section of the OHJDK JavaDoc for further information.

Adding HelpBook/helpset

Once you have constructed a Book instance using the HelpBook or helpset constructors, you must add the Book to your Help instance. This is accomplished by calling the following method on the Help instance:

Method Detail

Method Detail
addBook(Book book) This method adds a Book instance to the help system. Author defined views contained in the Book will be displayed in the Help navigator window, and topics from the Book will be available to display. Parameters: `book` - the Book instance to add to the help system

addBook(Book book)

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

Parameters:: book - the Book instance to add to the help system

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.

Showing the Navigator Window

You may instruct your Help instance to show the OHJ help navigator window by calling the showNavigatorWindow() method. There are versions of this method which take additional parameters to show the help navigator window with a particular navigator tab selected (i.e. Contents, Index, Search, etc.).

Method Detail

Method Detail
showNavigatorWindow() Show the help navigator window with the first navigator tab of the first book selected.
showNavigatorWindow(Book activeBook) Show the help 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) Show the help navigator window with a specific navigator tab selected. Use this method if you want to show a specific Navigator from a specific book. Parameters: `activeNavigator` - the Navigator to show initially selected

showNavigatorWindow()

Show the help navigator window with the first navigator tab of the first book selected.

showNavigatorWindow(Book activeBook)

Show the help 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)

Show the help navigator window with a specific navigator tab selected. Use this method if you want to show a specific Navigator from a specific book.

Parameters:: activeNavigator - the Navigator to show initially selected

Showing a Topic

The showTopic() method

You may instruct your Help instance to show a specific help topic by calling the showTopic() method and providing the topic ID and Book instance for that topic. There are versions of this method which take additional parameters to specify how the topic should be displayed.

Method Detail

Method Detail
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 will be created with the default size and position. 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).
showTopic(Book book, String topicID, boolean alwaysCreate) Shows the given topic from the given book. If `alwaysCreate` is true, a new window will always be created; if it is false, a new window will only be 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 will always be created; if it is false, a new window will only be created if no windows currently exist. The topic window will be 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.

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 will be created with the default size and position.

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

showTopic(Book book, String topicID, boolean alwaysCreate)

Shows the given topic from the given book. If alwaysCreate is true, a new window will always be created; if it is false, a new window will only be 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 will always be created; if it is false, a new window will only be created if no windows currently exist. The topic window will be 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.

Catching TopicDisplayExceptions

Exceptions are thrown by the showTopic() method when an error is encountered in the topic display process. For example, if you attempt to display a topic id which does not exist (is not present in the map file), a TopicDisplayException will be thrown. By catching the TopicDisplayException, you will have the opportunity to take action when an error occurs. In the following example, the programmer has decided to show a special author defined error topic in response to a TopicDisplayException.

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

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 users application session. Disposing closes all files and frees memory used by the Help object. To dispose of the Help object, call the dispose() method:

Method Detail

Method Detail
dispose() Dispose of the help system. This method frees up all the 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()`.

dispose()

Dispose of the help system. This method frees up all the 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 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.