001: package prefuse.action;
002:
003: import java.util.logging.Logger;
004:
005: import prefuse.Visualization;
006: import prefuse.activity.Activity;
007:
008: /**
009: * <p>Actions are building blocks that perform any number of operations on a
010: * Visualization, typically processing VisualItems to set various visual
011: * attributes. This class is a base implementation for Action instances.
012: * Developers can subclass this class and implement the <code>run</code> method
013: * to create their own custom Actions.</p>
014: *
015: * <p>After instantiating an Action, you should register it with a particular
016: * Visualization before running it. Use the
017: * {@link prefuse.Visualization#putAction(String, Action)} to do this. This
018: * will ensure that the Action is configured to use that Visualization. If
019: * an Action is part of an {@link ActionList} or {@link ActionSwitch}, it is
020: * sufficient to only register that CompositeAction with the Visualization
021: * -- all contained Action instances will be configured appropriately. You
022: * can then run the Actions using the {@link prefuse.Visualization#run(String)}
023: * method and other similar methods of the {@link prefuse.Visualization} class.
024: * </p>
025: *
026: * <p>As a subclass of Activity, Actions can be of two kinds.
027: * <i>Run-once</i> action lists have
028: * a duration value of zero, and simply run once when scheduled. Actions
029: * with a duration greater than zero can be executed multiple times, waiting
030: * a specified step time between each execution until the activity has run for
031: * its full duration. A duration of Activity.INFINITE will result in a
032: * continually re-running Action.</p>
033: *
034: * @author <a href="http://jheer.org">jeffrey heer</a>
035: */
036: public abstract class Action extends Activity {
037:
038: private final static Logger s_logger = Logger
039: .getLogger(Action.class.getName());
040:
041: /** A reference to the visualization processed by this Action. */
042: protected Visualization m_vis;
043:
044: /**
045: * Creates an action instance with zero duration. This Action will only
046: * run once if invoked.
047: */
048: public Action() {
049: this (null);
050: }
051:
052: /**
053: * Create a new Action with a specified duration.
054: * @param duration the Action duration in milliseconds
055: */
056: public Action(long duration) {
057: super (duration, Activity.DEFAULT_STEP_TIME);
058: }
059:
060: /**
061: * Create a new Action with a specified duration and step time.
062: * @param duration the Action duration in milliseconds
063: * @param stepTime the time to wait between invocation of the Action
064: */
065: public Action(long duration, long stepTime) {
066: super (duration, stepTime);
067: }
068:
069: /**
070: * Create a new Action with a specified Visualization and zero duration.
071: * @param vis the Visualization this Action should process. If this
072: * Action is registered with another Visualization, this value will
073: * be overwritten.
074: */
075: public Action(Visualization vis) {
076: this (vis, 0);
077: }
078:
079: /**
080: * Create a new Action with a specified Visualization and duration.
081: * @param vis the Visualization this Action should process. If this
082: * Action is registered with another Visualization, this value will
083: * be overwritten.
084: * @param duration the Action duration in milliseconds
085: */
086: public Action(Visualization vis, long duration) {
087: super (duration, Activity.DEFAULT_STEP_TIME);
088: m_vis = vis;
089: }
090:
091: /**
092: * Create a new Action with a specified Visualization, duration and
093: * step time.
094: * @param vis the Visualization this Action should process. If this
095: * Action is registered with another Visualization, this value will
096: * be overwritten.
097: * @param duration the Action duration in milliseconds
098: * @param stepTime the time to wait between invocation of the Action
099: */
100: public Action(Visualization vis, long duration, long stepTime) {
101: super (duration, stepTime);
102: m_vis = vis;
103: }
104:
105: // ------------------------------------------------------------------------
106:
107: /**
108: * Runs this Action, triggering whatever processing this Action performs.
109: * Subclass this method to create custom Actions.
110: * @param frac the fraction of this Action's duration that has elapsed.
111: */
112: public abstract void run(double frac);
113:
114: /**
115: * Runs this Action (as an Activity). Called by the Activity super-class.
116: * @see prefuse.activity.Activity#run(long)
117: */
118: protected void run(long elapsedTime) {
119: Visualization vis = getVisualization();
120: if (vis != null) {
121: synchronized (vis) {
122: run(getPace(elapsedTime));
123: }
124: } else {
125: s_logger.info("Running unsynchronized Action");
126: run(getPace(elapsedTime));
127: }
128: }
129:
130: /**
131: * Return the Visualization processed by this Action.
132: * @return the {@link prefuse.Visualization} instance.
133: */
134: public Visualization getVisualization() {
135: return m_vis;
136: }
137:
138: /**
139: * Set the Visualization processed by this Action.
140: * @return the {@link prefuse.Visualization} to process.
141: */
142: public void setVisualization(Visualization vis) {
143: m_vis = vis;
144: }
145:
146: } // end of class Action
|