com.sas.swing.util
Class SASJavaHelp

com.sas.swing.util.SASJavaHelp

public class SASJavaHelp

A wrapper class for JavaHelp that allows the Java developers internally here at SAS to invoke JavaHelp directly or through multiple accessor methods.

Usage

Instantiation

A developer can instantiate a SASJavaHelp object by using the Class Constructor SASJavaHelp(), or either of the three explicit constructors SASJavaHelp(String) or SASJavaHelp(String,Locale) or SASJavaHelp(String, Locale, LoggerFactoryInterface).

For 9.2, in order to support cross-docProduct links within the VJR a custom protocol handler had to be introduced to correctly resolve the cross-docProduct links based on ClassLoader and docProduct dependencies. This custom protocol handler was added by registering it with the System "java.protocol.handler.pkgs" property.

The SASJavaHelp() constructor is just used to instantiate the object and the object will not point to a 'docProduct' unless either the getHelpSet(String) method or setDocProduct(String) method is called. The SASJavaHelp(String) constructor points to the specified docProduct in the default Locale of the JVM. The SASJavaHelp(String,Locale) constructor points to the specified docProduct in the specified locale. Each of the three previous constructors will use a default Log4J logger for logging purposes. The SASJavaHelp(String,Locale,LoggerFactoryInterface) constructor allows the calling application to use a logger implementation for logging purposes. A 'docProduct' is the name given to a collection of documentation that describes partof an application, plug-in, or wizard. For example, the docProduct which covers the main part of SAS Management Console is referred to as 'console'; and, the docProduct which covers the New Library Wizard for Data Builder is referred to as 'newlibrary'. Each docProduct consists of the necessary files to display the documentation in the JavaHelp viewer. They include a helpset (.hs) file, map (.jhm) file, toc (.xml) file, and a keywords (.xml) file; all the html files that make up the documentation; a search database; and some necessary images. The locale is used in two different ways. Although the locale does say which locale the documentation should be displayed in, the string representation of the Locale object is used to help the SASJavaHelp object create the right directory path to the documentation product's helpset file.

Creating the Path to the HelpSet File

The SASJavaHelp object uses many parts to create the correct path to the docProduct's helpset file. First, the application's installation root must be on the ClassPath during run-time. This is vital because without the installation root on the ClassPath, the SASJavaHelp object will not be able to find the documentation. The install process for your application should take care of this. Second, the docProduct's will be installed, for your application, as Jar files in the VJR. Since there are many docProducts for one application, the SASJavaHelp object builds the path to each one the same way. The path to the helpset file takes on the general form of 'doc/<string representation of the locale>/<docProduct>/config/<docProduct>.hs'. Depending on the Locale of the object we can have multiple copies of the same docProduct for an application.

• For example:
  • If the Locale is English, the directory structure would be: doc/en/<docProduct>/config/<docProduct>.hs
  • If the Locale was Japanese, the directory structure would be: doc/ja/<docProduct>/config/<docProduct>.hs
  • If the Locale was French Canadian, the directory structure would be: doc/fr_CA/<docProduct>/config/<docProduct>.hs
  • But for each Locale that the application is translated for, a 'locale directory' should exist.

The calling application can also set a default ClassLoader for the SASJavaHelp object to use instead of the System ClassLoader. This is useful when multiple ClassLoaders are used for an application such as the 9.2 version of SMC and its many plug-ins. The plug-ins and their help are loaded with a different ClassLoader than the parent SMC application itself. This is accomplished by using the setDefaultClassLoader(ClassLoader) method before any of the Context-sensitive methods below are called. You must also set the default ClassLoader before you call any of these methods: showContext(String), showContext(String,String), showHelp(String), showHelp(String,String), or the getHelpSet(String) method if you wish to override the ClassLoader for the object.

The JavaHelp Viewer

The default JavaHelp viewer consists of a toolbar, content pane, and navigation pane. The toolbar is made up of previous/next topic buttons and print/printer set-up buttons. The content pane, found on the right side, uses HTML 3.2 as its format for displaying topics. The navigation pane, found on the left side, is usually made up of a TOC, Index, and Full-text Search. Each of these is represented by a tab. All or some of these navigators can be left out. This simplifies the navigation pane but does not allow the user to use the hidden tabs.

