|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
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.
new HelpIndex(). This is recommended for beans.
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:
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 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.
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).
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.jarrun time file and your index file (eg
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.