com.ccg.awt
Class TriggerButton

java.lang.Object
  java.awt.Component
      java.awt.Button
          com.ccg.awt.TriggerButton

All Implemented Interfaces:

ActionListener, ImageObserver, MenuContainer, Serializable, EventListener, Accessible

public class TriggerButton
extends Button
implements ActionListener

An easy way to create localized buttons and link callbacks. Often one needs to create GUI button objects that the user can "press". When the user "presses" the button, typically the programmer would like to have one or more methods called on particular objects. This class simplifies the process. It does this in the following manner:

1. It allows one to create buttons which are localized based on the contents of a resource bundle.
2. It then allows one easily trigger the invocation of any method of one or more objects when the user "presses" the button.

   This allows one to write much "cleaner" looking GUI classes as demonstrated in the demo applet.

   Since:

   1.0

   Version:

   $Revision: 1.3 $

   Author:

   $Author: pkb $

   See Also:

   create(com.ccg.util.Lookup, java.lang.String), addTrigger(java.lang.Object, java.lang.String), Serialized Form

   Nested Class Summary

   Nested classes/interfaces inherited from class java.awt.Button

   Button.AccessibleAWTButton

   Nested classes/interfaces inherited from class java.awt.Component

   Component.AccessibleAWTComponent, Component.BltBufferStrategy, Component.FlipBufferStrategy

   Field Summary

   Fields inherited from class java.awt.Component

   BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

   Fields inherited from interface java.awt.image.ImageObserver

   ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

   Constructor Summary

   TriggerButton()
   Construct the button without an initial label.

   TriggerButton(String label)
   Construct the button with an initial label.

   Method Summary

   void	actionPerformed(ActionEvent aevent) Handle the condition when the users presses the button.
   Exception	addTrigger(Object o, String methodName) Add a method to be invoked when button action occurs.
   void	addTriggerMethod(Object o, Method m, Object[] params) Add a method to be invoked when button action occurs.
   Exception	addTriggerPopupMenu(PopupMenu pm) Add a PopupMenu to display when button pressed.
   static TriggerButton	create(Lookup lookup, String tag) The easy way to create localizable trigger buttons.

   Methods inherited from class java.awt.Button

   addActionListener, addNotify, getAccessibleContext, getActionCommand, getActionListeners, getLabel, getListeners, paramString, processActionEvent, processEvent, removeActionListener, setActionCommand, setLabel

   Methods inherited from class java.awt.Component

   action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, deliverEvent, disable, disableEvents, dispatchEvent, doLayout, enable, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getAlignmentX, getAlignmentY, getBackground, getBounds, getBounds, getColorModel, getComponentAt, getComponentAt, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeys, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphics, getGraphicsConfiguration, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocation, getLocationOnScreen, getMaximumSize, getMinimumSize, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPreferredSize, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, invalidate, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusable, isFocusCycleRoot, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, layout, list, list, list, list, list, locate, location, lostFocus, minimumSize, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paint, paintAll, postEvent, preferredSize, prepareImage, prepareImage, print, printAll, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, reshape, resize, resize, setBackground, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeys, setFocusTraversalKeysEnabled, setFont, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setMinimumSize, setName, setPreferredSize, setSize, setSize, setVisible, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle, update, validate

   Methods inherited from class java.lang.Object

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

   Constructor Detail

   TriggerButton

   public TriggerButton()

   Construct the button without an initial label. This constructor initializes the button with a label. Use the addTriggerMethod(java.lang.Object, java.lang.reflect.Method, java.lang.Object[]) and addTrigger(java.lang.Object, java.lang.String) methods to register methods to be invoked when the button action is invoked.

   Since:

   1.0

   See Also:

   create(com.ccg.util.Lookup, java.lang.String), addTriggerMethod(java.lang.Object, java.lang.reflect.Method, java.lang.Object[])

   TriggerButton

   public TriggerButton(String label)

   Construct the button with an initial label. This constructor initializes the button with a label. Use the addTriggerMethod(java.lang.Object, java.lang.reflect.Method, java.lang.Object[]) and addTrigger(java.lang.Object, java.lang.String) methods to register methods to be invoked when the button action is invoked.

   Since:

   1.0

   See Also:

   create(com.ccg.util.Lookup, java.lang.String), addTriggerMethod(java.lang.Object, java.lang.reflect.Method, java.lang.Object[])

   Method Detail

   create

   public static TriggerButton create(Lookup lookup,
                                      String tag)

   The easy way to create localizable trigger buttons. This method creates a TriggerButton object based on the contents of a Lookup table. This has two nice advantages. One, it simplifies the process of localizing your application. Two, it removes the decision of how the button should be labeld from the code. Using this method, you can use standard Java property files to:

   • Control whether or not your button even exist (you can prevent buttons from being shown).
   • Control the label of the button.

   Consider the following example resource file:

    # Player start button, comment out if you want to remove from
    # what is displayed the the user.
   
    Player.Start.label=Start
    

   If we were to load the above resource file using the TagLookup class with a initial tag of "Player", a ResourceBundle (say is was "myproject.MyStrings" resource (don't forget the ".poperties" extension). The following code fragment could be used:

   
    TagLookup lookup = new TagLookup(myGui,"Player");
    TriggerButton tb = TriggerButton.create(rb,".Start");
    if (tb) add(tb);               // add to GUI if it was configured
    

   That's all there is to it, you would have created and added the button to your panel if it was configured, and the label would be "Start".

   Parameters:

   lookup - Used to lookup the ".label" to associate with the button (if the ".label" isn't found, then no button is created).

   tag - Since your lookup table may contain definitions for many GUI objects, set this to the "Tag" associated with your label (may ".Start" for Start button resources, ".Stop" for Stop button resources etc.)

   Returns:

   A new MenuChoice if both "tag.choice" and "tag.label" are defined and valid in the resource bundle. If "tag.default" is found in the resource bundle, it will be the initially selected item. If valid values are not found in the resource bundle, then null is returned (this allows one to remove menus simply by commenting out lines in the resource bundle - as long as you handle the null which might be returned).

   Since:

   1.0

   See Also:

   addTrigger(java.lang.Object, java.lang.String), TagLookup.TagLookup(Class,String)

   addTriggerMethod

   public void addTriggerMethod(Object o,
                                Method m,
                                Object[] params)

   Add a method to be invoked when button action occurs. Use this method to register the invocation of a specific method of a specific object when the button is pressed. This version allows one to specify a set of arguments to pass to the invoked method.

   Parameters:

   o - Object to invoke the method on (must not be null).

   m - Method to invoke on object (must not be null).

   args - Optional arguments to pass to method when it is invoked (may be null).

   Since:

   1.0

   See Also:

   addTrigger(java.lang.Object, java.lang.String)

   addTrigger

   public Exception addTrigger(Object o,
                               String methodName)

   Add a method to be invoked when button action occurs. Use this method to register the invocation of a specific method of a specific object when the button is pressed. This registration allows one to simply pass the Object and name of the method to be invoked. It assumes that the method doesn't require any parameters.

   This version looks up the Method object for you. If this lookup throws an Exception, then the desired trigger action will not be registered and the exception thrown will be returned. This method does not throw any exceptions itself since it assumes that you will only pass valid values to it.

   Parameters:

   o - Object to invoke the method on (must not be null).

   methodName - Name of method to invoke (must not be null). It is used to lookup the Method for the object passed.

   Returns:

   If everything goes well, null is returned. However, if there is a problem with the method you want to invoke, its possible an exception will be thrown. If an Exception is thrown, it will be returned (and your trigger method probably won't work as expected).

   Since:

   1.0

   See Also:

   addTriggerMethod(java.lang.Object, java.lang.reflect.Method, java.lang.Object[])

   addTriggerPopupMenu

   public Exception addTriggerPopupMenu(PopupMenu pm)

   Add a PopupMenu to display when button pressed. This method links a PopupMenu item to the button that will be displayed when the user clicks on the button.

   Parameters:

   pm - {java.awt.PopupMenu} to associate with the button.

   Returns:

   If everything goes well, null is returned. However, if there is a problem with the method you want to invoke, its possible an exception will be thrown. If an Exception is thrown, it will be returned (and your trigger method probably won't work as expected).

   Since:

   1.0

   See Also:

   addTriggerMethod(java.lang.Object, java.lang.reflect.Method, java.lang.Object[])

   actionPerformed

   public void actionPerformed(ActionEvent aevent)

   Handle the condition when the users presses the button. This method invokes all of the registered methods.

   Specified by:

   actionPerformed in interface ActionListener

   Parameters:

   aevent - ActionEvent which we are processing (typically generated by the GUI when the user presses the button.

   Since:

   1.0

   See Also:

   addTrigger(java.lang.Object, java.lang.String)