com.jstatcom.component
Class JHelpAction

java.lang.Object
  javax.swing.AbstractAction
      com.jstatcom.component.JHelpAction

All Implemented Interfaces:

java.awt.event.ActionListener, java.io.Serializable, java.lang.Cloneable, java.util.EventListener, javax.swing.Action

public class JHelpAction
extends javax.swing.AbstractAction

This class provides an AbstractAction that is geared towards supporting the creation and display of JavaHelp sets. It should be constructed via the get*Instance static factory methods that create instances of this class with slightly different behaviour.

Usage note:
Because usually there is only one helpset loaded in an application, the HelpBroker is static and needs to be constructed first. Therefore the startHelpWorker method must be invoked before any help action can be carried out. It takes the name of the helpset as an argument and constructs the HelpBroker in a worker thread. This should be done at program start.

Author:

Markus Kraetzig

See Also:

Serialized Form

Field Summary

Fields inherited from interface javax.swing.Action

ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON

Method Summary

void	actionPerformed(java.awt.event.ActionEvent evt) Action method that is invoked, when an action event is catched.
static JHelpAction	getFocusInstance(java.lang.String name) Gets an instance of this class that invokes showHelpFromFocus in its actionPerformed method.
static JHelpAction	getFocusInstance(java.lang.String name, javax.swing.Icon icon) Same usage as getFocusInstance(String name) but with an icon.
static JHelpAction	getShowHelpInstance(java.lang.String name) Gets an instance of this class that invokes showHelp in its actionPerformed method.
static JHelpAction	getShowHelpInstance(java.lang.String name, javax.swing.Icon icon) Same usage as getShowHelpInstance(String name) but with an icon.
static JHelpAction	getShowIDInstance(java.lang.String name, javax.swing.Icon icon, java.lang.String helpID) Same usage as getShowIDInstance(String name, String helpID) but with an icon.
static JHelpAction	getShowIDInstance(java.lang.String name, java.lang.String helpID) Gets an instance of this class that invokes showHelp(helpID) in its actionPerformed method.
static JHelpAction	getTrackInstance(java.lang.String name) Gets an instance of this class that invokes trackFieldHelp in its actionPerformed method.
static JHelpAction	getTrackInstance(java.lang.String name, javax.swing.Icon icon) Same usage as getTrackInstance(String name) but with an icon.
static void	showHelp() Shows the helpset that has been initialized via startHelpWorker.
static void	showHelp(java.lang.String target) Shows the topic associated with target in the helpset that has been initialized via startHelpWorker.
static void	showHelpFromFocus() Shows the topic associated with the component that currently has focus in the helpset that has been initialized via startHelpWorker.
static void	startHelpWorker(java.util.List helpSetList) Creates a worker thread to initialize a HelpBroker object for a helpsets contained in helpSetList.
static void	startHelpWorker(java.lang.String hSetName) Creates a worker thread to initialize a HelpBroker object for a helpset specified by hSetName.
static void	trackFieldHelp() Shows the topic associated with the component that is clicked on with the mouse in the helpset that has been initialized via startHelpWorker.

Methods inherited from class javax.swing.AbstractAction

addPropertyChangeListener, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener, setEnabled

Methods inherited from class java.lang.Object

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

Method Detail

actionPerformed

public void actionPerformed(java.awt.event.ActionEvent evt)

Action method that is invoked, when an action event is catched.

Parameters:

evt - the action event

Throws:

java.lang.IllegalStateException - if HelpBroker was not initialized via startHelpWorker before

getFocusInstance

public static JHelpAction getFocusInstance(java.lang.String name)

Gets an instance of this class that invokes showHelpFromFocus in its actionPerformed method. When this action is invoked, the helptopic for the component that currently has focus is displayed, given that it has a valid helpID.

Parameters:

name - the name of the action, usually displayed as text in components accepting AbstractAction objects

Returns:

initialized action object that displays the helpset set by startHelpWorker

getFocusInstance

public static JHelpAction getFocusInstance(java.lang.String name,
                                           javax.swing.Icon icon)

Same usage as getFocusInstance(String name) but with an icon.

Parameters:

name - the name of the action, usually displayed as text in components accepting AbstractAction objects

icon - the icon to be displayed by components accepting this action

Returns:

initialized action object that displays the helpset set by startHelpWorker

getShowHelpInstance

public static JHelpAction getShowHelpInstance(java.lang.String name)

Gets an instance of this class that invokes showHelp in its actionPerformed method.

Parameters:

name - the name of the action, usually displayed as text in components accepting AbstractAction objects

