On-line Help

This document explains the on-line help features of Image2000 and presents a cookbook for help authoring. The intended audience is (a) Image2000 developers and (b) those who want to edit and/or extend Image2000 on-line help.

Image2000 uses the JavaHelp package to format and present help. See http://java.sun.com/products/javahelp. The following subsections assume that the reader is familiar with JavaHelp.

Image2000 Help Features

Image2000 has the following help features:

• The Help menu has three entries ("Contents", "Index", and "Search") that display the standard JavaHelp window. Depending upon the particular menu entry selected, one of the three JavaHelp navigators is automatically selected. The help text window shows the highest level of Image2000 help.
• The Help menu has an entry for "On Item". Selecting this entry turns the cursor into a question mark that may be used to click on any control. If the control has associated help, then that help is displayed; if the control does not have associated help, then the help associated with the parent control is displayed (and so on until the highest-level control is encountered). Note that a DAG node is considered a control: clicking the question mark cursor on a DAG node presents a description of the underlying JAI operation.
• The main windows's toolbar has a question mark icon that has the same behavior as the "On Item" menu entry.
• The DAG editor's library panel has a Help button that displays a description of the currently-selected JAI operation.
• The DAG editor's "Properties..." dialogs have tooltip help for each parameter.
• The menu mode dialogs for image operations have a Help button that displays a description of the operation. These dialogs also have tooltip text that describes each parameter.
• The F1 key (and the HELP key if available) displays help text on the control that currently has focus. If the control has no associated help text, then JavaHelp walks the component parent chain, displaying the first help found. Because of the counterintuitive behavior of "focus" within Java/Swing, this feature is of questionable value.

Information for Help Authors

Help IDs

A "helpId" is a string associated with an Image2000 component e.g., a button, window, etc. The string is a key (or "target" in JavaHelp terminology) into the help database. JavaHelp jtm files map helpIds into URLs, each URL identifying the help text associated with the corresponding helpId. The core Image2000 has three jtm mapping files: help/map.jhm for basic help text, help/jai-ops.htm for the JAI operations, and help/codecs.htm for codecs.

For the following components, Image2000 automatically sets the HelpId:

• Image2000 main frame: i2k.top.
• Image windows: i2k.image-window.
• DAG windows: i2k.dag-window.
• DAG nodes: op-jai-operation-name-all-lowercase.
• Codecs: decoder-codec-name for decoder (read) parameters and encoder-codec-name for encoder (write) parameters. The codec names are lowercase.
• Menubars: as defined by the helpId attribute (if any) of the <menubar> XML tag that defines the menubar.
• Menus: as defined by the helpId attribute (if any) of the <menu> XML tag that defines the menu.
• Menu entries: the helpId (if any) of the corresponding Action. (The helpId associated with the Action is defined by the helpId attribute of the <action> XML tag.)
• Toolbars: the helpId of the helpId attribute (if any) of the <toolbar> XML tag.
• Toolbar entries: the helpId (if any) of the corresponding Action.

(The details of defining actions, menus, and toolbars in XML, including the assignment of helpIds, are described in Configuration File Formats.)

Image2000 uses component-level helpIds for context-sensitive help as follows:

• Question mark help: When using the Help menu's "On Item" entry (or, equivalently, the main toolbar's "help" button), the helpId of the selected component determines the help page to be displayed. If the selected component does not have a helpId, then JavaHelp uses the helpId of the parent component and so on until the highest-level component is encountered.
• Help key focus help: Image2000 processes the F1 (and Help key, if avaiable) according to JavaHelp's CSH.displayHelpFromFocus() method, i.e., the F1 key produces the help text associated with the helpId of the component that currently has focus. (As mentioned above, this feature is of questionable value because "focus" is a illusive concept for the end user.)

Help Authoring Cookbook

1. Edit help/Map.jhm to provide "target" URLs for each helpId described above. For image operations, edit help/jai-ops.jhm to define the targets.
2. Place html files referenced by the targets in the help/html directory.
3. Edit help/toc.xml to define the help Table of Contents.
4. Edit help/index.xml to define index entries. If you do not want an index, then delete the index view section of help/main.hs, the main helpset file.
5. Before delivery, run help/jhindexer.bat to construct the search database. The indexing program builds the database in the help/JavaHelpSearch directory.

Properties

By default, Image2000 takes the main helpset from help/main.hs. You may override this default by setting the i2k.main.helpset.url to be the URL of the main helpset file.

You may request that Image2000 load additional helpset files by setting the i2k.aux.helpset.url property. This property may be a simple URL or a list of URLs separated with semi-colons.

JAI Operation Parameter Help

Parameter dialogs for JAI operations (in DAG mode or menu mode) have a tooltip for each paramter. The tooltip text for a parameter comes from the XML oplib definition of the operation, i.e., the description attribute of the <param> tag. If the description attribute is omitted for a parameter, then the tooltip text comes from the parameter description in the JAI operation registry.

The ability to override the JAI parameter description in the oplib definition is critical: the property editor for a parameter may perform a conversion from "user units" to "JAI units". For example, the Rotate operation has the following XML definition:

The DegreePropertyEditor accepts user input in degrees and converts to radians. The description attribute, "rotation angle in degrees", overrides the JAI registry description of the parameter, telling the user the proper units for input.

Help for Plugins

Image2000 plugins define their own help text. See Plugins.

Known Problems

The following are known problems:

• Use jar files for help text? The delivery would be much smaller. This has not been done because the the jar protocol does not currently permit relative URLs and our jhm files would have hard-coded directories.
• While JavaHelp is loading classes or data, the Image2000 logic attempts to display an hourglass cursor. The cursor does not always appear, a real annoyance to the user.