In this chapter:

• JavaHelp introduction
• JavaHelp API overview
• Basic help example
• Adding dialog-style help
• Customizing the help viewer
• Creating a custom help view

JavaHelp includes a standard Swing-based help viewer illustrated in figure 25.1 below. This viewer contains a toolbar in its northern region and a split pane in the center. The toolbar contains two buttons allowing navigation between help topics that have been visited previously in a forward/backward style. The left split pane component is a tabbed pane containing a table of contents, help index, and search navigation facilities. The right split pane component is an editor pane used to display the content of the currently selected help topic. Help content is expected to be in the form of HTML documents, enabling rich display capabilities and greatly simplifying the delivery of help files across the Internet.

To use JavaHelp in an application we need to prepare a set of files described below. With the exception of content files and search files, each file is expected to be in the XML format. (In describing each XML-based file below, we present a simple example implementation which we will use in the section 25.3 application.)

This system file uses the XML format to deliver information about other help components and files. XML tags used in this file have the following meaning:

<?xml version='1.0' encoding='ISO-8859-1' ?>

<helpset version="1.0">

<title>Basic Layout Example - Help</title>

<maps>

<homeID>top</homeID>

<mapref location="Layout.jhm"/>

</maps>

<view>

<name>TOC</name>

<label>Table Of Contents</label>

<type>javax.help.TOCView</type>

<data>LayoutTOC.xml</data>

</view>

<view>

<name>Index</name>

<label>Help Index</label>

<type>javax.help.IndexView</type>

<data>LayoutIndex.xml</data>

</view>

<view>

<name>Search</name>

<label>Search</label>

<type>javax.help.SearchView</type>

<data>JavaHelpSearch</data>

</view>

</helpset>

<?xml version='1.0' encoding='ISO-8859-1' ?>

<map version="1.0">

<mapID target="top" url="LayoutFrame.html" />

<mapID target="FlowLayout" url="FlowLayout.html" />

<mapID target="GridLayout" url="GridLayout.html" />

<mapID target="BorderLayout" url="BorderLayout.html" />

<mapID target="BoxLayout" url="BoxLayout.html" />

</map>

This system file uses the XML format to deliver information about a help topics table of contents. This represents a view that typically contains references to help topic IDs in a logically grouped order. XML tags used in this file have the following meaning:

<?xml version='1.0' encoding='ISO-8859-1' ?>

<toc version="1.0">

<tocitem>Basic Layout Example - TOC

<tocitem text="Frame" target="top"/>

<tocitem text="FlowLayout" target="FlowLayout"/>

<tocitem text="GridLayout" target="GridLayout"/>

<tocitem text="BorderLayout" target="BorderLayout"/>

<tocitem text="BoxLayout" target="BoxLayout"/>

</tocitem>

</toc>

This system file uses the XML format to deliver information representing a help index view. This view is very similar to a TOC view described above, but typically organizes references to help topics in alphabetical order. XML tags used in this file have the following meaning:

<?xml version='1.0' encoding='ISO-8859-1' ?>

<index version="1.0">

<indexitem text="Index">

<indexitem text="B">

<indexitem target="BorderLayout" text="BorderLayout"/>

<indexitem target="BoxLayout" text="BoxLayout"/>

</indexitem>

<indexitem text="F">

<indexitem target="FlowLayout" text="FlowLayout"/>

<indexitem target="top" text="Frame"/>

</indexitem>

<indexitem text="G">

<indexitem target="GridLayout" text="GridLayout"/>

</indexitem>

</indexitem>

</index>

To generate binary files constituting the necessary search data, we first create content files for our help system (usually HTML), change to the directory containing these files, and run the following command listing each of our help content files as parameters:

com.sun.java.help.search.Indexer file1 file2 ...

This generates several files and places them in the default "JavaHelpIndex" sub-directory (see the JavaHelp documentation for more options available in generating search data).

The JavaHelp search mechanism can be used to support client-side searching, server-side searching, and stand-alone seaching. As with the whole JavaHelp system, we are provided with very flexible choices in both the presentation and deployment of this information.

ClassLoader loader = this.getClass().getClassLoader();

URL url = HelpSet.findHelpSet(loader, "MyHelpSet.hs");

HelpSet hs = new HelpSet(loader, url);

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.

JButton btHelp = new JButton("Help");

hb.enableHelpOnButton(btHelp, "MyTopicID", null);

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:

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.

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.

