import java.awt.Cursor;
import java.awt.event.ActionEvent;
import javax.swing.AbstractAction;
import javax.swing.Action;
 
/**
 * An implementation of actionPerformed() is supplied, where it is broken into
 * three phases:  a non-busy preActionPerformed() phase, a busy
 * busyActionPerformed() phase, and a non-busy postActionPerformed() phase.
 *
 * When busyActionPerformed() is invoked, it is wrapped by the setting the
 * glass pane, the wait cursor, the status text on status bar, and the
 * indeterminate progress bar on the status bar.  Long running code in
 * busyActionPerformed() should be wrapped in a foxtrot-like thread to allow
 * AWT-Event thread processing.  busyActionPerformed() is declared abstract,
 * so it must be provided by any concrete subclasses.
 * Both preActionPerformed() and postActionPerformed() may be overridden to do
 * any pre-busy-action work or post-busy-action work.
 *
 * In preActionPerformed(), if you want to skip busyActionPerformed(), return
 * PERFORM_POST_ACTION to jump right to postActionPerformed() or return
 * PERFORM_NO_ACTION to just exit actionPerformed().  In busyActionPerformed(),
 * if you want to skip postActionPerformed(), return PERFORM_NO_ACTION.
 *
 * If you don't want or need to use any of this fancy action stuff, you can
 * override actionPerformed() like normal, although you must still supply a
 * busyActionPerformed() (it doesn't have to do anything).
 */
abstract public class MyAbstractAction extends AbstractAction
{
   /**
    * used to tell actionPerformed() that busyActionPerformed() should be
    * invoked after preActionPerformed()
    */
   protected static final int PERFORM_BUSY_ACTION = 0;
 
 
   /**
    * used to tell actionPerformed() that postActionPerformed() should be
    * invoked, either right after preActionPerformed() or busyActionPerformed()
    */
   protected static final int PERFORM_POST_ACTION = 1;
 
 
   /**
    * used to tell actionPerformed() to not invoke either preActionPerformed()
    * or busyActionPerformed()
    */
   protected static final int PERFORM_NO_ACTION = 2;
 
 
   /**
    * must be implemented by concrete subclasses
    * perform any busy action that requires the busy cursor, indeterminate
    * progress bar, and action process status message to be displayed.
    * If normal processing occurred, should return PERFORM_POST_ACTION, but
    * if we don't want to have postActionPerformed() called, then it should
    * return PERFORM_NO_ACTION.
    * @param e is the action event to perform
    * @return status about whether to call post action function
    */
   abstract public int busyActionPerformed(ActionEvent e);
 
 
   /**
    * override to perform anything that needs to occur prior to the busy action.
    * Should return PERFORM_BUSY_ACTION if busyActionPerformed() is needed.
    *
    * @param e is the action event to perform
    * @return status about whether to call busyActionPerformed(),
    * postActionPerformed(), or neither
    */
   public int preActionPerformed(ActionEvent e)
   {
      // override to do something interesting
      return PERFORM_BUSY_ACTION;
   }  // preActionPerformed()
 
 
   /**
    * override to perform anything that needs to occur after the busy action
    * @param e is the action event to perform
    */
   public void postActionPerformed(ActionEvent e)
   {
      // override to do something interesting
   }  // postActionPerformed()
 
 
   /**
    * handle the action event. First, perform any pre-action.  Then set the
    * UI up for doing a busy thing.  Then perform the busy action.  Then
    * restore UI to non-busy state.  Then perform any post-action.
    * @param e is the action event to be processed
    */
   public void actionPerformed(ActionEvent e)
   {
      UserInterface ui = MyApplication.getInstance().getUserInterface();
 
      // prevent action if user events are already disabled
      if (!ui.areUserEventsEnabled())
      {
         return;
      }
 
      // perform any pre-action
      int status = preActionPerformed(e);
 
      // setup the busy action
      if (status == PERFORM_BUSY_ACTION)
      {
         StatusBar statusBar = ui.getStatusBar();
 
         // set glass pane
         ui.disableUserEvents();
 
         // start indeterminate progress bar on status bar
         statusBar.startProgressBar();
 
         // set the action short description text on the status bar
         statusBar.setActionText((String)getValue(Action.SHORT_DESCRIPTION));
            
         // set wait cursor
         Cursor oldCursor = ui.getCursor();
         ui.setCursor(ui.getWaitCursor());
 
         // perform main busy action
         status = busyActionPerformed(e);
 
         // return ui, et al, to default state
         ui.setCursor(oldCursor);
         statusBar.setActionText("Ready");
         statusBar.stopProgressBar();
         ui.enableUserEvents();
      }
 
      // perform any post-action
      if (status == PERFORM_POST_ACTION)
      {
         postActionPerformed(e);
      }
   }  // actionPerformed()
 
}  // class MyAbstractAction