creating help files in java.pdf

7/29/2019 Creating Help Files in Java.pdf

1/21

All rights reserved. Reproduction and/or distribution in whole or inpart in electronic, paper or other forms without written permission

is prohibited.

Java ReferencePoint SuiteSkillSoft Corporation. (c) 2002. Copying Prohibited.

Reprinted for Balaji Nallathambi, [email protected]

Reprinted with permission as a subscription benefit of Books24x7,http://www.books24x7.com/
http://www.books24x7.com/http://www.books24x7.com/


2/21

Table of ContentsPoint 1: Creating Help Files in Java................................................................................................1

JavaHelp: An Overview....................................................................................................................2Features of JavaHelp..............................................................................................................2JavaHelp Libraries.................................................................................................... ..............3Hierarchy of the Help Files......................................................................................................4

Deploying JavaHelp System............................................................................................................6Deploying JavaHelp System for Desktop and Network Applications......................................6Deploying JavaHelp System by Embedding in Applications...................................................7Deploying JavaHelp System Using Component and Help Server..........................................7FullText Search.....................................................................................................................8

The JavaHelp System.....................................................................................................................10Methods of the HelpSet Class..............................................................................................10Creating Help Files Using the HelpSet Class.......................................................................11

Context Sensitive Help...................................................................................................................16Types of ContextSensitive Help..........................................................................................16

The CSH Class.....................................................................................................................16HelpBroker Interface.............................................................................................................17

Using JAR Files..............................................................................................................................18Creating JAR Files................................................................................................................18

Related Topics................................................................................................................................19

i


3/21

Point 1: Creating Help Files in JavaSmita JaikumarThe javax.help package enables you to create online documentation for applications, applets, andJavaBean components. This package includes classes, such as HelpSet and HelpBroker, you useto develop and deploy online help.

This ReferencePoint explains how to use the JavaHelp API to add help to Java applications. It alsodescribes the three classes, HelpSet, HelpBroker, and Context Sensitive Help (CSH) of thejavax.help package.

Reprinted for v697039, Verizon SkillSoft, SkillSoft Corporation (c) 2002, Copying Prohibited
http://www.books24x7.com//viewer.asp?bookid=4128&chunkid=610502986?bkid=4128&destid=8343#8343


4/21

JavaHelp: An OverviewJavaHelp version 1.1.3 is an optional package of the Java Development Toolkit (JDK) version 1.1and the Java Software Developers Kit (SDK) version 2, Standard Edition. You can download theJavaHelp API from http://java.sun.com.

It is compatible with both versions of JDK.

To use the JavaHelp version 1.1.3, you need the Swing package version 1.1 or later. You can useSwing components to implement the DefaultHelpBroker class. This class helps obtain a visualrepresentation of the HelpSet file. JavaHelp version 1.1 includes demonstration programs,examples, and source code. Demonstration files are located in the demos\bin directory.

Features of JavaHelp

The JavaHelp system includes:

Integrated Development Environment (IDE) Demo: A simulation of the IDE and includes acomplete help on the system.

API Viewer: A help viewer that displays API documentation for the JavaHelp system.

Merge Demo: An application that demonstrates how to merge the HelpSet information.

Browser Demo: A simulation of the JavaHelp viewer that is executed in a Web browser.

Components of the JavaHelp system are help viewer, table of contents, index, full text search,context sensitive help, merging, and JavaBeans support. Figure 211 shows the help viewerwindow:

http://java.sun.com/http://java.sun.com/


5/21

Figure 211: The Java Development Environment Help WindowThe help viewer window consists of:

Left pane, the navigation pane: Displays all available help topics. It also displays the table ofcontents for a specific topic. The topic that is selected is highlighted.

Right pane, the content pane: Displays the information pertaining to the topic that is selectedin the navigation pane. There is a topic ID and a corresponding Uniform Resource Locater(URL) associated with each help file.

The Java Archive (JAR) format helps encapsulate information into a single file that is compressed.JavaHelp system reads the data from the archive and nonarchive format. The JavaHelp systemsupports contextsensitive help that is activated when you execute applications. You can use thehelp system to merge information from various sources and present the information as a single fileto end users.

An end user can invoke the help system using help buttons or the help menu and contextsensitivehelp:

Help buttons or Help menu: You can select an option from the Help menu in a GUIapplication. The JavaHelp system links the topic ID with the specific URL, which containshelp text, and displays the help information in the content pane. The IDs are mapped to theURL using a metadata file, called the map file. The file contains topic IDs and their links tothe specific URL. For example, to display the help information to save the file, you need tomap the ID, save_hlp to a file called, SaveAs.html in the map file. The syntax to map a topicID to the specific URL is:

Context Sensitive Help: You can invoke the corresponding contextsensitive help to explaingraphical components, such as buttons or icons.

JavaHelp Libraries

Libraries of the JavaHelp system are stored in the javahelp\lib folder. Table 211 lists the librariesstored in the javahelp\lib folder:

Table 211: JavaHelp Libraries

Library Description

jh.jar Contains all classes and interfaces required for the help viewer, the table of contents,and the index.

jhbasic.jar Is a part of jh.jar and is used for simple help systems where you do not need a fulltextsearch database.

jhtools.jar Contains classes required to create a fulltext search database.

jhall.jar Contains classes of the JavaHelp system and tools to create a search database.

jsearch.jar Contains the default fulltext search engine for the JavaHelp system.

The jhindexer tool creates fulltext search database used by the JavaHelp system and the jhsearchtool queries the fulltext search database created by the jhindexer tool.

Java ReferencePoint Suite 3



6/21

Hierarchy of the Help Files

The help files that are created, are compressed into a Java Archive (JAR) file for deployment of thehelp package.

Figure 212 shows help topics in a hierarchical manner:

Figure 212: Hierarchy of Help TopicsAll files in the JavaHelp system are directed to their respective destination using URLs. Forexample, Topic is a relative link, where thepath of the file is specified.

Relative links are useful when you need to compress and package help files into JAR files andinstall help files on the computer of an end user.

Files required for HelpSet are:

The HelpSet file with .hs extension

The Map file with extension .jhm

The Toc file with extension .xml

Html files with help data and with extension .html




7/21

In addition to help files pertaining to a topic, the help information also includes metadata. There aretwo types of metadata in the JavaHelp system, the navigational and HelpSet data. Navigationalmetadata files contain information used by the JavaHelp system navigators, such as table ofcontents, index, and fulltext search.

To display help information in the help viewer using the JavaHelp system, the HelpSet data is

required. There are two important files in the HelpSet data HelpSet and Map.

When you request for the information, the HelpSet file is invoked and the map file is read. TheHelpSet file contains the path of the map file. The Map files contain the Topic ID that links to therespective URL.

Figure 213 shows the hierarchy of HelpSet files:

Figure 213: Hierarchy of HelpSet Files




8/21

Deploying JavaHelp SystemYou can set up the JavaHelp system in various applications and across networks. It is possible todeploy help files in a desktop application or a network application. It can also be deployed inapplications that:

Embed help files

Uses the help component

Use help server to display help information

Deploying JavaHelp System for Desktop and Network Applications

A desktop application runs on a standalone computer and does not depend on a Web browser. Inthis case, the Java application and the help data reside on the same system, as shown in Figure214:

Figure 214: Deploying Help in a StandAlone EnvironmentWhen deploying help in standalone environment, an application requests for help on a specific

topic. In response, an instance of JavaHelp is created and the help files are loaded. The help viewerdisplays the requested information.

In a network application, help files and the application reside on different systems, as shown inFigure 215:



9/21

Figure 215: Deploying Help in a Network EnvironmentWhen an application requests for help files, an instance of JavaHelp is created, data is accessedfrom the network, and help files are displayed.

Deploying JavaHelp System by Embedding in Applications

You can implement the embedded help system directly in the application using JFC components.

This help can be viewed in the same window as the application, as shown in Figure 216:

Figure 216: Deploying Embedded HelpDeploying JavaHelp System Using Component and Help Server

You use the component help system in an application that is made up of various interactingcomponents. For example, this help system could be used in applications that contain two or moreJavaBeans components. In component help, individual help files of components are combinedtogether in a single help file, as shown in Figure 217:




10/21

Figure 217: Deploying Component HelpThe Help server enables you to display help information using the JavaHelp system for applications

written in various languages, such as C, C++, or Visual Basic. Each application will have associatedhelp files. These applications make requests to the help server through remote procedure callmechanisms. The help server is also used when you want to display help for a whole suite ofapplications instead of individual help files. Figure 218 shows the deployment of the help server:

Figure 218: Deploying Help Using the Help ServerFullText Search

When you enter the text on which you need help, the search engine scans the entire database anddisplays appropriate search results. The JavaHelp system provides a fulltext search facility thatyou can use in a standalone, client, or server environment.

This search feature works best in a standalone environment because all the components in thehelp system, such as help topics, the search engine and the search database, are available locally.

