org.crosswire.common.swing

## Class ActionFactory

- java.lang.Object
- - org.crosswire.common.swing.ActionFactory

- All Implemented Interfaces:
    ActionListener, EventListener, Actionable

      public class ActionFactory
      extends Object
      implements ActionListener, Actionable

  The ActionFactory is being radically updated. Take the following with a grain of salt. The ActionFactory is responsible for creating CWActions and making them available to the program. Each Action is constructed from resources of the form: ActionName.field=value where ActionName is the ACTION_COMMAND_KEY value and field is one of the CWAction constants, e.g. LargeIcon.
  Field is one of:
  - Name - This is required. The value is used for the text of the Action.
    A mnemonic can be specified by preceding the letter with _. Using this letter in a case insensitive search, the earliest position of that letter will cause the it to be underlined. In a platform dependent way it provides a keyboard mechanism to fire the action. For example, on Windows, alt + mnemonic will cause a visible, active element with that mnemonic to fire. For this reason, it is important to ensure that two visible, active elements do not have the same mnemonic.
    Note: Mnemonics are suppressed on MacOSX.
  - ToolTip - A tip to show when the mouse is over an element. If not present, Name is used. This is likely to change. It is redundant to show a tooltip that is identical to the shown text.
  - SmallIcon - A 16x16 pixel image to be shown for the item. The value for this is a path which can be found as a resource.
    Note: the small icon will be used when actions are tied to menu items and buttons.
  - LargeIcon - A 24x24 pixel image to be shown for the item when large items are shown. Currently, these are only used for the ToolBar, when a large toolbar is requested. The value is a resource path to the image.
  - AcceleratorKey - A key on the keyboard, which may be specified with 0x25 kind of notation.
    Accelerators are global key combinations that work within an application to fire the action. When the action is shown as a menu item the accelerator will be listed with the name. Note: The accelerator key and it's modifiers are converted into a `KeyStroke` with `KeyStroke.getKeyStroke(key, modifierMask);`
  - AcceleratorKey.Modifier - A comma separated list of ctrl, alt, and shift, indicating what modifiers are necessary for the accelerator.
    Note: ctrl will use a platform's command key. On MacOSX this is the Apple/Command key. Other platforms use Ctrl.
  - Enabled - Defaults to true when not present. It is disabled when the value does not match "true" regardless of case. This is used to initialize widgets tied to actions to disabled. Once the action is created, it's state can be changed and the tied widgets will behave appropriately.
  - Shared - Defaults to true when not present. It is unshared when the value does not match "true" regardless of case. When false, each copy of the action is independent of other copies.

  In order to facilitate easier translation, Enabled, SmallIcon and LargeIcon can be specified in a parallel resource, whose name is suffixed with "_control" as in Desktop_control. This is meant to extrapolate the constant behavior of an action into a file that probably does not need to be internationalized. If it does, for example, to suppress the display of icons, then one would create a resource further suffixed with the language and perhaps country, as in Desktop_control_fa.

  To add another twist, several actions may have the same name and mnemonic, differing perhaps by tooltip. To facilitate the sharing of these definitions, an Aliases resource is defined to contain common values. If the value of a ActionName.Name is prefixed with "Alias.", as in Go.Name=Alias.Go, then Go will be used as the ActionName to look up values in the Aliases resource.

  Aliases defines defaults that can be overridden by the referring resource file. The only value that cannot be overridden is Name.

  When an action is fired, this class, as a listener, reflects the action on the class providing the resource. For example, DesktopActions creates an ActionFactory from the Desktop ResourceBundle. When the Exit action is fired, ActionFactory calls DesktopActions.doExit(ActionEvent event) or DesktopActions.doExit(), if the first did not exist.

  Author:
    DM Smith, Joe Walker
  See Also:
    `The GNU General Public License for details.`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private Map<String,CWAction>` | `actions` The map of known CWActions
    `private Object` | `bean` The object to which we forward events
    `private static org.slf4j.Logger` | `log` The log stream
    `private static String` | `METHOD_PREFIX` The prefix to methods that we call
    `private static String` | `MISSING_RESOURCE` The tooltip for actions that we generate to paper around missing resources Normally we would assert, but in live we might want to limp on.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ActionFactory()` Creates an ActionFactory that merely holds actions.
    `ActionFactory(Object bean)` Creates an ActionFactory that merely arranges for actions to be called against a bean.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `actionPerformed(ActionEvent ev)`
    `void` | `actionPerformed(String action)`
    `CWAction` | `addAction(String key)`
    `CWAction` | `addAction(String key, String name)` Lookup an existing action for actionName.
    `private CWAction` | `buildAction(String key, String name)`
    `JButton` | `createJButton(CWAction action, ActionListener listener)` Build a button from an action.
    `Action` | `findAction(String key)` Get the Action for the given actionName.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### MISSING_RESOURCE

          private static final String MISSING_RESOURCE

      The tooltip for actions that we generate to paper around missing resources Normally we would assert, but in live we might want to limp on.
      See Also:
        Constant Field Values

    - #### METHOD_PREFIX

          private static final String METHOD_PREFIX

      The prefix to methods that we call
      See Also:
        Constant Field Values

    - #### bean

          private Object bean

      The object to which we forward events

    - #### actions

          private Map<String,CWAction> actions

      The map of known CWActions

    - #### log

          private static final org.slf4j.Logger log

      The log stream

  - ### Constructor Detail

    - #### ActionFactory

          public ActionFactory()

      Creates an ActionFactory that merely holds actions. It does not lookup properties to construct an action. Constructing an action is the responsibility of the calling class. It does not arrange for actions to perform actions.

    - #### ActionFactory

          public ActionFactory(Object bean)

      Creates an ActionFactory that merely arranges for actions to be called against a bean. It does not lookup properties to construct an action. Constructing an action is the responsibility of the calling class.
      Parameters:
        `bean` -

  - ### Method Detail

    - #### actionPerformed

          public void actionPerformed(String action)

      Specified by:
        `actionPerformed` in interface `Actionable`

    - #### actionPerformed

          public void actionPerformed(ActionEvent ev)

      Specified by:
        `actionPerformed` in interface `ActionListener`

    - #### findAction

          public Action findAction(String key)

      Get the Action for the given actionName.
      Parameters:
        `key` - the internal name of the CWAction
      Returns:
        CWAction null if it does not exist

    - #### createJButton

          public JButton createJButton(CWAction action,
                              ActionListener listener)

      Build a button from an action.
      Parameters:
        `action` - the action to use
      Returns:
        the button

    - #### addAction

          public CWAction addAction(String key,
                           String name)

      Lookup an existing action for actionName. Otherwise construct, store and return an action.
      Parameters:
        `key` - The short name by which this action is known. It is used to lookup the action for reuse.
        `name` - This is required. The value is used for the text of the Action.
        A mnemonic can be specified by preceding the letter with _. Using this letter in a case insensitive search, the earliest position of that letter will cause the it to be underlined. In a platform dependent way it provides a keyboard mechanism to fire the action. For example, on Windows, alt + mnemonic will cause a visible, active element with that mnemonic to fire. For this reason, it is important to ensure that two visible, active elements do not have the same mnemonic.
        Note: Mnemonics are suppressed on MacOSX.
      Returns:
        the stored or newly constructed action

    - #### addAction

          public CWAction addAction(String key)

    - #### buildAction

          private CWAction buildAction(String key,
                             String name)