Bean Detailed Instructions

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.

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.

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.

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.

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

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.

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.

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:

• If the user asks to display a page in HelpIndex, HelpIndex sends Hi Brow a hiEvent with full link information. Brow will send a hiEvent back. HelpIndex will do nothing as the displayPage has not changed.
• If the user navigates to a new page within Hi Brow, Brow first sends HelpIndex a simple hiEvent. HelpIndex recognises this as a different displayPage (and synchronises with it if necessary) and sends back a full hiEvent. Brow will do nothing as the displayPage has not changed.

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.

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.

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.

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.

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).

• Set current selection in Contents

• Select index file
  Use setCurrentIndex() change the index file. It must be passed the String IndexURL of the matching IndexParam. The IndexURL must existing in the index already.

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>

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.