In this section we will add help capabilities to the introductory layout example from chapter 4, section 4.2, demonstrating five JInternalFrames each using a different layout manager. Each of these internal frames will receive a help topic placed in a separate HTML file. The HelpSet, map, TOC, and index files for this example were listed in section 25.1, and are used to create a HelpSet instance. We will assign String IDs to each internal frame using the CSH class and attach an InternalFrameListener to transfer focus to a the first component in a selected frame’s! content pane (because focus does not get transferred by default when a new internal frame is selected). By using a our HelpSet’s HelpBroker we will then enable help on each frame, which can be invoked through the F1 key.

import java.awt.*;
import java.awt.event.*;
import java.util.*;
import java.io.*;
import java.net.*;

import javax.swing.*;
import javax.swing.border.*;
import javax.swing.event.*;
import javax.help.*;

public class CommonLayoutsDemo extends JFrame 
{
  protected HelpSet m_hs;
  protected HelpBroker m_hb;
  static final String HELPSETNAME = "Help/Layout.hs";

  public CommonLayoutsDemo() {
    super("Layout Managers [Help]");
    setSize(500, 380);

    createHelp();
    InternalFrameAdapter activator = new InternalFrameAdapter() {
      public void internalFrameActivated(InternalFrameEvent e) {
        JInternalFrame fr = (JInternalFrame)e.getSource();
        Component c = fr.getContentPane().getComponent(0);
        if (c != null)
          c.requestFocus();
      }
    };

    JDesktopPane desktop = new JDesktopPane();
    getContentPane().add(desktop);

    JInternalFrame fr1 = 
      new JInternalFrame("FlowLayout", true, true);
    // Unchanged code from section 4.2
    CSH.setHelpIDString(fr1,"FlowLayout");
    fr1.addInternalFrameListener(activator);

    JInternalFrame fr2 = 
      new JInternalFrame("GridLayout", true, true);
    // Unchanged code from section 4.2
    CSH.setHelpIDString(fr2,"GridLayout");
    fr2.addInternalFrameListener(activator);

    JInternalFrame fr3 = 
      new JInternalFrame("BorderLayout", true, true);
    // Unchanged code from section 4.2
    CSH.setHelpIDString(fr3,"BorderLayout");
    fr3.addInternalFrameListener(activator);

    JInternalFrame fr4 = 
      new JInternalFrame("BoxLayout - X", true, true);
    // Unchanged code from section 4.2
    CSH.setHelpIDString(fr4,"BoxLayout");
    fr4.addInternalFrameListener(activator);

    JInternalFrame fr5 = 
      new JInternalFrame("BoxLayout - Y", true, true);
    // Unchanged code from section 4.2
    CSH.setHelpIDString(fr5,"BoxLayout");
    fr5.addInternalFrameListener(activator);
        
    // Unchanged code from section 4.2
  }

  public static void main(String argv[]) {
    new CommonLayoutsDemo ();
  }

  protected void createHelp() {
    ClassLoader loader = this.getClass().getClassLoader();
    URL url;
    try {
      url = HelpSet.findHelpSet(loader, HELPSETNAME);
      m_hs = new HelpSet(loader, url);
      m_hb = m_hs.createHelpBroker();
      m_hb.enableHelpKey(getRootPane(), "Frame", m_hs);
    } 
    catch (Exception ex) { ex.printStackTrace(); }
  }
}

The CommonLayoutsDemo constructor calls our custom createHelp() method to initialize JavaHelp functionality (see below). Each JInternalFrame is associated with a proper help ID using the CSH.setHelpIDString() method.

An InternalFrameAdapter (implementation of InternalFrameListener--see chapter 16) is used to detect whenever an internal frame is acivated, and transfer focus to the first component within its content pane. This is done because even though JInternalFrame can be activated by a mouse click over it's surface, this does not necessarily transfer focus to it. The focus may still belong to the component in the previously active JInternalFrame. This causes undesirable effects with JavaHelp because in this case we need to show a help topic based on the currently selected frame. By manually transfering focus to a child of the active JInterna! lFrame the correct help topic will be displayed when help is invoked. Thus, we add an instance of this listener to each internal frame.

The createHelp() method retrieves the URL corresponding to the help set for this application, and instantiates our HelpSet and HelpBroker instance variables. The enableHelpKey() method enables help functionality using the F1 key, and sets the default topic ID to "Frame" on the application’s JRootPane.

// Unchanged imports from section 13.5

import javax.help.*;

