oracle.help
Class Help

java.lang.Object
  |
  +--oracle.help.Help

All Implemented Interfaces:

java.util.EventListener, oracle.ewt.help.HelpProvider, oracle.bali.ewt.help.HelpProvider, oracle.help.navigator.NavigatorListener

public class Help

extends java.lang.Object

implements oracle.bali.ewt.help.HelpProvider, oracle.ewt.help.HelpProvider, oracle.help.navigator.NavigatorListener

The Help class provides a default implementation of a help system using the Oracle Help for Java components. This class provides APIs for programmatically controlling the help system. The APIs supported by this class can be divided into following categories :

• APIs to add and remove Book objects from the help system
• APIs to implement context-sensitive help
• APIs to control the help system user interface

Book objects

Applications populate the Help object with help content via Book objects. Book objects contain the information that the help system needs to display the application's documentation. Book objects can be added or removed from the Help System anytime after their creation using the addBook() and removeBook() methods respectively. See the OHJ File Formats document for more information on the supported file formats for Books.

Context-sensitive help

Applications can show particular topics using the showTopic() methods. The application programmer specifies the topicID of the help content page to show. This topicID is resolved to an HTML page through the merged map file created from the Books added to the help system.

In addition, to the showTopic() methods the help system supports Oracle EWT's HelpProvider interface. See the showHelp() methods.

Help User Interface

The default help system implementation consists of the following user-interface elements:

• The Navigator Window (and the Navigators it contains)
• Topic Windows

This class provides APIs to manipulate the visible state of each of these elements. In addition, you can optionally pass a Navigator argument to the showNavigatorWindow method to select which Navigator is initially displayed in the NavigatorWindow.

Pluggable HTML browser

Oracle Help for Java supports a pluggable HTML browser interface. Applications can specify their own HTMLBrowser subclass for displaying help topics. Refer to oracle.help.htmlBrowser package for more information on this interface. The default HTMLBrowser component used for topic display is Oracle's modified version of ICESoft's ICE Browser.

See Also:

Book, HTMLBrowser

Constructor Summary

Help()
Creates an instance of the Help object with ICEBrowser as the HTMLBrowser component used for topic display.

Help(java.applet.AppletContext appletContext, java.lang.String targetFrame)
Creates an instance of the Help object using the native browser as the topic display through the given applet context.

Help(java.applet.AppletContext appletContext, java.lang.String targetFrame, boolean combineBooks, boolean useLabelInfo)
Creates an instance of the Help object using the native browser as the topic display through the given applet context.

Help(boolean combineBooks, boolean useLabelInfo)
Creates an instance of the Help object with ICEBrowser as the HTMLBrowser component used for topic display.

Help(boolean combineBooks, boolean useLabelInfo, boolean dockedByDefault)
Creates an instance of the Help object with ICEBrowser as the HTMLBrowser component used for topic display.

Help(java.lang.Class htmlBrowserClass)
Creates an instance of the Help object with specified browser as the HTMLBrowser component used for topic display.

Help(java.lang.Class htmlBrowserClass, boolean combineBooks, boolean useLabelInfo)
Creates an instance of the Help object with specified HTMLBrowser as the HTMLBrowser component used for topic display.

Help(java.lang.Class htmlBrowserClass, boolean combineBooks, boolean useLabelInfo, boolean standAloneMode)
Creates an instance of the Help object with specified HTMLBrowser as the HTMLBrowser component used for topic display.

Help(java.lang.Class htmlBrowserClass, boolean combineBooks, boolean useLabelInfo, boolean standAloneMode, boolean dockedByDefault)
Creates an instance of the Help object with specified HTMLBrowser as the HTMLBrowser component used for topic display.

Method Summary

