Sun Microsystems 1.1.3 JavaHelp User's Guide

JAR Files

The map file is used to associate topic IDs with the URL or path name of HTML

HelpSet File

When the JavaHelp system is activated by your application, the first thing it does is read the HelpSet file specified by the application. The HelpSet file defines the HelpSet for that application. A HelpSet is the set of data that comprises your help system. The HelpSet file includes the following information:

Map file

View information

topic files.

Information that describes the navigators being used in the HelpSet. The standard navigators are: table of contents, index, and full-text search. Information about custom navigators is included here as well.

HelpSet title The name of the top-level TOC folder.

Home ID The name of the (default) ID that is displayed when the help viewer is called without specifying an ID.

Sub-HelpSets Optional section can be used to statically include other HelpSets using the

tag. The HelpSets indicated using this tag are merged automatically into the HelpSet that contains the tag. More details about merging

can be found in Merging HelpSets.

After your product is installed on your user’s system, it must be able to find the HelpSet file. The application specifies the path to the HelpSet file when it starts the JavaHelp system. By convention, the name of the HelpSet file ends with the

.hs

extension.

HelpSet File Format

The format of the HelpSet file is based on the World Wide Web Consortium Extended Markup

Language (XML 1.0) proposed recommendation:

http://www.w3.org/TR/PR-xml-971208

The following is an example of a HelpSet file (description follows):

<?xml version=’1.0’ encoding=’ISO-8859-1’ ?>

<!DOCTYPE helpset

PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 1.0//EN"

"http://java.sun.com/products/javahelp/helpset_1_0.dtd">

<title>Java Development Environment - Help</title>

<maps>

</maps>

<view>

<label>Table Of Contents</label>

<type>javax.help.TOCView</type>

<data>IdeHelpTOC.xml</data>

</view>

<view>

<name>Index</name>

<label>Index</label>

<type>javax.help.IndexView</type>

<data>IdeHelpIndex.xml</data>

</view>

<view>

<name>Search</name>

<label>Search</label>

<type>javax.help.SearchView</type>

JavaHelpSearch

</data>

</view>

</helpset>

The HelpSet Tags

The following table describes the HelpSet tags:

<title>

<maps>

<view>

Defines the HelpSet. It can contain all of the following tags.

Names the HelpSet. This string can be accessed by the application and used in the presentation (for example, in the viewer header stripe).

Specifies the default topic and URL of the map file used in the

HelpSet. Contains the following tags:

[IMAGE] Specifies the name of the (default) ID that is displayed when the help viewer is called if an ID is not explicitly specified.

<mapref> Specifies the map files. Note that in the

1.0 release only one map file may be specified. Contains the following attribute: location

[IMAGE] URL of the map file.

Defines the navigators used in the HelpSet. Each navigator is defined by its own <view>. May contain all of the following tags:

<name>

<label>

Names the view.

Specifies a label associated with the view.

This string can be accessed by the application and used in the presentation (for example, in the navigator’s tab).

<type>

Specifies the path to the navigator class.

<data>

[IMAGE] Specifies the path to the data used by the navigator. When used with the search navigator, it contains the following attribute: engine [IMAGE] Path to the search engine class.

[IMAGE] This optional tag can be used to specify HelpSets you want merged

with the HelpSet that contains the tag. See Merging HelpSets for

more information. Contains the following attribute: location

[IMAGE] URL of the HelpSet file to be merged.

[IMAGE] See also:

application’s HelpSet file--the next thing it does is read the map file listed in the HelpSet file. The map

The Map File

When the JavaHelp system is activated by your application, the first thing it does is read the

file is used to associate topic IDs with URLs (paths to HTML topic files). By convention, map file names include the

.jhm

suffix.

The format of the map file is based on the World Wide Web Consortium Extended Markup Language

(XML).

The following is an example of a short map file:

<?xml version=’1.0’ encoding=’ISO-8859-1’ ?>

<!DOCTYPE map

PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Map Version 1.0//EN"

"http://java.sun.com/products/javahelp/map_1_0.dtd">

</map>

Note that images referred to as IDs (for example, in the TOC) can also be associated with an ID--in this example, toplevelfolder is associated with the GIF image toplevel.gif

The Map Tags

The following are descriptions of the map tags:

<map>

Defines the map. It contains

<mapID>

tags.

<mapID>

Defines a map entry. Uses the following attributes: target

Specifies the ID to associate with the URL specified in the url

attribute.

url

Specifies the URL to associate with the ID specfied in the target

attribute.

[IMAGE] See also:

JAR Files

Extracting files from JAR files

JAR Files

This topic describes how JAR files are used in the JavaHelp system.

The JAR protocol

Using JAR Files

After you create your help information, you will usually encapsulate it into a single file and compress it for delivery to your users. The JavaHelp system uses the JAR (Java ARchive) format for encapsulation and compression. The JAR file format is based on the popular ZIP file format. The

JavaHelp system automatically extracts information from the JAR file when it is required.

Until support is available from GUI-base help authoring tools, the jar command (located in the JDK bin folder) must be used from a command-line prompt to create, read, and extract data from JAR files.

Sample Help Hierarchy

The following sections refer to this sample help hierarchy:

[IMAGE]

The jar

Command

The jar

command syntax is:

jar [ctxvfm] [jar-file] [manifest-file] files ...

Option flags are:

c create new archive

t list table of contents for archive

x extract named (or all) files from archive

v generate verbose output on standard error

f specify JAR file name

m include manifest information from specified

manifest file

For more detailed information about the jar command or format, please refer to http://java.sun.com/beans/jar.html

[IMAGE]

The jar

command is located in the bin

directory of the JDK.

Creating JAR Files

To create a JAR file from your help files, make the top level help folder the current folder. The jar command descends recursively through the different directories and copies all of the files to the JAR file.

Use the following steps to create a JAR file named my_help.jar

from the hierarchy example above,:

C:\> cd ...\help

(where "..." is the path above the

\help

folder)

C:...\help> jar -cvf my_help.jar *

The jar -cvf

command copies all the files in the

\help

folder and in all folders hierarchically beneath it into a JAR file named my_help.jar

. As the command creates the JAR file, it reports its progress with output like the following:

adding: my_helpset.hs (in=5757) (out=2216) (deflated 61%)

This indicates that the file my_helpset.hs

was added to the JAR file and compressed 61% (from

5272 bytes to 2150 bytes).

When you create a JAR file, the jar

command automatically creates a manifest file for you. The manifest file consists of a list of files present within the archive itself.

Listing JAR Files

Use the t

option to list the files included in a JAR file:

C:\> jar -tvf my_help.jar

5272 Fri Apr 03 14:48:04 PST 1998 META-INF/MANIFEST.MF

5757 Fri Apr 03 12:21:04 PST 1998 my_helpset.hs

1345 Wed Feb 18 14:40:16 PST 1998 my_map.jhm

1478 Wed Feb 18 14:40:16 PST 1998 my_toc.xml

4678 Thu Mar 12 07:28:54 PST 1998 my_index.xml

2345 Thu Mar 12 07:28:32 PST 1998 JavaHelpSearch/DOCS

3456 Thu Mar 19 11:26:56 PST 1998 JavaHelpSearch/DOCS.TAB

1457 Fri Mar 13 13:30:06 PST 1998 JavaHelpSearch/OFFSETS

1465 Thu Mar 19 11:26:56 PST 1998 JavaHelpSearch/POSITIONS

1234 Thu Mar 19 11:26:56 PST 1998 JavaHelpSearch/SCHEMA

3214 Thu Mar 19 11:26:56 PST 1998 JavaHelpSearch/TMAP

3113 Thu Mar 12 07:28:36 PST 1998 topics/topic1/subtopicA/topic.html

230 Thu Mar 19 11:26:56 PST 1998 topics/topic1/subtopicB/topic.html

1661 Wed Feb 18 14:40:46 PST 1998 topics/topic2/subtopicA/topic.html

3181 Wed Feb 18 14:40:46 PST 1998 topics/topic2/subtopicB/topic.html

1667 Thu Mar 19 11:26:56 PST 1998 topics/topic3/subtopicA/topic.html

9072 Thu Mar 12 07:28:36 PST 1998 topics/topic3/subtopicB/topic.html

3673 Thu Mar 19 11:26:56 PST 1998 topics/topic3/subtopicC/topic.html

551 Fri Mar 13 13:30:12 PST 1998 topics/topic3/subtopicD/topic.html

Extracting Files from JAR Files

Use the x

option to extract files from the JAR file:

C:\> jar -xvf my_help.jar

extracted: META-INF/MANIFEST.MF

extracted: my_helpset.hs

extracted: my_map.jhm

extracted: my_toc.xml

extracted: my_index.xml

extracted: JavaHelpSearch/DOCS

extracted: JavaHelpSearch/DOCS.TAB

extracted: JavaHelpSearch/OFFSETS

extracted: JavaHelpSearch/POSITIONS

extracted: JavaHelpSearch/SCHEMA

extracted: JavaHelpSearch/TMAP