Implementing a clientside fulltext search is different from implementing a standalone fulltextsearch because in a clientside search, you need to download the help components from theserver. In the clientside search environment, when you initiate a search, the search data isdownloaded from the server and stored in the memory of the browser. A search for the requestedinformation is made, and the search results are displayed in the help viewer.




11/21

Note In a clientside search, when a request is made for the first time, it takes some time todisplay search results, but subsequent requests are processed faster because they arestored in the memory of the browser.

In a serverside search, help components are stored on the server. When you request help, thedatabase is scanned and the search results are displayed on the client side computer.




12/21

The JavaHelp SystemWhen creating help files for applications, you should plan the hierarchy for the help files. In theJavaHelp system, the help viewer displays one help file at a time. Group related topics under asingle category, so that they can be easily linked. The JavaHelp System uses the HelpSet class tocreate help files.

Methods of the HelpSet ClassThe javax.help.HelpSet class is a collection of help information and contains the HelpSet file, tableof contents, topic files, and the map file. This class extends java.lang.Object. Table 212 lists themethods of the HelpSet class:

Table 212: Methods of the HelpSet Class

Method Description

add(HelpSet hs) Adds an object of the HelpSet class.

AddHelpSetListener Adds a listener for the HelpSetEvent class.

Contains Indicates whether or not this HelpSet is subHelpSet of the object.

CreateHelpBroker Creates a visual representation for the object of the specific HelpSetclass.

FindHelpSet Locates a HelpSet file and returns the URL.

GetCombinedMap Specifies the map for the HelpSet file.

GetHelpSets Lists all HelpSet files added to the specific HelpSet file.

GetHelpSetURL Retrieves the base URL for the specific HelpSet file.

GetHomeID Returns the ID when the end user presses the Home button.

GetKeyData Returns the data that corresponds to the key.

GetTitle Returns the title of the specific HelpSet file.

Parse Parses a HelpSet file.

Remove Removes a HelpSet file from the HelpSet file.

RemoveHelpSetListener Removes the listener for the specific HelpSet file.SetLocalMap Specifies the map for the specific HelpSet file.

SetTitle Specifies the title for the specific HelpSet file.

ToString Prints the name of the specific HelpSet file.

Table 213 lists the tags used to create a HelpSet file:

Table 213: Tags Used to Create a HelpSet File

Tag Description

Specifies the HelpSet file.

Specifies the title for the help window.

Includes two tags, homeID and mapref. The homeID tag specifies the name of the IDthat is displayed. The mapref tag specifies the map file with the location and the URL.

Specifies navigators used in the HelpSet file. This tag also contains:

: Specifies the name of the view.

: Specifies a label for the view as it appears in the navigation pane.

: Specifies the path to the navigator class.



13/21

: Specifies the path that must be used by the navigator.

Table 214 lists the tags of a Map file:

Table 214: Tags for a Map File

Tag Description

Defines a map. This tag contains the tag .

Determines a map entry that specifies the mapID and the associated URL.

Creating Help Files Using the HelpSet Class

JavaHelp System uses the methods of the HelpSet class to create help files that display helpinformation. Listing 211 shows the code to create a JFrame component that contains login andpassword text boxes. It also contains Login, Help, and Cancel buttons.

Listing 211: Creating a JFrame Component to Login