void	addBook(Book book) Add a book to the help system's library.
void	dispose() Dispose the help system.
void	enableFavoritesNavigator(java.net.URL location) Creates a Favorites Navigator using the file at location as the information to construct the navigator This method should be invoked after the construction of the Help object and before the help system is displayed
Navigator[]	getAllNavigators() Get the Navigator objects displayed in the Navigator Window.
int	getBookCount() Returns the number of Book objects currently in the help system's library.
Book[]	getBooks() Get all of the Book objects currently in the help system's library.
static java.lang.String	getHelpEncoding() Get the Character Set Encoding used by the Oracle Help for Java classes for reading in client help files.
static java.util.Locale	getHelpLocale() Get the Locale currently being used by the Oracle Help for Java classes for Locale sensitive operations and resource loading.
static void	registerClientWindow(java.awt.Window aWindow) Clients should register Window instances with the Help object.
void	registerCustomProtocolHandler(java.lang.String customProtocol, CustomProtocolHandler handler) Registers a CustomProtocolHandler for a custom protocol Consider the following HTML: <a href="custom:protocolName:protocolValue"/> When OHJ follows links that link, it will check for any CustomProtocolHandlers registered by the identifier "protocolName." If it finds a CustomProtocolHandler, its handleValue method will be invoked, passing protocolValue as the value
void	removeAllBooks() Removes all books from the help system's library.
void	removeBook(Book book) Remove a book from the help system.
void	setDefaultBook(Book book) Sets the default book for use with the showHelp methods.
void	setDefaultTopicID(java.lang.String topicID) Sets the default topicID for use with the showHelp methods.
static void	setHelpEncoding(java.lang.String helpEncoding) Set the Character Set Encoding used by the Oracle Help for Java classes for reading in client help files.
static void	setHelpLocale(java.util.Locale helpLocale) Set the Locale used by the Oracle Help for Java classes for Locale sensitive operations and resource loading.
void	setHelpOnHelp(Book book, java.lang.String topicID) Calling this method with valid book and topicID parameters will enable the "Help on Help" menu option in the Help Navigator.
void	setHelpOnHelp(java.net.URL helpOnHelpURL) Calling this method with a valid URL parameter will enable the "Help on Help" menu option in the Help Navigator.
void	setIconImage(java.awt.Image iconImage) Call this method to set a custom image for the window icons in the Oracle Help for Java windows.
void	setVisible(boolean visible) Sets the visibility of the help system.
void	showHelp(java.awt.Component component) Implements the HelpProvider interface from Oracle's JEWT toolkit.
void	showHelp(java.lang.Object book, java.lang.String topicID, java.awt.Component object) Implements the HelpProvider interface from Oracle's EWT toolkit.
void	showNavigatorWindow() Show the Navigator Window
void	showNavigatorWindow(Book activeBook) Show the Navigator Window with the NavigatorTabPanel for the given Book initially displayed.
void	showNavigatorWindow(Navigator activeNavigator) Show the Navigator Window with a specific Navigator displayed initially.
void	showTopic(Book book, java.lang.String topicID) Shows the given topic from the given book in a currently existing topic window.
void	showTopic(Book book, java.lang.String topicID, boolean alwaysCreate) Shows the given topic from the given book.
void	showTopic(Book book, java.lang.String topicID, boolean alwaysCreate, java.awt.Point location, java.awt.Dimension size) Shows the given topic from the given book.
void	topicActivated(oracle.help.navigator.NavigatorEvent e) Public method as a result of the NavigatorListener interface.
void	topicSelected(oracle.help.navigator.NavigatorEvent e) Public method as a result of the NavigatorListener interface.
static void	unregisterClientWindow(java.awt.Window aWindow) Clients should unregister each Window instance that they registered with the registerClientWindow() method once the window will no longer be active.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Help

public Help()

Creates an instance of the Help object with ICEBrowser as the HTMLBrowser component used for topic display. Each instance of Help is displayed and managed separately. Applications should call this method only once and cache the Help reference for use in subsequent calls. This constructor will instruct the help system to show all of the views from the added books in one tab panel, and to ignore author defined labels for views in favor of standard tab labels.

See Also:

ICEBrowser

Help

public Help(java.lang.Class htmlBrowserClass)