public class FTPApp extends JFrame 
{
  // Unchanged code from section 13.5

  protected HelpSet m_hs;
  protected HelpBroker m_hb;
  static final String HELPSETNAME = "Help/FTP.hs";

  public FTPApp() {
    super("FTP Client [Help]");

    createHelp();
        
    JPanel p = new JPanel();
    p.setLayout(new DialogLayout2(5, 5));
    p.setBorder(new EmptyBorder(5, 5, 5, 5));

    // Unchanged code from section 13.5

    JButton btHelp = new JButton("Help");
    btHelp.setToolTipText("Show help");
    m_hb.enableHelpOnButton(btHelp, "top", null);
    p.add(btHelp);

    btHelp = new JButton(new ImageIcon("onItem.gif"));
    btHelp.setToolTipText("Component help");
    btHelp.addActionListener(
      new CSH.DisplayHelpAfterTracking(m_hb));
    p.add(btHelp);

    CSH.setHelpIDString(m_txtUser,"UserName");
    CSH.setHelpIDString(m_txtPassword,"Password");
    CSH.setHelpIDString(m_txtURL,"URL");
    CSH.setHelpIDString(m_txtFile,"File");
    CSH.setHelpIDString(m_btPut,"PutButton");
    CSH.setHelpIDString(m_btGet,"GetButton");
    CSH.setHelpIDString(m_btFile,"FileButton");
    CSH.setHelpIDString(m_btClose,"CloseButton");
        
    setSize(520,340);
    setResizable(false);
    setVisible(true);
  }

  protected void createHelp() {
    ClassLoader loader = this.getClass().getClassLoader();
    URL url;
    try {
      url = HelpSet.findHelpSet(loader, HELPSETNAME);
      m_hs = new HelpSet(loader, url);
      m_hb = m_hs.createHelpBroker();
      m_hb.enableHelpKey(getRootPane(), "top", m_hs);
    } 
    catch (Exception ex) { ex.printStackTrace(); }
  }

  // Unchanged code from section 13.5
}

The mechanism of adding help to this application is very similar to that of the previous example. We add IDs to each button and text field component using CSH’s setHelpIDString() method, and enable help invocation on the frame’s JRootPane using an identical createHelp() method (see previous example).

Two new buttons are added to the button row. The first one is titled "Help". Method enableHelpOnButton() is called on the HelpBroker instance to invoke the display of the default help topic when this button is pressed. The second button receives a predefined ActionListener retrieved with the CSH.DisplayHelpAfterTracking() method. This listener displays a custom question mark cursor and displays the appropriate help topic corresponding to the clicked component. (Note that once a component is clicked and help is shown, the cursor reverts back to normal.)

So far we've seen how to add the help viewer to an application and invoke it through pressing F1 or a button. However, we may very well want to customize help functionality by adding a component to the help viewer toolbar, or adding a custom navigational view. The current release of the JavaHelp does include a fairly powerful GUI, however, there are certainly cases where this is not enough. In this and the next section we will show how to integrate two new features into the help viewer: a "Home" toolbar button switching to the home help topic (specified by the <homeID> HelpSet file tag), and a "History" view providing quick return to a specific previously viewed topic.

The bad news is that (at least in this release) JavaHelp does not provide any direct access to the JHelp instance constituting the help viewer. So no customization can be done though provided functionality. The good news is that by taking advantage of the fact that JHelp is a java.awt.Container subclass, we can gain access to its child components indirectly and do what we need.

// Unchanged imports from section 25.4

public class FTPApp extends JFrame 
{
  // Unchanged code from section 25.4