import java.io.*;import java.net.*;import javax.swing.*;import java.awt.event.*;import java.awt.*;import java.util.*;import javax.swing.Timer;import javax.help.*;public class Login extends JFrame implements ActionListener{JLabel lblUserName;JLabel lblUserPwd;JTextField txtUsrName;

JPasswordField txtUsrPwd;JButton btnLogin;JButton btnCancel;JButton btnHelp;String UsrName;char[] UsrPwd;String strPwd;Socket toServer;

ObjectInputStream streamFromServer;PrintStream streamToServer;

public Login(){this.setTitle("Login");//Creating a layoutJPanel panel=new JPanel();

panel.setLayout(new GridBagLayout());GridBagConstraints gbCons=new GridBagConstraints();gbCons.gridx=0;gbCons.gridy=0;gbCons.gridwidth=1;gbCons.gridheight=1;gbCons.weightx=1.0;gbCons.weighty=1.0;lblUserName=new JLabel("User Name ");panel.add(lblUserName, gbCons);gbCons.gridx=1;gbCons.gridy=0;gbCons.gridwidth=1;gbCons.gridheight=1;gbCons.weightx=1.0;gbCons.weighty=1.0;txtUsrName=new JTextField(20);panel.add(txtUsrName, gbCons);




14/21

gbCons.gridx=0;gbCons.gridy=1;gbCons.gridwidth=1;gbCons.gridheight=1;gbCons.weightx=1.0;gbCons.weighty=1.0;lblUserPwd=new JLabel("Password ");panel.add(lblUserPwd, gbCons);gbCons.gridx=1;gbCons.gridy=1;

gbCons.gridwidth=1;gbCons.gridheight=1;gbCons.weightx=1.0;gbCons.weighty=1.0;txtUsrPwd=new JPasswordField(20);panel.add(txtUsrPwd, gbCons);JPanel btnPanel=new JPanel();

//Adding buttons to the PanelbtnLogin=new JButton("Login");

btnPanel.add(btnLogin);btnLogin.addActionListener(this);btnHelp=new JButton("Help");

btnPanel.add(btnHelp);btnHelp.addActionListener(this);btnCancel=new JButton("Cancel");

btnPanel.add(btnCancel);

btnCancel.addActionListener(this);try

{URL url = new URL("file:/d:/help/help.hs");// replace this with the actual location of your help set

HelpSet help = new HelpSet(null, url);HelpBroker helpb = help.createHelpBroker();

btnHelp.addActionListener(new CSH.DisplayHelpFromSource(helpb));}

catch (Exception e){

System.out.println(e);}

gbCons.gridx=1;gbCons.gridy=3;gbCons.gridwidth=1;

gbCons.gridheight=1;gbCons.weightx=1.0;gbCons.weighty=1.0;gbCons.anchor=GridBagConstraints.EAST;panel.add(btnPanel, gbCons);getContentPane().add(panel);setDefaultCloseOperation(EXIT_ON_CLOSE);setVisible(true);setSize(450,200);

}void showdlg(){

JOptionPane.showMessageDialog(this,"Invalid Password or Login name", "Message", JOp}public void actionPerformed(ActionEvent e1){JButton button=(JButton)e1.getSource();

if(button.equals(btnCancel)){this.dispose();}}public static void main(String args[]){

new Login();}

}

The above code creates a JFrame component that shows the login screen. Figure 219 shows theoutput of the above listing:




15/21

Figure 219: The JFrame Component to LoginWhen you click the Help button, help is initiated and the HelpSet file is called. Listing 212 showsthe code for the HelpSet file:

Listing 212: The HelpSet File

Helpitem1TOCTable Of Contentsjavax.help.TOCViewhelpTOC.xml

Listing 212 shows the code for the HelpSet file. Save this file with the .hs extension. This file isthe primary file that contains mappings to the respective URL. Figure 2110 shows the output ofthe above listing:




16/21

Figure 2110: The Help WindowFor the entire view of help files, you need the xml file, map file, and html files. Listing 213 showsthe code for the xml file:

Listing 213: Contents of the xml File

Listing 213 shows the code for the xml file that contains the links to specific Html files. Save thisfile with .xml extension.

Listing 214 shows the code for the map file:

Listing 214: Contents of the Map File


17/21

In Listing 214, the mapID tag is used to link the topic ID to the URL.

Listing 215 shows the code for the html file, help1.htm and help2.htm:

Listing 215: The HTML File

Help

This is the first Help Page

The above listing shows the code for the first help page. Save it as help1.htm.

Listing 216 shows the code for the second help page:

Listing 216: HTML File

Help

This is the second Help page.

The above listing shows the code for the second HTML help file. Save it as help2.htm. Create twomore files, help3.html and help4.htm. You can create as many files as you need. You need tospecify the files in the map file and in the HelpSet file.




18/21

Context Sensitive HelpJavaHelp system provides contextsensitive help for GUI interface components, such as menuoptions, buttons, and text boxes.

To implement contextsensitive help, you need to associate the JavaHelp ID to the specific GUIobject. These IDs are then linked to the respective URLs in the map file.

Types of ContextSensitive Help

There are two types of contextsensitive help in the JavaHelp system userinitiated andsysteminitiated help. You can invoke userinitiated help by an explicit action, such as clicking thehelp button or using a help menu option.

In systeminitiated help, system messages or status warnings are displayed when the end userperforms an action.

Userinitiated help can be:

Windowlevel help: Initiated when you need help on the application window or on the dialogbox in focus. Press the F1 key to initiate windowlevel help. You can also use the Help keyon the keyboard if one exists. The help viewer displays the help information, by default.

Fieldlevel help: Initiated when you want to find help on a GUI object. Click the button withthe question mark symbol (?) on the standard toolbar to obtain the information about a GUIobject. The help information about the required object is displayed in the help viewer.

Initiated by a help menu: Initiated explicitly using the help menu when an option from thehelp menu is selected.

Initiated by a help button: Initiated when the end user clicks the Help button on a dialog box.

Invoking help using a help button is similar to using the F1 key when the dialog box is infocus.

The CSH Class

The ContextSensitive Help (CSH) class provides access to contextsensitive help. This classcreates a default JavaHelp viewer and ActionListeners for help keys and help buttons.

Table 215 lists the methods defined by the CSH class:

Table 215: Methods of the CSH Class

Method Description

setHelpIDString Specifies the help ID for a component.

getHelpIDString Returns the help ID for a component.

GetHelpSet Returns HelpSet of a component.

SetHelpSet Specifies HelpSet for a component.

TrackCSEvents Tracks events for context sensitive help.



19/21

HelpBroker Interface

The JavaHelp system uses the HelpBroker interface, which provides methods to implementcontextsensitive help. The HelpBroker interface hides the implementation information. Thisinterface is used by default for presenting the HelpSet files.

Table 216 lists methods of the HelpBroker interface:

Table 216: Methods of the HelpBroker Interface

Method Description

enableHelp Enables help for a component.

enableHelpKey Enables help for a menu item.

enableHelpOnButton Enables help for a component. It specifies the Help ID and HelpSet. Thismethod also adds ActionListener.

getCurrentID Returns the currently displayed ID.

getCurrentURL Returns the currently displayed ID for the URL that is shown.

getCurrentView Returns the name of the current navigational view.

getFont Returns the font for HelpBroker.setFont Specifies the font for HelpBroker.

getLocation Determines the position for the visual representation of help files.

isDisplayed Determines whether or not the presentation is visible.

isViewDisplayed Determines whether or not the navigational view is visible.

setSize Defines the size of the presentation.

setViewDisplayed Hides or shows the navigational view.

You can use HelpBroker with other components of the JavaHelp system, as shown in Figure2111:

Figure 2111: Using HelpBroker for Various Components




20/21

Using JAR FilesAfter creating help files, you need to compress and encapsulate them into a single file using the jarcommand. This command must be executed from the command line.

Creating JAR Files

The command to create a jar file is:

jar [options] [jarfile] [manifestfile]

Table 217 lists the options of the jar command:

Table 217: Options of the jar Command

Option Description

C Creates a new archive file.

T Specifies that the table of content must be listed.

X Specifies the files that need to be extracted from the JAR archive.

V Specifies that the output generated must be verbose. If this option is specified,each file that is added to the JAR is listed.

F Specifies the JAR file name.

M Includes the manifest information from the specified manifest file.Note A manifest file is a file that contains information about the files

included in a JAR file.

0 (zero) Specifies that the JAR files must not be compressed.

C Specifies that files must be archived in a different directory at the time ofexecution.

You can create a JAR file for the hierarchy of help files where Help is the main folder that containsthe helpset.hs, the helpset file, map.jhm, the map file, toc.xml, the table of contents file, and theindex.xml that contains the help topic index. In the Help folder, you have Topic1, Topic2, and Topic3 folders that contain subtopicA, subtopicB, and subtopicC subfolders. These folders includehtml files, which contain the actual help information.

To create a jar file:

Select the Help directory in the command prompt.1.

Execute the command:

jar cvf Help.jar

2.

When you execute the above command, it copies all the files in respective folders in a hierarchicalformat. A manifest file is automatically created when you create a JAR file.

To extract the JAR file, execute:

jar xvf Help.jar

You need not extract files from the JAR file to use with the JavaHelp system because the JavaHelpsystem can read files directly from the JAR files.



21/21

Related TopicsFor related information on this topic, you can refer to:

Using Collections in Java

Optimizing Java Code in Applications

Using Databases in Java

Creating GUI with Swing
http://www.books24x7.com//viewer.asp?bookid=4128&chunkid=610502986?bkid=4128&destid=1050#1050http://www.books24x7.com//viewer.asp?bookid=4128&chunkid=610502986?bkid=4128&destid=1228#1228http://www.books24x7.com//viewer.asp?bookid=4128&chunkid=610502986?bkid=4128&destid=1147#1147http://www.books24x7.com//viewer.asp?bookid=4128&chunkid=610502986?bkid=4128&destid=2183#2183http://www.books24x7.com//viewer.asp?bookid=4128&chunkid=610502986?bkid=4128&destid=1050#1050

creating help files in java.pdf

Documents