Creates an instance of the Help object with specified browser as the HTMLBrowser component used for topic display. Each instance of Help is displayed and managed separately. Applications should call this method only once and cache the Help reference for use in subsequent calls. This constructor will instruct the help system to show all of the views from the added books in one tab panel, and to ignore author defined labels for views in favor of standard tab labels.

Parameters:

htmlBrowserClass - the HTMLBrowser subclass to use as the topic display component

See Also:

HTMLBrowser

Help

public Help(java.applet.AppletContext appletContext,
            java.lang.String targetFrame)

Creates an instance of the Help object using the native browser as the topic display through the given applet context. Each instance of Help is displayed and managed separately. Applications should call this method only once and cache the Help reference for use in subsequent calls.

This constructor will instruct the help system to show all of the views from the added books in one tab panel, and to ignore author defined labels for views in favor of standard tab labels.

Note that using the native browser for topic display through an applet context results in the loss of many of OHJ's ICE Browser specific topic display features (toc syncing, popups, window-types, a-links, etc).

Parameters:

appletContext - the AppletContext to use to show topics in the native browser

targetFrame - the name of the target frame in the native browser to use when showing topics

See Also:

AppletContext

Help

public Help(boolean combineBooks,
            boolean useLabelInfo)

Creates an instance of the Help object with ICEBrowser as the HTMLBrowser component used for topic display. Each instance of Help is displayed and managed separately. Applications should call this method only once and cache the Help reference for use in subsequent calls.

Parameters:

combineBooks - if true the help system will show all of the views from the Books added to the help system in one tab panel, if false the help sytem will create a different tab panel for each book

useLabelInfo - if true the help system uses the author defined label information for display and view merging, if false the help system uses standard Navigator labels

See Also:

HTMLBrowser

Help

public Help(boolean combineBooks,
            boolean useLabelInfo,
            boolean dockedByDefault)

Creates an instance of the Help object with ICEBrowser as the HTMLBrowser component used for topic display. Each instance of Help is displayed and managed separately. Applications should call this method only once and cache the Help reference for use in subsequent calls.

Parameters:

combineBooks - if true the help system will show all of the views from the Books added to the help system in one tab panel, if false the help sytem will create a different tab panel for each book

useLabelInfo - if true the help system uses the author defined label information for display and view merging, if false the help system uses standard Navigator labels

dockedByDefault - if true the help system displays with the Help Navigator and Topic Window initially docked

See Also:

HTMLBrowser

Help

public Help(java.lang.Class htmlBrowserClass,
            boolean combineBooks,
            boolean useLabelInfo)

Creates an instance of the Help object with specified HTMLBrowser as the HTMLBrowser component used for topic display. Each instance of Help is displayed and managed separately. Applications should call this method only once and cache the Help reference for use in subsequent calls.

Parameters:

htmlBrowserClass - the HTMLBrowser subclass to use as the topic display component

combineBooks - if true the help system will show all of the views from the Books added to the help system in one tab panel, if false the help sytem will create a different tab panel for each book

useLabelInfo - if true the help system uses the author defined label information for display and view merging, if false the help system uses standard Navigator labels

See Also:

HTMLBrowser

Help

public Help(java.lang.Class htmlBrowserClass,
            boolean combineBooks,
            boolean useLabelInfo,
            boolean standAloneMode)

Creates an instance of the Help object with specified HTMLBrowser as the HTMLBrowser component used for topic display. Each instance of Help is displayed and managed separately. Applications should call this method only once and cache the Help reference for use in subsequent calls. This constructor contains an extra parameter enabling a "stand-alone" mode for running OHJ, where the Help object will exit the JVM (via System.exit) once all help windows have been closed. The stand-alone mode should be set to false if you are launching OHJ from a Java application (otherwise closing help would exit your application!).

Parameters:

htmlBrowserClass - the HTMLBrowser subclass to use as the topic display component

combineBooks - if true the help system will show all of the views from the Books added to the help system in one tab panel, if false the help sytem will create a different tab panel for each book

useLabelInfo - if true the help system uses the author defined label information for display and view merging, if false the help system uses standard Navigator labels

standAloneMode - if true the help system will exit the JVM when all help windows have been closed. This should be set to false if you are launching OHJ from your java application.