extracted: topics/topic1/subtopicA/topic.html

extracted: topics/topic1/subtopicB/topic.html

extracted: topics/topic2/subtopicA/topic.html

extracted: topics/topic2/subtopicB/topic.html

extracted: topics/topic3/subtopicA/topic.html

extracted: topics/topic3/subtopicB/topic.html

extracted: topics/topic3/subtopicC/topic.html

extracted: topics/topic3/subtopicD/topic.html

Note that it is not necessary to extract files from the JAR file to use them with the JavaHelp system.

The JavaHelp system reads files directly from the JAR file as they are required.

The JAR: Protocol

The Java

2 SDK implements a protocol for referring explicitly to files within JAR files. The syntax of the jar:

protocol is:

jar:<url>!/{entry}

The jar:

protocol can be used to refer to entries within JAR files, the entire JAR file, or a directory as base URLs (JAR directory).

Examples:

An entry within a JAR file:

jar:http://www.foo.com/bar/baz.jar!/COM/foo/Quux.class

A JAR file:

jar:file://www.foo.com/bar/baz.jar!/

A JAR directory:

jar:file://www.foo.com/bar/baz.jar!/COM/foo/

[IMAGE]

"!/" is referred to as the separator.

For more information, refer to the Java

2 SDK documentation.

[IMAGE] See also:

IDs are defined (associated with a URL) in the map file.

Table of Contents File

The table of contents (TOC) file describes to the TOC navigator the content and layout of the TOC.

The format of the TOC file is based on the World Wide Web Consortium Extended Markup Language

(XML). The following is a very small example of a TOC file:

<?xml version=’1.0’ encoding=’ISO-8859-1’ ?>

<!DOCTYPE toc

PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp TOC Version 1.0//EN"

"http://java.sun.com/products/javahelp/toc_1_0.dtd">

<tocitem target="jde.intro">Introduction to JDE Online Help />

</tocitem>

</tocitem>

</toc>

This example produces the following TOC display:

[IMAGE]

The TOC Tags

The following table describes the TOC tags:

<toc> Defines the TOC. It contains <tocitem> tags.

Defines a TOC entry. Nesting entry1 within entry2 defines entry2 to be hierarchically contained within entry1. Uses the following attributes: text

Specifies the text for the entry.

target (optional) Specifies the ID to display when the entry is chosen by the user.

image

(optional) Specifies the image displayed in front of a TOC entry. The argument to this attribute is an ID defined (associated with a GIF or JPEG

image) in the map file. If this attribute is not specified, the default

folder/file images are displayed.

[IMAGE] See also:

user. IDs are defined (associated with a URL) in the map file.

Index File

The index file describes to the index navigator the content and layout of the index. The format of the index file is based on the World Wide Web Consortium Extended Markup Language (XML). The following is a very small example of a index file:

<?xml version=’1.0’ encoding=’ISO-8859-1’ ?>

<!DOCTYPE index

PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Index Version 1.0//EN"

"http://java.sun.com/products/javahelp/index_1_0.dtd">

</indexitem>

</index>

This example produces the following index display:

[IMAGE]

The Index Tags

The following table describes the index tags:

<index>

Defines the index. It can contains

tags.

Defines a index entry. Nesting entry1 within entry2 defines entry2 to be hierarchically contained within entry1. Uses the following attribute: text Specifies the text for the entry.

target

(optional) Specifies the ID to display when the entry is chosen by the

[IMAGE] See also:

JAR Files

topic URLs in the map file. The fact that hard URL addresses are not embedded in the application

Context-Sensitive Help

The JavaHelp system provides a number of features that enable you to provide context-sensitive help to your users. Context-sensitive help is information provided to users based on the context of the task in which they are involved.

Implementing context-sensitive help involves associating help topics with objects in the application’s graphical user interface (GUI) such as menu items, buttons, text boxes, and windows. Help authors generally work with developers to determine which topics are assigned to each object. The developer assigns JavaHelp IDs to the application’s GUI objects, then the help author associates those IDs with

code allows the author to change topics without requiring the developer to change the application.

For details about how context-sensitive help is implemented for an application, see Implementing

Context-Sensitive Help.

Types of Context-Sensitive Help

The JavaHelp system provides mechanisms for two types of context-sensitive help: user-initiated help and system-initiated help.

User-Initiated Help

User initiated help delivers information to users when they explicitly ask for it. The JavaHelp system includes the following user-initiated mechanisms:

Window-Level Help

Users can obtain help about container objects such as application windows and dialog boxes that have focus by pressing the F1 function key (on systems with a Help key, the Help key also works). An object is considered to have focus when it is in a state that allows the user to interact with it. By default, help information is displayed in the help viewer.

Field-Level Help

Users can use field-level help to obtain help about any GUI object. To use field-level help, the user:

1. Clicks the field-level help button [IMAGE] or chooses the Help->Field-Level Help menu item to change the cursor to the special field-level help cursor ([IMAGE] )

2. Selects a GUI object

By default, help information is displayed in the help viewer and the cursor returns to its original state.

Help Menu

The Help menu can be used to provide help to users about specific tasks or objects. The following

Help menu contains a submenu of items that provide help about completing various tasks.

[IMAGE]

Help Button

It is common for dialog boxes to contain a Help button that provides help information about how to use the dialog box. Clicking the Help button is usually equivalent to pressing the F1 key while the dialog box has focus.

System-Initiated Help

Most applications provide information automatically when the user performs a particular action. Most commonly, this information consists of status, warning, or error messages. It is also possible for the application to use the help viewer to provide more detailed help based on user actions.

[IMAGE] See also:

search engine. The process of creating the search database is described in Creating the Full-Text

Full-Text Search

The JavaHelp system full-text search engine uses a natural language search technology that not only retrieves documents, but locates specific passages within those documents where answers to queries are likely to be found. The technology involves a conceptual indexing engine that analyzes documents to produce an index of their content and a query engine that uses this index to find relevant passages in the material.

As the help author, you create the search database that is searched by the JavaHelp system full-text

Search Database.

How Searching Works

To initiate a search the user enters a natural language query in the search navigator Find text box. The results are reported back to the user in the following display:

[IMAGE]

The circle in the first column indicates the ranking of the matches for that topic. The more

filled-in the circle is, the higher the ranking. There are five possible rankings (from highest to lowest): [IMAGE]

The number in the second column indicates the number of times the query was matched in the listed topic.

The text specifies the name of the topic (as specified in the topic’s <TITLE> tag) in which matches are found.

[IMAGE]

To avoid confusion, be sure the

<TITLE>

tag corresponds to the title used in the table of contents.

Relaxation Ranking

The search engine uses a technique called relaxation ranking to identify and score specific passages of text that are likely to answer the user’s query. The relaxation ranking algorithm compares the user’s query terms with occurrences of the same or related terms in the help topics. The search engine attempts to find passages in the help topics in which as many as possible of the query terms occur in the same form and the same order. The search engine automatically relaxes these constraints to identify passages in which:

Not all of the terms occur

The terms occur in different forms

The terms occur in a different order

The terms occur with intervening words

The search engine assigns appropriate penalties (that lower the ranking) to the passages for these deviations from the specified query.

[IMAGE]

The ranking process improves when queries are more complex and include more information.

Morphing

The JavaHelp search engine uses "morphing" technology to find words with common roots. For example, when the term "build" is included in a search string, matches that contain "built", "builder",

"building", and "builds" are returned.

[IMAGE]

In the 1.0 release, the morphing feature is only available for the Engish (en) locale.

[IMAGE] See also:

. As described in Setting Up a JavaHelp System, the search database

Creating the Full-Text Search Database

When a user initiates a full-text search, the JavaHelp system full-text search engine searches a special search database to find matches quickly. You use the jhindexer command to create the search database for your help topics.

The search database created by the jhindexer

command consists of six files located in a folder named

JavaHelpSearch

folder is usually located in the same folder as the rest of the help metadata files.

Example

The following example describes how to use the jhindexer command in its simplest form. For details about other features of the jhindexer

command, see The jhindexer

Command.

The example assumes that your help information is arranged in the following hierarchy:

[IMAGE]

[IMAGE] To create a full-text search database:

1. Make the ...\help folder the current folder

2. Specify the top-level folders as arguments to the jhindexer

command:

jhindexer topic1 topic2 topic3

[IMAGE]

Note that the jhindexer

command is located in the javahelp\bin

folder of the JavaHelp system release.

The jhindexer

command recursively descends the help hierarchy, indexing all the files it encounters. When finished, jhindexer places the search database files in a folder named

JavaHelpSearch

in the current folder:

[IMAGE]

[IMAGE] To verify the validity of a full-text search database:

1. Make the

...\help

folder the current folder

2. Specify the JavaHelpSearch

folder as the argument to the jhsearch command:

jhsearch JavaHelpSearch

[IMAGE] See also:

engine to locate matches. You can use the jhsearch command to verify the validity of the database.

Full-Text Search

The jhindexer

Command

The jhindexer

creates a full-text search database used by the JavaHelp system full-text search

