JavaHelp, an optional package of the Java platform, is a great tool for implementing online
documentation for your applications. It's both an engine that displays documentation and an API that drives that engine. JavaHelp's appearance is highly customizable. In its standard
form, it consists of a content pane capable of displaying any
HTML 3.2 page and a navigation pane for browsing the online
documentation, as shown in Figure A
. In this article,
I'll explain how to implement JavaHelp in your
Nuts and bolts Figure B
Writing online documentation to be used with JavaHelp is extremely
straightforward. To demonstrate the process, I will develop
documentation for a preferences dialog box for a hypothetical
application, shown in Figure B.
Example preferences dialog box
The first step is to organize the documentation into topics. Each topic
is a separate HTML 3.2 page contained in its own file. Topics
are the units of JavaHelp online documentation and are
displayed one at a time in the content pane.
organization of the documentation into topics is entirely up
to you. In this example, I decided to create a topic for the
dialog box as a whole and one topic for each field and button.
Table A shows these topics.
Topics for preferences dialog box
setting and button corresponds to a topic stored
in a separate file. There is also one topic for
the dialog box itself.|
|Control ||Topic file|
stop width ||help/tab_stop.html|
|Autosave minutes ||help/autosave.html|
backup file ||help/write_backup.html|
The next step is to create a map file
that associates IDs
with URLs (paths to
HTML topic files). The IDs are used as a portable way to refer
to topic files without the need to hard-code the path to the
As you can see in Listing
, the map file format is simple. It's just an XML
file with one tag (mapID
) for each ID. The
attribute defines the ID and the url
attribute defines the topic file's path. As a rule of thumb,
there should be one ID for each topic file.
you need to create a table of contents for your documentation.
The table of contents is an XML file that describes the
organization of your documentation, used by JavaHelp to create
a tree view of your documentation's layout.
B shows, the table of contents file format is
straightforward. The tocitem tag defines an entry,
which can be nested to show the hierarchy between them. The
text attribute defines the text to be displayed in the
tree view and the target attribute defines the ID of
the topic to be displayed when the entry is
If the target
attribute is omitted, the entry is just a
placeholder and does not display any topic when selected. This
is especially useful for entries that do not correspond to any
topic but contain other entries.
The set of all files
that make up the online documentation (topic files, map file,
table of contents file, etc.) is called a helpset. To
tie everything together, you must create a helpset
file so that JavaHelp can find all the pieces of your
Listing C shows a sample helpset file.
The helpset file is an XML file that contains several tags that
describe your helpset. The title tag defines a title to
be displayed by JavaHelp. The maps tag defines the URL
that points to your map file (tag mapref, attribute
location), as well as the ID of the topic to display
when the documentation is first displayed and no topic is
selected (tag homeID).
The tag view
defines how you want to browse the documentation. You can use
several different views, called navigators, to do
that. The tag name defines a name for the navigator
(for use in the application), and the tag label defines
text to be displayed by JavaHelp for the navigator. The tag
type is the fully qualified name of the navigator class
(javax.help.TOCView for the table of contents
navigator) and the tag data specifies the data to be
used by the navigator (the URL to the table of contents file,
in the case of the table of contents
Figure C shows how the several files
relate to each other.
Help file relation
Adding JavaHelp to your application Setting
The process of integrating the online
documentation with your application is incredibly simple.
JavaHelp already provides the bulk of the code, so the amount
of effort required is minimal.
The first step is to
construct a javax.help.HelpSet object to encapsulate
your helpset. To do that, use the
HelpSet(ClassLoader,URL) constructor, passing
null as the first parameter (to use the default class
loader) and the URL to your helpset file as the
You can use the static method
findHelpSet(ClassLoader,String) of the class HelpSet to
get a URL to your helpset given its pathname. The advantage is
that the method applies localization rules and searches
through the application classpath, jar files,
Next, you need to create a HelpBroker
object. The HelpBroker drives the several classes that
compose the JavaHelp system to display the online
documentation when requested.
Finally, you must set up
your application to display the documentation when requested
by the user. The most common way to do that is to set up a
button or a menu item that, when pressed (in the case of the
button) or selected (in the case of the menu item), displays a
For each button or menu item, just
call the method HelpBroker.enableHelpOnButton. This
method accepts three parameters. The first is the button or
menu item object that will activate the help. The second is
the ID of the topic to be displayed when the button/menu item
is pressed/selected. And the third is the HelpSet
object. The HelpBroker class takes care of all the hard
work for you.
Another way to add online
documentation to your application is to use
In this case, the user
requests help about a specific component by pressing a key, or
clicking on it.
JavaHelp provides all the support
needed to create context-sensitive. First, you associate an ID
with each component for which you want to provide
context-sensitive help. This determines the topic to display
when context-sensitive help is requested for that component.
This is accomplished by the method HelpBroker.enableHelp.
Much like the enableHelpOnButton method, it receives as
parameters the component or menu item, the ID of the topic
corresponding to the component, and the helpset.
want to set up a help key that displays the topic of the
component that has the focus, call the method
HelpBroker.enableHelpKey. As parameters, pass the root
pane of the dialog box/application, the ID of the topic to
display if no component has the focus, and the helpset. Notice
that the help key is platform-dependent; usually it is the
If you want to display the topic when the
user clicks on the component, create an instance of the class
CSH.DisplayHelpAfterTracking (pass the
HelpBroker object as the parameter to its constructor),
and add it as an event listener to a button or a menu item (by
using the addActionListener method of the
When the user presses the button or selects
the menu item, JavaHelp changes the cursor to a custom help
cursor to indicate that context-sensitive help is active.
Then, when the user clicks on a component, JavaHelp displays
its associated topic, if any, and changes the cursor back to
normal, deactivating the context-sensitive help.
D shows the complete code for the preferences dialog
box of the Figure B. It uses a help button to display help
about the dialog box and the help key to display
context-sensitive help about each component.
Online documentation is an
essential component of any application today. Using JavaHelp,
you can add a professional-looking help system to your
application with no effort.
JavaHelp does all the hard
work for you so that you can concentrate on the application
itself. Its clear separation of help contents and the code
that drives it makes it easy to develop the documentation in
parallel with the application.