Bean Detailed Instructions

Last modified: 13 March 1998.

Page Contents Starting HelpIndex  Setting Properties  After Start  Serialisation  Applet Context  Linking to a browser bean  Bean events  Making a help pane  Help Dialog  Contents Synchronisation  Previous/Next in Contents  Context-sensitive Help  Program Control  Using as an applet 
See also Bean Information  Sample code  HiDemo example  Common usage guidelines  GUI Help Systems 

This page mainly expands on the Hi HelpIndex bean common usage guidelines, ie it gives the details that a programmer needs.

Developers will also need to know about the bean files and how to use them. Your Java development environment will usually take care of preparing the necessary files for distribution with your application.


Starting HelpIndex

Your IDE may generate the necessary code to insert Hi HelpIndex into your project. It will either just construct a new HelpIndex object or incarnate it using Beans.instantiate(cls,"COM.phdcc.hi.HelpIndex").

It is simpler to call new HelpIndex() (though calling Beans.instantiate(...) works fine). Please read the notes about specify filenames.

You must set at least one IndexParam in the index property (either using your IDE or by calling setIndex()).

Finally, do not forget to call the start() method, once the HelpIndex bean has been added to a container.


Setting Properties

[ HelpIndex does not have a useful bean customizer yet. ]

Use your Java or Web development IDE to set the properties of the HelpIndex bean. The appropriate editor is invoked to edit the property.

The design-time HelpIndex bean includes an editor for the index property.

A programmer can be informed when [bound] properties change by registering a PropertyChangeListener with HelpIndex. The listener will be sent a PropertyChange event after the property has changed.

HelpIndex currently has no [constrained] properties.


After Start

As described above, you call the start() method to build the HelpIndex panel.

You can change properties after start() has been called.

For changes to major properties, the HelpIndex panel will be rebuilt, losing the user's current place in the Contents, etc.

Minor property changes will not lose the user's place, eg colours and font. Note that you can force a panel rebuild by calling restart(). For example, you might want to do this if you have set a font of a different size.


Serialisation

The HelpIndex bean may be serialized and deserialized. It simply saves and restores all its properties in this process.

Remember to call start() if you deserialize a HelpIndex object by hand.


Applet Context

HelpIndex will have an AppletContext (a) if run as an applet in a browser, (b) if instantiated using Beans.instantiate(), or (c) if you explicitly give it one.
HelpIndex will not have an AppletContext if just instantiated via new HelpIndex(). This is recommended for beans.
(What about when de-serialized?)

If HelpIndex has an AppletContext it will use it where appropriate, ie when accessing file or displaying pages.

When displaying a page, HelpIndex first informs any property change listeners (as described below) and then, if available, uses the AppletContext to request that the page be displayed.

Note that the AppletContext given by Beans.instantiate() is only rudimentary, but the code base and document base are valid, for example. But displaying a page will do nothing.


Linking to a browser bean

You must link HelpIndex to a browser bean if you want to display pages in a Java application. You must link the browser back to HelpIndex if you want HelpIndex to synchronise itself with the browser's current page.

HelpIndex will first inform any property change and hiEvent listeners that it wants to display a page. Then, if available, it also uses the AppletContext to request that the page be displayed.

So, when HelpIndex wants to display a page, first it sets its displayTarget and displayPage properties. Then any hiListeners are informed.

The easiest way to cope with Display page commands is to listen for hiEvent commands, ie implement the hiListener interface, ie displayPage(HiEvent)

Alternatively, you will typically need an intermediary (adaptor) class to listen for changes in the displayTarget and displayPage properties. The intermediary should note any changes in displayTarget and then act on any changes to displayPage.

If you want HelpIndex to synchronise itself with the page currently being displayed in the browser bean, then you will have to link the browser's displayPage (or equivalent) property back to the HelpIndex displayPage property.

See the example code for one way of linking to a browser bean. The HiDemo example shows both event and property change linking.


Bean events

As described above, in Linking to a browser bean, HelpIndex generates a hiEvent command when Display Page is pressed.

The hiListener interface requires you to have a method displayPage(HiEvent).

hiEvents come in two forms. The simplest form just contains the displayPage and displayTarget. HelpIndex usually generates the full form which also includes the following information (if available): previous in contents, next in contents, parent in contents and home in contents. A navigation bean should listen for these full events and set its navigation buttons accordingly.

If HelpIndex and Hi Brow send each other hiEvents then the following events sequences may be generated:


Making a help pane

You will need somewhere to display your help information.

You might simply put your chosen browser bean in your main window frame and make it visible when you want the help to be seen.

Alternatively, you may want the help text displayed in a separate window above your application. A modeless dialog box might well be appropriate here.

The HiDemo example source has examples of both these techniques.


Help Dialog

Your application will usually want to have a Help+Topics menu item.

Simply add the HelpIndex bean to your dialog. If the user requests that a page be displayed, remember the page and target, close the help dialog and display the page.

The HiDemo example source has an example of this technique.


Contents Synchronisation

First, set the syncedToBrowser property to true.

Next, link the browser's current display page, back to HelpIndex. Do this either using properties, or send a hiEvent message to HelpIndex.

If syncedToBrowser is false, you can still synchronise on demand using the syncToBrowserNow() method.

See the HiDemo example source.


Previous/Next in Contents

Browser beans like Hi Brow need to have a separate navigation control for Back and Forward buttons, etc.

In addition to these normal options, HelpIndex can provide navigation buttons to take users through the web site in the order defined by the index file. Ie you might provide Previous in Contents, Next in Contents, Parent in Contents and Home in Contents buttons.

This can be done simply by listenening for hiEvents generated by HelpIndex. If, for example, the hiEvent.prevPage is non-null then the Previous in Contents button can be enabled; if the user clicks on this button then generate a simple hiEvent to go to this page.

See Linking to a browser bean and Bean events above for more details.


Context-sensitive Help

Context-sensitive help means several things:
First, if a Help button is pressed in a dialog, then an appropriate help page is displayed.
Second, a ? button or Shift+F1 help gets a "What's This" style cursor. The user clicks on a control/etc and help appears for it.
Finally, if a user pressed F1 in an editor, help is provided on the word under the cursor.

HelpIndex only helps in the latter case. After you have got the word under the cursor, simply pass it to the lookupKeyword() method. Any matching keywords are shown in the HelpIndex Index. If there is only one hit, you can opt to have it shown straight away in the browser.

Enquiry API

Index access methods...

HelpIndex could also have methods to allow you to get the Contents. This could be useful if you want to construct your own Contents tree. HelpIndex would be invisible in this scenario. Possible function: getListOfChildren(child n).


Program Control

As well as all the above techniques, Hi HelpIndex may also be controlled with these further functions. In addition, all the standard Java API is available, eg setVisible()

Using as an applet

The HelpIndex bean may be used as an applet. Use it in the normal way, specifying the parameters you need.

Here is some typical HTML:

<APPLET code=COM.phdcc.hi.HelpIndex width=250 height=250 archive="hi230.jar">
<param name=mode value="applet high">
<param name=index1 value="myindex.hi">
</APPLET>
Simply include this HTML in a web page, alongside the hi230.jar run time file and your index file (eg myindex.hi).
Obviously, the above code can only be run successfully in a fully compliant JDK 1.1+ browser.

Note that when run as an applet in Navigator 4, Navigator will not find the default gif files in hi230.jar. So you will have to put these files in the same directory as hi230.jar: hi.gif, hiicons.gif, hitabs.gif (unless you provide alternates via parameters).

??? In the future, properties in a .ser "pickle file" or resource file may be supported.


HelpIndex    PHD