Using CSHManager to Implement Context-Sensitive Help
OHJ's CSHManager class provides a generic way to associate help topics with user interface controls and to launch context-sensitive help when the end user presses the F1 key or selects Help from a right-click context menu. OHJ also provides an API for explicitly displaying the help topic associated with a component.
The following sections provide an introduction to using CSHManager. For more information, see the API documentation for oracle.help.CSHManager.
You should create an instance of the CSHManager class before creating user interface components. The CSHManager constructor is summarized below.
CSHManager() Constructor
CSHManager(Help help)
Creates a new instance of the CSHManager class. All the subsequent calls to this manager object will use the specified Help object.
Parameters:
help - The Help object to be used for displaying help.
Setting the Default Book
If you only have one Book of help content, you may want to use the setDefaultBook() method to define it as the default book for context-sensitive help. This allows you to call the addComponent() method (described below) without entering the book parameter.
setDefaultBook() Method
setDefaultBook(Book book)
Sets the specified Book as the default Book. This will be as used the default Book for components registered without a specified Book.
Parameters:
book - The Book to be set.
If you have more than one Book, the default Book will only be used for those components for which you have not assigned a specific Book. In a multiple Book help system, you should, in general, assign specific Books to your components.
Associating Topic IDs with User Interface Components
Use the addComponent() method to associate topic IDs (as defined in the map file) with Java user interface components. You will have to call one of the versions of this method for each component that requires context-sensitive help.
addComponent() Method
addComponent(Component component, String topicId)
Registers a component with the help manager.
The default Book is used for looking up the topicId. If no default Book is registered at the time of calling this method, then the component is not registered with the help manager, and help will not be shown if showHelpForComponent() is later called for this component.
For components registered using this method, CSHManager will not display help in response to an F1 key press or a right mouse-click event.
Parameters:
component - The component to be added.
topicId - The topic ID to associate with this component.
addComponent(Component component, Book book, String topicId)
Registers a component with the help manager. The provided book is used for looking up the topicId.
For components registered using this method, CSHManager will not display help in response to an F1 key press or right mouse-click event.
Parameters:
component - The component to be added
book - The Book containing the help topic.
topicId - The topic ID to associate with this component
The default Book is used for looking up the topicId. If no default Book is registered at the time of calling this method, the component is not registered with the help manager, and help will not be shown if showHelpForComponent() is later called for this component.
Parameters:
component - The component to be added.
topicId - The author-defined topic ID to be associated with this component
needF1Help - If true, displays help for this component in response to F1 key press events
needPopupHelp - If true, displays a Help pop-up menu upon right mouse click and launches context-sensitive help if the Help menu item is selected
addComponent(Component component, Book book, String topicId, boolean needF1Help, boolean needPopupHelp)
Registers a component with the help manager. The provided book is used for looking up the topicId.
Parameters:
component - The component to be added
book - The Book containing the help topic.
topicId - The topic ID to be associated with this component
needF1Help - If true, displays help for this component in response to F1 key press events
needPopupHelp - If true, displays a Help pop-up menu upon right mouse click and launches context-sensitive help if the Help menu item is selected
Explicitly Showing Help for Components
Call the showHelpForComponent() method on the CSHManager when you explicitly want to display the help topic associated with a component. For example, if you want to launch context-sensitive help when the user presses a Help button in a dialog box, you could call this method in the button's event handler.
showHelpForComponent() Method
showHelpForComponent(Component component)
Shows help for the specified component. If the specified component was not registered via addComponent(), no help will be shown.
