Bean Common Usage

Using the Hi HelpIndex bean

Please consult the Bean Information and Bean class documentation for full details.

Common Usage

In addition to the standard Hi HelpIndex functionality, bean developers will want to consider these topics. Click on Details for programmer details of how to perform each task.

Creating the bean   Details

You can just use new HelpIndex() to construct a new HelpIndex object. (Or you can use Beans.instantiate(cls,"COM.phdcc.hi.HelpIndex").) 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.

Set the properties   Details

Use the bean customiser or your IDE editor to edit the properties visually. Alternatively, set the appropriate properties by hand in your code.

Browser bean   Details

The HelpIndex bean will typically need to be linked up to a browser bean.

Do this either using hiEvents, or by listening for displayPage property changes.

When HelpIndex wants to display a page, first it sets its displayTarget and displayPage properties. Then it sends a hiEvent to all registered hiListeners.

It is easiest to use hiEvents. If using Hi Brow, simply make Hi Brow listen for HelpIndex hiEvents, and vice versa.

If using properties, link displayTarget and displayPage to the browser bean, and vice versa. So you will typically need an intermediary (adaptor) class to listen for changes in these two properties. The intermediary should note any changes in displayTarget and then act on any changes to displayPage.

Help pane   Details

The user could opt to view the help system in a pane (window) within the normal application workspace. This could be done in two ways:

• More easily, simply show the Hi HelpIndex panel with its Contents, Index and other tabs.
• Alternatively, you can combine Hi HelpIndex in a more complex tab panel of your own design, eg a Workspace panel with Files, Resources and Class View tabs. If your Contents tab is selected then the Hi HelpIndex Contents can be made visible. If your Index tab is selected then the Index can be made visible.
  [ This is two incarnations of HelpIndex... Hmmm. ]

Help Dialog   Details

From a Help+Topics (or similar menu item) throw up a dialog box which simply contains an instance of the HelpIndex bean, ie it shows its Contents, Index and other tabs.

Contents Synchronisation   Details

The HelpIndex Contents can be made to synchronise itself with the help page currently being shown by the browser bean.

You can set it up either always to synchronise itself, or just when needed.

Previous/Next in Contents   Details

You will typically provide the user with a navigation control panel for the browser bean. Back and Forward buttons can usually be linked directly to the browser bean history list.

Previous in Contents, Next in Contents, Parent in Contents and Home in Contents can be implemented by listenening for hiEvents.

Your browser bean control panel could also have a Sync with Content button, to synchronise the Hi HelpIndex Contents on demand.

Alternatively, if running on the web, use the Hi Jump applet to provide this functionality.

Context-sensitive Help

A fully fledged application will also want context-sensitive help.

This means being able to press F1 (or similar, eg Help button) to get help on the current window, dialog or control within a dialog. In some situations (eg development environments) when within a text editor, pressing F1 will request help on the current word under the cursor.

Further, some applications might need What's This? style help, eg once Shift+F1 is pressed, help is shown on the control where the user next clicks.

Details   The HelpIndex bean can assist in these situations. For example, the current word under the cursor can be passed to the HelpIndex bean Index of keywords. If it has just one match then the corresponding page is shown straight away. Otherwise the HelpIndex Index pane is made visible and the list of matches is displayed, for the user to refine the query.

Details   If all these scenarios are used, then several copies of Hi HelpIndex may be running at the same time (eg once in your tab Contents, once in your tab Index and once in the Help Dialog).
??? Instantiate a single invisible copy of the HelpIndex bean at start up and let it load its index file(s). Clone any copies you need and make these visible when appropriate.
You may want to use this approach even if you use HelpIndex once, as it is good to get HelpIndex loading its index files straight away at startup.

??? How to cope with different locale selection.

The Hi HelpIndex software comes with a basic but useful Hi Brow browser bean.

Here is a list of known browser beans.

• Sun's Hot Java bean

• The JDK 1.2 (JFC or Swing) JEditorPane may be used to display HTML pages.