package prefuse.action;

import java.util.logging.Logger;

import prefuse.Visualization;
import prefuse.activity.Activity;

/**
 * <p>Actions are building blocks that perform any number of operations on a
 * Visualization, typically processing VisualItems to set various visual
 * attributes. This class is a base implementation for Action instances.
 * Developers can subclass this class and implement the <code>run</code> method
 * to create their own custom Actions.</p>
 * 
 * <p>After instantiating an Action, you should register it with a particular
 * Visualization before running it. Use the
 * {@link prefuse.Visualization#putAction(String, Action)} to do this. This
 * will ensure that the Action is configured to use that Visualization. If
 * an Action is part of an {@link ActionList} or {@link ActionSwitch}, it is
 * sufficient to only register that CompositeAction with the Visualization
 * -- all contained Action instances will be configured appropriately. You
 * can then run the Actions using the {@link prefuse.Visualization#run(String)}
 * method and other similar methods of the {@link prefuse.Visualization} class.
 * </p>
 * 
 * <p>As a subclass of Activity, Actions can be of two kinds. 
 * <i>Run-once</i> action lists have
 * a duration value of zero, and simply run once when scheduled. Actions
 * with a duration greater than zero can be executed multiple times, waiting
 * a specified step time between each execution until the activity has run for
 * its full duration. A duration of Activity.INFINITE will result in a
 * continually re-running Action.</p>
 *
 * @author <a href="http://jheer.org">jeffrey heer</a>
 */
public abstract class Action extends Activity {
    
    private final static Logger s_logger 
        = Logger.getLogger(Action.class.getName());
    
    /** A reference to the visualization processed by this Action. */
    protected Visualization m_vis;
    
    /**
     * Creates an action instance with zero duration. This Action will only
     * run once if invoked.
     */
    public Action() {
        this(null);
    }
    
    /**
     * Create a new Action with a specified duration.
     * @param duration the Action duration in milliseconds
     */
    public Action(long duration) {
        super(duration, Activity.DEFAULT_STEP_TIME);
    }
    
    /**
     * Create a new Action with a specified duration and step time.
     * @param duration the Action duration in milliseconds
     * @param stepTime the time to wait between invocation of the Action
     */
    public Action(long duration, long stepTime) {
        super(duration, stepTime);
    }
    
    /**
     * Create a new Action with a specified Visualization and zero duration.
     * @param vis the Visualization this Action should process. If this
     * Action is registered with another Visualization, this value will
     * be overwritten.
     */
    public Action(Visualization vis) {
        this(vis, 0);
    }
    
    /**
     * Create a new Action with a specified Visualization and duration.
     * @param vis the Visualization this Action should process. If this
     * Action is registered with another Visualization, this value will
     * be overwritten.
     * @param duration the Action duration in milliseconds
     */
    public Action(Visualization vis, long duration) {
        super(duration, Activity.DEFAULT_STEP_TIME);
        m_vis = vis;
    }
    
    /**
     * Create a new Action with a specified Visualization, duration and
     * step time.
     * @param vis the Visualization this Action should process. If this
     * Action is registered with another Visualization, this value will
     * be overwritten.
     * @param duration the Action duration in milliseconds
     * @param stepTime the time to wait between invocation of the Action
     */
    public Action(Visualization vis, long duration, long stepTime) {
        super(duration, stepTime);
        m_vis = vis;
    }
    
    // ------------------------------------------------------------------------
    
    /**
     * Runs this Action, triggering whatever processing this Action performs.
     * Subclass this method to create custom Actions.
     * @param frac the fraction of this Action's duration that has elapsed.
     */
    public abstract void run(double frac);

    /**
     * Runs this Action (as an Activity). Called by the Activity super-class.
     * @see prefuse.activity.Activity#run(long)
     */
    protected void run(long elapsedTime) {
        Visualization vis = getVisualization();
        if ( vis != null ) {
            synchronized (vis) {
                run(getPace(elapsedTime));
            }
        } else {
            s_logger.info("Running unsynchronized Action");
            run(getPace(elapsedTime));
        }
    }
    
    /**
     * Return the Visualization processed by this Action.
     * @return the {@link prefuse.Visualization} instance.
     */
    public Visualization getVisualization() {
        return m_vis;
    }
    
    /**
     * Set the Visualization processed by this Action.
     * @return the {@link prefuse.Visualization} to process.
     */
    public void setVisualization(Visualization vis) {
        m_vis = vis;
    }

} // end of class Action