1. JavaHelp introduction
2. JavaHelp API overview
3. Basic JavaHelp example
4. Adding dialog-style help
5. Customizing the JHelp viewer
5. Creating a custom help view
25.2 JavaHelp API overview
This class represents a collection of help information files we discussed above: HelpSet, table of contents (TOC), index, content, and map files. To create a HelpSet instance we must supply two parameters: a ClassLoader instance used to locate any classes required by the navigators in the help set, and the URL of the main HelpSet file. The following code shows a typical HelpSet instantiation, assuming the main HelpSet file, MyHelpSet.hs, is contained in the current running directory:
ClassLoader loader = this.getClass().getClassLoader();
URL url = HelpSet.findHelpSet(loader, "MyHelpSet.hs");
HelpSet hs = new HelpSet(loader, url);
25.2.2 The HelpBroker interface
abstract interface javax.help.HelpBroker
This interface describes a component used to manage the presentation and interaction with a HelpSet. We can use the HelpSet.createHelpBroker() method to retrieve an instance of HelpBroker. We can then use HelpBroker's enableHelpKey() method, specifying the String ID of a desired help topic, to enable JavaHelp on a given Component. This is often used on a JRootPane (see chapter 3):
HelpBroker hb = hs.createHelpBroker();
hb.enableHelpKey(myFrame.getRootPane(), "MyTopicID", hs);
When F1 is pressed while that component, or one of its children, has the focus, the JavaHelp viewer will appear displaying the appropriate help topic. If a child component has the focus and has an associated help ID assigned, the help viewer will display the help topic specific to that component. Otherwise the default topic (specified as "MyTopicID" above) will be displayed.
We can also use the enableHelpOnButton() method to enable the display of JavaHelp when a specific button is pressed:
JButton btHelp = new JButton("Help");
hb.enableHelpOnButton(btHelp, "MyTopicID", null);
A default implementation is provided by the javax.help.DefaultHelpBroker class.
25.2.3 The Map interface
abstract interface javax.help.Map
This interface defines a String ID to URL mapping. The inner class Map.ID is used to identify a help topic. It encapsulates a HelpSet reference / String ID pair. Given an ID we can get the associated URL and vice versa. Each HelpSet has an associated Map instance.
This class represents the main JavaHelp viewer capable of displaying help set data using JTree or JList navigators in a JTabbedPane, and a content viewer (normally a JEditorPane for HTML display). The current implementation of JavaHelp does not provide public access to this class via HelpSet or HelpBroker instances. Later in this chapter we'll see how to gain access to this component for customization.
25.2.5 The HelpModel interface
abstract interface javax.help.HelpModel
This interface represents the model of a JHelp viewer component. It maintains IDs and URLs corresponding to the HelpSet being displayed in a JHelp instance, and fires HelpModelEvents (see below) when the current help topic is changed.
This class represents a navigation control (JTree or JList) for the GUI presentation of help topic data. Instances of JHelpNavigator reside in the tabbed pane on the left side of the JHelp viewer. Any number of navigators can be present in a HelpSet. JavaHelp provides three sub-classes of JHelpNavigator used in JHelp by default: JHelpIndexNavigator, JHelpSearchNavigator, and JHelpTOCNavigator. Each JHelpNavigator displays data retrieved through a specific NavigatorView instance.
abstract class javax.help.NavigatorView
Instances of NaviagtorView define what type of data a view accepts and how it is parsed. They aso define how data will be presented visually by specifying a corresponding component used to view it. JavaHelp provides three sub-classes of NavigatorView used in JHelp by default: IndexView, SeachView, and TOCView--each of which specify the corresponding JHelpNavigator subclass discussed above for representation.
This class provides simple access to context-sensitive help by supplying several static methods. Context-sensitive help is the provision of certain help information based on the user's current task. Implementing this type of help often involves associating help topics with each component in a GUI and tracking context-sensitive events. Particularly important is the CSH.setHelpIDString(JComponent comp, String helpID) method, which assigns a String ID to a given Swing component. When all IDs are assigned, we can create a button or menu item to trigger content sensitive help, and attach a special predefined ActionListener:
JButton btItemHelp = new JButton("Item Help");
When this button is pressed, a custom mouse cursor displaying a pointer and a question mark appears. When a component is clicked the JavaHelp viewer is displayed showing the help topic corresponding to the selected component's assigned ID (if it has one).
Instances of this class are used as user objects in a navigational view's JTree or JList. Subclasses of TreeItem include IndexItem, used in the Index navigator, and TOCItem, used in the TOC navigator. A SearchTOCItem class extends TOCItem and is used in the Search navigator.
25.2.9 The HelpModelListener interface
abstract interface javax.help.event.HelpModelListener
This interface describes a listener which receives javax.help.event.HelpModelEvents when the current help topic is changed (i.e. whenever a new topic is selected in a navigator). HelpModelListener implementations must implement the idChanged() method which takes a HelpModelEvent as parameter. We can add a HelpModelListeners to a HelpModel using its addHelpModelListener() method.
25.2.10 Setting up JavaHelp
To run all examples in this chapter you will need to do the following (this will vary depending on your platform):
1. Download and install JavaHelp 1.0 (or the most recent release).
2. Copy all files in your javahelp\bin directory to your jdk1.2\bin directory.
3. Copy the contents of your javahelp\lib directory to your jdk1.2\lib directory.
4. Each example includes Windows batch files set up with the assumption that you have installed Java 2, and the above files, in c:\jdk1.2. If you are not using Windows or do not have Java 2 installed in this directory, you will need to write your own scripts or modify these batch files accordingly.