To build a full-text search database use the following commands:

Win32

jhindexer [ options] [file | folder]*

Solaris/SPARC

jhindexer [ options] [file | folder]*

If the argument is a folder, the folder is searched recursively for JavaHelp system content files.

The following options are available:

-c

file

-db dir

-locale

lang_country_variant

[IMAGE]

-logfile

file

-nostopwords

-verbose

A configuration file name. See Config File below.

The name of the database output folder. By default the output folder is named

JavaHelpSearch

and is created in the current folder.

The name of the locale as described in java.util.Locale

. For example: en_US

(English, United States) or en_US_WIN

(English,

United States, Windows variant).

Captures jhindexer

messages in a specified file. You can use this option to preserve jhindexer

output on Win32 machines where the console window is dismissed after execution terminates.

Causes stopwords to be indexed in the full-text search database.

Displays verbose messages while processing.

Stopwords

You can direct the JavaHelp system full-text search indexer to exclude certain words from the database index--these words are called stopwords. By default, the indexer ignores (does not index) the following stopwords when it encounters them in your help topics: a all am an and any are as at be but by can could did do does etc for from goes got had has have he her him his how if in is it let me more much must my nor not now of off on or our own see set shall she should so some than that the them then there these this those though to too us was way we what when where which who why will would yes yet you

You can override the indexer’s default stopword behavior in two ways:

Use the

-nostopwords

option with the jhindexer

command. This forces the indexer to ignore stopwords and to index every word in your help topics.

Use the config

file to specify your own list of stopwords.

Config File

You can use the config

file to:

Change the path names of the files as they are stored in the search database. This is useful when you create the search database using paths to topic files that are different from the paths the help system will later use to find them.

Explicitly specify the names of the topic files you want indexed.

Specify your own list of stopwords.

Changing Path Names

You can remove and prepend portions of the topic file names as they are stored in the search database.

This is useful when the path to the topic files you use during development is different from the path the help system will later use to find the topic files during searches.

[IMAGE] To remove a portion of the path name from all of the indexed files:

Add the following line to the config

file:

IndexRemove path where path is the portion of the path you want removed.

For example, to change:

/public_html/JavaHelp/demo/docs/file.html

to:

docs/file.html

add the following line to the config

file:

IndexRemove /public_html/JavaHelp/demo/

[IMAGE] To prepend a different path to the indexed files:

Add the following line to the config

file:

IndexPrepend path

For example, to change:

docs/file.html

to:

my_product/install/docs/file.html

add this line to the config

file:

IndexPrepend my_product/install/

Specifying Files for Indexing

You can also explicitly specify a list of the names of the files you want indexed. In the config

file, specify the list in the following format:

File filename

[IMAGE] Be sure to use "/" as the file separator when specifying files for indexing.

Specifying Stopwords

You can specify your own list of stopwords to the indexer using the config

file. When you specify

your own list, the default stopword list is not used. You can specify a list of stopwords in two ways:

Add the list of words directly into the config

file using the following format:

StopWords word, word, word...

In the config

file, specify the name of a file that contains a list of stopwords:

StopWordsFile filename

StopWordsFile must contain a list of stopwords, one stopword per line.

[IMAGE] See also:

The jhsearch

The jhsearch

Command

The javahelp\bin\jhsearch

command is a command-line program that you can use to query the JavaHelp system full-text search database created with the jhindexer command. The jhsearch

command can be used to verify the validity of a search database without invoking the help viewer.

To use jhsearch

Win32

jhsearch database_folder

Solaris/SPARC

jhsearch database_directory

By default, the jhindexer

command creates the database files in a database folder named

JavaHelpSearch .

[IMAGE] See also:

The jhindexer

popups/secondary windows to your topics, see The JHSecondaryViewer Component. If you are using

Using Popup and Secondary Windows

The JavaHelp system supports two types of HTML-based secondary windows:

Popup Windows

Secondary Windows

Both types of secondary windows are implemented as a lightweight component class that can be added to HTML topics by means of the <

OBJECT

> tag. This topic describes the functionality and characteristics of these windows. For information about how to use the <

OBJECT

> tag to add

an authoring tool, the tool will handle these details for you.

[IMAGE]

Popups and secondary windows are not used in the JavaHelp System User’s Guide because they cannot be included in the PDF version. To see actual examples of how these windows can be used, experiment with the object demo located in:

demos\bin

You can also launch the object demo program using shortcuts (program groups, desktop icons, links) that you may have created during the installation of the JavaHelp system.

Differences Between Popups and Secondary Windows

Popups and secondary windows are functionally very similar. They are both fully capable HTML windows that can include graphics, links, and lightweight components. Most of the features described in this topic apply to both types of windows. The following lists describe their differences:

Popups:

Are always displayed directly adjacent to the object the user clicks to activate the popup.

Cannot be resized or moved by the user.

Are dismissed whenever focus is changed to another part of the help viewer.

[IMAGE]

Secondary windows:

Can be displayed anywhere on the screen.

Can be iconified, resized, and moved by the user.

Persist until they are dismissed or the help viewer is dismissed.

[IMAGE]

Working with Popups and Secondary Windows

This section describes the different aspects of popups/secondary windows that you (the help author) can control.

To see examples of popups and secondary windows, try the object demo located in:

demos\bin

The <

OBJECT

> tag used to add these windows to your help topics is described in Using the

OBJECT

> Tag.

Content

The content of popup/secondary windows is rendered by the same HTML engine used in the main help viewer. Anything that is rendered in the main help viewer can be used in popup/secondary windows--including links, graphics, and lightweight components (for example, popup/secondary windows). Topics displayed in the windows can be specified using URLs or JavaHelp system IDs.

Activation

Users activate popup/secondary windows by clicking on one of the following:

Button

(

[IMAGE]

)

Text object

Graphic object

A standard button provided as part of the popup/secondary window component. You can use the button as pictured to the left or you can specify a string of text or an image to replace the ">" character on the button.

A specified string of text inserted inline with the text of the topic. The author can control font characteristics of the text to make it stand out.

A GIF or JPG image.

Window Size

You can specify the height and width of the popup/secondary window. When content exceeds the size of the window, scroll bars are automatically added to the window.

Window Location (secondary windows only)

You can specify the position of secondary windows on the screen.

Named Windows (secondary windows only)

You can name secondary windows. This enables you to reuse an already active window.

Text

When you add text to a button, or use a text object as an activator, you can control the following font characteristics:

Font family You can set the font family to:

Serif

SansSerif

Monospaced

Dialog

DialogInput

Symbol

Additional fonts will be supported in future versions of the Java

2 Platform.

Font size You can set the size of the font to: xx-small x-small small medium large x-large xx-large bigger

(Increases the current base font size by 1) smaller

(Decreases the current base font size by 1)

nnpt

(Sets the font size to a specific point value of nn)

(Increases the current base font size by a value of n)

-n

(Decreases the current base font size by a value of n)

n

(Sets the font size to the point size associated with the index n)

Font weight You can set the weight of the font to: plain bold

Font style You can set the style of the font to: plain italic

Font color You can set the color of the font to: black blue cyan darkGray gray green lightGray magenta orange pink red white yellow

[IMAGE] See also:

The JHSecondaryViewer Component

The JavaHelp 1.0 release provides popup and secondary window support through the

JHSecondaryViewer lightweight component. Popups and secondary windows are added to help topics by means of the <

OBJECT

> tag. This topic describes how to use the <

OBJECT

> tag for this purpose.

To see how popups and secondary windows work, you can experiment with the object

demo located in:

demos\bin

You can also launch the object demo program using shortcuts (program groups, desktop icons, links) that you may have created during the installation of the JavaHelp system.

The topic files used in that demo provide examples of the < OBJECT > tag in use. These files are located in:

demos\hs\object

The following example creates a popup that is activated by clicking on the text object "Click here":

</OBJECT>

The < param > element specifies parameters to the JHSecondaryViewer component. The < param > element takes two attributes: " name

", and " value

". Parameters may be specified in any order--if parameters conflict, the one specified last is used. Valid parameter names are: viewerStyle content id viewerActivator viewerSize viewerLocation viewerName iconByName iconByID text textFontFamily textFontSize textFontWeight textFontStyle textColor

Parameter Definitions

viewerStyle

Specifies whether the window is a popup or secondary window (see Using Popup and Secondary

Windows for a list of differences). The valid values for this parameter are "

javax.help.Popup

" and " javax.help.SecondaryWindow

". If the viewerStyle

parameter is omitted the window is created as a secondary window. Example:

content

The URL of the topic displayed in the popup or secondary window. The URL must be specified relative to the base address of the containing topic. Example:

The ID of the topic displayed in the popup or secondary window. The ID must be defined in the map file for that HelpSet. Example:

viewerActivator

Specifies how the user activates the window (see Using Popup and Secondary Windows for details

about activation). Valid values are: javax.help.LinkButton

User activates the window by clicking on the standard button provided as part of the popup/secondary window

lightweight component. You can use the text

parameter to add text to the button or you can use the iconByName or iconByID