Displaying Help from the Application

After instantiation, the developer may add Context-sensitive help to their application. Context-sensitive help is information provided to users based on the context of the task in which they are involved. The three kinds of Context-sensitive help the SASJavaHelp object provides delivery mechanisms for is:

• Window-level Help: Allows users to obtain information about container objects such as application windows and dialog boxes that have the focus, usually displayed by pressing the F1 key. Can be added by the enableHelpKey(Component,String,String) method.
• Help Button: Provides help to users about specific tasks or objects, usually displayed by clicking on a button. Can be added by either the enableHelpOnClick(Component,String,String) or enableContextOnClick(Component,String,String) methods.
• Menu Item: Provides help to users about specific tasks or objects, usually displayed by choosing a menu item. Can be added by either the enableHelpOnClick(Component,String,String) or enableContextOnClick(Component,String,String) methods.
• These three methods attach an ActionListener to the component which displays the appropriate topic when the action is performed; therefore, the developer does not have to code for that.

If the developer chooses to have their own ActionListeners for the components, the SASJavaHelp object provides methods which will display the help without attaching an ActionListener to the component. These methods are:

• showContext(String)
• showContext(String,String)
• showHelp(String)
• showHelp(String,String)

Finally, if the developer chooses to use extra functionality not provided by the SASJavaHelp object, they can use the DefaultHelpBroker instance of the object to perform the desired extra functionaility. They can get the DefaultHelpBroker object by the getDefaultHelpBroker() method. They may also use the HelpSet object, getHelpSet() or getHelpSet(String), to get extra functionaility.

Behavior

The SASJavaHelp object encapsulates all the necessary Sun Microsystems JavaHelp API calls into one central class. This allows the developers to concentrate more on the source code for their application than the source code to call the help.

Field Summary

static java.lang.String

RB_KEY

Constructor Summary

SASJavaHelp()
Creates a null SASJavaHelp object.

SASJavaHelp(java.lang.String docProduct)
Creates a SASJavaHelp object which points at a documentation product in the default locale directory.

SASJavaHelp(java.lang.String docProduct, java.util.Locale appLocale)
Creates a SASJavaHelp object which points at a documentation product in the specified locale directory.

Method Summary

void	enableContextOnClick(java.awt.Component comp, java.lang.String docProd, java.lang.String id) Add an ActionListener to the component and set the documentation product and mapID to be displayed.
void	enableHelpKey(java.awt.Component comp, java.lang.String docProd, java.lang.String id) Enable the F1 key on a component.
void	enableHelpOnClick(java.awt.Component comp, java.lang.String docProd, java.lang.String file) Add an ActionListener to the component and set the documentation product and html file to be displayed.
java.awt.Window	getActivationWindow() Return the activation window for the JavaHelp presentation of this object.
javax.help.DefaultHelpBroker	getDefaultHelpBroker() Return the DefaultHelpBroker of this object.
java.lang.String	getDocProduct() Return the documentation product name of this object.
void	getHelpInfo() Print out all the JavaHelp information for this object.
javax.help.HelpSet	getHelpSet() Return the HelpSet file of this object.
javax.help.HelpSet	getHelpSet(java.lang.String docProd) Return the HelpSet file for the documentation product.
java.util.Locale	getLocale() Return the locale of this object.
java.awt.Point	getLocation() Return the point of the JavaHelp browser for this object.
java.awt.Dimension	getSize() Return the size of the JavaHelp browser for this object.
void	setActivationWindow(java.awt.Window window) Set the activation window for the DefaultHelpBroker of this object.
void	setDefaultHelpBroker(javax.help.DefaultHelpBroker broker) Set the DefaultHelpBroker of this object.
void	setDocProduct(java.lang.String docProductName) Set the documentation product name of this object.
void	setHelpSet(javax.help.HelpSet hs) Set the HelpSet file of this object.
void	setLocale(java.util.Locale loc) Set the locale for this object.
void	setLocation(java.awt.Point point) Set the top-left corner of the JavaHelp browser for this object measured from the screen origin.
void	setSize(java.awt.Dimension dim) Set the size of the JavaHelp browser for this object.
void	showContext(java.lang.String mapID) Display the mapID in the right-side of the viewer.
void	showContext(java.lang.String docProd, java.lang.String mapID) Display the mapID for the documentation product.
void	showHelp(java.lang.String file) Display the file in the right-side of the viewer.
void	showHelp(java.lang.String docProd, java.lang.String file) Display the file for the documentation product.

