JavaHelp^TM 1.0 - Context Sensitive Help

Copyright 1998-1999 Sun Microsystems

Context-Sensitive Help

Context-sensitive help in the JavaHelp system is organized around the notion of the ID->URL map referred by the <map> section of a HelpSet file. The key concept is that of the Map.ID which is comprised of a String/HelpSet instance pair. The String is intented to be unique within the local map of the HelpSet. This is very important when considering HelpSet merging, otherwise IDs would be required to be unique over all HelpSets that might ever be merged.

There are three parts involved in assigning Context Sensitive Help to an application:

1. Define the appropriate String ID->URL map,
2. Assign an ID to each desired visual object,
3. Enable some user action to activate the help.

Defining the ID->URL map

The Map interface provides a means for associating IDs (HelpSet.string) with URLs. One such map is constructed from one or more map files that provide a simpler "String ID" to URL mapping, with the HelpSet being given either explicitly or implicitly.

JavaHelp has two classes that implement the Map interface: FlatMap and TryMap. A FlatMap does not support nesting of other maps into it, while a TryMap does. A FlatMap is a simple implementation while TryMap should support inverse lookups (for example, getIDFromURL) more efficiently. The implementation of TryMap JavaHelp 1.0 is not particularly efficient.

Both FlatMap and TryMap have public constructors. The constructor for FlatMap takes two arguments: the first one provides a URL to a property file providing a list of String and URL pairs; the second argument is a HelpSet. The HelpSet is used together with each String-URL pair to create the actual Map.ID objects that comprise the FlatMap. The constructor for TryMap has no arguments: the Map is created empty and other Maps are added (or removed) from it.

The Map interface can also be implemented by some custom class. One such class could be used to, for example, programatically generate the map.

Assigning an ID to Each Visual Object

The next step is to assign to each desired GUI object an ID that will lead to the desired help topic. There are two mechanisms involved: an explicit ID, either a plain String, or a Map.ID, is assigned to the GUI object; and there is a rule that is used to infer the Map.ID for an GUI object based on its container hierachy.

The two basic methods to assign IDs are setHelpIDString(Component, String) and setHelpSet(Component, String). If both are applied to a Component, then a Map.ID is assigned to that Component. If only setHelpIDString() is applied, then the HelpSet instance is obtained implicitly, as indicated later. A method overload is provide for MenuItem objects.

These methods take a Component as an argument. The implementation may vary depending on whether the argument is a JComponent or a plain AWT Component.

The methods getHelpIDString(Component) and getHelpSet(Component) recursively traverse up the container hierachy of the component trying to locate a Component that has been assigned a String ID. When found, the methods return the appropriate value. As before there is also an overloaded method for MenuItem.

Enabling a Help Action

The final step is to enable for some action to trigger the presentation of the help data. CSH currently provides several ActionListener classes that can be used:

Name	Description
DisplayHelpFromFocus()	Locate the Component currently owning the focus, then find the ID assigned to it and present it on the HelpBroker. This is to be used by "Help" keys.
DisplayHelpAfterTracking()	Start tracking events until a mouse event is used to select a Component, then find the ID assigned and present it. This is to be used by a "What's this" type of interface.
DisplayHelpFromSource()	Find the ID assigned to the source of the action event and present it.

In addition, HelpBroker also provides some convenience methods that interact with these ActionListeners:

Name	Description
enableHelpKey(root, stringID, helpSet)	Set the ID and helpset of root which will act as the default help to present, then register an appropriate ActionListener to be activated via the "Help" key. DefaultHelpBroker uses CSH.DisplayHelpFromFocus as the ActionListener.
enableHelp(Component, stringId, helpSet)	Set the ID and HelpSet to the component. This information is usually recovered either using the "Help" key or through the DisplayHelpAfterTracking class.
enableHelpOnButton(Component, stringId, helpSet)	Set the ID and HelpSet to the component, which must be a "Button". When the button is "pressed" the Help information given in the arguments will be presented.

Since these methods are from a specific HelpBroker, if a HelpSet is not associated with the GUI object then the HelpSet of the HelpBroker will be used automatically.

Help Support for JDialogs

It is often useful to associate help information with dialog boxes using a Help button. Ideally the standard javax.swing.JOptionPane would have direct support for this but, due to timing constraints this was not possible. Expect full support for this feature in a forthcoming version of Swing.