Easy to Learn Java: Programming Articles, Examples and Tips

Start with Java in a few days with Java Lessons or Lectures

Home

Code Examples

Java Tools

More Java Tools!

Java Forum

All Java Tips

Books

Submit News
Search the site here...
Search...
 

Swing Chapter 25. (Special topics) JavaHelp. Easy for reading, Click here!

Custom Search
Swing Chapter 25. (Special topics) JavaHelp. Easy for reading, Click here!

[ Return to Swing (Book) ]

Page: 1/6 



Next Page (2/6) Next Page

Chapter 25. JavaHelp

Subpages: 1. JavaHelp introduction
2. JavaHelp API overview
3. Basic JavaHelp example
4. Adding dialog-style help
5. Customizing the JHelp viewer
5. Creating a custom help view

In this chapter:

  •          JavaHelp introduction
  •          JavaHelp API overview
  •          Basic JavaHelp example
  •          Adding dialog-style help
  •          Customizing the JHelp viewer
  •          Creating a custom help view

25.1  JavaHelp introduction

Most software developers do not look forward to spending time documenting and explaining their product. However, the commercial success of any modern software project greatly depends on the quality and availability of the help information provided to end users. As Java apps evolve into more extensive and sophisticated solutions, they require a robust, uniform, and effective mechanism for providing help to these users. For this reason JavaSoft has developed the JavaHelp API: a full-featured, platform-independent, extensible help system that gives developers and authors the ability to efficiently incorporate an online help system into applications (both network and stand-alone), applets, JavaBean components, HTML pages, operating systems, and devices. The 1.0 release of this API is available for download from the JavaSoft web site (see http://java.sun.com/products/javahelp/).

Note: You will need to download and install the JavaHelp API before running the examples in this chapter.

JavaHelp includes a standard Swing-based help viewer illustrated in figure 25.1 below. This viewer contains a toolbar in its northern region and a split pane in the center. The toolbar contains two buttons allowing navigation between help topics that have been visited previously in a forward/backward style. The left split pane component is a tabbed pane containing a table of contents, help index, and search navigation facilities. The right split pane component is an editor pane used to display the content of the currently selected help topic. Help content is expected to be in the form of HTML documents, enabling rich display capabilities and greatly simplifying the delivery of help files across the Internet.

Note: JavaHelp also provides a way to deliver multi-lingual help depending on the currently selected locale. This capability, along with the more comprehensive internationalization support provided by Java 2, is very powerful, currently under major development, and lie beyond the scope if this text.

To use JavaHelp in an application we need to prepare a set of files described below. With the exception of content files and search files, each file is expected to be in the XML format. (In describing each XML-based file below, we present a simple example implementation which we will use in the section 25.3 application.)

Reference: For more information about XML see http://www.w3.org/TR/WD-xml-lang-970331.html. It is likely that in the near future, we will have graphical tools available to facilitate quick and easy construction of these system files. However, at this point we are forced to delve into some of the details of XML coding to accomplish this.

25.1.1  HelpSet file

This system file uses the XML format to deliver information about other help components and files. XML tags used in this file have the following meaning:

<helpset>: top level of a HelpSet document. The <version> and <lang> attributes can specify file version and language respectively.

<title>: title to be displayed in the help viewer's title bar.

<maps>: defines a section representing a HelpSet map (discussed below).

  <homeID>: ID of the default help topic, which should be listed in the map file.

  <mapref>: specifies a map file or URL with its <location> attribute.

<view>: defines a section representing a help view contained in the help viewer tabbed pane. A HelpSet file may contain an arbitrary number of views.

    <name>: a name identifying the view.

  <label>: used for displaying the tooltip text of the view's corresponding tabbed pane tab (more descriptive than a name).

  <type>: the view type (fully qualified name of the class to be instantiated to create this view component). Normally a subclass of NavigatorView (see below).

  <data>: specifies a data file or URL used in this view. The optional <engine> attribute can be used to define the fully qualified name of the class defining a search engine.

The following is a typical example of a HelpSet file, Layout.hs:

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

<helpset version="1.0">

  <title>Basic Layout Example - Help</title>

  <maps>

     <homeID>top</homeID>

     <mapref location="Layout.jhm"/>

  </maps>

  <view>

    <name>TOC</name>

    <label>Table Of Contents</label>

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

    <data>LayoutTOC.xml</data>

  </view>

  <view>

    <name>Index</name>

    <label>Help Index</label>

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

    <data>LayoutIndex.xml</data>

  </view>

  <view>

    <name>Search</name>

    <label>Search</label>

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

    <data>JavaHelpSearch</data>

  </view>

</helpset>

25.1.2  Map file

This system file uses the XML format to provide a mapping of help topic IDs (text strings) to URLs (which can be either local or remote and of the form file:, http:, ftp:, or jar:). Multiple map files can be used in a HelpSet. In such a case the mappings will be merged and we are expected to always provide unique IDs because of this. XML tags used in this file have the following meaning:

<map>: top level of the map document. The <version> and <lang> attributes can specify file version and language respectively.

<mapID>: represents a single map entry. The <target> attribute specifies the string ID of the help topic and the <url> attribute specifies the associated URL of the HTML content file constituting its documentation. The optional <lang> attribute allows specification of a language to use when displaying this topic.

The following is a typical example of a map file, Layout.jhm:

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

<map version="1.0">

    <mapID target="top" url="LayoutFrame.html" />

    <mapID target="FlowLayout" url="FlowLayout.html" />

    <mapID target="GridLayout" url="GridLayout.html" />

    <mapID target="BorderLayout" url="BorderLayout.html" />

    <mapID target="BoxLayout" url="BoxLayout.html" />

</map>

25.1.3  Table of Contents (TOC) file

This system file uses the XML format to deliver information about a help topics table of contents. This represents a view that typically contains references to help topic IDs in a logically grouped order. XML tags used in this file have the following meaning:

<toc>: top level of TOC document. The <version> and <lang> attributes can specify file version and language respectively.

<tocitem>: defines a TOC entry. The <target> attribute specifies the string ID of the target help item listed in a map file. The <text> attribute specifies the TOC view text to represent the corresponding help topic.

The following is an example of a TOC file, LayoutTOC.xml:

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

<toc version="1.0">

    <tocitem>Basic Layout Example - TOC

        <tocitem text="Frame" target="top"/>

        <tocitem text="FlowLayout" target="FlowLayout"/>

        <tocitem text="GridLayout" target="GridLayout"/>

        <tocitem text="BorderLayout" target="BorderLayout"/>

        <tocitem text="BoxLayout" target="BoxLayout"/>

    </tocitem>

</toc>

25.1.4  Index file

This system file uses the XML format to deliver information representing a help index view. This view is very similar to a TOC view described above, but typically organizes references to help topics in alphabetical order. XML tags used in this file have the following meaning:

<index>: top level of a help index document. The <version> and <lang> attributes can specify file version and language respectively.

<indexitem>: defines index entry. Attribute <target> contains string ID of the target help item listed in the map file. Attribute <text> contains text to be displayed in the index.

Here's an example of the index file, LayoutIndex.xml:

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

<index version="1.0">

  <indexitem text="Index">

    <indexitem text="B">

      <indexitem target="BorderLayout" text="BorderLayout"/>

      <indexitem target="BoxLayout" text="BoxLayout"/>

    </indexitem>

    <indexitem text="F">

      <indexitem target="FlowLayout" text="FlowLayout"/>

      <indexitem target="top" text="Frame"/>

    </indexitem>

    <indexitem text="G">

      <indexitem target="GridLayout" text="GridLayout"/>

    </indexitem>

  </indexitem>

</index>

25.1.5  Help Content files

JavaHelp uses the HTML format for data files making up the actual help topic content. We can place help topics in one or more HTML files using typical fonts, images, and links to create a robust and efficient help system. We can also embed JComponents using the <OBJECT> tag (see chapter 19 for more about Swing's HTML support).

25.1.6  Search files

JavaHelp supports access to search engines, and provides a default search engine of its own: com.sun.java.help.search.DefaultSearchEngine. Search engines used to perform searches are subclasses of javax.help.search.SearchEngine (as is DefaultSearchEngine). A JavaHelp search engine uses a search database residing in the directory specified by the <data> tag of the search view section in the HelpSet file (see above). This directory contains necessary search data pre-generated based on given content. This data is searched using a specified engine pointed at by the <data> tag's engine attribute (if none is specified the default is used).

To generate binary files constituting the necessary search data, we first create content files for our help system (usually HTML), change to the directory containing these files, and run the following command listing each of our help content files as parameters:

    com.sun.java.help.search.Indexer file1 file2 ...

This generates several files and places them in the default "JavaHelpIndex" sub-directory (see the JavaHelp documentation for more options available in generating search data).

The JavaHelp search mechanism can be used to support client-side searching, server-side searching, and stand-alone seaching. As with the whole JavaHelp system, we are provided with very flexible choices in both the presentation and deployment of this information.



[ Return to Swing (Book) ]


Top 10 read Java Articles
 Get free "1000 Java Tips eBook"

 Java Calendar and Date: good to know facts and code examples

 Array vs ArrayList vs LinkedList vs Vector: an excellent overview and examples

 How can I convert any Java Object into byte array? And byte array to file object

 The Java Lesson 1: What is Java?

 How do I compare two dates and times, date between dates, time between times and

 Maven vs Ant or Ant vs Maven?

 How to open, read, write, close file(s) in Java? Examples on move, rename and de

 Java Array

 Java: JLabel font and color


[ More in News Section ]
Java Lessons

The Java Lesson 1:
What is Java?
The Java Lesson 2:
Anatomy of a simple Java program
The Java Lesson 3:
Identifiers and primitive data types
The Java Lesson 4:
Variables, constants, and literals
The Java Lesson 5:
Arithmetic operations, conversions, and casts
The Java Lesson 6:
Boolean expressions and operations
The Java Lesson 7:
Bitwise operations
The Java Lesson 8:
Flow control with if and else
The Java Lesson 9:
switch statements
The Java Lesson 10:
for, while, and do-while statements
The Java Lesson 11:
Using break and continue
The Java Lesson 12:
Class methods and how they are called
The Java Lesson 13:
Using the Math class
The Java Lesson 14:
Creating and calling custom class methods
The Java Lesson 15:
Overloading class methods
The Java Lesson 16:
An introduction to objects and object references
The Java Lesson 17:
The String class
The Java Lesson 18:
The StringBuffer class
The Java Lesson 19:
Initializing and processing arrays of primitives
The Java Lesson 20:
Initializing and processing arrays of objects
The Java Lesson 23:
Inheritance and overriding inherited methods
The Java Lesson 24:
abstract classes and polymorphism
The Java Lesson 25:
Interfaces, instanceof, and object conversion and casting
The Java Lesson 26:
Introduction to graphical programming and the java.awt packa
The Java Lesson 27:
The Component class
The Java Lesson 28:
Containers and simple layout managers
The Java Lesson 29:
The Color and Font classes
The Java Lesson 30:
Drawing geometric shapes
The Java Lesson 31:
Choice, List, and Checkbox controls
The Java Lesson 32:
Using the Scrollbar graphical control
The Java Lesson 33:
Menus and submenus
The Java Lesson 34:
An introduction to applets and the Applet class
The Java Lesson 35:
Essential HTML to launch an applet and pass it parameters
The Java Lesson 36:
Mouse event processing
Java Lesson 37:
Menus and submenus
Java Lesson 38:
The WindowListener interface and the WindowAdapter class
Java Lesson 39:
An introduction to GridBagLayout
Java Lesson 40:
An introduction to the Java Collections API
Java Lesson 41:
Exception handling with try, catch, and finally blocks
Java Lesson 42:
Claiming and throwing exceptions
Java Lesson 43:
Multithreading, the Thread class, and the Runnable interface
Java Lesson 44:
An introduction to I/O and the File and FileDialog classes
Java Lesson 45:
Low-level and high-level stream classes
Java Lesson 46:
Using the RandomAccessFile class
Java Lessons by
Joh Huhtala: Update

Latest articles
 Java Profiler JProbe to Resolve Performance Problems Faster

 SSL with GlassFish v2, page 5

 SSL with GlassFish v2, page 4

 SSL with GlassFish v2, page 3

 SSL with GlassFish v2, page 2

 The Java Lesson 2: Anatomy of a simple Java program, page 2

 New site about Java for robots and robotics: both software and hardware.

 Exceptions -III: What's an exception and why do I care?

 Exceptions -II: What's an exception and why do I care?

 Exceptions: What's an exception and why do I care?

 Double your Java code quality in 10 minutes, here is receipt

 Murach's Java Servlets and JSP

 How to get ascii code from a char in Java?

 Can we just try without catch? Yes!

 Make Tomcat page load faster

 Make your Tomcat More secure - limit network address for certain IP addresses

 New Java book online starts now here...

 Implementing RESTful Web Services in Java

 Firefox trimming from 1 GB to 40 Mb with many tabs opened

 SSL with GlassFish v2

 My request to replublish Tech Tips

 Search JavaFAQ.nu site here

 New Advanced Installer for Java 6.0 brings XML updates and imports 3rd party MSI

 EJB programming restrictions

 Maven vs Ant or Ant vs Maven?

 Why Java does not use default value which it should?

 How to unsign signed bytes in Java - your guide is here

 The Java Lesson 3: Identifiers and primitive data types. Page 2

 The Java Lesson 7: Bitwise operations with good examples, click here! Page 4

 The Java Lesson 7: Bitwise operations with good examples, click here! Page 3


[ More in News Section ]


Home Code Examples Java Forum All Java Tips Books Submit News, Code... Search... Offshore Software Tech Doodling

RSS feed Java FAQ RSS feed Java FAQ News     

    RSS feed Java Forums RSS feed Java Forums

All logos and trademarks in this site are property of their respective owner. The comments are property of their posters, all the rest 1999-2006 by Java FAQs Daily Tips.

Interactive software released under GNU GPL, Code Credits, Privacy Policy