uic.model
Class UICAction

java.lang.Object
  extended by uic.model.UICSimpleAction
      extended by uic.model.UICAction
All Implemented Interfaces:
ActionListener, EventListener
Direct Known Subclasses:
UICToggleAction

public class UICAction
extends UICSimpleAction
implements ActionListener

This action class contains all the information to provide high quality widgets and an action. The idea behind an action is that one object wraps a certain functionality and provdes various ways to access that functionality. A good example is a print action.

Creating an action and using it with the ActionFactory creates widgets like buttons or menu entries. When your users click the button or select the menu item the action will be informed and a method of your choosing will be invoked. Notice that the default version uses the QueuedPolicy.

Since:
1.2
See Also:
ActionFactory, UICToggleAction

Nested Class Summary
 class UICAction.StatusBarUpdater
          Helper class.
 
Nested classes/interfaces inherited from class uic.model.UICSimpleAction
UICSimpleAction.Arguments, UICSimpleAction.DirectMultiThreadingPolicy, UICSimpleAction.DirectPolicy, UICSimpleAction.ExecutePolicy, UICSimpleAction.OnlyLastPolicy, UICSimpleAction.QueuedPolicy, UICSimpleAction.SimpleQueuedPolicy
 
Field Summary
static String ARGUMENT_SOURCE
          an Object: the source object that threw the event.
protected  UICSimpleAction updateUICommmand
           
 
Fields inherited from class uic.model.UICSimpleAction
currentPolicy, target, targetObject
 
Constructor Summary
UICAction(String name)
          Base constructor.
UICAction(String name, Object targetObject, String targetMethod, String title)
           
UICAction(String name, Object targetObject, String targetMethod, String title, ActionFactory actions)
           
UICAction(String name, Object targetObject, String targetMethod, String title, String iconBaseName)
           
UICAction(String name, Object targetObject, String targetMethod, String title, String iconBaseName, ActionFactory actions)
           
UICAction(String name, Object targetObject, String targetMethod, String title, String iconBaseName, String keyStroke)
           
UICAction(String name, Object targetObject, String targetMethod, String title, String iconBaseName, String keyStroke, ActionFactory actions)
           
UICAction(String name, Object targetObject, String targetMethod, String title, String iconBaseName, String keyStroke, String toolTipText, String whatIsThis)
           
UICAction(String name, Object targetObject, String targetMethod, String title, String iconBaseName, String keyStroke, String toolTipText, String whatIsThis, ActionFactory actions)
          Create new action.
 
Method Summary
 void actionPerformed(ActionEvent e)
           
 void addComponent(AbstractButton c)
          A button component that represents this action the the users user interface can be registered here.
protected  void addIcon(AbstractButton button, IconFactory iconFactory)
           
protected  void addKeyStroke(JMenuItem button)
           
 JMenuItem createMenuItem(IconFactory iconFactory)
           
 JMenuItem createPopupMenuItem(IconFactory iconFactory)
           
 AbstractButton createToolBarButton(IconFactory iconFactory)
           
protected  void decorateButton(AbstractButton button, IconFactory iconFactory)
           
protected  void doAction(Object[] args)
          Called to actually execute the action on the registered method.
protected  Class getArgumentClass(String argumentType)
          For the uniquely defined argumentType (as also used in UICSimpleAction.getTargetSignatures()) return the Class.
protected  Object getArgumentValue(EventObject source, String argumentType)
          For the uniquely defined argumentType (as also used in UICSimpleAction.getTargetSignatures()) return the value.
 Iterator getComponentsIterator()
           
 String getIconBaseName()
          The name of the icon that will be used on buttons.
 KeyStroke getKeyStroke()
           
 String getName()
          Return the name key.
protected  List getTargetSignatures()
          Return a List object with instances of the Arguments class.
 String getTitle()
          return the title of this action, this is mostly the name on screen.
 String getToolTipText()
           
 String getWhatIsThis()
          The text used in the popup for whatIs help.
 void setEnabled(boolean enabled)
          Enable disable this action and all its registered components.
 void setIconBaseName(String iconBaseName)
          The name of the icon that will be used on buttons.
 void setKeyStroke(KeyStroke keyStroke)
           
 void setName(String name)
          Set the unique key that is the name of this action.
 void setStatusBar(StatusBar statusBar)
          Register a statusbar that will be used to show whatIs texts on on mouseOver of the menuitems.
protected  void setTexts(AbstractButton button)
           
 void setTitle(String title)
          Set the title of this action, this is mostly the name on screen.
 void setToolTipText(String toolTipText)
           
 void setUIUpdateCommand(Object object, String targetMethod)
          Set an additional target for this action which will be in the AWT Thread.
 void setUIUpdateCommand(Object object, String targetMethod, UICSimpleAction.Arguments arguments)
          Set an additional target for this action which will be in the AWT Thread.
 void setWhatIsThis(String whatIsThis)
          The text used in the popup for whatIs help.
 String toString()
          returns the title.
 