Returns:

initialized action object that displays the helpset set by startHelpWorker

getShowHelpInstance

public static JHelpAction getShowHelpInstance(java.lang.String name,
                                              javax.swing.Icon icon)

Same usage as getShowHelpInstance(String name) but with an icon.

Parameters:

name - the name of the action, usually displayed as text in components accepting AbstractAction objects

icon - the icon to be displayed by components accepting this action

Returns:

initialized action object that displays the helpset set by startHelpWorker

getShowIDInstance

public static JHelpAction getShowIDInstance(java.lang.String name,
                                            java.lang.String helpID)

Gets an instance of this class that invokes showHelp(helpID) in its actionPerformed method. When this action is invoked, the helptopic associated with helpID is displayed.

Parameters:

name - the name of the action, usually displayed as text in components accepting AbstractAction objects

helpID - the identifier for the helptopic to display, must be a valid target, for example html.var_modeling

Returns:

initialized action object that displays the helpset set by startHelpWorker

getShowIDInstance

public static JHelpAction getShowIDInstance(java.lang.String name,
                                            javax.swing.Icon icon,
                                            java.lang.String helpID)

Same usage as getShowIDInstance(String name, String helpID) but with an icon.

Parameters:

name - the name of the action, usually displayed as text in components accepting AbstractAction objects

icon - the icon to be displayed by components accepting this action

helpID - the identifier for the helptopic to display, must be a valid target, for example html.var_modeling

Returns:

initialized action object that displays the helpset set by startHelpWorker

getTrackInstance

public static JHelpAction getTrackInstance(java.lang.String name)

Gets an instance of this class that invokes trackFieldHelp in its actionPerformed method. When this action is invoked, the helptopic for the component that is clicked on next is displayed, given that it has a valid helpID. The mouse pointer changes during that operation. This is useful for displaying context sensitive help.

Parameters:

name - the name of the action, usually displayed as text in components accepting AbstractAction objects

Returns:

initialized action object that displays the helpset set by startHelpWorker

getTrackInstance

public static JHelpAction getTrackInstance(java.lang.String name,
                                           javax.swing.Icon icon)

Same usage as getTrackInstance(String name) but with an icon.

Parameters:

name - the name of the action, usually displayed as text in components accepting AbstractAction objects

icon - the icon to be displayed by components accepting this action

Returns:

initialized action object that displays the helpset set by startHelpWorker

showHelp

public static void showHelp()

Shows the helpset that has been initialized via startHelpWorker.

Throws:

java.lang.IllegalStateException - if HelpBroker was not initialized via startHelpWorker before

showHelp

public static void showHelp(java.lang.String target)

Shows the topic associated with target in the helpset that has been initialized via startHelpWorker.

Parameters:

target - the help ID to display

Throws:

java.lang.IllegalStateException - if HelpBroker was not initialized via startHelpWorker before

showHelpFromFocus

public static void showHelpFromFocus()

Shows the topic associated with the component that currently has focus in the helpset that has been initialized via startHelpWorker. If the component does not have a valid help ID, the default topic is displayed.

Throws:

java.lang.IllegalStateException - if HelpBroker was not initialized via startHelpWorker before

startHelpWorker

public static void startHelpWorker(java.lang.String hSetName)

Creates a worker thread to initialize a HelpBroker object for a helpset specified by hSetName.

This method should be called at program start to prepare the helpset for display. Usually it should only be called once. All other methods rely on the availability of the HelpBroker object created by this method. this method.

Parameters:

hSetName - the name of the helpset to statically initialize JHelpAction with, must be a valid filename that can be transformed to a URL, usually stated relative to the resource directory of this class

Throws:

java.lang.IllegalArgumentException - if (hSetName == null)

startHelpWorker

public static void startHelpWorker(java.util.List helpSetList)

Creates a worker thread to initialize a HelpBroker object for a helpsets contained in helpSetList. All helpsets are merged dynamically.

This method should be called at program start to prepare the helpset for display. Usually it should only be called once. All other methods rely on the availability of the HelpBroker object created by this method.

Parameters:

helpSetList - the list containing all helpsets to merge and load

Throws:

java.lang.IllegalArgumentException - if (helpSetList == null)

trackFieldHelp

public static void trackFieldHelp()

Shows the topic associated with the component that is clicked on with the mouse in the helpset that has been initialized via startHelpWorker. If the component does not have a valid help ID, the default topic is displayed. This operation is useful for implementing context sensitive help.

Throws:

java.lang.IllegalStateException - if HelpBroker was not initialized via startHelpWorker before