See Also:

HTMLBrowser

Help

public Help(java.lang.Class htmlBrowserClass,
            boolean combineBooks,
            boolean useLabelInfo,
            boolean standAloneMode,
            boolean dockedByDefault)

Creates an instance of the Help object with specified HTMLBrowser as the HTMLBrowser component used for topic display. Each instance of Help is displayed and managed separately. Applications should call this method only once and cache the Help reference for use in subsequent calls. This constructor contains an extra parameter enabling a "stand-alone" mode for running OHJ, where the Help object will exit the JVM (via System.exit) once all help windows have been closed. The stand-alone mode should be set to false if you are launching OHJ from a Java application (otherwise closing help would exit your application!).

Parameters:

htmlBrowserClass - the HTMLBrowser subclass to use as the topic display component

combineBooks - if true the help system will show all of the views from the Books added to the help system in one tab panel, if false the help sytem will create a different tab panel for each book

useLabelInfo - if true the help system uses the author defined label information for display and view merging, if false the help system uses standard Navigator labels

standAloneMode - if true the help system will exit the JVM when all help windows have been closed. This should be set to false if you are launching OHJ from your java application.

dockedByDefault - if true the help system displays with the Help Navigator and Topic Window initially docked

See Also:

HTMLBrowser

Help

public Help(java.applet.AppletContext appletContext,
            java.lang.String targetFrame,
            boolean combineBooks,
            boolean useLabelInfo)

Creates an instance of the Help object using the native browser as the topic display through the given applet context. Each instance of Help is displayed and managed separately. Applications should call this method only once and cache the Help reference for use in subsequent calls.

Note that using the native browser for topic display through an applet context results in the loss of many of OHJ's ICE Browser specific topic display features (toc syncing, popups, window-types, a-links, etc).

Parameters:

appletContext - the AppletContext to use to show topics in the native browser

targetFrame - the name of the target frame in the native browser to use when showing topics

combineBooks - if true the help system will show all of the views from the Books added to the help system in one tab panel, if false the help sytem will create a different tab panel for each book

useLabelInfo - if true the help system uses the author defined label information for display and view merging, if false the help system uses standard Navigator labels

See Also:

AppletContext

Method Detail

setHelpLocale

public static void setHelpLocale(java.util.Locale helpLocale)

Set the Locale used by the Oracle Help for Java classes for Locale sensitive operations and resource loading. Importantly, this method should be called before the Help object or any Book objects have been created. If the Locale is not set, or is set to null, Oracle Help for Java will use the system default Locale.

Most clients will want to use the system default Locale (the Locale that has been chosen by the end user on their operating system), in which case you will not need to call this method.

Parameters:

helpLocale - -- The Locale, if null, the system default Locale will be used.

getHelpLocale

public static java.util.Locale getHelpLocale()

Get the Locale currently being used by the Oracle Help for Java classes for Locale sensitive operations and resource loading.

Convenience wrapper for oracle.help.common.util.StaticLocaleContext.getLocale()

setHelpEncoding

public static void setHelpEncoding(java.lang.String helpEncoding)

Set the Character Set Encoding used by the Oracle Help for Java classes for reading in client help files. Importantly, this method should be called before any Book objects have been created. If the Character Set Encoding is not set, or is set to null, Oracle Help for Java will use the default encoding of the default Locale.

Most clients will want to use the default encoding of the default Locale (the Locale that has been chosen by the end user on their operating system), in which case you will not need to call this method.

Parameters:

helpEncoding - -- The name of a Java supported Character Set Encoding.

getHelpEncoding

public static java.lang.String getHelpEncoding()

Get the Character Set Encoding used by the Oracle Help for Java classes for reading in client help files. If null is returned, this indicates that the default encoding of the system default Locale is being used.

setIconImage

public void setIconImage(java.awt.Image iconImage)

Call this method to set a custom image for the window icons in the Oracle Help for Java windows.

Parameters:

iconImage - -- The Image to use as the icon for the Oracle Help for Java windows.

setVisible

