#
JavaHelpTM 1.0 - JavaHelp Class Structure

## Copyright 1998-1999 Sun Microsystems

## Packages

JavaHelp is a standard extension for JDK1.1 and JDK1.2. The API is defined in the `javax.help` package, with the exceptions of the search API classes, which are defined mainly in the `javax.help` package, but other packages are also involved. The complete list is:

Package | Description
--- | ---
javax.help | Main package
javax.help.event | Event & Listener classes
javax.help.plaf | Interface to the ComponentUI classes
javax.help.plaf.basic | Basic look and feel; currently no specific PLAF classes are needed
javax.help.resources | Localization classes.
javax.help.search | search classes.

An implementation of the extension may also include some implementation classes that are not intented to be used directly. The Reference Implementation also includes additional classes of utility to Help authors.

## API Structure

This section describes the general principles behind the API classes. More details are available in the javadoc information on the classes. The reference implementation also provides code fragments exemplifying the use of these classes.

As indicated in Overview.html, the API classes in javax.help are conceptually structured in several collections. The different collections are addressed to different tasks and users. The boundaries between some of these collections are not sharp, but the classification helps to reduce the number of concepts, and actions, needed to perform simple tasks.

- Basic Content Presentation
- Complete Access to JavaHelp Functionality
- Swing classes
- Full-Text Search

### Basic Content Presentation

Some applications only are interested in presenting some help information to the user, minimizing the interaction between the help author and the application developer. The basic actions to perform are:

- Locating a HelpSet, perhaps after localization;
- Reading that HelpSet, including any related data, like Map files, TOCs, Indices, and Search database; and
- Visually presenting this HelpSet.

The abstraction of a HelpSet is javax.help.HelpSet, while the abstraction of its visual presentation is javax.help.HelpBroker. A `HelpBroker` provides for some interaction with the presentation regardless of the actual visual details; the default presentation is `DefaultHelpBroker`. An application can provide on-line help using only these two classes.

Sub-HelpSets listed in the HelpSet file using the <subhelpset> tag will be merged automatically before presenting them to the user.

These two classes (an ancillary classes, like Exception classes) do not have any dependency on Swing for their definition, although `DefaultHelpBroker` depends on Swing for its implementation.

### Detailed Control and Access

The `HelpBroker` interface provides substantial control of the presentation of a HelpSet, without leaking unwanted GUI details of the presentation. For example, this interface can be used to interact with the two-pane default presentation of the reference implementation, as well as to interact with some presentation embedded within the application. Additionally, since the HelpBroker does not use any Swing types or concepts, it does not require Swing for its implementation. But some applications will want access to such details as the map from ID to URLs. JavaHelp provides classes for this.

### Extensibility

Content extensibility is described through a `NavigatorView` which provides access to some context information plus a way of presenting this information. `TOCView`, `IndexView`, and `SearchView` are standard views for Table Of Contents, Index, and full-text search.

The standard views yield standard `JHelpTOCNavigator`, `JHelpIndexNavigator`, and `JHelpSearchNavigator` Swing components. The standard views also provide access to the content; this access uses subclasses of `TreeItem`.

New views can be added; for instance a new TOC presentation can be obtained by subclassing TOCView and just changing the JHelpNavigator returned by it. Another view may keep the same JHelpNavigator but use a format for the encoding of the view data (perhaps even generating the data dynamically); this is done by redefining the getDataAsTree method. The presentation of new Views can be derived from the standard ones by subclassing.

### Swing components

JavaHelp provides a collection of Swing components that are used to implement the DefaultHelpBroker and can also be used directly, as in embedded help. The components follow the standard MVC from Swing. There are two main models: `HelpModel` and `TextHelpModel`.

`HelpModel` models changes to the location within a HelpSet; components that want to respond to these changes should listen to events originating within the model - this is how synchronized views work. The location within the model is represented by objects of type `Map.ID`; these correspond to a String (an ID), and a HelpSet providing context to that ID. A HelpSet needs to be explicitly given (in general) because of the ability of merging HelpSets. `TextModel` provides additional information when the content is textual. A TextModel can queried for the current highlights, which a client may present visually. The `DefaultHelpModel` is the default model implementing both models.

`JHelpContentViewer` is the Swing component for the content, while context corresponds to several subclasses of `JHelpNavigator`. `JHelp` is a common grouping of these classes into synchronized views of content.

The basic structure of the Swing classes is shown in the next figure; for additional information about the Swing classes check the Swing Connection home page

A Swing control acts as the main interface to developers. All `ComponentUI` objects for a particular look and feel are managed by a JFC object called `UIFactory`. When a new Swing component is created, it asks the current `UIFactory` to create a `ComponentUI` object. Vendors or developers can ship different `ComponentUI's` to suit their specific needs.

A Swing control then delegates the tasks of rendering, sizing and performing input and output operations to the `ComponentUI`. The `ComponentUI's` `installUI` and `deinstallUI` methods add behavior and structure to the raw Swing component by adding listeners, setting the layout manager, and adding children.

The Swing model defines the component's non-view-specific state. The Swing component communicates changes to the model and listens (through listeners) to the model for changes. Finally, the model provides data to the `ComponentUI` for display.

The ComponentUI objects in the JavaHelp Swing classes are currently fully defined in terms of the other components, hence, there are only `javax.help.plaf.basic` classes, and none of the other PLAF packages are needed.

### Context Sensitive Help

JavaHelp supports a `Map` between identifiers and URLs. `FlatMap` and `TryMap` are two implementations; sofisticated users can provide their own implementations to satisfy different requirements (for example, the map data may be generated dynamically). The main class used to associate specific content with graphic objects is `CSH`.

### Search

JavaHelp supports a standard full-text search view and navigator. The view interacts with a search engine through the types in the `javax.help.search` package. The reference implementation provides a search engine implementing these interfaces but others can also be used; the specific search engine used is part of the information given to the search view. By doing this separation we provide the capability of full-text searching while not imposing specific formats.

The search package has not conceptual dependencies on any other portions of JavaHelp, and it can be used independently. The Reference Implementation provides one such implementation packaged in a JAR file that depends only on the basic platform.

JavaHelpTM 1.0
Send your comments to javahelp-comments@eng.sun.com
Last modified: Mon Apr 12 16:46:01 MDT 1999