Implementing Context-Sensitive Help

The JavaHelp system provides classes and methods that help you implement context-sensitive help in your applications. The following sections:

Summarize the context-sensitive help system
Describe the basic elements of the system
Describe how to implement context-sensitive help

Summary

The following table summarizes the context-sensitive help system.

CSH Type Activation Mechanism Object for Which Help Is Provided Implementation Steps

Window-Level Press F1 (or Help) key Window with focus

Set helpIDs for components
Capture F1 key press
Get window that has focus
Get helpID for window
Display help

Field-Level 1. Activate field-level help
2. Navigate with mouse or keyboard
3. Select object Selected object

Set helpIDs for components
Activate field-level help (button or menu item)
Track context-
sensitive events
Get helpID for selected object
Display help

Help Button
Menu Item Click button or choose menu item Topic associated with button or menu item

Create button or menu object
Set helpID on object
Get helpID on object
Display help

System Initiated Internal, varies Internal, varies

Display help

CSH Type	Activation Mechanism	Object for Which Help Is Provided	Implementation Steps
Window-Level	Press F1 (or Help) key	Window with focus	Set helpIDs for components Capture F1 key press Get window that has focus Get helpID for window Display help
Field-Level	1. Activate field-level help 2. Navigate with mouse or keyboard 3. Select object	Selected object	Set helpIDs for components Activate field-level help (button or menu item) Track context- sensitive events Get helpID for selected object Display help
Help Button Menu Item	Click button or choose menu item	Topic associated with button or menu item	Create button or menu object Set helpID on object Get helpID on object Display help
System Initiated	Internal, varies	Internal, varies	Display help

Basic Elements

This section describes the low-level elements used in implementing context-sensitive help.

If you use the "convenience" methods in the HelpBroker object to implement context-sensitive help, these low-level elements are managed for you.

The basic steps for implementing context-sensitive help are:

Set and get Component help properties for GUI objects
Track context-sensitive events

Setting and Getting `Component` Help Properties

In order to provide context-sensitive help for GUI Components and menu items, you must associate a help ID with that Component or menu item. To make that association, you set the helpID property and (if you use multiple HelpSets) the HelpSet for the Component or menu item. The JavaHelp system CSH class provides the following convenient methods for setting and getting the helpID for Components and menu items:

public static void setHelpIDString(Component comp, String helpID);

Sets the helpID for a component.

public static String getHelpIDString(Component comp);

Returns the helpID for a component

public static void setHelpSet(Component comp, HelpSet hs);

Sets the HelpSet for a component.

public static HelpSet getHelpSet(Component comp);

Returns the HelpSet of a component.

public static void setHelpIDString(MenuItem comp, String helpID);

Sets the helpID for a menu item.

public static String getHelpIDString(MenuItem comp);

Returns the helpID for a menu item.

public static void setHelpSet(MenuItem comp, HelpSet hs);

Sets the HelpSet for a menu item.

public static HelpSet getHelpSet(MenuItem comp);

Returns the HelpSet of a menu item.

Tracking Context-Sensitive Events

The context-sensitive help class provides a method you can use to easily track context-sensitive events. This method traps all non-navigational events until an object is selected. It returns the selected object.

	public static Component CSH.trackCSEvents()

Implementing Context-Sensitive Help

The following sections describe how to use the JavaHelp system to implement the different forms of context-sensitive help.

The HelpBroker

The JavaHelp system defines a HelpBroker interface that provides "convenience" methods that greatly simplify the job of implementing context-sensitive help. HelpBroker methods hide much of the underlying implementation details--in exchange, using the HelpBroker limits the flexibility of your implementation. For example, if you use the DefaultHelpBroker, you must display help information in the standard help viewer.

You can implement context-sensitive help without using the HelpBroker, or use it for some tasks and not for others. For example, if your implementation requires something not provided in the HelpBroker (for instance, you want to display context-sensitive help in a different viewer), you must use the basic classes (CSH, JHelp) directly. For information about those classes, use the JavaHelp system apiviewer command.

