Hi HelpIndex Bean

Page Contents	Class at a Glance  Class Description  Properties  Methods  Events  Supporting Classes  Possible improvements
See also	Bean Information  Using in the BDK Beanbox  Sample code  HiDemo example

Purpose

The Hi HelpIndex site map bean provides a contents tree and/or keyword search index for a web site and CD-ROMs, or as the help system for other programs. Different languages are supported and multiple site map index files can be used.

The HelpIndex bean may be run as an applet on a web page, or used in a Java project like any other bean.

index - the array of index file descriptions
displayPage - the page the browser should display or is displaying
displayTarget - the target for the next browser displayPage

HiEvent displayPage() - a display page request

Creation

Either: HelpIndex hi = new HelpIndex()

Or: HelpIndex hi = (HelpIndex) Beans.instantiate(cl,"COM.phdcc.hi.HelpIndex");

The Hi HelpIndex bean will typically be used to provide the basis of a help system for a Java application. Hi HelpIndex will therefore usually need to be accompanied by a browser bean (ie a bean which can display an HTML page in its window), such as the supplied Hi Brow or Sun's Hot Java Bean.

The Developer usage instructions show how the HelpIndex bean could be used in a Help pane or Help Dialog, and how to provide Contents Synchronisation. Guidance on Context-sensitive Help systems is given.

setIndex() - add an Index/Language file.
displayPage() - process a HiEvent message.
lookupKeyword() - lookup a keyword in the Index and display a single hit.

Overview

The HelpIndex bean is an applet bean for use on web sites or in applications.

It therefore is a class which may be manipulated as an ordinary panel.

In applications, the HelpIndex bean is usually linked to a browser bean which will display information to the user.
Using HiEvent messages is the easiest way to process display page requests.
Alternatively, the displayPage and displayTarget properties may be bound to the browser.

The browser's current display page URL string should also be bound back (using HiEvent messages or the displayPage property), so HelpIndex can synchronise with the page currently being displayed.

A BeanInfo class, HelpIndexBeanInfo, explicitly provides information for properties, events, and methods.

The event information is not now given explicitly as it throws the JBuilder designer.

A useless bean customiser is provided.
• Initially a standard BeanBox style property editor must be used (ie no customiser)
• Later a custom wizard (similar to Hi Lab's Test+New Web Page wizard) could be provided.
• Eventually, a complete Java equivalent of Hi Lab could be provided as the customizer.

Please see the examples page.

If a property is [bound] then any changes (via setXXX()) are notified after the change has occurred. The HelpIndex bean calls the PropertyChangeListener.propertyChange() method on any registered listeners, passing a PropertyChangeEvent with the old and new values.

Properties which are only available to bean users are indicated by a single asterisk. A double asterisk indicates a standard Component property used by Hi HelpIndex. The "Param Equiv" column shows the equivalent applet parameter, where it is not obvious.

The colours are explained in the Colour Properties Guide below.

The use of filenames is also explained below.

	Type	Name		Description		Default	Param Equiv
**	Color	background	[bound]	Background colour	(rw)	white	bgColor
	boolean	buttonShape	[bound]	True if the Contents' buttons are shaped square. Round if false. Get using isButtonShapeSquare(). Set using setButtonShapeSquare().	(rw)	false ie Round
	Color	cardBgColor	[bound]	Card Background Colour	(rw)	#FFFFCC
	String	contentsIcons	[bound]	URL string of the Contents Icons image gif in the required format.	(rw)	"hiicons.gif"
*	boolean	contentsOnly	[bound]	True if only the Contents panel is shown, ie with no tabs above or Display Page below.	(rw)	false
*	String	currentIndex	[bound]	IndexURL of index to display	(rw)
*	String	displayPage	[bound]	URL String of page to display.	(rw)
*	String	displayTarget	[bound]	Target of page to display.	(rw)
	Color	fieldBgColor	[bound]	Field background colour	(rw)	white
**	Font	font	[bound]	Font	(rw)	Dialog, 12 pt
**	Color	foreground	[bound]	Foreground colour	(rw)	black	fgColor
	boolean	highMode	[bound]	True if display is higher than it is wide. Display mode	(rw)	true	mode
	String	icon	[bound]	URL string of the icon image gif in the required format.	(rw)	"hi.gif"
	Color	iconBgColor	[bound]	Icon mode background colour	(rw)	bgColor
	boolean	iconCloseMode	[bound]	True if floating window closes after a page is displayed. Display mode	(rw)	false	mode
	boolean	iconMode	[bound]	True if icon displayed initially. Click for floating window. Display mode	(rw)	false	mode
	boolean	iconPopupMode	[bound]	True if floating window pops up straight away. Display mode	(rw)	false	mode
	IndexParam[]	index	indexed	Index and language files It has its own property editor.	(rw)	none	index1, etc.
	IndexParam[]	indexes		Index and language files Provided for IDEs which do not support indexed properties	(rw)	none	index1, etc.
	int	indexLines	[bound]	Lines in keywords list box	(rw)	4
*	boolean	indexOnly	[bound]	True if only the Index panel is shown, ie with no tabs above or Display Page below.	(rw)	false
	Dimension	minIconWindowSize	[bound]	Minimum width and height of icon window	(rw)
	int	minQueryLength	[bound]	Minimum chars in query	(rw)	0
	int	pageLines	[bound]	Lines in pages list box	(rw)	2
	Color	selectColor	[bound]	Contents select colour	(rw)	green
*	boolean	syncedToBrowser	[bound]	Contents selection is synchronised to the browser's current document	(rw)	false
	String	tabIcons	[bound]	URL string of the tab Icons image gif in the required format.	(rw)	"hitabs.gif"
	String	target	[bound]	Target frame	(rw)	"_self"
	Color	tipBgColor	[bound]	Tip background colour	(rw)	#EFFFFF

If the Hi HelpIndex bean has an AppletContext then it will first try to open the filename as a URL, using the AppletContext codeBase or documentBase as appropriate to provide defaults (eg like new URL(getCodeBase(),filename);).
Note that this still allows you to specify absolute file URLs (though if run as an applet, you may not be able to access it).

If there is no AppletContext and the filename is a full URL then Hi HelpIndex will attempt to open this URL.

If not an absolute URL (or if the URL open fails) then Hi HelpIndex tries to open the file from the CLASSPATH. [ To do this, a slash character "/" is prefixed to filename.]
If "." is in the CLASSPATH, then specifying a filename of "hilogo.gif" will load this image file.

NB if specifying a Windows file as an absolute URLs, use the following style: file:///D:/JBuilder/myclasses/hilogo.gif
Do not the bar character after the drive letter, eg file:///D|/

instantiation	HelpIndex()
control	displayPage(HiEvent hie)	Display the given page in the given target
	getIndexCount()	Returns the number of items in the index property array
	lookupKeyword( String lookupText, boolean displayHit))	Display the Index tab and lookup given string. If displayHit and there is a single hit, then the hit is displayed.
	restart()	requests that the HelpIndex screen be rebuilt
	setIndex(int n, IndexParam value)	As well as changing the index array, you can use this call to add a new IndexParam onto the end of the index array
	syncToBrowserNow()	Synchronises the Contents selection now