public void setVisible(boolean visible)

Sets the visibility of the help system.

Parameters:

visible - if true the help system will show the Navigator Window, if false the help system will hide the navigator window and all topic windows

addBook

public void addBook(Book book)

Add a book to the help system's library.

Parameters:

book - the book to add to the help system's library

removeBook

public void removeBook(Book book)

Remove a book from the help system.

Parameters:

book - the book to remove from the help system's library

removeAllBooks

public void removeAllBooks()

Removes all books from the help system's library.

getBooks

public Book[] getBooks()

Get all of the Book objects currently in the help system's library.

Returns:

Book[] the books

getBookCount

public int getBookCount()

Returns the number of Book objects currently in the help system's library.

Returns:

int the book count

registerClientWindow

public static void registerClientWindow(java.awt.Window aWindow)

Clients should register Window instances with the Help object. This allows the Help object to track which window (among those registered) is active, if any. If the active window is a modal dialog and Help is requested, the Help object may take special action so that the help windows are not blocked by the active modal dialog. Note, users of Oracle's Look And Feel/JEWT toolkit do not need to explicitly call this method.

Parameters:

aWindow - the Window instance to register

unregisterClientWindow

public static void unregisterClientWindow(java.awt.Window aWindow)

Clients should unregister each Window instance that they registered with the registerClientWindow() method once the window will no longer be active. Failure to unregister windows may result in the window not being garbage collected.

Parameters:

aWindow - the Window to unregister

registerCustomProtocolHandler

public void registerCustomProtocolHandler(java.lang.String customProtocol,
                                          CustomProtocolHandler handler)

Registers a CustomProtocolHandler for a custom protocol Consider the following HTML: <a href="custom:protocolName:protocolValue"/> When OHJ follows links that link, it will check for any CustomProtocolHandlers registered by the identifier "protocolName." If it finds a CustomProtocolHandler, its handleValue method will be invoked, passing protocolValue as the value

showNavigatorWindow

public void showNavigatorWindow()

Show the Navigator Window

showNavigatorWindow

public void showNavigatorWindow(Navigator activeNavigator)

Show the Navigator Window with a specific Navigator displayed initially.

Parameters:

activeNavigator - -- the Navigator to show initially, if parameter is null, the Navigator Window will be shown with the previously selected Navigator displayed

showNavigatorWindow

public void showNavigatorWindow(Book activeBook)

Show the Navigator Window with the NavigatorTabPanel for the given Book initially displayed. If the Help object was created with the combineBooks flag set to false, a separate NavigatorTabPanel was created for each book that was added to the Help object. This version of the showNavigatorWindow method allows you to programmatically select which Book's tab panel is displayed initially.

If the Help object was created with combineBooks set to true, then the one and only tab panel will be displayed regardless of the book passed as a parameter.

Parameters:

activeBook - -- the Book object whose associated NavigatorTabPanel should be initially displayed when the Navigator Window is shown. The Book should have already been added to the Help system, if it has not been or if the parameter is null the previously selected NavigatorTabPanel will be initially displayed.

getAllNavigators

public Navigator[] getAllNavigators()

Get the Navigator objects displayed in the Navigator Window.

showTopic

public void showTopic(Book book,
                      java.lang.String topicID)
               throws oracle.help.topicDisplay.TopicDisplayException

Shows the given topic from the given book in a currently existing topic window. If no topic windows currently exist, a new window will be created with default size.

Parameters:

book - The book to show the topic from.

topicID - The topicID for the topic to show.

Throws:

oracle.help.topicDisplay.TopicDisplayException - if the specified topic cannot be displayed

showTopic

public void showTopic(Book book,
                      java.lang.String topicID,
                      boolean alwaysCreate)
               throws oracle.help.topicDisplay.TopicDisplayException

Shows the given topic from the given book. If 'alwaysCreate' is true, a new window will always be created; if it is false, a new window will only be created if no windows currently exist.

Parameters:

book - The book to show the topic from.

topicID - The topicID for the topic to show.

alwaysCreate - If true, always create a new window; if false, reuse a window if possible.

Throws:

oracle.help.topicDisplay.TopicDisplayException - if the specified topic cannot be displayed

showTopic

public void showTopic(Book book,
                      java.lang.String topicID,
                      boolean alwaysCreate,
                      java.awt.Point location,
                      java.awt.Dimension size)
               throws oracle.help.topicDisplay.TopicDisplayException

Shows the given topic from the given book. If 'alwaysCreate' is true, a new window will always be created; if it is false, a new window will only be created if no windows currently exist.

Parameters:

book - The book to show the topic from.

topicID - The topicID for the topic to show

alwaysCreate - If true, always create a new window; if false, reuse a window if possible.

location - Location of the topic window.

size - Size of the topic window.

Throws:

oracle.help.topicDisplay.TopicDisplayException - if the specified topic cannot be displayed

showHelp

public void showHelp(java.lang.Object book,
                     java.lang.String topicID,
                     java.awt.Component object)

Implements the HelpProvider interface from Oracle's EWT toolkit. This acts similarly to showTopic, with the following exceptions:

1. Passing a null topicID will cause the "default" topicID to be used.
2. Passing a null book will cause the "default" book to be used.
3. If any default being used is null, this call will instead act like a call to showContents.

Specified by:

showHelp in interface oracle.ewt.help.HelpProvider

Parameters:

book - The book to show the topic from.

topic - The topicID for the topic to show

object - the Component for which help is being displayed. Pass null if no Component is involved.

showHelp

public void showHelp(java.awt.Component component)

Implements the HelpProvider interface from Oracle's JEWT toolkit. This method should not be used by non-Oracle OHJ users. JEWT's HelpUtils class is used to identify the Book and topicID for the Component. If no topicID is associated with the component, the Navigator Window is shown.

Specified by:

showHelp in interface oracle.bali.ewt.help.HelpProvider

Parameters:

component - the Component for which help is being displayed.

setHelpOnHelp

public void setHelpOnHelp(java.net.URL helpOnHelpURL)

Calling this method with a valid URL parameter will enable the "Help on Help" menu option in the Help Navigator. When the menu option is selected, the html page at the specified URL will be displayed in the topic window.

Parameters:

helpOnHelpURL - The url of an html page to display for Help on Help.

setHelpOnHelp

public void setHelpOnHelp(Book book,
                          java.lang.String topicID)

Calling this method with valid book and topicID parameters will enable the "Help on Help" menu option in the Help Navigator. When the menu option is selected, the help topic mapped to this topicID will be displayed in the topic window.

Parameters:

book - the Book that contains the help on help topics (this book must have been added to the help system)

topicID - the topic id of the help topic to display for Help on Help

setDefaultBook

public void setDefaultBook(Book book)

Sets the default book for use with the showHelp methods. This book will be used when a null book is passed to showHelp.

Parameters:

book - The book to use as default.

setDefaultTopicID

public void setDefaultTopicID(java.lang.String topicID)

Sets the default topicID for use with the showHelp methods. This topic will be used when a null topicID is passed to showHelp.

Parameters:

topicID - The topicID to use as default.

dispose

public void dispose()

Dispose the help system. This method frees up all the resources used by the help system. Applications should call this method when they do not need help anymore. You should not call any methods on the Help object after calling dispose().

topicSelected

public void topicSelected(oracle.help.navigator.NavigatorEvent e)

Public method as a result of the NavigatorListener interface. Internal hook called when a Topic has been selected in the Navigator Window

Specified by:

topicSelected in interface oracle.help.navigator.NavigatorListener

topicActivated

public void topicActivated(oracle.help.navigator.NavigatorEvent e)

Public method as a result of the NavigatorListener interface. Internal hook called when a Topic has been activated in the Navigator Window

Specified by:

topicActivated in interface oracle.help.navigator.NavigatorListener

enableFavoritesNavigator

public void enableFavoritesNavigator(java.net.URL location)

Creates a Favorites Navigator using the file at location as the information to construct the navigator This method should be invoked after the construction of the Help object and before the help system is displayed

Parameters:

location -