JavaHelp is intuitive and functions similarly to other online help systems. If you are familiar with WinHelp or HTML Help, you should have no problem navigating through a JavaHelp system. This section guides you through working with a JavaHelp system and shows you how JavaHelp’s basic features work.
Note
If you have not yet downloaded the sample files discussed earlier in this chapter, you should do so before continuing. While the screen shots in this section provide a sufficient “look” at JavaHelp, only the system itself can provide you with its actual “feel.”
The way users will start the JavaHelp system depends on how you
connect it to an application or applet. Usually, it is as simple as
clicking a button or selecting a menu item. To run a JavaHelp system
independently of an application (for example, when you are testing a
HelpSet), use the
hsviewer
utility Sun includes with
JavaHelp. Under Windows, you can launch the
hsviewer utility through a shortcut created in
the Start menu when you installed
JavaHelp. Under Unix
or Linux, you can find
hsviewer in the demos/bin
subdirectory in the JavaHelp installation area.
The HelpSet Viewer starts by displaying a simple file-selection dialog. Specify the HelpSet filename and the URL of the directory where it resides, as shown in Figure 1.3.
Give it a try: specify the Aviation HelpSet file and URL in the
hsviewer utility. The easiest way to do this is
to click the Browse button and
browse for the HelpSet file. Once you have specified the HelpSet name
and directory URL, click the Display
button to load the HelpSet into the JavaHelp system.
After you load the Aviation HelpSet, take a look at the HelpSet Viewer’s structure. As discussed earlier, the standard HelpSet Viewer uses a tripane window to display its menus, toolbar, navigation controls, and help topics. As you saw in Figure 1.1, the toolbar pane contains the menu and toolbar, which offer menus and controls to assist you in viewing the current HelpSet. The navigation pane contains a TOC, index, or word-search index. The content pane displays the current help topic. You can not only read the topic’s content in this pane but can also access pop-up and secondary windows for expanded information, launch multimedia clips (if you have a multimedia component), and follow hyperlinks to other topics or web pages. Hyperlinks can lead not only to HTML pages in the current HelpSet, but also to web sites on the Internet, as shown with the avbook.com link in the Aviation introductory topic. (The HelpSet Viewer cannot display all HTML-format files. See Chapter 4, for more information.)
The JavaHelp toolbar contains previous and next buttons, similar to those found in web browsers. The previous and next buttons enable you to browse back and forth through topics you have previously viewed. They do not advance you back and forth in order of the help topics as they exist in the TOC. Like a web browser, these buttons are not enabled until you begin navigating through the help system and have viewed topics to which you can move back and forth.
The toolbar also contains print buttons next to the previous and next buttons. You use the print buttons to set up the page’s print options and to print the help topic that is displayed in the HelpSet Viewer.
As you read a help topic, you might find that you would rather display the topic in the entire viewer instead of taking up space for the navigation pane. You can easily show and hide the navigation pane using buttons, as shown in Figure 1.4.
There are also menus at the top of the HelpSet Viewer. These menus offer basic functions such as opening a web page, selecting a new HelpSet, or setting font preferences. If you click Open page from the File menu, the HelpSet Viewer displays the window shown in Figure 1.5.
You can use this window to access not only topics from the current HelpSet but also HTML pages from any web site. If you are connected to the Internet, try typing http://www.oreilly.com in the URL box and then click the OK button. As you probably guessed, the HelpSet Viewer displays the O’Reilly web site.
If you select Set HelpSet from the File menu, the viewer displays the same window shown in Figure 1.3 for selecting a new HelpSet. You can also change the fonts in the navigation pane by clicking Set Font from the Options menu. When the Set Font window appears, simply select a font and size.
Below the toolbar controls and menus is the navigation pane. The navigation controls are very important in any online documentation system. Online documentation is useless if users cannot find the information they need. As shown earlier in Figure 1.1, the navigation pane in the JavaHelp system provides three types of navigation controls (or navigators):
You access each navigation control by clicking its associated tab, as shown in Figure 1.6.
The TOC provides navigation information similar to the TOC of a book. Individual topics are grouped into categories (like sections of a book are grouped into chapters). Each category (represented in Figure 1.6 by a folder icon) can contain both subcategories and individual topics. You can open and close a category by double-clicking the category name or by single-clicking the level icon to its left. You view a help topic by clicking its title. Give it a try using the following steps with the Aviation HelpSet:
Double-click the Airplane Structure category in the TOC.
An overview topic that is associated with the category appears in the content pane, and a list of help topics expands below the Airplane Structure folder in the TOC.
Click a help topic within the Airplane Structure category.
As you would expect, the associated topic appears in the content pane.
Now is a good time to use the previous and next buttons in the toolbar to see how they integrate with the TOC. Click the previous button.
The content pane “jumps” (backward or forward) to the previously displayed topic. Notice that the highlighted category or topic in the TOC stays synchronized with the topic displayed in the content pane.
The
index
provides
navigation information similar to the index of a book, with one
distinct difference: in the JavaHelp index, you can type a
word, or any character
string, directly to find it in the index. Under the index tab (the
middle tab), in the Find box, type
the word landing (the index is
case-sensitive, so be sure
to use all lowercase letters as shown) and press Enter. The system
highlights the first index item that matches the search string, and
the index item’s associated topic displays in the content pane.
With landing still typed in the Find box, press Enter again. As you keep
pressing Enter, subsequent index items are highlighted in the index
and their associated topics display in the content pane. You can also
scroll through the index to select items from it.
JavaHelp also offers a word-search index facility through which users can type a word or phrase and have the system display a choice of topics that contain that word or phrase. The search is case-insensitive. The helpfulness of this feature depends on the search term the user types. With a specific term, such as “metadata file,” the word-search facility will probably find just the desired topics. With a general term, such as “file,” the word-search facility will probably find too many topics.
Give this feature a try with the Aviation HelpSet. Under the
word-search index tab (the tab on the right), in the Find box, type retractable
landing
gear and then press
Enter. The result of the word search is a list
of topics. Each topic is annotated
with the number of
hits—
the number of occurrences of the
search term, exactly or approximately, within the topic.
The HelpSet Viewer automatically displays the first help topic in the list of hits, with the occurrences of the search term highlighted. In the navigation pane, each hit is annotated with a number and an icon. The number indicates how often the search term appears in the help topic; the icon represents the ranking of that topic’s matches, i.e., how close the text in the topic is to the specified search term. There are five possible rankings, from a full circle (highest ranking) to an empty circle (lowest ranking).
For example, when you enter the phrase retractable
landing
gear, the viewer
generates several topic titles. The title “Landing Gear”
has a full circle because all of the words in the search phrase
(“retractable,” “landing,” and
“gear”) appear in the topic together. The title
“Drag” has a half-filled circle because only two of the
words (“landing” and “gear”) appear in the
topic. The title “Airports” has an almost empty circle
because only one word (“landing”) appears in the topic.
When you access help topics using navigation controls, you can work with them as if they were in a standard web browser. You can scroll through and read topics the same way you do with a web browser. Also, hyperlinks work the same way as in a browser. When you see blue underlined text in a topic, click it to go to the topic associated with that link. You can access pop-up windows, secondary windows, and multimedia clips through help topics. To see how these features work, go through the following steps with the Aviation HelpSet:
If it is not already selected, click Introduction to Aviation.
When the help topic opens, click the JavaHelp Note button.
A pop-up window appears, providing a note. You are not limited to buttons for providing pop-up windows; you can also use an image or a regular text link.
Click anywhere in the HelpSet Viewer (but not in the pop-up window) to close the pop-up window.
Click the TOC folder titled Airplane Structure.
When the help topic opens, click the picture of the airplane.
A similar pop-up window appears.
Click anywhere in the HelpSet Viewer to close the pop-up window.
In the TOC, open the folders Flight Environment, Airports, and then Runways and Taxiways, and then click the TOC help topic titled Markings.
When the help topic opens, click the bulleted blue text “Runway markings.”
This time a secondary window appears. Notice that this window looks more like a standard window than did the pop-up window. You can move, resize, and close the secondary window like a standard window.
Close the secondary window by clicking its close button.
I discuss pop-up windows and secondary windows in more detail in Chapter 6.
Get Creating Effective JavaHelp now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.
