O'Reilly logo

Creating Effective JavaHelp by Kevin Lewis

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

Seeing JavaHelp in Action

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.


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.”

Starting the JavaHelp System

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.

HelpSet Viewer: specifying a HelpSet

Figure 1-3. HelpSet Viewer: specifying a HelpSet

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.

Working with the JavaHelp Interface

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.)

Using Toolbar Controls and Menus

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.

HelpSet Viewer: showing and hiding the navigation pane

Figure 1-4. HelpSet Viewer: showing and hiding the navigation pane

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.

HelpSet Viewer: opening a help topic or web page

Figure 1-5. HelpSet Viewer: opening a help topic or web page

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.

Navigating Through the JavaHelp System

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):

  • TOC

  • Index

  • Word-search index (known as the Find feature in other online help systems)

You access each navigation control by clicking its associated tab, as shown in Figure 1.6.

JavaHelp navigation controls

Figure 1-6. JavaHelp navigation controls

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:

  1. 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.

  2. Click a help topic within the Airplane Structure category.

    As you would expect, the associated topic appears in the content pane.

  3. 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.

Viewing Help Topics

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:

  1. If it is not already selected, click Introduction to Aviation.

  2. 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.

  3. Click anywhere in the HelpSet Viewer (but not in the pop-up window) to close the pop-up window.

  4. Click the TOC folder titled Airplane Structure.

  5. When the help topic opens, click the picture of the airplane.

    A similar pop-up window appears.

  6. Click anywhere in the HelpSet Viewer to close the pop-up window.

  7. In the TOC, open the folders Flight Environment, Airports, and then Runways and Taxiways, and then click the TOC help topic titled Markings.

  8. 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.

  9. Close the secondary window by clicking its close button.

I discuss pop-up windows and secondary windows in more detail in Chapter 6.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required