Field Detail

RB_KEY

public static final java.lang.String RB_KEY

See Also:

Constant Field Values

Constructor Detail

SASJavaHelp

public SASJavaHelp()

Creates a null SASJavaHelp object. The documentation product is set to null, and the locale is set to the default locale of the Java Virtual Machine. The object will not point to a documentation product until either the setDocProduct(String) or the getHelpSet(String) methods are called. A default Log4J logger will be used for logging purposes.

See Also:

setDocProduct(String), setLocale(Locale), getHelpSet(String), setLoggerFactory(LoggerFactoryInterface)

SASJavaHelp

public SASJavaHelp(java.lang.String docProduct)

Creates a SASJavaHelp object which points at a documentation product in the default locale directory. The default locale directory is set to the default locale of the Java Virtual Machine. A default Log4J logger will be used for logging purposes.

Parameters:

docProduct - the product to display documentation for

See Also:

setLocale(Locale), setLoggerFactory(LoggerFactoryInterface)

SASJavaHelp

public SASJavaHelp(java.lang.String docProduct,
                   java.util.Locale appLocale)

Creates a SASJavaHelp object which points at a documentation product in the specified locale directory. A default Log4J logger will be used for logging purposes.

Parameters:

docProduct - the product to display documentation for

appLocale - the locale the documentation should be displayed in; Also corresponds to a portion of the path to the HelpSet file

See Also:

setLoggerFactory(LoggerFactoryInterface)

Method Detail

showHelp

public void showHelp(java.lang.String docProd,
                     java.lang.String file)

Display the file for the documentation product. The argument docProd may be null, but the documentation product for the SASJavaHelp object has to be set either by the constructor, setDocProduct(String) method, or getHelpSet(String) method. A default ClassLoader can be set using the setDefaultClassLoader(ClassLoader) method which allows the SASJavaHelp object to search for the file using a ClassLoader other than the System ClassLoader. If the file exists, initialize the right-side of the viewer. If the file does not exist, or is null, try to display the default homeID or another suitable TOCItem of the documentation product. Another TOCItem will be displayed if switching documentation products (HelpSets), there is a bug in the JavaHelp API that does not allow the browser to display the homeID of another HelpSet. So in that case, the next suitable TOCItem is highlighted and displayed.

Parameters:

docProd - the documentation product the html file exists in

file - the html file to display on the right-side of the viewer

See Also:

showHelp(String), setDocProduct(String), getHelpSet(String), setDefaultClassLoader(ClassLoader)

showHelp

public void showHelp(java.lang.String file)

Display the file in the right-side of the viewer. If it does not exist or is null, try to display the homeID or another suitable TOCItem of the current documentation product.

NOTE: The documenation product must be set by either a constructor call, setDocProduct(String) method call, or getHelpSet(String) method call. A default ClassLoader can be set using the setDefaultClassLoader(ClassLoader) method which allows the SASJavaHelp object to search for the file using a ClassLoader other than the System ClassLoader. This is to help the object find the appropriate file.

Parameters:

file - the html file to display on the right-side of the viewer

See Also:

showHelp(String, String), setDocProduct(String), getHelpSet(String), setDefaultClassLoader(ClassLoader)

showContext

public void showContext(java.lang.String docProd,
                        java.lang.String mapID)