parameters to add images to the button.

javax.help.LinkLabel

[IMAGE]

User activates the window by clicking on a text object or

GIF/JPEG image. The text object is specified by means of

the text

parameter and the image is specified by means of the iconByName and iconByID parameters.

Examples:

viewerSize

The width and height (in pixels) of the window. Example:

viewerLocation (secondary windows only)

The x,y position (in pixels) of the upper left corner of the secondary window on the screen--0,0 being the upper left corner of the screen. Popups ignore this parameter. Example:

viewerName (secondary windows only)

Names a window. This makes it possible to reuse an active window. Popups ignore this parameter.

Example:

iconByName

The URL of a GIF/JPEG image. Images can be used in two ways:

The user clicks on an image to activate a window. In this case iconByName

is used in conjunction with the following parameter:

The images added to the standard button the user clicks on to activate a window. In this case iconByName

is used in conjunction with the following parameter:

Example:

iconByID

The ID of a GIF/JPEG image. The ID must be defined in the map file for that HelpSet. Images can be used in two ways:

The user clicks on an image to activate a window. In this case iconByID

is used in conjunction with the following parameter:

The images added to the standard button the user clicks on to activate a window. In this case iconByID

is used in conjunction with the following parameter:

Example:

text

The string of text that the user clicks on to activate the window. The font characteristics of this text can be controlled using these parameters:

textFontFamily textFontSize

textFontWeight textFontStyle textColor

Example:

textFontFamily

The font family of the text object. Valid values are:

Serif

SansSerif

Monospaced

Dialog

DialogInput

Symbol

Additional fonts will be supported in future versions of Java

2 SDK.

Example:

textFontSize

The size of the font in the text object. Valid values are: xx-small x-small small medium large x-large xx-large bigger

(Increases the current base font size by 1) smaller

(Decreases the current base font size by 1)

nn

(Sets the font size to a specific pt value of nn)

(Increases the current base font size by a value of n)

-n

(Decreases the current base font size by a value of n)

n

(Sets the font size to the point size associated with the index n)

Example:

textFontWeight

The weight of the font in the text object. Valid values are: plain bold

Example:

textFontStyle

The style of the font in the text object. Valid values are: plain italic

Example:

textColor

The color of the font in the text object. Valid values are: black blue cyan darkGray gray green lightGray magenta orange pink red white yellow

Example:

[IMAGE] See also:

Using Popup and Secondary Windows

Creating Lightweight Java Components

Programming with the JavaHelp System

The topics in this chapter of the JavaHelp System User’s Guide describe the aspects of the JavaHelp system of primary interest to application developers.

The JavaHelp classes are distributed in the following JAR files. The JAR files are located in the javahelp\lib

folder. jh.jar

[IMAGE]

The standard library, it includes everything needed to use the help viewer and the standard navigator types (TOC, index, full-text search).

jhbasic.jar A subset of jh.jar

that does not include support for the full-text search engine.

This may be useful for very simple help systems that do not require a full-text search database or help systems where size is important.

jhall.jar Includes all of the JavaHelp system classes, including the tools required to create a search database.

jsearch.jar The default full-text search engine used in the JavaHelp system.

Supplemental Information

You will probably find the following supplemental documentation and source code useful:

API

[IMAGE]

The javadoc generated documentation of the JavaHelp API is included with this release. You can view the API using the JavaHelp API viewer

( demos\bin\apiviewer

) or using a web browser

( doc\api\index.html

)

Specification The JavaHelp 1.0 specification is included in this release and can be found at:

Sample

Source Files

doc\spec\index.html

This release includes demo programs that demonstrate JavaHelp system

functionality. Sources for the demo programs are included in the release at:

demos\src

[IMAGE] See also:

Creating Lightweight Java Components

Adding the JavaHelp System to Applications

The process of adding the JavaHelp system to your application is summarized in the following steps:

1. Import the JavaHelp system classes:

import javax.help.*;

[IMAGE]

Be sure to add one of the JavaHelp system libraries (for example, jh.jar

) to your application’s

CLASSPATH.

2. Find the HelpSet file and create the HelpSet object:

try {

URL hsURL = HelpSet.findHelpSet(null, "../help/myHelpSet.hs");

hs = new HelpSet(null, hsURL);

} catch (Exception ee) {

System.out.println("HelpSet "+helpsetName+" not found")

return;

}

3. Create a HelpBroker object:

hb = hs.createHelpBroker();

4. Create a "Help" menu item to trigger the help viewer:

JMenu help = new JMenu("Help");

menuBar.add(help);

menu_help = new JMenuItem(helpsetLabel);

menu help.addActionListener(new CSH.DisplayHelpFromSource(mainHB));

HelpSet

The first thing your application does is read the HelpSet file specified by the application. The HelpSet file defines the HelpSet for that application. A HelpSet is the set of data that constitutes your help system. The HelpSet file includes the following information:

Map file

View information

The map file is used to associate topic IDs with the URL or path name of HTML

topic files.

HelpSet title The name of the top-level TOC folder.

Home ID The name of the (default) ID that is displayed when the help viewer is called without specifying an ID.

Sub-HelpSets This optional section can be used to statically include other HelpSets using the tag. The HelpSets indicated using this tag are merged automatically into the

HelpSet that contains the tag. More details about merging can be found in

Merging HelpSets.

For more information about the HelpSet file, see HelpSet File.

HelpBroker

The HelpBroker is an agent that negotiates and manages the display of help content for your application. The HelpBroker also provides "convenience" methods that you can use to implement

context-sensitive help. See Implementing Context-Sensitive Help for details.

You can implement a help system without using the HelpBroker. However, without the HelpBroker you have to write code to directly manage the HelpViewer and JHelp objects, navigators, and context-sensitive help functionality (F1 key on dialogs, help button activation, and on item help button/menu activation).

For a list and description of the HelpBroker methods, see the API at: doc\api\javax\help\HelpBroker.html.

[IMAGE] See also:

The JavaHelp system provides classes and methods that help you implement context-sensitive help in

Implementing Context-Sensitive Help

your applications. The following sections:

Summarize the context-sensitive help system

Describe the basic elements of the system

Describe how to implement context-sensitive help

Summary

The following table summarizes the context-sensitive help system.

CSH Type Activation Mechanism

Object for Which Help Is

Provided

Window-Level

Press F1 (or Help) key

Field-Level

Help Button

Menu Item

Click button or choose menu item

System

Initiated

1. Activate field-level help

2. Navigate with mouse or keyboard

3. Select object

Selected object

Internal, varies

Window with focus

Topic associated with button or menu item

Internal, varies

Implementation Steps

Set helpIDs for components

Capture F1 key press

Get window that has focus

Get helpID for window

Display help

Set helpIDs for components

Activate field-level help (button or menu item)

Track context- sensitive events

Get helpID for selected object

Display help

Create button or menu object

Set helpID on object

Get helpID on object

Display help

Basic Elements

This section describes the low-level elements used in implementing context-sensitive help.

[IMAGE]

If you use the "convenience" methods in the HelpBroker object to implement context-sensitive help,

these low-level elements are managed for you.

The basic steps for implementing context-sensitive help are:

1. Set and get Component help properties for GUI objects

2. Track context-sensitive events

Setting and Getting

Component

Help Properties

In order to provide context-sensitive help for GUI Components and menu items, you must associate a help ID with that Component or menu item. To make that association, you set the helpID

property and (if you use multiple HelpSets) the

HelpSet

for the Component or menu item. The JavaHelp system

CSH

class provides the following convenient methods for setting and getting the helpID

for

Components and menu items:

public static void setHelpIDString(Component comp, String helpID);

Sets the helpID for a component.

public static String getHelpIDString(Component comp);

Returns the helpID for a component

public static void setHelpSet(Component comp, HelpSet hs);

Sets the HelpSet for a component.

public static HelpSet getHelpSet(Component comp);

Returns the HelpSet of a component.

public static void setHelpIDString(MenuItem comp, String helpID);

Sets the helpID for a menu item.

public static String getHelpIDString(MenuItem comp);

Returns the helpID for a menu item.

public static void setHelpSet(MenuItem comp, HelpSet hs);

Sets the HelpSet for a menu item.

public static HelpSet getHelpSet(MenuItem comp);

Returns the HelpSet of a menu item.

Tracking Context-Sensitive Events

The context-sensitive help class provides a method you can use to easily track context-sensitive events. This method traps all non-navigational events until an object is selected. It returns the selected object.

public static Component CSH.trackCSEvents()

Implementing Context-Sensitive Help

The following sections describe how to use the JavaHelp system to implement the different forms of context-sensitive help.

The HelpBroker

The JavaHelp system defines a HelpBroker interface that provides "convenience" methods that greatly simplify the job of implementing context-sensitive help. HelpBroker methods hide much of the underlying implementation details--in exchange, using the HelpBroker limits the flexibility of your implementation. For example, if you use the DefaultHelpBroker, you must display help information in the standard help viewer.

[IMAGE]