  public FTPApp() {
    super("FTP Client [Customizing Help]");

    // Unchanged code from section 25.4

    WindowListener wndCloser = new WindowAdapter() {
      public void windowClosing(WindowEvent e) {
        disconnect();
        System.exit(0);
      }

      Frame m_helpFrame = null;
      public void windowDeactivated(WindowEvent e) {
        if (m_helpFrame != null)
          return;
        Frame[] frames = getFrames(); // Only available in Java 2
        for (int k = 0; k < frames.length; k++) {
          if (!(frames[k] instanceof JFrame))
            continue;
          JFrame jf = (JFrame)frames[k];
          if (jf.getContentPane().getComponentCount()==0)
            continue;
          Component c = jf.getContentPane().
            getComponent(0);
          if (c == null || !(c instanceof JHelp))
            continue;
          m_helpFrame = jf;
          JHelp jh = (JHelp)c;
          for (int s=0; s<jh.getComponentCount(); s++) {
            c = jh.getComponent(s);
            if (c == null || !(c instanceof JToolBar))
              continue;
            JToolBar jtb = (JToolBar)c;
            jtb.addSeparator();
            JButton home = new JButton(new
              ImageIcon("Home.gif"));
            home.setToolTipText("Home Topic");
            jtb.add(home);
                       
            ActionListener alst = new ActionListener() { 
              public void actionPerformed(ActionEvent e) {
                try {
                  m_hb.setCurrentID(m_hs.getHomeID());
                }
                catch (Exception ex) {}
              }
            };
            home.addActionListener(alst);
          }
        }
      }
    };
    addWindowListener(wndCloser);

    // Unchanged code from section 25.4
  }

// Unchanged code from section 25.4

The idea behind this example is that when the application's frame is deactivated, this may have occurred because the help viewer's frame has become activated. So at that moment we can check all existing frames in the current JVM, and check whether they hold an instance of JHelp as a first child in the content pane. If so, we gain access to the JHelp instance and add our custom component to it.

To accomplish this, significant modification has been made to our WindowListener implementation, which previously only implemented the windowClosing() method. The Frame m_helpFrame instance variable holds a reference to the help viewer's frame (note that this frame is created only once and is hidden/shown as needed after that). The windowDeactivated() method checks this variable, and if it hasn’t been determined yet (i.e. if it is null) it retrieves an array of all the frames created by this JVM using the static Frame.getFrames() method (another nice new feature in Java 2). All these frames are examined! in turn. If one of them is an instance of JFrame and has an instance of JHelp as its first child, we take a reference to that child, cast it to JHelp, and, in turn, examine all its children. We know that one of these children should be an instance of JToolBar (since this only occurs before JHelp first becomes visible, there is no possibility that the toolbar has been undocked and left floating). As soon as it is found, we add() a JButton which calls setCurrentID() on o! ur! HelpSet when pressed:

The Map.ID instance returned by the getHomeID() method is supplied as an argument to this call, which sets the current topic in the viewer to the home topic specifed in our HelpSet file.

Figure 25.4 shows the JHelp viewer with a new toolbar button. Pressing this button shows the home topic as specified by the <homeID> tag in our HelpSet file. We can use a similar technique to add any other component to this toolbar, or to another JHelp constituent.

As we mentioned earlier, JavaHelp allows developers to add a new navigator view by simply adding a new <view> tag to the HelpSet file. Unfortunately this navigator view cannot gain an access to the viewer component that displays it (it can only have access to a data file supplied as a parameter with the <data> tag, similar to TOC or index views). We can work around this limitation by using the same basic technique used in the previous section to access the JHelp toolbar. The following example adds a custom navigational view to the JHelp viewer tabbed pane to display a selectable, dynamically changeable help topic history.!

public class FTPApp extends JFrame 
{
  // Unchanged code from section 25.5

  public FTPApp() {
    super("FTP Client [Help History]");

    // Unchanged code from section 25.5

    WindowListener wndCloser = new WindowAdapter() {
      // Unchanged code from section 25.5

      public void windowDeactivated(WindowEvent e) {
        // Unchanged code from section 25.5

          Enumeration en = jh.getHelpNavigators();
          while (en.hasMoreElements()) {
            JHelpNavigator jhn = (JHelpNavigator)
              en.nextElement();
            NavigatorView view = jhn.getNavigatorView();
            if (view instanceof HistoryView)
              ((HistoryView)view).setNavigator(jhn);
          }
        }
      }
    };
    addWindowListener(wndCloser);

    // Unchanged code from section 25.5
  }

import java.awt.*;
import java.awt.event.*;
import java.util.*;
import java.net.*;

import javax.swing.*;
import javax.swing.event.*;
import javax.swing.tree.*;

import javax.help.*;
import javax.help.event.*;

public class HistoryView extends TOCView
 implements HelpModelListener
{
  protected DefaultMutableTreeNode m_topNode;
  protected JTree m_tree;
  protected DefaultTreeModel m_model;
  protected TreePath m_zeroPath;

  public HistoryView(HelpSet hs, String name, String label,
   Hashtable params) {
    super(hs, name, label, hs.getLocale(), params);
  }

  public HistoryView(HelpSet hs, String name, String label,
   Locale locale, Hashtable params) {
    super(hs, name, label, locale, params);
  }

  public Component createNavigator(HelpModel model) {
    JHelpNavigator navigator = 
      new JHelpTOCNavigator(this, model);
    navigator.getUI().setIcon(new ImageIcon("History.gif"));
    return navigator;
  }

  public static MutableTreeNode parse(URL url, HelpSet hs,
    Locale locale, TreeItemFactory factory) {
      return new DefaultMutableTreeNode("History");
  }

  public void setNavigator(JHelpNavigator jhn) {
    jhn.getModel().addHelpModelListener(this);
    try {
      Container c = jhn;
      while (!(c instanceof JTree))
        c = (Container)(c.getComponent(0));
      m_tree = (JTree)c;
      TOCItem top = new TOCItem();
      top.setName("History");
      m_topNode = new DefaultMutableTreeNode(top);
      m_model = new DefaultTreeModel(m_topNode);
      m_tree.setModel(m_model);
      m_zeroPath = new TreePath(new Object[] { m_topNode });
    }
    catch (Exception ex) {
      ex.printStackTrace();
      System.err.println(ex.toString());
    }
  }

  public void idChanged(HelpModelEvent e) {
    // To avoid conflict with java.util.Map
    javax.help.Map.ID id = e.getID();
    if (m_topNode != null) {
      TOCItem item = new TOCItem(id, null, null);
      item.setName(id.id);
      for (int k=0; k<m_topNode.getChildCount(); k++) {
        DefaultMutableTreeNode child = 
          (DefaultMutableTreeNode)m_topNode.getChildAt(k);
        TOCItem childItem = (TOCItem)child.getUserObject();
        if (childItem.getID().equals(id))
          m_topNode.remove(child);
      }
      DefaultMutableTreeNode node = 
        new DefaultMutableTreeNode(item);
      m_topNode.insert(node, 0);
      m_model.reload(m_topNode);
      m_tree.expandPath(m_zeroPath);
    }
  }
}

One more <view> tag is now added to our FTP.hs XML HelpSet file to request the creation of a HistoryView with a name and label of "History." This results in a new navigator in JHelp’s navigational view tabbed pane. This navigator is connected to an instance of our custom HistoryView class.

To connect the history view to the viewer itself, some code has been added to our windowDeactivated() method in the WindowAdapter inner class. This code retrieves all help views using the getHelpNavigators() method, examines all of them in turn, and, if an instance of our custom HistoryView class is found, calls the setNavigator() method to pass a reference to JHelpNavigator to it.

This class represents a custom implementation of NavigatorView to provide easy access to previously viewed help topics. HistoryView implements HelpModelListener and extends TOCView to inherit its functionality and avoid writing our own NavigatorView sub-class. Instance variables:

The two available constructors delegate their work the corresponding superclass constructors. The createNavigator() method creates an instance of JHelpTOCNavigator (a sub-class of JHelpNavigator) to represent our historical view graphically, and assigns it a custom icon (to be displayed in JHelp’s navigational views tabbed pane).

Since we are not intending to parse any external data files in our historical view (all data is generated by the help viewer itself at run-time), the parse() method simply creates and returns an instance of DefaultMutableTreeNode with user object "History," and no child nodes.

Our custom setNavigator() method establishes a connection between this view and the JHelpNavigator component supplied as parameter representing our history information graphically. First, this view is added as a HelpModelListener to the JHelpNavigator‘s HelpModel to receive HelpModelEvents when a change in the current help topic occurs. Second, we search for the JHelpNavigator’s tree compone! nt by iterating through its containment hierarchy. Then the m_topNode variable is assigned a DefaultMutableTreeNode instance with a default TOCItem user object assigned a name of "History." We also assign the m_model variable as a reference to this tree's model, and m_zeroPath is used to store the path from the tree's root to m_topNode (which simply consists of m_topNode itself). Both variables are needed in idChanged().

The idChanged() method will be called when the current help topic is changed. This method receives an instance of HelpModelEvent which encapsultes, among other things, the new help topic ID. It then creates a new TOCItem using that ID, and checks all child nodes of m_topNode to find out whether the corresponding topic already exists in the history view. If so, it is removed to avoid redundancy. Then the new topic is inserted at the top of the tree. Thus the previously viewed topics appear listed from most recent at the top, to least recent at the bottom. Finally we call reload() on the tree model and expandPath() on the tree, using m_zeroPath, to make sure that the tree updates its graphical representation correctly after it is reloaded.