New Features and Changes in JavaHelp 2.0

This page describes the most significant changes since the JavaHelp 1.1.3 release.

Native Browser Support

Release 2.0_02 enables you to use a native browser to display your help topics in the topic pane of the help window. This alternate content viewer uses the Java Desktop Integrated Component (JDIC) browser component BasicNativeContentViewerUI to render content by using the native browser. The use of BasicNativeContentViewerUI requires that the JDIC libraries be installed. See http://jdic.dev.java.net for details on how to integrate the JDIC components into your application.

In your applications, you use this browser by adding the following import statement and then putting the call to setContentViewerUI before the code that creates the HelpBroker or JHelp component (for a code example that creates a HelpBroker, see Adding the JavaHelp System to Applications).

import javax.help.SwingHelpUtilities;
...
SwingHelpUtilities.setContentViewerUI("BasicNativeContentViewerUI");

Additionally, you can use the command-line parameters -ID and -contentViewer to cause hsviewer to use the alternate browser and display a given ID in the helpset, as follows:

java -jar hsviewer.jar -helpset HolidayHistory -classpath\ ../hsjar/holidays.jar -ID easter -contentViewer BasicNativeContentViewerUI

Installation Packages

JavaHelp is now released in a single zip file installation package. You must uninstall prior releases before unpacking V2.0 into a directory.

Running the JavaHelp Viewer

The JavaHelp viewer is now in the JAR file hsviewer.jar. To run it you must use a command similar to the following one:

java -jar c:\jh20\demos\bin\hsviewer.jar

For more information, see Viewing Helpsets.

JDK 1.1 is no longer supported

The earliest version of the JDK that is supported is the Java^TM 2 Platform, Standard Edition (J2SE^TM) JDK 1.2.2.

Change to API for Accessing Frames

In previous versions of JavaHelp, you could directly access the frame in which JavaHelp is displayed if you extended the DefaultHelpBroker. After extending DefaultHelpBroker, you were able access the protected JFrame frame field.

In JavaHelp 2, the frame field is no longer accessible. In applications that use JavaHelp 2, you will have to rewrite code that does this kind of frame access. Use the following methods:

WindowPresentation DefaultHelpBroker.getWindowPresentation(); Window WindowPresentation.getHelpWindow();

You will still be able to access the frame with the following method calls:

WindowPresentation pres = hb.getWindowPresentation(); Window win = pres.getHelpWindow();

Multi-Topic Printing

It is now possible to print more than one help page at a time. You can select a group of topics in a navigation pane, such as the TOC or index, and then choose the Print option to print them all out.

Comprehensive Merging Options

When helpsets are merged, there are new merge options available: UniteAppendMerge and SortMerge. UniteAppendMerge causes like items to be merged, making it possible, for example, to produce fully merged TOCs. SortMerge allows you to produce fully merged and canonically sorted indexes. For more information, see Merging Helpsets.

New Views in Help Viewer

In addition to the existing TOC, Index, and Search navigators, there are two new navigators that can be added to the navigation pane of the help viewer:

Glossary. Short technical descriptions of terms can be put in an XML-based file with a format similar to the index file.
Favorites. An XML-based collapsible and expandable display of the user's favorite topics.

Specifying View (Navigator) Icons or Text

When you specify a navigator by using the <view> tag in the helpset file, you can also specify the icon that displays in the tab above the navigator by using the <image> tag. For more information on setting view images, see the description of the <view> tags in The Helpset File.

You can display text instead of icons in the navigator tabs by setting the presentation tag's displayviewimage attribute to "false". For more information on setting this attribute, see the description of the <presentation> tag in The Helpset File.

Presentation Controls

It is now possible to display help in various kinds of windows (called presentations) from a Java application or from a helpset's table of contents. There are presentation controls in the helpset file and navigator files, a Presentation class, and context-sensitive help changes that support the class. These features provide you with more options for displaying your help content in the JavaHelp Viewer, in a secondary window, or in a popup window.

Not only can you specify the type of presentation window, but for each type of window you can designate the buttons that appear in the toolbar. In addition to the standard Back, Forward, and Print buttons, you can display buttons like the Reload button (reloads the current topic) and the Home button (goes to the main topic defined for the helpset).

For more information, see the Presentation feature in Helpset File and Implementing Context-Sensitive Help.

Customizable Toolbar Support in Helpset File

When you define a presentation window, you can specify if it has a toolbar, and, if so, which controls appear on the toolbar. For more information, see the <toolbar> tag in Helpset File.

Server-Based JavaHelp

The JavaHelp V1.0 API provided an initial foundation for developing online help for server-based applications. JavaHelp 2 extends support for server-based applications with a standard for a JavaHelp bean and a Java Server Pages^TM (JSP) tag library for accessing helpset data. For more information, see Server-Based JavaHelp.

Helpset File has an Implementation Section

The implementation section of the helpset, enclosed in the <impl> tag, enables you to use special viewers based on a MIME type. It can also simplify using an external browser to display your helpsets rather than using the default helpset viewer included in the JavaHelp system.

Specifying an <impl> section in a helpset file creates a registry that provides key data mapping to define the HelpBroker class to use in the HelpSet.createHelpBroker method. The registry also determines the content viewer to user for a given MIME type.

JEditorPane uses this mechanism to link a given MIME type with an editor kit.

For example, the JavaHelp system gets its default content pane viewer for HTML by linking the text/html MIME type to com.sun.java.help.impl.CustomKit, which is an extension of the Swing HTMLEditorKit. If you wanted to display PDF in the content pane, you could write your own PDF editor kit, and then you could map the MIME type for PDF (application/pdf) to your new editor kit.

Another use for this feature might be to replace the current HTMLEditorKit (the content viewer) with a web browser without having to change code as you do in JavaHelp 1.

To see how to declare the tag, see the <impl> tag in Helpset File.

Dynamic Context-Sensitive Help for Components

You can assign help IDs based on cursor position, selection, or some other mechanism inherent in an object. For more information, see Dynamic Map ID Assignment in "Implementing Context Sensitive Help."