You can implement context-sensitive help without using the HelpBroker, or use it for some tasks and not for others. For example, if your implementation requires something not provided in the

HelpBroker (for instance, you want to display context-sensitive help in a different viewer), you must use the basic classes (

CSH

JHelp

) directly. For information about those classes, use the JavaHelp system apiviewer

command.

A HelpBroker’s "convenience" methods enable:

Window-level help for a dialog box

Help buttons for dialog boxes

Buttons and menu items that activate field-level help

The following illustration shows how the HelpBroker and its context-sensitive methods ( hb.* ) are used with other JavaHelp system components:

[IMAGE]

HelpBroker Context-Sensitive Methods

A HelpBroker provides the following context-sensitive methods:

public void setHelpSet(HelpSet hs);

Sets the HelpSet for the current HelpBroker (there can be only one HelpSet per HelpBroker). If you use this method to change HelpSets, the displays in the corresponding

JHelp

component and

JHelpNavigator

are changed.

public HelpSet getHelpSet();

Gets the current HelpSet for the HelpBroker.

public void setCurrentID(Map.ID id) throws BadIDException;

Sets the current ID that is to be displayed in the help viewer. If hs

is null, the HelpBroker’s current

HelpSet is used. If hs

is different than the current HelpSet (and not contained in the current HelpSet), the setHelpSet

method is executed.

public void setCurrentURL(URL url, HelpSet hs) throws BadIDException;

Displays the specified URL in the help viewer. If hs

is null, the HelpBroker’s current HelpSet is used.

If hs

is different than the current HelpSet (and not contained in the current HelpSet), the setHelpSet

method is executed.

public void enableHelpKey(Component comp, String id, HelpSet hs);

Enables the Help key on a Component. This method works best when the component is the rootPane of a JFrame in Swing-based applications, or a java.awt.Window

(or subclass thereof) in

AWT-based applications. This method sets the default helpID and HelpSet for the Component and registers keyboard actions to trap the "Help" keypress. If the object with the current focus has a helpID, the helpID is displayed when the Help key is pressed, otherwise the default helpID is displayed.

public void enableHelp(Component comp, String id, HelpSet hs);

Enables help activation for a help component (for example, a Help button). This method:

Registers the helpID and HelpSet on comp

Sets the HelpBroker’s HelpActionListener on comp

public void enableHelp(MenuItem comp, String id, HelpSet hs)

Enables help activation for a MenuItem. This method:

Registers the helpID and HelpSet on comp

Sets the HelpBroker’s HelpActionListener on comp

public void enableHelpOnButton(Component comp, String id, HelpSet hs)

Enables help for a Component. This method sets the helpID and HelpSet for the Component and adds an actionListener. When an action is performed it displays the Component’s helpID and HelpSet in the default viewer. If the Component is not a javax.swing.AbstractButton

or a java.awt.Button

an IllegalArgumentException is thrown.

public void enableHelpOnButton(MenuItem comp, String id, HelpSet hs)

Enables help for a MenuItem. This method sets the helpID and HelpSet for the Component and adds an actionListener. When an action is performed it displays the helpID and HelpSet in the default viewer.

CSH Inner Classes

The CSH class contains three inner classes that provide support for context-sensitive help.

CSH.DisplayHelpAfterTracking

An ActionListener that displays help on a selected object after tracking context-sensitive events. Its constructor takes a HelpBroker object.

CSH.DisplayHelpFromFocus

An ActionListener that displays the help of the object that currently has focus. This method is used to enable HelpKey action listening for components other than the RootPane or window. This listener determines if the object with the current focus has a helpID, if it does the helpID is displayed. If the object does not have a helpID, the helpID on the action’s source is displayed (if one exists).

CSH.DisplayHelpFromSource

An actionListener that gets the helpID for the action source and displays the helpID in the help viewer.

Its constructor takes a HelpBroker object.

Window-Level Help

Start your window-level help implementation by setting the helpID and (if you use multiple HelpSets)

the HelpSet for each component for which you want help. If you do not set help for a given component,

CSH.getHelpID()

recursively searches through the component’s ancestors until it finds the first ancestor with a helpID, or until it reaches the last ancestor. For example:

JTextArea newText = new JTextArea();

hb.enableHelp(newText, "debug.overview", hs);

[IMAGE]

After you set the helpID/HelpSet for all components, use the HelpBroker enableHelpKey() method to enable the F1 key for the frame’s RootPane. The hb.getHelpKeyActionListener()

method enables the F1 key on

ActionListener objects other than root panes. For example:

rootpane = frame.getRootPane();

mainHelpBroker.enableHelpKey(rootpane, "top", null);

Field-Level Help

Start your field-level help implementation by setting the helpID and (if you use multiple HelpSets)

HelpSet for each component for which you want help. If you do not set help for a given component,

CSH.getHelpID()

recursively searches through the component’s ancestors until it finds the first ancestor with a helpID, or until it reaches the last ancestor.

After you set the helpID/HelpSet for all components, create a field-level help button or menu item. Set an ActionListener on the button or menu item with a HelpBroker object using getOnItemActionActionListener

. For example:

JToolBar toolbar=new JToolBar();

CSH.setHelpID(toolbar,"toolbar.main");

helpbutton= addButton(toolbar, "images/help.gif", "help");

helpbutton.addActionListener(new CSH.DisplayHelpAfterTracking(mainHelpBroker));

Help Menu/Button Help

To implement Help menu or Help button help:

1. Create a menu item or button

2. Set the helpID and (if you use multiple HelpSets) HelpSet on the object

3. Enable help on the object with the HelpBroker

The CSH class provides the CSH.DisplayHelpFromSource class to enable help on objects with types other than AbstractButton, Button, or MenuItem. For Example:

JButton helpButton = new JButton("Help");

mainHelpBroker.enableHelpButton(helpButton, "browse.strings", null);

System Initiated Help

Although system initiated help is rarely implemented using the help viewer, it is simple to do. When

help is presented internally within an application, pass a valid helpID to a HelpBroker object. For example:

try {

mainHelpBroker.setCurrentID(helpID);

} catch (Exception ee) {

System.err.println("trouble with visiting id; "+ee);

}

Sample Code

The following example shows the code required for the different types of context-sensitive help using a default HelpSet:

try {

ClassLoader cl = ApiDemo.class.getClassLoader();

URL url = HelpSet.findHelpSet(cl, helpsetName);

mainHS = new HelpSet(cl, url);

} catch (Exception ee) {

System.out.println ("Help Set "+helpsetName+" not found");

return;

} catch (ExceptionInInitializerError ex) {

System.err.println("initialization error:");

ex.getException().printStackTrace();

}

mainHB = mainHS.createHelpBroker();

// Enable window-level help on RootPane

rootpane = frame.getRootPane();

mainHB.enableHelpKey(rootpane, "top", null);

// Enable field-level help on various components

JToolBar toolbar=new JToolBar();

CSH.setHelpIDString(toolbar,"toolbar.main");

//Enable Menu/Button help on Help menu item

helpbutton= addButton(toolbar, "images/help.gif", "help");

mainHelpBroker.enableHelpButton(helpbutton, "browser.strings", null);

sourceIFrame = new JInternalFrame("Source", true, true, true, true);

CSH.setHelpIDString(sourceIFrame, "edit.editsource");

JTextArea newtext=new JTextArea();

CSH.setHelpIDString(newtext, "build.build");

newtext = new JTextArea();

CSH.setHelpIDString(newtext, "debug.overview");

newtext = new JTextArea();

CSH.setHelpIDString(newtext, "browse.strings");

// System Level help somewhere within the code

try {

mainHelpBroker.setCurrentID(helpID);

} catch (Exception ee) {

System.err.println("trouble with visiting id; "+ee);

}

[IMAGE] See also:

JavaHelp system components can be embedded directly into the application. The following pared down steps are taken from the idedemo sample program included with the JavaHelp release. A TOC navigator is added to the main application frame and the content pane is added to a tabbed display at the bottom of the main application frame. You can find the complete sources for the sample program at:

demos\src\sunw\demo\idedemo

1. Find the HelpSet file and create the HelpSet object:

try {

ClassLoader cl = ApiDemo.class.getClassLoader();

URL url = HelpSet.findHelpSet(cl, "api");

apiHS = new HelpSet(cl, url);

} catch (Exception ee) {

System.out.println ("API Help Set not found");

return;

}

2. Create the content pane:

JHelpContentViewer viewer1 = new JHelpContentViewer(apiHS);

3. Add the content pane to a container:

messages.setComponentAt(miscTabIndex, viewer1);

messages.setSelectedIndex(miscTabIndex);

4. Create a navigator (TOC):

xnav = (JHelpNavigator) apiHS.getNavigatorView("TOC").createNavigator(viewer1.getModel());

Use the same model for both the content pane and navigator components (viewer1) so changes generated by one component are reflected in the other component. Note that the TOC can be created using either the HelpSet getNavigatorView()

method or the JavaHelpNavigator getNavigatorView()

method. Both methods produce the same results, however using

HelpSet reduces the dependency on the GUI.

5. Add the navigator to the container:

content.add(xnav, "Center");

classViewerIFrame.setContentPane(content);

[IMAGE] See also:

This topic describes how you can create lightweight Java components and add them to HTML topics

Creating Lightweight Java Components

using the HTML <OBJECT> tag. The last section in this topic contains references to supplemental information about lightweight components and the HTML

tag.

[IMAGE]

References to supplemental information is included at the end of this topic.

Lightweight Components for HTML Topics

Components intended for HTML topic pages are very similar to generic lightweight components.

Components that do not require information about the View, or have setable parameters, can be used without modification.

View Information

Lightweight components that require information about the View must implement javax/javahelp/impl/ViewAwareComponent

. These components implement the method setViewData()

. The component can determine information from the View about the environment in which it is executing. For example, in the code snippet below the Document object is derived from the View:

private View myView;

static private URL base;

public void setViewData(View v) {

myView = v;

Document d = myView.getDocument();

// System.err.println("myDocument is: "+d);

base = ((HTMLDocument) d).getBase();

// System.err.println(" base is: "+base);

}

For more information about the Document interface see the Swing API:

http://java.sun.com/products/jfc/swingdoc-api-1.1/javax/swing/text/Document.html

Text formatting information can be derived from the View by querying its attribute set. Use the method getAttributes

as illustrated below:

AttributeSet as = v.getAttributes();

Format attributes can be used by the component when the AttributeSet is passed as a parameter to a

StyleConstants method. Methods exist to determine a number of attributes that include: the font family, font size, font weight, font style, underlining, background color, foreground color. For example, to determine what the default background color of an object:

Color color=StyleContants.getBackground(as)

For a full list of formatting attributes and corresponding methods see:

http://java.sun.com/products/jdk/1.2/docs/api/javax/swing/text/StyleConstants.html

Using Parameters

If your component takes parameters, you should follow these two additional steps:

1. Add accessor methods for each setable parameter

2. Create a BeanInfo class that corresponds to the lightweight component class

[IMAGE]

The component must accept parameter elements in any order.

Accessor Methods

Add accessor methods that enable the component to access the parameters through the Java reflection mechanism. In the following example, the AButton class has implemented accessor methods for the parameter "data" in the methods getData

and setData

private String data = "";

public void setData(String s) {

data = s;

}

public String getData() {

return data;

}

[IMAGE]

Even if the internal representation is not a String, both the returned value for the "getter" method and the parameter in the "setter" must be a String.

BeanInfo Class

Create a BeanInfo class that provides explicit information about the lightweight component. The only method used by the ContentViewer from the BeanInfo classes is getPropertyDescriptors . In the complete example below, JHSecondaryViewerBeanInfo defines the property data accessible through the getData()

and setData()

methods in JHSecondaryViewer:

public class JHSecondaryViewerBeanInfo extends SimpleBeanInfo {

public JHSecondaryViewerBeanInfo() {

}

public PropertyDescriptor[] getPropertyDescriptors() {

PropertyDescriptor back[] = new PropertyDescriptor[15];

try {

back[0] = new PropertyDescriptor("content", JHSecondaryViewer.class);

back[1] = new PropertyDescriptor("id", JHSecondaryViewer.class);

back[2] = new PropertyDescriptor("viewerName", JHSecondaryViewer.class);

back[3] = new PropertyDescriptor("viewerActivator", JHSecondaryViewer.class);

back[4] = new PropertyDescriptor("viewerStyle", JHSecondaryViewer.class);

back[5] = new PropertyDescriptor("viewerLocation", JHSecondaryViewer.class);

back[6] = new PropertyDescriptor("viewerSize", JHSecondaryViewer.class);

back[7] = new PropertyDescriptor("iconByName", JHSecondaryViewer.class);

back[8] = new PropertyDescriptor("iconByID", JHSecondaryViewer.class);

back[9] = new PropertyDescriptor("text", JHSecondaryViewer.class);

back[10] = new PropertyDescriptor("textFontFamily", JHSecondaryViewer.class);

back[11] = new PropertyDescriptor("textFontSize", JHSecondaryViewer.class);

back[12] = new PropertyDescriptor("textFontWeight", JHSecondaryViewer.class);

back[13] = new PropertyDescriptor("textFontStyle", JHSecondaryViewer.class);

back[14] = new PropertyDescriptor("textColor", JHSecondaryViewer.class);

return back;

} catch (Exception ex) {

return null;

}

Parameter Names

When naming parameters, be sure to avoid names reserved in the HTML 4.0 specification for use as

<OBJECT> tag attributes. For a complete list of <OBJECT> attributes see the HTML 4.0

specification:

http://w3c.org/TR/REC-html40/

Using the

<OBJECT>

Tag

You add lightweight components to JavaHelp topics by means of the

tag and its classid

attribute. The help viewer only recognizes classid

values prefixed with the " java:

" tag. All other classid tags are ignored. The following example creates an ALabel within the HTML topic:

You can use standard <OBJECT> tag attributes (see the HTML 4.0 specification for more details), but to be recognized the lightweight component must have "getter" and "setter" methods for those attributes. The "getter" and "setter" methods must operate on Strings. For example, in the following example width and height for the ALabel are set if there are getWidth

/ setWidth

and getHeight / setHeight methods in ALabel:

</OBJECT>

Parameters are passed to lightweight components using the

<param>

tag. A parameter is only recognized if the component has "getter" and "setter" methods for that parameter. The "getter" and

"setter" methods must operate on Strings. In the example below the help viewer passes a number of parameters and their values to a the JHSecondaryViewer component:

</OBJECT>

Supplemental Information

The following information is provided to supplement the information in this topic.

Lightweight Java Components

For general information about lightweight Java components see:

http://java.sun.com/products/jdk/1.2/docs/guide/awt/demos/lightweight/index.html

JavaHelp Components

As a reference, the sources to the lightweight components that implement JavaHelp system popups and secondary windows (

JHSecondaryViewer.java

and

JHSecondaryViewerBeanInfo.java

) can be found in src.jar

at:

com\sun\java\javahelp\impl

For a description of how the

tag is used to implement popups and secondary windows, see

The JHSecondaryViewer Component.

HTML 4.0 Specification

You can find a detailed description of the

tag as part of the HTML 4.0 specification:

http://w3c.org/TR/REC-html40/

[IMAGE] See also:

Using Popup and Secondary Windows

The JHSecondaryViewer Component

Localizing Help Information

This chapter contains information useful to localizers of JavaHelp systems. The following topics describe how to localize the various components of the JavaHelp system:

Describes how the presentation aspects of JavaHelp (primarily the help viewer) are localized.

Describes how to localize HelpSets.

Describes how to localize XML-based metadata files.

Describes how to localize HTML-base topic files.

Describes the interaction of fonts with the localization of help information.

Localizing the Full-Text

Search Database

Describes how to create localized full-text search databases.

Localizing Help Presentation

The JavaHelp system viewer generally inherits the locale from the application. For information about how applications are internationalized, see the internationalization section of The Java Tutorial at:

http://java.sun.com/docs/books/tutorial/i18n/index.html

The culturally dependent data (for example, messages and labels) for the presentation components is contained in the property file named javahelp.properties

in the javax.help.resources

package.

If the locale of the help viewer is different from the locale of the application, the locale of the

HelpBroker can be set using the

HelpBroker.setLocale()

method. Setting the locale of the

HelpBroker sets the locale for all subordinate components. If you do not use the HelpBroker, set the locale of the JHelp* components directly using their setLocal()

methods.

Data Input in the Viewer

There are two places in the JavaHelp system GUI where culturally dependent input is required: Index

Find and Search Query.

In both cases, platform-specific input methods are used. Once text is entered in the Index Find or

Search Query text boxes, additional locale-based processing is activated (usually by pressing the Enter key).

In the Index Find case, the input text is searched for within the index entries using locale-based comparisons. The locale used in Index Find is the locale of the Index navigator--usually the locale of the application, unless overridden using the

JHelpIndexNavigator.setLocale()

method.

In the Search Query case, the input text and the locale of the Search navigator are passed to a

HelpSearch

class. The

HelpSearch

class tokenizes the query text into words using the locale-specific tokenizer. The locale used in Search Query is the locale of the Search navigator--usually the locale of the application, unless overridden using the

HelpBroker.setLocale

JHelpSearchNavigator.setLocale

methods.

[IMAGE] See also:

The portal to all JavaHelp system help information is the HelpSet file which defines the HelpSet. The

Localizing HelpSets

HelpSet is the set of data that constitutes your help system and includes:

HelpSet file (XML)

Map file (XML)

TOC definition file (XML)

Index definition file (XML)

Topic files (HTML)

Full-text search database

All HelpSet data can be localized, often in multiple ways. The process of localizing HelpSets can be viewed as a cascading process, where each level of the cascade becomes more specific and takes precedence over the levels above it.

The following diagram shows the different levels in the JavaHelp system where the locale can be set and localization can occur, starting with the host application and moving into the HelpSet. Changes to locale are propagated down the hierarchy, with a change at each level overriding the locale set above it.

[IMAGE]

Legend:

[IMAGE] Described in Localizing Help Presentation

[IMAGE] Described in the following sections

[IMAGE] Described in Localizing XML Data

[IMAGE] Described in Localizing HTML Data

The HelpSet File

The locale of a HelpSet is usually set through the HelpSet file. The locale for the entire HelpSet can be specified through the HelpSet file, although portions of it can be be selectively overridden in the data files.

Finding the HelpSet File

When the application activates the JavaHelp system, the application uses the

HelpSet.findHelpSet

method to find the correct HelpSet file and return its location (URL). The full name of the HelpSet file is constructed based on the name of the HelpSet file specified as an argument to

HelpSet.findHelpSet

, and the locale based on either the system default locale or a locale specified as an optional argument.

The name of the locale-specific HelpSet file is constructed and then searched for in the following order

(from most to least specific):

1. name_language_country_variant .hs

2. name_language_country

.hs

3. name_language

.hs

4. name

.hs

5. name_defaultlanguage_defaultcountry_defaultvariant

.hs

6. name_defaultlanguage_defaultcountry

.hs

7. name_defaultlanguage

.hs

[IMAGE]

The defaults are derived from the system using the

Locale.getDefault

method.

Setting Locales in the HelpSet File

The HelpSet file can be used to control the locale of different aspects of the help system. The XML

language controls used to set locale are discussed in more detail in Localizing XML Data.

The xml:lang

attribute can be used within the

tag to specify the locale of the entire

HelpSet (the other elements in the HelpSet file automatically inherit the locale). For example:

The locale specified for the HelpSet in this manner overrides any locale acquired from the system or the application. For this reason, it is the most reliable means for setting the HelpSet locale.

The locale of the

<title>

element is always the same as locale of the HelpSet. Any xml:lang attributes specified for the

<title>

element are ignored.

Navigation View Locale

The xml:lang

attribute can also be used to change the locale of the navigator views specified in the

<view>

elements (for example, the TOC and index). Note, however, that this locale is overridden by any locale settings specified by xml:lang

attributes in the TOC and index XML definition files, as

described in XML Data.

The locale of the

<label>

element is always the same as the locale of the containing view. Any xml:lang

attributes specified for

<label>

elements are ignored.

Shipping Multiple Locales

JavaHelp makes it possible to simultaneously distribute multiple localized HelpSets--for example,

German, French, and English. As described above, the

HelpSet.findHelpSet

method determines the correct HelpSet file based on the system’s locale or as set by the application using

HelpBroker.setLocale()

. You can include multiple, localized HelpSet files and locate the appropriate version using this naming convention.

If you ship multiple locales, you will probably organize your help information a little differently than

is described in Setting Up a JavaHelp System. The following diagram shows one way you can

organize the help information by locale:

[IMAGE]

Note that the paths specified in the

<data>

sections of the localized HelpSet files must point to the

appropriate locations. For example:

<maps>

<mapref> location="de/Map.jhm" />

</maps>

<view>

<label>Holidays</label>

<type>javax.help.TOCView</type>

<data>de/HolidayTOC.xml</data>

</view>

Merging Localized HelpSets

JavaHelp system HelpSets can be merged. The locale of a HelpSet is maintained in a merge operation.

For instance, if the master HelpSet (locale en_US

) is merged with another Helpset (locale fr_FR

), the locale of both HelpSets is maintained.

Map Data

Map data should not be localized. If IDs ( target

attribute) are localized they will no longer match the IDs used internally in the application.

[IMAGE] See also:

HelpSet File

The XML prolog declaration

Localizing XML Data

The XML data that defines the TOC, index, and HelpSet files can be localized as specified in the XML

1.0 specification ( http://w3c.org/XML/ ). Both the character encoding and language can be set for these files.

Character Encoding

Character encoding is an unambiguous mapping of the members of a character set (letters, ideographs, digits, symbols, or control functions) to specific numeric code values. The specified encoding applies to the entire file. Character encoding can be set for XML files using the following methods (listed in order of precedence):

The HTTP protocol

[IMAGE]

Only one encoding can be specified for any file.

HTTP Protocol

If the XML file is provided by a server via the HTTP protocol, the server can specify the character set using the charset

parameter in the HTTP

Content-Type

field.

XML Prolog Declaration

Typically, the encoding attribute in the prolog to all of the XML metadata files is used to specify the encoding used for its character set. For example, the following prolog specifies the Latin-1

(ISO-8859-1) character set:

<?xml version=’1.0’ encoding=’ISO-8859-1’ standalone=’yes’ ?>

Setting the Language

The language can be set for the XML files using the following methods (listed in order of precedence):

The xml:lang

attribute, which can be set for any XML element (tag)

By inheritance from the closest parent element (tag)

The HTTP protocol

Content-Language

header

The default locale of the HelpSet

The default locale of the application

[IMAGE]

It is possible to mix languages within these files. A different language can be specified for each tag; however, only one character encoding can be specified for each file.

The xml:lang

Attribute

The language for any element (tag) in XML files can be set using the xml:lang attribute. For example:

<tocitem xml:lang="de" target="jde.intro">Homepage der JDE Online-Hilfe</tocitem> sets the language for that table of contents entry to German. Any elements (

tags) nested within that tag automatically inherit that language.

Typically, the xml:lang

attribute is set in the opening tag (for example,

), so all of the other elements in the TOC inherit the attribute. In this case the entire TOC is in German.

The syntax of the lang attribute is:

lang language-code primarycode

ISO639

IonaCode

UserCode subcode

= language-code

= primarycode (’-’ subcode)

= ISO639 | IonaCode | UserCode

= 2 alpha characters

= (i | I) ’-’ (alpha characters)

= (x | X) ’-’ (alpha characters)

= (alpha characters)

For more information about the lang

attribute, please refer to the XML recommendation at the World

Wide Web Consortium web site ( http://w3c.org/XML/

HTTP Protocol

If the XML file is provided by a server via the HTTP protocol, the server can specify the language for that file using the HTTP

Content-Language

header (for example,

Content-Language:en-US

[IMAGE] See also:

Inheritance from the closest element (tag)

Localizing HTML Data

The HTML data contained in topic files can be localized as specified in the HTML 4.0 specification

( http://w3c.org/TR/REC-html40/ ). Both the character encoding and the language can be set.

Character Encoding

Character encoding is an unambiguous mapping of the members of a character set (letters, ideographs, digits, symbols, or control functions) to specific numeric code values. Character encoding can be set for HTML files in the following ways (listed in order of precedence):

HTML charset

attribute on an external source (not recognized by the JavaHelp system)

[IMAGE]

Only one encoding can be specified for any file.

HTTP Protocol

If the HTML file is provided by a server via the HTTP protocol, the server can specify the character set using the charset

parameter in the HTTP

Content-Type

field.

<META> Declaration

The HTML

<META>

declaration can be used to specify the character encoding. Encoding is specified using the charset

parameter:

Specifying a Language

The language can be set in HTML files in the following ways (listed in order of precedence):

The lang

attribute

Content-Language

header

The default locale of the HelpSet

The default locale of the application

The HTML lang

Attribute

The lang attribute specifies the language of a specific element (tag>. It can be applied to every

HTML element except the following: <

APPLET>

<BASE>

<BR>

<FRAME>

<HR>

<PARAM>

, and

The following is an example of the lang

attribute being used with the

<P>

tag:

Any elements (tags) nested within a tag automatically inherit the parent tag’s language.

The syntax of the lang attribute is:

lang language-code primarycode

ISO639

IonaCode

UserCode subcode

= language-code

= primarycode (’-’ subcode)

= ISO639 | IonaCode | UserCode

= 2 alpha characters

= (i | I) ’-’ (alpha characters)

= (x | X) ’-’ (alpha characters)

= (alpha characters)

For more information about the lang

attribute, please refer to the HTML 4.0 specification at the

World Wide Web Consortium web site ( http://w3c.org/TR/REC-html40/

<META> Declaration

The HTML <META> declaration can be used to specify the file’s language. Language is specified using the

Content-Language

parameter:

HTTP Protocol

If the HTML file is provided by a server via the HTTP protocol, the server can specify the language for that file using the HTTP

Content-Language

header (for example,

Content-Language:en-US

[IMAGE] See also:

Localization and Fonts

The JavaHelp system displays information using the host default fonts. If a HelpSet contains information that cannot be presented using the default fonts, an alternate font glyph (usually a square) is displayed in its place.

The JavaHelp presentation font can be changed either by modifying the font.properties

file in the JRE or by setting the font in the HelpBroker or JHelp* components.

The

HelpBroker.setFont(Font f)

method sets the font for a JavaHelp presentation and propagates the font to all of the presentation components. JHelp* components can set their fonts using the setFont()

method.

For more information about Unicode font support and adding fonts to the JRE, please refer to the

Fonts section in the following documents:

(JDK 1.1)

http://java.sun.com/products/jdk/1.1/docs/guide/intl/

(Java 2 Platform)

http://java.sun.com/products/jdk/1.2/docs/guide/internat/

[IMAGE] See also:

The JavaHelp system full-text search database is constructed using the

jhindexer

command. The

jhindexer

command parses HTML topic files according to each file’s character encoding. If the document format (HTML, GIF, text) supports a language attribute, the document text is tokenized

according to the language attributes for its elements.

By default, jhindexer

assumes the default locale--use the locale

option to specify the locale directly to the jhindexer

command. The syntax for the locale option is:

jhindexer -locale language_country_variant

The argument to the option is the name of the locale as described in java.util.Locale

, for example, en_US

(English, United States) or en_US_WIN

(English, United States, Windows variant).

[IMAGE] See also:

Creating the Full-text Search Database

The jhindexer

The JavaHelp system provides a mechanism for merging HelpSets. You can use the merge

Merging HelpSets

functionality to append TOC, index, and full-text search information from one or more HelpSets to that of another HelpSet.

An example of where this functionality might be useful is in an application suite. The application suite may consist of a collection of constituent applications. As constituent applications are purchased and installed, their help information can be merged with help information from the other applications in the suite.

HelpSets can be merged statically or dynamically.

Static Merging

To merge HelpSets statically, add

tags to a master HelpSet file to specify other

HelpSets that you want to merge with the original HelpSet. The merge operation is performed whenever the containing HelpSet is instantiated.

In the following simple example, HelpSet2 is merged with HelpSet1 to produce the unified TOC display shown below:

-HelpSet1.hs-

<?xml version=’1.0’ encoding=’ISO-8859-1’ ?>

<!DOCTYPE helpset

PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 1.0//EN"

"http://java.sun.com/products/javahelp/helpset_1_0.dtd">

<title>HelpSet 1</title>

<maps>

</maps>

<view>

<label>Table Of Contents</label>

<type>javax.help.TOCView</type>

</view>

<subhelpset location="HelpSet2.hs" />

</helpset>

-HelpSet2.hs-

<?xml version=’1.0’ encoding=’ISO-8859-1’ ?>

<!DOCTYPE helpset

PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 1.0//EN"

"http://java.sun.com/products/javahelp/helpset_1_0.dtd">

<title>HelpSet 2</title>

<maps>

</maps>

<view>

<label>Table Of Contents</label>

<type>javax.help.TOCView</type>

</view>

</helpset>

[IMAGE]

The HelpSet that contains the

tag is considered to be the master HelpSet--all

HelpSets are merged with (appended to) the master HelpSet.

When HelpSets are merged, only views with the same name (

<name>

tag) as a view in the master HelpSet file are merged. Note that in the example above, both views are named "TOC".

Any views in the sub-HelpSets that do not match the views in the master HelpSet are not displayed.

Multiple

tags can be included in a HelpSet file. HelpSets are appended in the order in which they occur in the HelpSet file. If a HelpSet specified in a

tag is not found, it is ignored and no error is issued.

The

<subhelpset> location

attribute takes a URL as its argument.

Indexes are merged in the same manner as TOCs--by appending the merged indexes to the master

HelpSet.

Merged search databases are searched sequentially, however, query results are collated and presented together.

Dataless Master HelpSets

It is possible to create dataless master HelpSets that do not contain any view or map data of their own--a dataless master serves only as a container for specifying sub-HelpSets. This is accomplished by omitting the

<data>

for the views. All the notes listed above still apply.

The following example HelpSet file could serve as an dataless master for a suite of applications. The

JavaHelp system constructs a help display with whichever of the application sub-HelpSets ( app1.hs

- app2.hs

) are found installed on the user’s system:

<?xml version=’1.0’ encoding=’ISO-8859-1’ ?>

<!DOCTYPE helpset

PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 1.0//EN"

"http://java.sun.com/products/javahelp/helpset_1_0.dtd">

<title>JavaHelp System User’s Guide</title>

<view>

<label>Table Of Contents</label>

<type>javax.help.TOCView</type>

</view>

<view>

<name>Index</name>

<label>Index</label>

<type>javax.help.IndexView</type>

</view>

<view>

<name>Search</name>

<label>Search</label>

<type>javax.help.SearchView</type>

</view>

<subhelpset location="app1.hs" />

<subhelpset location="app2.hs" />

<subhelpset location="app3.hs" />

<subhelpset location="app4.hs" />

</helpset>

[IMAGE]

A master HelpSet can contain a mixture of both dataless and datafull views.

Dynamic Merging

HelpSets can also be merged programmatically using the JavaHelp API.

The basic API consists of the add(HelpSet)

method, and its corresponding remove(HelpSet) method. These methods fire

HelpSetEvent

events to the

HelpSetListeners

that have registered interest in them. The ComponentUIs for the TOC, index, and search views register for these events and react to changes.

The semantics of merging is implemented by individual

NavigatorViews

and

JHelpNavigators

. There are three basic methods: canMerge(NavigatorView) merge(NavigatorView) remove(NavigatorView)

The canMerge(NavigatorView)

method is present in both

NavigatorView

and

JHelpNavigator

, the

JHelpNavigator

method just calls into its corresponding

NavigatorView

method. The other two methods are present only in

JHelpNavigator

For more information about these classes and methods, refer to the JavaHelp API documentation. API information can be viewed using a web browser ( doc/api/overview-summary.html

) or by using the demos\bin\apiviewer

command.

A demonstration program ( demos\bin\merge

) is included with the JavaHelp system release. This program demonstrates how HelpSets can be merged and removed dynamically. The sources for that program are available in demos\src\sunw\demo\merge

JavaHelp System User’s Guide

JavaHelp

System User’s Guide

JavaHelp 1.1.3 - June 2002

Release Information

The JavaHelp 1.1.3 Release

Contents of the Release

Contents of the Release

Requirements

Requirements

JDK

Java 2 SDK Features

Tested Java Platforms

Changes Since the 1.1.2 Release

Changes Since the 1.1.2 Release

Demonstration Programs

Demonstration Programs

JavaHelp System User’s Guide

History of the Holidays

IDE Demo

Localized HelpSets

JavaHelp Libraries and Tools

The JavaHelp Libraries and Tools

Libraries

Tools

Limitations and Bugs

Limitations and Bugs

HTML Viewer

Full-text Search

Context Sensitive Help

Limitations on Running in Web Browsers

Other Bugs

List of Files in the JavaHelp 1.1.3 Release

List of Files in the JavaHelp 1.1.3 Release

Keeping in Touch

Keeping in Touch

The JavaHelp System

JavaHelp System Overview

Introduction

Introduction

JavaHelp System Features

JavaHelp System Features

Compression and Encapsulation

Embeddable Help Windows

Merging

JavaBeans Support

Scenarios

Descriptive Scenarios

Invocation Mechanisms

Invocation Mechanisms

Menus and Buttons

Tooltips

Browser-Based Applications (Applets)

Presentation and Deployment

Standalone Application

JavaHelp System Lightweight Components

JavaHelp System Lightweight Components

Authoring Help Information

Authoring Help Information

Viewing HelpSets <LINK REL="stylesheet" TYPE="text/css" HREF="../jhug.css"

TITLE="Style">

Viewing HelpSets

Java

2 Platform

Displaying a HelpSet with an Executable JAR File

Setting Up a JavaHelp System

Setting Up a JavaHelp System

Authoring

Links

File Separators ("/" vs. "\")

The Map File

JAR Files

Table of Contents File

The TOC Tags

Index File

The Index Tags

Context-Sensitive Help

Types of Context-Sensitive Help

System-Initiated Help

Sample Help Hierarchy

Extracting Files from JAR Files

Morphing

Creating the Full-Text Search Database

Specifying Files for Indexing

Example

The jhindexer Command

iii

Specifying Stopwords

The jhsearch Command

The jhsearch

Using Popup and Secondary Windows

Using Popup and Secondary Windows

The JHSecondaryViewer Component

Parameter Definitions

Differences Between Popups and Secondary Windows

Working with Popups and Secondary Windows

The JHSecondaryViewer Component

Programming with the JavaHelp System

Adding the JavaHelp System to Applications

Supplemental Information

HelpSet

Summary

HelpBroker

Implementing Context-Sensitive Help

Tracking Context-Sensitive Events

HelpBroker Context-Sensitive Methods

The HelpBroker

CSH Inner Classes

Window-Level Help

Field-Level Help

Help Menu/Button Help

System Initiated Help

Sample Code

Using Parameters

Accessor Methods

Embedding JavaHelp Components

Creating Lightweight Java Components

Creating Lightweight Java Components

Lightweight Components for HTML Topics

Supplemental Information

Localizing Help Information

Localizing Help Presentation

Data Input in the Viewer

Localizing HelpSets

Setting Locales in the HelpSet File

Finding the HelpSet File

Navigation View Locale

Shipping Multiple Locales

Merging Localized HelpSets

Map Data

Localizing XML Data

Character Encoding

HTTP Protocol

XML Prolog Declaration

Localizing HTML Data

Specifying a Language

Localization and Fonts

Localizing the Full-Text Search Database