adding/removing listeners	addPropertyChangeListener()	add a listener for post-notification of changes in a bound property
	removePropertyChangeListener()	remove a listener for post-notification of changes in a bound property
	addHiListener()	add a listener for Hi display page events
	removeHiListener()	remove a listener for Hi display page events

PropertyChangeEvents events are post-notifications of a property change (bound).

HiEvent objects are sent to every registered HiListener registered using addHiListener().
A HiEvent indicates that HelpIndex is requesting that a page be displayed in a target frame. Note that a full HiEvent is sent if possible, ie with home, parent, previous and next in contents information.

EventListener Interfaces:	PropertyChangeListener HiListener
Event Objects:	PropertyChangeEvent HiEvent

HelpIndex receives HiListener HiEvent displayPage() messages to synchronize the Contents with another Hi source, such as the Hi Brow browser bean.

Note that only the displayPage and displayTarget properties are used, so only the shorter HiEvent constructor need be used.

EventListener Interfaces:	HiListener
Event Objects:	HiEvent

public class COM.phdcc.hi.IndexParam
{
    public String   IndexURL;                 // URL of index file
    public String   IndexURLCharEncoding;     // Character Encoding, or null
    public String   LanguageURL;              // URL of language file, or null
    public String   LanguageURLCharEncoding;  // Character Encoding, or null
    public boolean  noContents;               // do not display contents
    public	boolean noIndex;                  // do not display index
    public boolean  Sort;                     // sort contents
    public boolean  Index;                    // show index initially
    public boolean  Expanded;                 // expand contents
    public String   SelectURL;                // URL in Contents to select initially, or null
    public String   InitialQuery;             // Initial query in Index, or null
    public Locale   IndexLocale;              // Locale, or null
};

public class COM.phdcc.hi.HiEvent extends java.util.EventObject
{
    // Sending information to HelpIndex
    public String displayPage;
    public String displayTarget;

    HiEvent(Object source, String displayPage, String displayTarget);

    // HelpIndex generates events with this information as well.
    public String prevPage;
    public String prevTarget;
    public String nextPage;
    public String nextTarget;
    public String parentPage;
    public String parentTarget;
    public String homePage;
    public String homeTarget;

    HiEvent(Object source,
            String displayPage, String displayTarget,
            String prevPage,    String prevTarget,
            String nextPage,    String nextTarget,
            String parentPage,  String parentTarget,
            String homePage,    String homeTarget);
}

public interface COM.phdcc.hi.HiListener extends java.util.EventListener
{
    public void displayPage(HiEvent hie);
}

• If just displaying the Contents or just the Index, then there is no way within HelpIndex for the user to change index/language file. Possible solutions include:
  • Right click menu allows selection of new index.
  • Merge all index files into one:
    
    • In Contents, each index file will have a root entry. How would it cope with different languages? (Possibly just show those index files with a matching language. How would a new language be selected?)
      
    • In the Index, the keywords for each index used will be merged together.

• The bean implements java.beans.Visibility so that it can run on a server. This means that it will not show itself. New access methods need to be defined for other server code to use.

  An invisible instance of HelpIndex could be used within an application. HelpIndex will read in its index files, and your program will use an enhanced Enquiry API to see the Contents and look up keywords in the Index.