Adding the JavaHelp System to Applications

The following code sample adds a JavaHelp system to an application. It is followed by a series of steps explaining more about what is happening in the code:

import javax.help.*;
// Find the HelpSet file and create the HelpSet object:
   String helpHS = "myHelpSet.hs";
   ClassLoader cl = ApiDemo.class.getClassLoader();
   try {
      URL hsURL = HelpSet.findHelpSet(cl, helpHS);
      hs = new HelpSet(null, hsURL);
   } catch (Exception ee) {
      // Say what the exception really is
      System.out.println( "HelpSet " + ee.getMessage());
      System.out.println("HelpSet "+ helpHS +" not found")
      return;
   }
// Create a HelpBroker object:
   hb = hs.createHelpBroker();
// Create a "Help" menu item to trigger the help viewer:
   JMenu help = new JMenu("Help");
   menuBar.add(help);
   menu_help = new JMenuItem("Launch Help");
   menu_help.addActionListener(new CSH.DisplayHelpFromSource( hb ));

The folllowing steps explain more about the preceding code sample:

Import the JavaHelp system classes:
```
import javax.help.*;
```
Be sure to add one of the JavaHelp system libraries (for example, jh.jar) to your application's CLASSPATH.

Find the helpset file and create the helpset object:

String helpHS = "myHelpSet.hs";
ClassLoader cl = ApiDemo.class.getClassLoader();
try {
    URL hsURL = HelpSet.findHelpSet(cl, helpHS);
    hs = new HelpSet(null, hsURL);
} catch (Exception ee) {
    System.out.println( "HelpSet " + ee.getMessage());
    System.out.println("HelpSet "+ helpHS +" not found")
    return;
}

In this code sample, findHelpSet() takes a ClassLoader object as its first parameter. If you add your helpset's directory to the CLASSPATH, findHelpSet() will find it because it calls ClassLoader.getResource(), which searches the directories in the CLASSPATH for the helpset file. If getResource()finds a .jar file under a directory, it opens the .jar file and searches in it for the helpset file.

For more information on setting the class path, see http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/classpath.html.

Create a HelpBroker object:
```
hb = hs.createHelpBroker();
```

Create a "Help" menu item to trigger the help viewer:

JMenu help = new JMenu("Help");
menuBar.add(help);
menu_help = new JMenuItem(("Launch Help");
menu_help.addActionListener(new CSH.DisplayHelpFromSource( hb ));

Helpset

The first thing your application does is read the helpset file specified by the application. The helpset file defines the helpset for that application. A helpset is the set of data that constitutes your help system. The helpset file includes the following information:

Map file The map file is used to associate topic IDs with the URL or path name of HTML topic files.

View information Information that describes the navigators being used in the helpset. The standard navigators are: table of contents, index, and full-text search. Information about custom navigators is included here as well.

Helpset title The title of the helpset as defined in the helpset file's <title> tag.

Home ID The name of the (default) ID that is displayed when the help viewer is called without specifying an ID.

Sub-helpsets This optional section can be used to statically include other helpsets by using the tag. The helpsets indicated by this tag are merged automatically into the helpset that contains the tag. More details about merging can be found in Merging Helpsets.

For more information about the helpset file, see Helpset File.

HelpBroker

The HelpBroker is an agent that negotiates and manages the display of help content for your application. The HelpBroker also provides "convenience" methods that you can use to implement context-sensitive help. See Implementing Context-Sensitive Help for details.

You can implement a help system without using the HelpBroker. However, without the HelpBroker you have to write code to directly manage the HelpViewer and JHelp objects, navigators, and context-sensitive help functionality (F1 key on dialogs, help button activation, and on item help button/menu activation).

For a list and description of the HelpBroker methods, see the API at: doc\api\javax\help\HelpBroker.html.

See also:

Programming with the JavaHelp System

Implementing Context-Sensitive Help

Embedding JavaHelp Components

Map file	The map file is used to associate topic IDs with the URL or path name of HTML topic files.
View information	Information that describes the navigators being used in the helpset. The standard navigators are: table of contents, index, and full-text search. Information about custom navigators is included here as well.
Helpset title	The title of the helpset as defined in the helpset file's `<title>` tag.
Home ID	The name of the (default) ID that is displayed when the help viewer is called without specifying an ID.
Sub-helpsets	This optional section can be used to statically include other helpsets by using the tag. The helpsets indicated by this tag are merged automatically into the helpset that contains the tag. More details about merging can be found in Merging Helpsets.