Integrating with the Help *button* isn't too difficult. It's integrating with the table of contents on the Help *viewer* that's impossible (or at least impossible for all practical purposes).

Here's some code from a property page in one of my tools.

  public HelpTopic getHelpTopic() {
    return new ZipHelpTopic(
      null,
      getClass().getResource("/doc/file-props.html").toString()
      );
  }

This works when the documentation is in the jar file with the classes. Here's a brief explanation of what's going on.

Property pages define a method called getHelpTopic that returns a HelpTopic. When the Help button is pressed, this method is used to get the help file. This technique will work equally well with any other class that uses a HelpTopic (wizards are one that come to mind).

Return a ZipHelpTopic from those methods. I don't know why it's called a ZipHelpTopic, because I can't tell that anything in particular needs to be zipped. Also I don't know what that first argument to the constructor is about. Passing null seems to work. I'm not sure it's even used.

For the second constructor argument, pass the URL (as a String) to your documentation file. In this case I'm using getResource to find the documentation within the jar. Since the argument to getResource starts with a slash, the doc directory should be at the jar's root. Without the slash the file would be something like "com/mypackage/doc/file-props.html."

Again, the key points are to use ZipHelpTopic for the HelpTopic and to use getResource if you want to distribute the documentation inside the tool's jar file. If you put it in the documentation directory, I guess you need to hard code in the jar file name and add that to JBuilder's installation directory.

Now allow me to editorialize briefly. :-) In my opinion it's better to put the documentation in the tool's jar rather than in the documentation directory. It's easier for people to install your tool, there's less chance of people messing it up, users can call your jar files whatever they choose, and you really don't gain anything by putting it in the doc directory.

2001-Apr-20 11:06am gyles19@visi.com

Here's an example taken from a wizard, the help file is located in the distributed jar file in the jar-directory "com/acme/package/help/". The wizard class is located in the jar-directory "com/acme/package/".

package com.acme.package;
class MyWizard... {

...

    public void help(WizardPage currentPage, WizardHost host) {
        // Get the URL to the the help file, it's relative path compared to
this class is help/MyHelp.html
        URL url = this.getResource("help/MyHelp.html");
        HelpTopic topic = new ZipHelpTopic(null, url.toExternalForm());
        HelpManager.showHelp(topic, currentPage.getPageComponent(host));
    }
}

    return new ZipHelpTopic(new ZipHelpBook("j2mewtkdoc.jar"), "ToolkitPropertyPage.html");