Display the mapID for the documentation product. The mapID is a unique id referenced by the target parameter in the map(.jhm) file. The argument docProd may be null, but the documentation product for the SASJavaHelp object has to be set either by the constructor, the setDocProduct(String) method, or getHelpSet(String) method. A default ClassLoader can be set using the setDefaultClassLoader(ClassLoader) method which allows the SASJavaHelp object to search for the mapID using a ClassLoader other than the System ClassLoader. If the mapID exists, initialize the right-side of the viewer. If the mapID does not exists, or is null, try to display the default homeID or another suitable TOCItem of the documentation product. Another TOCItem will be displayed if switching documentation products (HelpSets), there is a bug in the JavaHelp API that does not allow the browser to display the homeID of another HelpSet. So in that case, the next suitable TOCItem is highlighted and displayed.

Parameters:

docProd - the documentation product the mapID exists in

mapID - the id corresponding to a topic in the Map file of the documentation product

See Also:

showContext(String), setDocProduct(String), getHelpSet(String), setDefaultClassLoader(ClassLoader)

showContext

public void showContext(java.lang.String mapID)

Display the mapID in the right-side of the viewer. If it does not exist or is null, try to display the homeID or another suitable TOCItem of the current documentation product.

NOTE: The documentation product must be set by either a constructor call, setDocProduct(String) method call, or getHelpSet(String) method call. A default ClassLoader can be set using the setDefaultClassLoader(ClassLoader) method which allows the SASJavaHelp object to search for the mapID using a ClassLoader other than the System ClassLoader. This is to help the object find the appropriate mapID.

Parameters:

mapID - an id to display on the right-side of the viewer

See Also:

showContext(String, String), setDocProduct(String), getHelpSet(String), setDefaultClassLoader(ClassLoader)

getHelpInfo

public void getHelpInfo()

Print out all the JavaHelp information for this object. Actually calls the printHelpInfo method with a value of null.

enableHelpKey

public void enableHelpKey(java.awt.Component comp,
                          java.lang.String docProd,
                          java.lang.String id)
                   throws java.lang.IllegalArgumentException

Enable the F1 key on a component. The F1 key is the standard help key for the JavaHelp API. This method works best when the component is the rootPane of a JFrame in Swing or java.awt.Window (or subclass) in AWT. This method sets the default mapID and the documentation product for the Component and registers keyboard actions to trap the "F1" keypress. docProd may be null, but the documentation product must be set by either the constructor, setDocProduct(String) method, or getHelpSet(String) method. id may be null; if so, a suitable TOCItem or the homeID of the documenation product will be displayed. A default ClassLoader can be set using the setDefaultClassLoader(ClassLoader) method which allows the SASJavaHelp object to search for the id using a ClassLoader other than the System ClassLoader.

Parameters:

comp - the component to display help for

docProd - the documentation product the mapID is in. May be null, if a doc product has already been set

id - the mapID to display for this component. May be null

Throws:

java.lang.IllegalArgumentException - if comp is null

See Also:

setDocProduct(String), getHelpSet(String), setDefaultClassLoader(ClassLoader)

enableContextOnClick

public void enableContextOnClick(java.awt.Component comp,
                                 java.lang.String docProd,
                                 java.lang.String id)
                          throws java.lang.IllegalArgumentException

Add an ActionListener to the component and set the documentation product and mapID to be displayed. When an action is performed, mainly a single mouse-click on a JButton or JMenuItem, display the docProd and id in the JavaHelp viewer. The component can not be null, and must be an instance of JButton or JMenuItem. If docProd is null and a documentation product has not been set by either a constructor call, the setDocProduct(String) method, or getHelpSet(String) method, an error is generated. If the id is null or invalid, a valid mapID will be displayed.

NOTE: The difference between this method and enableHelpOnClick(Component,String,String) is that enableHelpOnClick takes an actual html filename (minus the .html) as the last String parameter. This method, on the other hand, takes a mapID, which is a unique id referenced by the target parameter in the map(.jhm) file.

A default ClassLoader can be set using the setDefaultClassLoader(ClassLoader) method which allows the SASJavaHelp object to search for the id using a ClassLoader other than the System ClassLoader.

Parameters:

comp - the component to attach the ActionListener too

docProd - the documentation product the id resides in. May be null; if a doc product has been set already

id - the mapID to be displayed. May be null

Throws:

java.lang.IllegalArgumentException - if comp is null or not an instance of JButton or JMenuItem

See Also:

enableHelpOnClick(Component,String,String), setDocProduct(String), getHelpSet(String), setDefaultClassLoader(ClassLoader)

enableHelpOnClick

public void enableHelpOnClick(java.awt.Component comp,
                              java.lang.String docProd,
                              java.lang.String file)
                       throws java.lang.IllegalArgumentException

Add an ActionListener to the component and set the documentation product and html file to be displayed. When an action is performed, mainly a single mouse-click on a JButton or JMenuItem, display the documentation product and html file in the JavaHelp viewer. The component can not be null, and must be an instance of JButton or JMenuItem. If docProd is null and a documentation product has not been set by either a constructor call, the setDocProduct(String) method, or getHelpSet(String) method, an error is generated. If the file is null or invalid, a valid html file will be displayed.

NOTE: The difference between this method and enableContextOnClick(Component,String,String) is that enableContextOnClick takes an actual mapID as the last String parameter. This method, on the other hand, takes an html filename (minus the .html). A default ClassLoader can be set using the setDefaultClassLoader(ClassLoader) method which allows the SASJavaHelp object to search for the html file using a ClassLoader other than the System ClassLoader.

Parameters:

comp - the component to attach the ActionListener too

docProd - the documentation product the file resides in. May be null if a doc product has already been set

file - the html file to be displayed (minus the .html). May be null

Throws:

java.lang.IllegalArgumentException - if comp is null or not an instance of JButton or JMenuItem

See Also:

enableContextOnClick(Component,String,String), setDocProduct(String), getHelpSet(String), setDefaultClassLoader(ClassLoader)

setHelpSet

public void setHelpSet(javax.help.HelpSet hs)

Set the HelpSet file of this object. This method does not need to be called unless the developer wants to use this object to display other HelpSets not included in the 'doc' tree for their product.

The 'doc' tree is the directry where the product's documentation is installed.

To create a HelpSet object:

• Use the HelpSet.findHelpSet(ClassLoader,String) method to create a URL.
• Create the new HelpSet instance:
  • URL hsURL = HelpSet.findHelpSet( null, "newHelpSet.hs" );
  • HelpSet hs = new HelpSet( null, hsURL );

Can be used in conjunction with getDefaultHelpBroker() and Sun Microsystems' JavaHelp API to perform actions on these other HelpSets.

Parameters:

hs - this object's new HelpSet file

See Also:

getHelpSet(), getHelpSet(String), getDefaultHelpBroker()

getHelpSet

public javax.help.HelpSet getHelpSet()

Return the HelpSet file of this object.

Returns:

this object's HelpSet file

See Also:

setHelpSet(HelpSet), getHelpSet(String)

getHelpSet

public javax.help.HelpSet getHelpSet(java.lang.String docProd)

Return the HelpSet file for the documentation product. Creates a path to the .hs file while checking to make sure it exists; and if so, sets the HelpSet object, Path to the HelpSet, and URL to the HelpSet for this object. When creating the helpset path, this object first checks the full string representation of its Locale object. If a path can not be established, the object cycles through the different manifestations of the Locale. If the path can not be verfied with the different manifestations of the Locale, this object tries to create the helpset path using the English Locale. If a path can not be established, null is returned symbolizing that the path could not be parsed correctly, the .hs file did not exist, or the different manifestations of the Locale did not exist in the path. Null is also returned if the docProd argument is null and a documentation product has not been set for this object. If you do not specify a documentation product for this method, one will have to be assigned either by a constructor call or the setDocProduct(String) method. The current HelpSet file is returned if docProd is the same documentation product as the object's current one. If docProd is a different documentation product, this object will return a new HelpSet file corresponding to it, if a helpset path could be established. This object also allows a different ClassLoader to be set using the setDefaultClassLoader(ClassLoader) method, which this object will use instead of the System ClassLoader to try and establish a helpset path.

Parameters:

docProd - the documentation product

Returns:

the HelpSet file for the documentation product, current HelpSet file of this object, or null if the HelpSet file can not be found

See Also:

setDocProduct(String), setDefaultClassLoader(ClassLoader)

setLocale

public void setLocale(java.util.Locale loc)

Set the locale for this object. The string representation of loc is substituted in when this object searches for the HelpSet file. If this method is not called, the locale of this object is set to the default locale of the Java Virtual Machine by two of the constructors: SASJavaHelp() and SASJavaHelp(String). The third constructor, SASJavaHelp(String,Locale), explictly sets the locale for this object. This object cycles through the different manifestations of the loc to build a valid path, if a valid path can not be established, the locale of this object will be set to English.

Parameters:

loc - this object's new locale

See Also:

getLocale(), SASJavaHelp(), SASJavaHelp(String), SASJavaHelp(String,Locale)

getLocale

public java.util.Locale getLocale()

Return the locale of this object.

Returns:

this object's locale

See Also:

setLocale(Locale)

setDefaultHelpBroker

public void setDefaultHelpBroker(javax.help.DefaultHelpBroker broker)

Set the DefaultHelpBroker of this object.

Parameters:

broker - this object's new DefaultHelpBroker

See Also:

getDefaultHelpBroker()

getDefaultHelpBroker

public javax.help.DefaultHelpBroker getDefaultHelpBroker()

Return the DefaultHelpBroker of this object.

Returns:

this object's DefaultHelpBroker

See Also:

setDefaultHelpBroker(DefaultHelpBroker)

setDocProduct

public void setDocProduct(java.lang.String docProductName)

Set the documentation product name of this object. A documentation product (docProduct) is the name given to a collection of documentation that describes partof an application, plug-in, or wizard. This method is valid anytime the developer wants to change the documentation product of the object. Can be used in conjuction with the enableHelpKey(Component,String,String), enableHelpOnClick(Component,String,String), and enableContextOnClick(Component,String,String) methods when null is passed in as their docProd parameter.

Parameters:

docProductName - this object's new documenation product name

See Also:

getDocProduct(), enableHelpKey(Component,String,String), enableHelpOnClick(Component,String,String), enableContextOnClick(Component,String,String)

getDocProduct

public java.lang.String getDocProduct()

Return the documentation product name of this object.

Returns:

this object's documenation product name

See Also:

setDocProduct(String)

setActivationWindow

public void setActivationWindow(java.awt.Window window)

Set the activation window for the DefaultHelpBroker of this object. Used mainly to attach the JavaHelp presentation to modal dialogs so the JavaHelp presentation will depend on the state of the dialog. If window is not a modal dialog, then the JavaHelp presentation will act independently as a seperate frame.

Parameters:

window - this object's new window to attach the JavaHelp presentation too

See Also:

getActivationWindow()

getActivationWindow

public java.awt.Window getActivationWindow()

Return the activation window for the JavaHelp presentation of this object.

Returns:

this object's activation window

See Also:

setActivationWindow(Window)

setLocation

public void setLocation(java.awt.Point point)

Set the top-left corner of the JavaHelp browser for this object measured from the screen origin. Developers sometime set the JavaHelp browser to either side of their application so it will not be obscured. By default, the JavaHelp browser is initially displayed in the top-left corner of the screen and with a certain height/width. There is not a preferred help policy referring to help windows, but most developers like to either display the help window to the right of their application or directly in the center.

Parameters:

point - this object's new point to display the top-left corner of the JavaHelp browser; measured from the screen origin

See Also:

getLocation(), setSize(Dimension)

getLocation

public java.awt.Point getLocation()

Return the point of the JavaHelp browser for this object.

Returns:

this object's presentation point of the JavaHelp browser

See Also:

setLocation(Point), getSize()

setSize

public void setSize(java.awt.Dimension dim)

Set the size of the JavaHelp browser for this object. By default, the JavaHelp browser is initially displayed with ample viewing space, but more space may be desired.

Parameters:

dim - this object's new size for the JavaHelp browser

See Also:

getSize(), setLocation(Point)

getSize

public java.awt.Dimension getSize()

Return the size of the JavaHelp browser for this object.

Returns:

this object's size of the JavaHelp browser

See Also:

setSize(Dimension), getLocation()