com.tivoli.twg.console
Class TWGHelpContext

java.lang.Object
  extended bycom.tivoli.twg.console.TWGHelpContext

public class TWGHelpContext
extends java.lang.Object

This class is used for all Director help associations. A help context provides the base structure to allow task frames and other windows to associate a specific help panel with a specific frame window or dialog. A component would create one instance of this class for their use, passing in the instance of the main gui and the name of the mapping file to use to locate the correct HTML file for a specific topic ID. This context is then used to associate help to components using addHelp().

TWGTaskFrame will automatically create a help context if the task has specified the helpTopicsMapping attribute in the tasks property file. The helpTopicsMapping property specifies another property file that will contain the mappings of help topics to html help files. A TWGTaskFrame instance only has to request its context using getHelpContext() and it can then associate help with any of the components within the frame by using addHelp() on that context. Note that help cannot be specified directly on the frame itself, but must be set on a component with the frame. When F1 is pressed while that frame has focus, help is then invoked. Additionally, if help is associated with a button or menu, then pressing that button or selecting that menu will invoke help.

See Also:
TWGDynamicHelp, TWGTaskFrame

Constructor Summary
TWGHelpContext(com.tivoli.twg.console.TWGMainGUI gui, java.lang.String bundleName)
          A help instance is used to locate the appropriate html file to display based on the locale.
 
Method Summary
 void addHelp(javax.swing.JComponent comp, java.lang.String topicID)
          Register a help listener to initiate a help event for this component.
 java.lang.String getBundle()
          Convenience method for retrieving the help context's resource bundle.
static java.lang.String getHelpNLSDirectory(boolean full)
          Determine the language name to use as the directory for loading the HTML files from.
static java.net.URL getValidNLSHelpURL(java.lang.String htmlFile)
          Find the closest matching valid URL to load the help files file.
 void launchHelp(java.lang.String bundleName, java.lang.String topicID)
          Launch the help window (if not already showing) and use the specified bundle and topic ID as the page to show.
 void removeHelp(javax.swing.JComponent comp)
          Unregister the help listener that would initiate a help event if the component specified (or the window it is in) has the focus.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

TWGHelpContext

public TWGHelpContext(com.tivoli.twg.console.TWGMainGUI gui,
                      java.lang.String bundleName)
A help instance is used to locate the appropriate html file to display based on the locale. Each help instance has a resource bundle that is used to map the topic ids to the html files. This bundle will find the appropriate file based on the topic id requested and the current locale.

Parameters:
gui - The instance of the main console controller. If null, then we launch help using a default size each time. If non-null, we can query the previous size and location used to display the help window.
bundleName - The name of the resource bundle that contains the mappings of the topic IDs to the html file names. This file is in the same format as a regular properties file.
Method Detail

addHelp

public void addHelp(javax.swing.JComponent comp,
                    java.lang.String topicID)
Register a help listener to initiate a help event for this component. If the component specified is a button or a menu item, an action listener is registered with the component. This means a help event is generated if the button is pressed or if that menu item is selected. If the component is not a button or menu item, then register F1 as the key that will initiate a help event if the component specified (or the window it is in) has the focus. The help event will contain the topicID as event data.

Parameters:
comp - The component to register the help for.
topicID - Identifies the help panel to bring up when help is requested. If NULL is set, then dynamic help is setup for the component and the component will be queried for the topic ID (and optionally a different mapping file) when help is requested.

removeHelp

public void removeHelp(javax.swing.JComponent comp)
Unregister the help listener that would initiate a help event if the component specified (or the window it is in) has the focus. This will unregister the action listener or keyboard action depending on which kind of listener was originally setup.


launchHelp

public void launchHelp(java.lang.String bundleName,
                       java.lang.String topicID)
Launch the help window (if not already showing) and use the specified bundle and topic ID as the page to show. If the help window is already up, then just change the page to the one specified. Make sure we look up the html file from the correct locale location.

Parameters:
bundleName - The name of the resource bundle that is searched for the topic ID specified.
topicID - The name of the topic ID to search for in the resource bundle specified. This topic will be matched with an HTML file which is used as the visible page for the help window.

getBundle

public java.lang.String getBundle()
Convenience method for retrieving the help context's resource bundle.

Returns:
A string containing the name of the resource bundle.

getHelpNLSDirectory

public static java.lang.String getHelpNLSDirectory(boolean full)
Determine the language name to use as the directory for loading the HTML files from.

Parameters:
full - If true, then use both language and country locale additions. Otherwise, just use language modifiers in the search.
Returns:
A string containing the name of the directory to add to the base documentation directory in order to locate the correct HTML files for the locale.

getValidNLSHelpURL

public static java.net.URL getValidNLSHelpURL(java.lang.String htmlFile)
Find the closest matching valid URL to load the help files file. Use the same strategy that resource bundles follow to navigate up the chain. If a valid URL cannot be found, return null.

Parameters:
htmlFile - The base name of the help file to be loaded.
Returns:
A URL that can be used to load the help.