Methods inherited from class uic.model.UICSimpleAction
createArguments, equals, execute, execute, execute, execute, isEnabled, setDirect, setExecutionPolicy, setTarget, setTarget
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

updateUICommmand

protected UICSimpleAction updateUICommmand

ARGUMENT_SOURCE

public static final String ARGUMENT_SOURCE
an Object: the source object that threw the event.

See Also:
Constant Field Values
Constructor Detail

UICAction

public UICAction(String name)
Base constructor.


UICAction

public UICAction(String name,
                 Object targetObject,
                 String targetMethod,
                 String title,
                 ActionFactory actions)

UICAction

public UICAction(String name,
                 Object targetObject,
                 String targetMethod,
                 String title,
                 String iconBaseName,
                 ActionFactory actions)

UICAction

public UICAction(String name,
                 Object targetObject,
                 String targetMethod,
                 String title,
                 String iconBaseName,
                 String keyStroke,
                 ActionFactory actions)

UICAction

public UICAction(String name,
                 Object targetObject,
                 String targetMethod,
                 String title)

UICAction

public UICAction(String name,
                 Object targetObject,
                 String targetMethod,
                 String title,
                 String iconBaseName)

UICAction

public UICAction(String name,
                 Object targetObject,
                 String targetMethod,
                 String title,
                 String iconBaseName,
                 String keyStroke)

UICAction

public UICAction(String name,
                 Object targetObject,
                 String targetMethod,
                 String title,
                 String iconBaseName,
                 String keyStroke,
                 String toolTipText,
                 String whatIsThis)

UICAction

public UICAction(String name,
                 Object targetObject,
                 String targetMethod,
                 String title,
                 String iconBaseName,
                 String keyStroke,
                 String toolTipText,
                 String whatIsThis,
                 ActionFactory actions)
Create new action.

Parameters:
name - The identifying name of the action, must be unique.
targetObject - The object that contains the method we want to connect to.
targetMethod - the name of the method we want to connect to.
title - the name used on buttons or in a menu entry.
iconBaseName - the basename the new widgets can use to fetch the correct icon, or null if none
keyStroke - the keyStroke in the format accepted by javax.swing.KeyStroke.getKeyStroke(String)
toolTipText - the text for tooltips, or null for none
whatIsThis - the text for the statusBar.
actions - the actionFactory this action belongs to.
See Also:
KeyStroke.getKeyStroke(String)
Method Detail

addComponent

public void addComponent(AbstractButton c)
A button component that represents this action the the users user interface can be registered here. Any button that is added to this action will trigger the action to respond on a button 'press' after adding it using the addComponent method. Additionaly en/disabling the action will make the component also en/disable.


getName

public String getName()
Return the name key.


setName

public void setName(String name)
Set the unique key that is the name of this action.


setEnabled

public void setEnabled(boolean enabled)
Enable disable this action and all its registered components. Incoming events will not cause the action to be commited when the action is disabled.

Overrides:
setEnabled in class UICSimpleAction
Parameters:
enabled - the new state of the action.

getTitle

public String getTitle()
return the title of this action, this is mostly the name on screen.


setTitle

public void setTitle(String title)
Set the title of this action, this is mostly the name on screen. Notice that it is wise to first run the title through the Translator before setting the title.

Setting the title on an action will not change created buttons/menu items.


getIconBaseName

public String getIconBaseName()
The name of the icon that will be used on buttons. This name will be searched for in the icon collections, adding resolution information will be done based on context.


setIconBaseName

public void setIconBaseName(String iconBaseName)
The name of the icon that will be used on buttons. This name will be searched for in the icon collections, adding resolution information will be done based on context.


getToolTipText

public String getToolTipText()

setToolTipText

public void setToolTipText(String toolTipText)

getWhatIsThis

public String getWhatIsThis()
The text used in the popup for whatIs help. This is functionality that at the moment is only available when using a MainWindow.

See Also:
MainWindow

setWhatIsThis

public void setWhatIsThis(String whatIsThis)
The text used in the popup for whatIs help. This is functionality that at the moment is only available when using a MainWindow.

See Also:
MainWindow

getComponentsIterator

public Iterator getComponentsIterator()
Returns:
an iterator over all added components.

getKeyStroke

public KeyStroke getKeyStroke()

setKeyStroke

public void setKeyStroke(KeyStroke keyStroke)

setStatusBar

public void setStatusBar(StatusBar statusBar)
Register a statusbar that will be used to show whatIs texts on on mouseOver of the menuitems.


actionPerformed

public void actionPerformed(ActionEvent e)
Specified by:
actionPerformed in interface ActionListener

getTargetSignatures

protected List getTargetSignatures()
Description copied from class: UICSimpleAction
Return a List object with instances of the Arguments class. Extending classes should implement this to return all the target method signatures that are searched for should the user create an action without an Arguments instance.

