JavaHelpTM 1.0 - JavaHelp Class Structure
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.
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.
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:
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.
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.
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.
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.
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.
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.