JavaHelp Goes Online

The JavaHelp^TM API -- a platform-independent, extensible system for application help and online documentation -- is now available as an early-access release from Java Software. You can download the new release at no cost from the Java Developer Connection.

If you have worked with earlier versions of JavaHelp, you'll notice that this newest early-access release includes new functionality and enhancements. In particular, it supports JDK 1.1 as well as JDK 1.2. Other key enhancements include context-sensitive help, merging support, search enhancements, and support for Swing 1.1 Beta.

The JavaHelp API, written entirely in the Java^TM programming language, provides capabilities for navigating, searching, and displaying information. Information architects and software developers can use the JavaHelp software to deliver online help for components, applets, and applications. Authors can also use the JavaHelp software for electronic publishing for the Web and corporate intranet. For more information about JavaHelp, including the JavaHelp specification, FAQ, communications, and events, visit the JavaHelp web site (java.sun.com/products/javahelp).

Types of Context-Sensitive Help

Context-sensitive help is information provided to the user based on the context of the task in which they are involved. The JavaHelp system provides mechanisms for two types of context-sensitive help: user initiated help and system initiated help.

User-Initiated Help

User-initiated help delivers information to users when they explicitly ask for it. The JavaHelp system includes the following user initiated mechanisms:

• Window-Level Help
• Field-Level Help
• The Help Menu
• The Help Button

Window-Level Help

Users can obtain window-level help -- that is, help about container objects such as application windows and dialog boxes that have focus -- by pressing the F1 function key (on systems with a Help key, the Help key also works). An object is considered to have focus when it is in a state that the user can interact with it.

---

NOTE: It is technically possible to use this mechanism to provide context-sensitive help for any object that has focus when the F1 key is pressed. However, in order to make JavaHelp system implementations as consistent as possible, you are strongly encouraged to use this mechanism only to provide help at the window level. Use the field-level help mechanism to provide help for other GUI objects.

By default, help information is displayed in the help viewer.

---

Field-Level Help

You can use field-level help to obtain help about any GUI object. Here's how to use field-level help:

1. Click the field-level help button or choose the Help->Field-Level Help menu item to change the cursor to a special field-level help cursor.
    
2. Select a GUI object

By default, help information is displayed in the help viewer and the cursor returns to its original state.

The Help Menu

JavaHelp provides a Help menu that can be used to provide help to users about specific tasks or objects. The Help menu contains a sub-menu of items that provide help about completing various tasks.

The Help Button

It is common for dialog boxes to contain a Help button that provides help information about how to use the dialog box. Clicking the Help button is usually equivalent to pressing the F1 key while the dialog box has focus.

System-Initiated Help

Most applications provide information automatically when the user performs a particular action. Most commonly, this information consists of status, warning, or error messages. It is also possible for the application to use the help viewer to provide more detailed help based on user actions.

Implementing Context-Sensitive Help

The JavaHelp system provides classes and methods that help you implement context-sensitive help in your applications. This section

• Summarizes the context-sensitive help system.
   
• Describes the basic elements of the system.
   
• Describes how to implement context-sensitive help.

The following table summarizes the context-sensitive help system.

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:

1. Set and get JComponent help properties for GUI objects.
    
2. Track context-sensitive events.
    

Setting and Getting JComponent Help Properties

To provide context-sensitive help for a GUI component (that is, a component that is sub-classed from the JComponent class), you must associate a help ID with that component. To make that association, you set the helpID property and (if you use multiple HelpSets) the HelpSet in the JComponent. The JavaHelp system CSH class provides the following convenient methods for setting and getting the JComponent helpID:

public static void setHelpID(JComponent comp, String helpID);
public static String getHelpID(JComponent comp);
public static void setHelpSet(JComponent comp, HelpSet hs);
public static HelpSet getHelpSet(JComponent comp);

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 trackCSEvents(Component comp)

Using Context-Sensitive Help

This section describes how to use the JavaHelp system to implement the different forms of context-sensitive help. The first section describes the HelpBroker object and the subsequent sections describe:

• Window-level help
• Field-level help
• Help menu/button help
• System initiated help
• Sample Code

The HelpBroker

The JavaHelp system includes a HelpBroker object 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, it limits the flexibility of your implementation. For example, if you use the HelpBroker you must display help information in the standard help viewer.

---

 

NOTE: 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 example, 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, please use the JavaHelp system apiviewer command to view their API information.

---

 

The HelpBroker 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

The 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
         (String helpID, HelpSet hs) 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 setURL(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 ActionListener getHelpKeyActionListener(); 

The ActionListener for F1 and Help key activation. Set the returned ActionListener on the component that will be receiving the keypress event.

 public ActionListener getFieldLevelActionListener(); 

The ActionListener for field-level help. Set the returned ActionListener on the component (for example, button or menu item) that will be receiving the activation event that activates field-level help.

 public ActionListener getHelpActionListener(); 

The ActionListener for a Help object. Set the returned ActionListener on the help component (for example, a Help button) that will receive the action (for example, a keypress).

 public void enableHelpKey(RootPane root,
         String id, HelpSet hs); 

This enables window-level help on the RootPane. This method:

• Registers F1 and Help key presses with the RootPane.
• Sets a default helpID for the RootPane.
• Registers the HelpBroker's HelpActionListener with the RootPane.

  public void enableHelp(JComponent 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.

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.

In order to make JavaHelp system implementations as consistent as possible, you are strongly encouraged to use this mechanism only to provide help at the window level (set the helpID only on the RootPane). Use the field-level help mechanism to provide help for other GUI objects.

After you set the helpID/HelpSet for all components, enable the F1 key for the frame's RootPane with a HelpBroker object using enableHelpKey(). The hb.getHelpKeyActionListener() method enables the F1 key on ActionListener objects others than root panes. The following code fragment is an 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 an field-level help button or menu item. Set an ActionListener on the button or menu item with a HelpBroker object using getFieldLevelActionListener. The following code fragment is an example:

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

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 HelpBroker provides the hb.getHelpActionListener method to enable help on objects with types other than AbstractButton. The following code fragment is an example:

 JButton helpButton = new JButton("Help");
 mainHelpBroker.enableHelp(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. The following code fragment is an example:

                              :

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

Sample Code

The following samples show the kinds of code that are required for the different types of context-sensitive help using a default HelpSet.

   // Get the HelpSet and the HelpBroker if (hs == null) {
      try { URL url = HelpSet.findHelpSet(null, "api");
         // URL url = HelpSet.findHelpSet(null, helpsetName);
         hs = new HelpSet(null, url); }
      catch (Exception ee) {
          System.out.println ("API Help Set not found");
          return;
      }
   }
   mainHelpBroker = hs.createHelpBroker(); 

   // Enable window-level help on the RootPane
   rootpane = frame.getRootPane();
   mainHelpBroker.enableHelpKey(rootpane, "top", null);

                                    :

   // Set the HelpID on the various components
   JToolBar toolbar=new JToolBar();
   CSH.setHelpID(toolbar,"toolbar.main");

                                    :

   // Enable field-level help on the help button
   helpbutton = addButton(toolbar, "images/help.gif", "help");
   helpbutton.addActionListener
          (mainHelpBroker.getFieldLevelActionListener());
          
                                    :

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

                                     :

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

                                     :

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

                                     : 

   newtext = new JTextArea();
   CSH.setHelpID(newtext, "browse.strings");

                                     :

   JMenu menu =  new JMenu("File");
   CSH.setHelpID(menu, "menus.file");

                                     :

   // Enable Menu/Button help on the Help menu item
   JButton helpButton = new JButton("Help");
   mainHelpBroker.enableHelp
          (helpButton, "browse.strings", null);

                                     :

   menu = new JMenu("Edit");
   CSH.setHelpID(menu, "menus.edit");

                                     :

   // System Level help somewhere within the code 
   try {
      mainHelpBroker.setCurrentID(helpID);
   } 
   catch (Exception ee) {
      System.err.println("trouble with visiting id; "+ee); } 

                                     :