A HelpBroker's "convenience" methods enable:

Window-level help for a dialog box
Help buttons for dialog boxes
Buttons and menu items that activate field-level help

The following illustration shows how the HelpBroker and its context-sensitive methods (hb.*) are used with other JavaHelp system components:

HelpBroker Context-Sensitive Methods

A HelpBroker provides the following context-sensitive methods:

public void setHelpSet(HelpSet hs);

Sets the HelpSet for the current HelpBroker (there can be only one HelpSet per HelpBroker). If you use this method to change HelpSets, the displays in the corresponding JHelp component and JHelpNavigator are changed.

public HelpSet getHelpSet();

Gets the current HelpSet for the HelpBroker.

public void setCurrentID(Map.ID id) throws BadIDException;

Sets the current ID that is to be displayed in the help viewer. If hs is null, the HelpBroker's current HelpSet is used. If hs is different than the current HelpSet (and not contained in the current HelpSet), the setHelpSet method is executed.

public void setCurrentURL(URL url, HelpSet hs) throws BadIDException;

Displays the specified URL in the help viewer. If hs is null, the HelpBroker's current HelpSet is used. If hs is different than the current HelpSet (and not contained in the current HelpSet), the setHelpSet method is executed.

public void enableHelpKey(Component comp, String id, HelpSet hs);

Enables the Help key on a Component. This method works best when the component is the rootPane of a JFrame in Swing-based applications, or a java.awt.Window (or subclass thereof) in AWT-based applications. This method sets the default helpID and HelpSet for the Component and registers keyboard actions to trap the "Help" keypress. If the object with the current focus has a helpID, the helpID is displayed when the Help key is pressed, otherwise the default helpID is displayed.

public void enableHelp(Component comp, String id, HelpSet hs);

Enables help activation for a help component (for example, a Help button). This method:

Registers the helpID and HelpSet on comp
Sets the HelpBroker's HelpActionListener on comp

public void enableHelp(MenuItem comp, String id, HelpSet hs)

Enables help activation for a MenuItem. This method:

Registers the helpID and HelpSet on comp
Sets the HelpBroker's HelpActionListener on comp

public void enableHelpOnButton(Component comp, String id, HelpSet hs)

Enables help for a Component. This method sets the helpID and HelpSet for the Component and adds an actionListener. When an action is performed it displays the Component's helpID and HelpSet in the default viewer. If the Component is not a javax.swing.AbstractButton or a java.awt.Button an IllegalArgumentException is thrown.

public void enableHelpOnButton(MenuItem comp, String id, HelpSet hs)

Enables help for a MenuItem. This method sets the helpID and HelpSet for the Component and adds an actionListener. When an action is performed it displays the helpID and HelpSet in the default viewer.

CSH Inner Classes

The CSH class contains three inner classes that provide support for context-sensitive help.

CSH.DisplayHelpAfterTracking

An ActionListener that displays help on a selected object after tracking context-sensitive events. Its constructor takes a HelpBroker object.

CSH.DisplayHelpFromFocus

An ActionListener that displays the help of the object that currently has focus. This method is used to enable HelpKey action listening for components other than the RootPane or window. This listener determines if the object with the current focus has a helpID, if it does the helpID is displayed. If the object does not have a helpID, the helpID on the action's source is displayed (if one exists).

CSH.DisplayHelpFromSource

An actionListener that gets the helpID for the action source and displays the helpID in the help viewer. Its constructor takes a HelpBroker object.

Window-Level Help

Start your window-level help implementation by setting the helpID and (if you use multiple HelpSets) the HelpSet for each component for which you want help. If you do not set help for a given component, CSH.getHelpID() recursively searches through the component's ancestors until it finds the first ancestor with a helpID, or until it reaches the last ancestor. For example:


	                   :
	JTextArea newText = new JTextArea();
	hb.enableHelp(newText, "debug.overview", hs);
	                   :

