#
JavaHelpTM 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 `Map`s 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.

JavaHelpTM 1.0
Send your comments to javahelp-comments@eng.sun.com
Last modified: Mon Apr 12 19:15:49 MDT 1999