JavaHelp
Goes Online
The
JavaHelpTM API -- a platform-independent,
extensible system for application help and online documentation
-- is now available as an early-access release from Java Software.
You can download the new release at no cost from the Java Developer
Connection.
If you have worked with earlier versions
of JavaHelp, you'll notice that this newest early-access release
includes new functionality and enhancements. In particular, it
supports JDK 1.1 as well as JDK 1.2. Other key enhancements include
context-sensitive help, merging support, search enhancements,
and support for Swing 1.1 Beta.
The JavaHelp API, written entirely in
the JavaTM programming language,
provides capabilities for navigating, searching, and displaying
information. Information architects and software developers can
use the JavaHelp software to deliver online help for components,
applets, and applications. Authors can also use the JavaHelp software
for electronic publishing for the Web and corporate intranet.
For more information about JavaHelp, including the JavaHelp specification,
FAQ, communications, and events, visit the JavaHelp web site (java.sun.com/products/javahelp).
Types of Context-Sensitive Help
Context-sensitive
help is information provided to the user based on the context
of the task in which they are involved. 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 window-level help -- that is, 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 the user can interact with it.
NOTE: It is technically possible
to use this mechanism to provide context-sensitive help for any
object that has focus when the F1 key is pressed. However, in
order to make JavaHelp system implementations as consistent as
possible, you are strongly encouraged to use this mechanism only
to provide help at the window level. Use the field-level help
mechanism to provide help for other GUI objects.
By default, help information is displayed
in the help viewer.
Field-Level
Help
You can use field-level
help to obtain help about any GUI object. Here's how
to use field-level help:
- Click the field-level help button or choose
the Help->Field-Level Help menu item to change the cursor
to a special field-level help cursor.
- Select a GUI object
By default, help information is displayed
in the help viewer and the cursor returns to its original state.
The Help Menu
JavaHelp
provides a Help menu that can be used to provide help to users about
specific tasks or objects. The Help menu contains a sub-menu of
items that provide help about completing various tasks.
The 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.
Implementing
Context-Sensitive Help
The
JavaHelp system provides classes and methods that help you implement
context-sensitive help in your applications. This
section
- Summarizes the context-sensitive help
system.
- Describes the basic elements of the system.
- Describes how to implement context-sensitive
help.
The following table summarizes the context-sensitive
help system.
CSH Type |
Activation Mechanism |
Object for Which Help Provided |
Implementation Steps |
Window-Level |
Press F1 (or Help) key
|
Window with focus |
- Set helpIDs for components
- Capture F1 key press
- Get window that has focus
- Get helpID for window
- Display help
|
Field-Level |
1. Activate field-level help
2. Navigate with mouse or keyboard
3. Select object |
Selected object |
- Set helpIDs for components
- Activate field-level help (button or menu
item)
- Track context-
sensitive events
- Get helpID for selected object
- Display help
|
Help Button or Menu Item
|
Click button or choose menu item
|
Topic associated with button or
menu item |
- Create button or menu object
- Set helpID on object
- Get helpID on object
- Display help
|
System- Initiated |
Internal, varies |
Internal, varies |
|
Basic Elements
This
section describes the low-level elements used in implementing context-sensitive
help.
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:
- Set and get JComponent
help properties for GUI objects.
- Track context-sensitive events.
Setting and Getting JComponent Help Properties
To
provide context-sensitive help for a GUI component (that is, a component
that is sub-classed from the JComponent class), you must associate
a help ID with that component. To make that association, you set
the helpID
property and (if you use multiple HelpSets) the HelpSet
in the JComponent. The JavaHelp system CSH
class provides the following convenient methods for setting and
getting the JComponent helpID:
public static void setHelpID(JComponent comp, String helpID);
public static String getHelpID(JComponent comp);
public static void setHelpSet(JComponent comp, HelpSet hs);
public static HelpSet getHelpSet(JComponent comp);
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 trackCSEvents(Component
comp)
Using Context-Sensitive Help
This
section describes how to use the JavaHelp system to implement the
different forms of context-sensitive help. The first section describes
the HelpBroker
object
and the subsequent sections describe:
The HelpBroker
The
JavaHelp system includes a HelpBroker object 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, it limits the flexibility of
your implementation. For example, if you use the HelpBroker you
must display help information in the standard help viewer.
NOTE: 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 example, 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, please use the
JavaHelp system apiviewer
command to view their API information.
The HelpBroker 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:
HelpBroker Context-Sensitive
Methods
The
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
(String helpID, HelpSet hs) 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 setURL(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 ActionListener getHelpKeyActionListener();
The
ActionListener for F1 and Help key activation. Set the returned
ActionListener on the component that will be receiving the keypress
event.
public ActionListener getFieldLevelActionListener();
The
ActionListener for field-level help. Set the returned ActionListener
on the component (for example, button or menu item) that will be
receiving the activation event that activates field-level help.
public ActionListener getHelpActionListener();
The ActionListener for a Help object. Set
the returned ActionListener on the help component (for example,
a Help button) that will receive the action (for example, a keypress).
public void enableHelpKey(RootPane root,
String id, HelpSet hs);
This enables window-level help on the RootPane. This method:
- Registers F1 and Help key presses with
the RootPane.
- Sets a default helpID for the RootPane.
- Registers the HelpBroker's HelpActionListener
with the RootPane.
public void enableHelp(JComponent 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.
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.
In order to make JavaHelp system implementations as consistent as
possible, you are strongly encouraged to use this mechanism only
to provide help at the window level (set the helpID
only on the RootPane). Use the field-level help mechanism to provide
help for other GUI objects.
After you set the helpID/HelpSet for all
components, enable the F1 key for the frame's RootPane with a HelpBroker
object using enableHelpKey().
The hb.getHelpKeyActionListener()
method enables the F1 key on ActionListener
objects others than root panes. The following code fragment is an
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 an field-level help button or menu item. Set
an ActionListener on the button or menu item with a HelpBroker object
using getFieldLevelActionListener.
The following code fragment is an example:
JToolBar toolbar = new JToolBar();
CSH.setHelpID(toolbar,"toolbar.main");
:
helpbutton = addButton(toolbar, "images/help.gif", "help");
helpbutton.addActionListener
(mainHelpBroker.getFieldLevelActionListener());
Help
Menu/Button Help
To
implement Help menu or Help
button help:
Create a menu item or button
Set the helpID and (if you use multiple
HelpSets) HelpSet on the object
Enable help on the object with the HelpBroker
The HelpBroker provides the hb.getHelpActionListener
method to enable help on objects with types other than AbstractButton.
The following code fragment is an example:
JButton helpButton = new JButton("Help");
mainHelpBroker.enableHelp(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. The following code fragment is an example:
:
try {
mainHelpBroker.setCurrentID(helpID);
} catch (Exception ee) {
System.err.println("trouble with visitinG id; "+ee);
}
:
Sample
Code
The following samples show the kinds of code
that are required for the different types of context-sensitive help
using a default HelpSet.
// Get the HelpSet and the HelpBroker if (hs == null) {
try { URL url = HelpSet.findHelpSet(null, "api");
// URL url = HelpSet.findHelpSet(null, helpsetName);
hs = new HelpSet(null, url); }
catch (Exception ee) {
System.out.println ("API Help Set not found");
return;
}
}
mainHelpBroker = hs.createHelpBroker();
// Enable window-level help on the RootPane
rootpane = frame.getRootPane();
mainHelpBroker.enableHelpKey(rootpane, "top", null);
:
// Set the HelpID on the various components
JToolBar toolbar=new JToolBar();
CSH.setHelpID(toolbar,"toolbar.main");
:
// Enable field-level help on the help button
helpbutton = addButton(toolbar, "images/help.gif", "help");
helpbutton.addActionListener
(mainHelpBroker.getFieldLevelActionListener());
:
sourceIFrame =
new JInternalFrame("Source", true, true, true, true);
CSH.setHelpID(sourceIFrame, "edit.editsource");
:
JTextArea newtext=new JTextArea();
CSH.setHelpID(newtext, "build.build");
:
newtext = new JTextArea();
CSH.setHelpID(newtext, "debug.overview");
:
newtext = new JTextArea();
CSH.setHelpID(newtext, "browse.strings");
:
JMenu menu = new JMenu("File");
CSH.setHelpID(menu, "menus.file");
:
// Enable Menu/Button help on the Help menu item
JButton helpButton = new JButton("Help");
mainHelpBroker.enableHelp
(helpButton, "browse.strings", null);
:
menu = new JMenu("Edit");
CSH.setHelpID(menu, "menus.edit");
:
// System Level help somewhere within the code
try {
mainHelpBroker.setCurrentID(helpID);
}
catch (Exception ee) {
System.err.println("trouble with visiting id; "+ee); }
:
|