After you set the helpID/HelpSet for all components, use the HelpBroker enableHelpKey() method to enable the F1 key for the frame's RootPane. The hb.getHelpKeyActionListener() method enables the F1 key on ActionListener objects other than root panes. For example:


	                   :
	rootpane = frame.getRootPane();
	mainHelpBroker.enableHelpKey(rootpane, "top", null);
	                   :

Field-Level Help

Start your field-level help implementation by setting the helpID and (if you use multiple HelpSets) HelpSet for each component for which you want help. If you do not set help for a given component, CSH.getHelpID() recursively searches through the component's ancestors until it finds the first ancestor with a helpID, or until it reaches the last ancestor.

After you set the helpID/HelpSet for all components, create a field-level help button or menu item. Set an ActionListener on the button or menu item with a HelpBroker object using getOnItemActionActionListener. For example:


	JToolBar toolbar=new JToolBar();
	CSH.setHelpID(toolbar,"toolbar.main");
	                   :
	helpbutton= addButton(toolbar, "images/help.gif", "help");
	helpbutton.addActionListener(new CSH.DisplayHelpAfterTracking(mainHelpBroker));

Help Menu/Button Help

To implement Help menu or Help button help:

Create a menu item or button
Set the helpID and (if you use multiple HelpSets) HelpSet on the object
Enable help on the object with the HelpBroker

The CSH class provides the CSH.DisplayHelpFromSource class to enable help on objects with types other than AbstractButton, Button, or MenuItem. For Example:


	JButton helpButton = new JButton("Help");
	mainHelpBroker.enableHelpButton(helpButton, "browse.strings", null);

System Initiated Help

Although system initiated help is rarely implemented using the help viewer, it is simple to do. When help is presented internally within an application, pass a valid helpID to a HelpBroker object. For example:


	                   :
	try {
	    mainHelpBroker.setCurrentID(helpID);
	} catch (Exception ee) {
	    System.err.println("trouble with visiting id; "+ee);
	}
	                   :

Sample Code

The following example shows the code required for the different types of context-sensitive help using a default HelpSet:


	try {
	    ClassLoader cl = ApiDemo.class.getClassLoader();
	    URL url = HelpSet.findHelpSet(cl, helpsetName);
	    mainHS = new HelpSet(cl, url);
	} catch (Exception ee) {
	    System.out.println ("Help Set "+helpsetName+" not found");
	    return;
	} catch (ExceptionInInitializerError ex) {
	    System.err.println("initialization error:");
	    ex.getException().printStackTrace();
	}
	mainHB = mainHS.createHelpBroker();
                           :
	// Enable window-level help on RootPane
	rootpane = frame.getRootPane();
	mainHB.enableHelpKey(rootpane, "top", null);
                           :
	// Enable field-level help on various components
	JToolBar toolbar=new JToolBar();
	CSH.setHelpIDString(toolbar,"toolbar.main");
                           :
	//Enable Menu/Button help on Help menu item
	helpbutton= addButton(toolbar, "images/help.gif", "help");
	mainHelpBroker.enableHelpButton(helpbutton, "browser.strings", null);

	sourceIFrame = new JInternalFrame("Source", true, true, true, true);
	CSH.setHelpIDString(sourceIFrame, "edit.editsource");

	JTextArea newtext=new JTextArea();
	CSH.setHelpIDString(newtext, "build.build");

	newtext = new JTextArea();
	CSH.setHelpIDString(newtext, "debug.overview");

	newtext = new JTextArea();
	CSH.setHelpIDString(newtext, "browse.strings");
                           :
	// System Level help somewhere within the code
	try {
	    mainHelpBroker.setCurrentID(helpID);
	} catch (Exception ee) {
	    System.err.println("trouble with visiting id; "+ee);
	}
                           :

See also: