oracle.help.viewer
Class Viewer

java.lang.Object
  |
  +--oracle.help.viewer.Viewer

All Implemented Interfaces:

java.util.EventListener, oracle.help.navigator.NavigatorListener

public class Viewer

extends java.lang.Object

implements oracle.help.navigator.NavigatorListener

The Viewer class provides a stand-alone application for displaying large sets of HTML documentation.

While the Help class (the default OHJ implementation) is meant for displaying context sensitive help for an application, the Viewer class is an alternative implementation that is specialized for stand-alone display of large sets of HTML documentation.

The Viewer class displays HTML content in a page size, docked window by default. It also provides the ability to view certain topics in an external browser. This can be done at both authoring time and run time. The author can specify that a link should be shown in an external browser by using an OHJ protocol (prepending "external:" to a link). Not that this "external:" protocol only works in the Helpset Viewer, and not ordinary OHJ deployments. At runtime, the user can choose to launch a help topic in an external browser by pressing the "View in External Browser" button. Also, all .pdf files will automatically be shown in an external browser.

The user may edit preferences to specify which external browser should be used, if any at all. These preferences may be loaded from and stored to an .xml file if a valid path is given at the command line.

The ViewerApplication class provides a harness for launching the Viewer from the command line.

You may also create and control an instance of the Viewer programmatically. The Viewer API is very similar to that of the Help object. The APIs supported by this class can be divided into following categories :

• APIs to add and remove Book objects from the Viewer
• APIs to show particular topics
• APIs to control the Viewer user interface

Book objects

Applications populate the Viewer object with HTML content via Book objects. Book objects contain the information that the Viewer needs to display the documentation. Book objects can be added or removed from the Viewer 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.

Showing topics

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

Viewer User Interface

The Viewer 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.

See Also:

Book

Field Summary

static java.lang.String	BROWSER_PATH
static java.lang.String	EXTERNAL_ENABLED
static java.lang.String	USE_DEFAULT_BROWSER

Constructor Summary

Viewer(java.net.URL openingPage, boolean standAloneMode)
Creates an instance of the Viewer object with ViewerICEBrowser as the HTMLBrowser component used for topic display.

Viewer(java.net.URL openingPage, boolean combineBooks, boolean useLabelInfo, boolean standAloneMode)
Creates an instance of the Viewer object with ViewerICEBrowser as the HTMLBrowser component used for topic display.

Method Summary

void	addBook(Book book) Add a book to the Viewer's library.
void	dispose() Dispose the Viewer.
Navigator[]	getAllNavigators() Get the Navigator objects displayed in the Navigator Window.
int	getBookCount() Returns the number of Book objects currently in the Viewer's library.
Book[]	getBooks() Get all of the Book objects currently in the Viewer'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.
void	removeAllBooks() Removes all books from the Viewer's library.
void	removeBook(Book book) Remove a book from the Viewer.
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 Viewer 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 Viewer.
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.

Methods inherited from class java.lang.Object

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

Field Detail

EXTERNAL_ENABLED

public static final java.lang.String EXTERNAL_ENABLED

USE_DEFAULT_BROWSER

public static final java.lang.String USE_DEFAULT_BROWSER

BROWSER_PATH

public static final java.lang.String BROWSER_PATH

Constructor Detail

Viewer

public Viewer(java.net.URL openingPage,
              boolean standAloneMode)

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

Parameters:

openingPage - the page which should be displayed upon starting up the application

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

See Also:

oracle.help.htmlBrowser.ViewerICEBrowser

Viewer

public Viewer(java.net.URL openingPage,
              boolean combineBooks,
              boolean useLabelInfo,
              boolean standAloneMode)

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

Parameters:

openingPage - the page which should be displayed upon starting up the application

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 Viewer will exit the JVM when all Viewer have been closed. This should be set to false if you are launching the Viewer from your java application.

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.

Convenience wrapper for import oracle.help.common.util.java.StaticLocaleContext 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 import oracle.help.common.util.java.StaticLocaleContext method

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.

Convenience wrapper for import oracle.help.common.util.java.StaticLocaleContext 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.

Convenience wrapper for import oracle.help.common.util.java.StaticLocaleContext method

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

Parameters:

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

addBook

public void addBook(Book book)

Add a book to the Viewer's library.

Parameters:

book - the book to add to the Viewer's library

removeBook

public void removeBook(Book book)

Remove a book from the Viewer.

Parameters:

book - the book to remove from the Viewer's library

removeAllBooks

public void removeAllBooks()

Removes all books from the Viewer's library.

getBooks

public Book[] getBooks()

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

Returns:

Book[] the books

getBookCount

public int getBookCount()

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

Returns:

int the book count

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 Viewer object was created with the combineBooks flag set to false, a separate NavigatorTabPanel was created for each book that was added to the Viewer object. This version of the showNavigatorWindow method allows you to programmatically select which Book's tab panel is displayed initially. If the Viewer 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 Viewer, 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

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 Viewer 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

dispose

public void dispose()

Dispose the Viewer. This method frees up all the resources used by the Viewer. Applications should call this method when they do not need help anymore. You should not call any methods on the Viewer 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