An example implementation could be this:

  List result = new ArrayList(1);
  result.add( new Arguments().addArgument("Source") );
  return result;
This will result in a call to UICSimpleAction.getArgumentClass(java.lang.String) with the string "Source" which returns a Class instance. In our example that would be java.lang.Object.

The result of this would be that a call to setTarget will try to find a method with an argument of type Object, and will search again if that is not found without any arguments.

Overrides:
getTargetSignatures in class UICSimpleAction
Returns:
a List object with instances of the Arguments class.
See Also:
UICSimpleAction.getArgumentValue(java.util.EventObject, java.lang.String), UICSimpleAction.getArgumentClass(java.lang.String)

getArgumentValue

protected Object getArgumentValue(EventObject source,
                                  String argumentType)
Description copied from class: UICSimpleAction
For the uniquely defined argumentType (as also used in UICSimpleAction.getTargetSignatures()) return the value. This method will always return 'null'; Extending actions can define various argumentType strings that can be used as an argument in the call to the target method of this action. The user decides on construction of the action which argumentTypes are to be used, if a certain value is requested to be sent to the targetMethod a call is made to this method to find its value based on the source event.

Note that base types can not be returned, since they are instances of object; you should wrap these in their object re-presentation (an Integer object for an int).

Overrides:
getArgumentValue in class UICSimpleAction
Parameters:
source - the event that caused the action to be fired. This is the event that the extending class passed to the execute method; so casting is fine.
argumentType - the uniquely defined name specifying the type of argument.
Returns:
the value to be passed to the taget method.

getArgumentClass

protected Class getArgumentClass(String argumentType)
Description copied from class: UICSimpleAction
For the uniquely defined argumentType (as also used in UICSimpleAction.getTargetSignatures()) return the Class. This method will always return 'null'; Extending actions can define various argumentType strings that can be used as an argument in the call to the target method of this action. The user decides on construction of the action which argumentTypes are to be used, if a certain value is requested to be sent to the targetMethod a call is made to this method to find the Class of the type.

Note that basetypes have a class of their own and you should return the correct one you expect the targetMethod to implement. returning Integer.class will search for an Integer; returing int.class will search for an int. This is important to note since the UICSimpleAction.getArgumentValue(java.util.EventObject, java.lang.String) method should return an Integer object in both cases.

Overrides:
getArgumentClass in class UICSimpleAction
Parameters:
argumentType - the uniquely defined name specifying the type of argument.
Returns:
the class of this argument to be found on the target method

doAction

protected void doAction(Object[] args)
Description copied from class: UICSimpleAction
Called to actually execute the action on the registered method. Notice that this method will never throw any Throwables due to bad implementations in the target method since they are all cought (and ignored) here. That said; exceptions made in the target method will be printed using a simple printStackTrace() call on the throwable.

Overrides:
doAction in class UICSimpleAction

setUIUpdateCommand

public void setUIUpdateCommand(Object object,
                               String targetMethod)
                        throws IllegalArgumentException
Set an additional target for this action which will be in the AWT Thread. After the action executed the target method for this action another target method will be executed as soon as possible, in the AWT Event thread.

In Swing many changes to model and widgets are not safe to do from any thread but the event-handling thread that Swing starts itself. This event-handling thread is called the AWT Event Thread and handles button clicks and any other user event, as well as repaints.

It is wise to move updates to various widgets to an extra UIUpdateCommand and register it using this method.

For the arguments see: setTarget

Throws:
IllegalArgumentException

setUIUpdateCommand

public void setUIUpdateCommand(Object object,
                               String targetMethod,
                               UICSimpleAction.Arguments arguments)
                        throws IllegalArgumentException
Set an additional target for this action which will be in the AWT Thread. After the action executed the target method for this action another target method will be executed as soon as possible, in the AWT Event thread.

In Swing many changes to model and widgets are not safe to do from any thread but the event-handling thread that Swing starts itself. This event-handling thread is called the AWT Event Thread and handles button clicks and any other user event, as well as repaints.

It is wise to move updates to various widgets to an extra UIUpdateCommand and register it using this method.

For the arguments see: setTarget

Throws:
IllegalArgumentException

toString

public String toString()
returns the title.

Overrides:
toString in class Object

createToolBarButton

public AbstractButton createToolBarButton(IconFactory iconFactory)

decorateButton

protected void decorateButton(AbstractButton button,
                              IconFactory iconFactory)

setTexts

protected void setTexts(AbstractButton button)

addKeyStroke

protected void addKeyStroke(JMenuItem button)

addIcon

protected void addIcon(AbstractButton button,
                       IconFactory iconFactory)

createMenuItem

public JMenuItem createMenuItem(IconFactory iconFactory)

createPopupMenuItem

public JMenuItem createPopupMenuItem(IconFactory iconFactory)


Copyright © 2002-2004 Thomas Zander Available under the Free Apache licence