Whitespace

git-svn-id: svn+ssh://src.earth.threerings.net/nenya/trunk@877 ed5b42cb-e716-0410-a449-f6a68f950b19

src/java/com/threerings/media/animation/Animation.java

@@ -28,9 +28,8 @@ import com.samskivert.util.ObserverList;
 import com.threerings.media.AbstractMedia;
 
 /**
- * The animation class is an abstract class that should be extended to
+ * The animation class is an abstract class that should be extended to provide animation
- * provide animation functionality. It is generally used in conjunction
+ * functionality. It is generally used in conjunction with an {@link AnimationManager}.
- * with an {@link AnimationManager}.
  */
 public abstract class Animation extends AbstractMedia
 {
@@ -45,8 +44,7 @@ public abstract class Animation extends AbstractMedia
     }
 
     /**
-     * Returns true if the animation has finished all of its business,
+     * Returns true if the animation has finished all of its business, false if not.
-     * false if not.
      */
     public boolean isFinished ()
     {
@@ -54,8 +52,7 @@ public abstract class Animation extends AbstractMedia
     }
 
     /**
-     * If this animation has run to completion, it can be reset to prepare
+     * If this animation has run to completion, it can be reset to prepare it for another go.
-     * it for another go.
      */
     public void reset ()
     {
@@ -87,8 +84,8 @@ public abstract class Animation extends AbstractMedia
     }
 
     /**
-     * Called when the animation is finished and the animation manager is
+     * Called when the animation is finished and the animation manager is about to remove it from
-     * about to remove it from service.
+     * service.
      */
     protected void willFinish (long tickStamp)
     {
@@ -96,8 +93,8 @@ public abstract class Animation extends AbstractMedia
     }
 
     /**
-     * Called when the animation is finished and the animation manager has
+     * Called when the animation is finished and the animation manager has removed it from
-     * removed it from service.
+     * service.
      */
     protected void didFinish (long tickStamp)
     {

src/java/com/threerings/media/animation/AnimationSequencer.java

@@ -33,21 +33,19 @@ import com.samskivert.util.StringUtil;
 import static com.threerings.media.Log.log;
 
 /**
- * An animation that provides facilities for adding a sequence of
+ * An animation that provides facilities for adding a sequence of animations that are fired after
- * animations that are fired after a fixed time interval has elapsed or
+ * a fixed time interval has elapsed or after previous animations in the sequence have completed.
- * after previous animations in the sequence have completed. Facilities
+ * Facilities are also provided for running code upon the completion of animations in the
- * are also provided for running code upon the completion of animations in
+ * sequence.
- * the sequence.
  */
 public class AnimationSequencer extends Animation
 {
     /**
-     * Constructs an animation sequencer with the expectation that
+     * Constructs an animation sequencer with the expectation that animations will be added via
-     * animations will be added via subsequent calls to {@link
+     * subsequent calls to {@link #addAnimation}.
-     * #addAnimation}.
      *
-     * @param animmgr the animation manager to which to add our animations
+     * @param animmgr the animation manager to which to add our animations when they are ready to
-     * when they are ready to start.
+     * start.
      */
     public AnimationSequencer (AnimationManager animmgr)
     {
@@ -56,32 +54,25 @@ public class AnimationSequencer extends Animation
     }
 
     /**
-     * Adds the supplied animation to the sequence with the given
+     * Adds the supplied animation to the sequence with the given parameters. Note that care
-     * parameters. Note that care should be taken if this is called after
+     * should be taken if this is called after the animation sequence has begun firing animations.
-     * the animation sequence has begun firing animations. Do not add new
+     * Do not add new animations after the final animation in the sequence has been started or you
-     * animations after the final animation in the sequence has been
+     * run the risk of attempting to add an animation to the sequence after it thinks that it has
-     * started or you run the risk of attempting to add an animation to
+     * finished (in which case this method will fail).
-     * the sequence after it thinks that it has finished (in which case
-     * this method will fail).
      *
-     * @param anim the animation to be sequenced, or null if the
+     * @param anim the animation to be sequenced, or null if the completion action should be run
-     * completion action should be run immediately when this "animation"
+     * immediately when this "animation" is ready to fired.
-     * is ready to fired.
+     * @param delta the number of milliseconds following the <em>start</em> of the previous
-     * @param delta the number of milliseconds following the
+     * animation in the queue that this animation should be started; 0 if it should be started
-     * <em>start</em> of the previous animation in the queue that this
+     * simultaneously with its predecessor int the queue; -1 if it should be started when its
-     * animation should be started; 0 if it should be started
+     * predecessor has completed.
-     * simultaneously with its predecessor int the queue; -1 if it should
+     * @param completionAction a runnable to be executed when this animation completes.
-     * be started when its predecessor has completed.
-     * @param completionAction a runnable to be executed when this
-     * animation completes.
      */
-    public void addAnimation (
+    public void addAnimation (Animation anim, long delta, Runnable completionAction)
-        Animation anim, long delta, Runnable completionAction)
     {
         // sanity check
         if (_finished) {
-            throw new IllegalStateException(
+            throw new IllegalStateException("Animation added to finished sequencer");
-                "Animation added to finished sequencer");
         }
 
         // if this guy is triggering on a previous animation, grab that
@@ -100,8 +91,7 @@ public class AnimationSequencer extends Animation
             // otherwise we have no trigger, we'll just start ASAP
         }
 
-        AnimRecord arec = new AnimRecord(
+        AnimRecord arec = new AnimRecord(anim, delta, trigger, completionAction);
-            anim, delta, trigger, completionAction);
 //         Log.info("Queued " + arec + ".");
         _queued.add(arec);
     }
@@ -174,11 +164,10 @@ public class AnimationSequencer extends Animation
     }
 
     /**
-     * Called when the time comes to start an animation.  Derived classes
+     * Called when the time comes to start an animation. Derived classes may override this method
-     * may override this method and pass the animation on to their
+     * and pass the animation on to their animation manager and do whatever else they need to do
-     * animation manager and do whatever else they need to do with
+     * with operating animations. The default implementation simply adds them to the media panel
-     * operating animations. The default implementation simply adds them
+     * supplied when we were constructed.
-     * to the media panel supplied when we were constructed.
      *
      * @param anim the animation to be displayed.
      * @param tickStamp the timestamp at which this animation was fired.
@@ -196,37 +185,31 @@ public class AnimationSequencer extends Animation
 
     protected class AnimRecord extends AnimationAdapter
     {
-        public AnimRecord (Animation anim, long delta, AnimRecord trigger,
+        public AnimRecord (
-                           Runnable completionAction) {
+            Animation anim, long delta, AnimRecord trigger, Runnable completionAction) {
             _anim = anim;
             _delta = delta;
             _trigger = trigger;
             _completionAction = completionAction;
         }
 
-        public boolean readyToFire (long now, long lastStamp)
+        public boolean readyToFire (long now, long lastStamp) {
-        {
             if (_delta == -1) {
-                // if we have no trigger, that means we should start
+                // if we have no trigger, that means we should start immediately, otherwise we wait
-                // immediately, otherwise we wait until our trigger is no
+                // until our trigger is no longer running (they are guaranteed not to be still
-                // longer running (they are guaranteed not to be still
+                // queued at this point because readyToFire is only called on an animation after
-                // queued at this point because readyToFire is only called
+                // all animations previous in the queue have been started)
-                // on an animation after all animations previous in the
+                return (_trigger == null) ? true : !_running.contains(_trigger);
-                // queue have been started)
-                return (_trigger == null) ?
-                    true : !_running.contains(_trigger);
 
             } else {
                 return (lastStamp + _delta <= now);
             }
         }
 
-        public void fire (long when)
+        public void fire (long when) {
-        {
 //             Log.info("Firing " + this + " at " + (when%10000) + ".");
 
-            // if we have an animation, start it up and await its
+            // if we have an animation, start it up and await its completion
-            // completion
             if (_anim != null) {
                 startAnimation(_anim, when);
                 _anim.addAnimationObserver(this);
@@ -238,8 +221,7 @@ public class AnimationSequencer extends Animation
             }
         }
 
-        public void fireCompletion (long when)
+        public void fireCompletion (long when) {
-        {
 //             Log.info("Completing " + this + " at " + (when%10000) + ".");
 
             // call the completion action, if there is one
@@ -254,22 +236,19 @@ public class AnimationSequencer extends Animation
             // make a note that this animation is complete
             _running.remove(this);
 
-            // kids, don't try this at home; we call tick() immediately so
+            // kids, don't try this at home; we call tick() immediately so that any animations
-            // that any animations triggered on the completion of previous
+            // triggered on the completion of previous animations can trigger on the completion of
-            // animations can trigger on the completion of this animation
+            // this animation rather than having to wait until the next tick to do so
-            // rather than having to wait until the next tick to do so
             tick(when);
         }
 
         @Override
-        public void animationCompleted (Animation anim, long when)
+        public void animationCompleted (Animation anim, long when) {
-        {
             fireCompletion(when);
         }
 
         @Override
-        public String toString ()
+        public String toString () {
-        {
             return "[anim=" + StringUtil.shortClassName(_anim) +
                 ((_anim == null) ? "" : ("/" + _anim.hashCode())) +
                 ", action=" + _completionAction +

src/java/com/threerings/media/animation/BlankAnimation.java

@@ -25,9 +25,8 @@ import java.awt.Graphics2D;
 import java.awt.Rectangle;
 
 /**
- * Displays nothing, but does so for a specified amount of time. Useful
+ * Displays nothing, but does so for a specified amount of time. Useful when you want to get an
- * when you want to get an animation completed event in some period of
+ * animation completed event in some period of time but don't actually need to display anything.
- * time but don't actually need to display anything.
  */
 public class BlankAnimation extends Animation
 {

src/java/com/threerings/media/animation/FadeAnimation.java

@@ -27,9 +27,8 @@ import java.awt.Rectangle;
 import com.threerings.media.effects.FadeEffect;
 
 /**
- * An animation that displays an image fading from one alpha level to
+ * An animation that displays an image fading from one alpha level to another in specified
- * another in specified increments over time.  The animation is finished
+ * increments over time. The animation is finished when the specified target alpha is reached.
- * when the specified target alpha is reached.
  */
 public abstract class FadeAnimation extends Animation
 {
@@ -41,8 +40,7 @@ public abstract class FadeAnimation extends Animation
      * @param step the alpha amount to step by each millisecond.
      * @param target the target alpha level.
      */
-    protected FadeAnimation (
+    protected FadeAnimation (Rectangle bounds, float alpha, float step, float target)
-        Rectangle bounds, float alpha, float step, float target)
     {
         super(bounds);
         _effect = new FadeEffect(alpha, step, target);

src/java/com/threerings/media/animation/SpriteAnimation.java

@@ -33,9 +33,8 @@ public class SpriteAnimation extends Animation
     implements PathObserver
 {
     /**
-     * Constructs a sprite animation for the given sprite. The first time
+     * Constructs a sprite animation for the given sprite. The first time the animation is ticked,
-     * the animation is ticked, the sprite will be added to the given
+     * the sprite will be added to the given sprite manager and started along the supplied path.
-     * sprite manager and started along the supplied path.
      */
     public SpriteAnimation (SpriteManager spritemgr, Sprite sprite, Path path)
     {

src/java/com/threerings/media/sprite/PathObserver.java

@@ -25,15 +25,14 @@ import com.threerings.media.FrameManager;
 import com.threerings.media.util.Path;
 
 /**
- * An interface to be implemented by classes that would like to be
+ * An interface to be implemented by classes that would like to be notified when a sprite
- * notified when a sprite completes or cancels its path.
+ * completes or cancels its path.
  */
 public interface PathObserver
 {
     /**
-     * Called when a sprite's path is cancelled either because a new path
+     * Called when a sprite's path is cancelled either because a new path was started or the path
-     * was started or the path was explicitly cancelled with {@link
+     * was explicitly cancelled with {@link Sprite#cancelMove}.
-     * Sprite#cancelMove}.
      */
     public void pathCancelled (Sprite sprite, Path path);
 
@@ -42,9 +41,9 @@ public interface PathObserver
      *
      * @param sprite the sprite that completed its path.
      * @param path the path that was completed.
-     * @param when the tick stamp of the media tick on which the path was
+     * @param when the tick stamp of the media tick on which the path was completed (see
-     * completed (see {@link FrameManager#tick}) (this may not be in the
+     * {@link FrameManager#tick}) (this may not be in the same time domain as
-     * same time domain as {@link System#currentTimeMillis}).
+     * {@link System#currentTimeMillis}).
      */
     public void pathCompleted (Sprite sprite, Path path, long when);
 }

src/java/com/threerings/media/util/Path.java

@@ -24,46 +24,42 @@ package com.threerings.media.util;
 import java.awt.Graphics2D;
 
 /**
- * A path is used to cause a {@link Pathable} to follow a particular path
+ * A path is used to cause a {@link Pathable} to follow a particular path along the screen. The
- * along the screen. The {@link Pathable} is responsible for calling
+ * {@link Pathable} is responsible for calling {@link #tick} on the path with reasonable frequency
- * {@link #tick} on the path with reasonable frequency (generally as a
+ * (generally as a part of the frame tick. The path is responsible for updating the position of
- * part of the frame tick. The path is responsible for updating the
+ * the {@link Pathable} based on the time that has elapsed since the {@link Pathable} started down
- * position of the {@link Pathable} based on the time that has elapsed
+ * the path.
- * since the {@link Pathable} started down the path.
  *
- * <p> The path should call the appropriate callbacks on the {@link
+ * <p> The path should call the appropriate callbacks on the {@link Pathable} when appropriate
- * Pathable} when appropriate (e.g. {@link Pathable#pathBeginning}, {@link
+ * (e.g. {@link Pathable#pathBeginning}, {@link Pathable#pathCompleted}).
- * Pathable#pathCompleted}).
  */
 public interface Path
 {
     /**
-     * Called once to let the path prepare itself for the process of
+     * Called once to let the path prepare itself for the process of animating the supplied
-     * animating the supplied pathable. Path users should also call {@link
+     * pathable. Path users should also call {@link #tick} after {@link #init} with the same
-     * #tick} after {@link #init} with the same initialization timestamp.
+     * initialization timestamp.
      */
     public void init (Pathable pable, long tickStamp);
 
     /**
-     * Called to request that this path update the position of the
+     * Called to request that this path update the position of the specified pathable based on the
-     * specified pathable based on the supplied timestamp information. A
+     * supplied timestamp information. A path should record its initial timestamp and determine
-     * path should record its initial timestamp and determine the progress
+     * the progress of the pathable along the path based on the time elapsed since the pathable
-     * of the pathable along the path based on the time elapsed since the
+     * began down the path.
-     * pathable began down the path.
      *
      * @param pable the pathable whose position should be updated.
      * @param tickStamp the timestamp associated with this frame.
      *
-     * @return true if the pathable's position was updated, false if the
+     * @return true if the pathable's position was updated, false if the path determined that the
-     * path determined that the pathable should not move at this time.
+     * pathable should not move at this time.
      */
     public boolean tick (Pathable pable, long tickStamp);
 
     /**
-     * This is called if the pathable is paused for some length of time
+     * This is called if the pathable is paused for some length of time and then unpaused. Paths
-     * and then unpaused. Paths should adjust any time stamps they are
+     * should adjust any time stamps they are maintaining internally by the delta so that time
-     * maintaining internally by the delta so that time maintains the
+     * maintains the illusion of flowing smoothly forward.
-     * illusion of flowing smoothly forward.
      */
     public void fastForward (long timeDelta);
 
@@ -73,10 +69,9 @@ public interface Path
     public void paint (Graphics2D gfx);
 
     /**
-     * When a path is removed from a pathable, whether that is because the
+     * When a path is removed from a pathable, whether that is because the path was completed or
-     * path was completed or because it was replaced by another path, this
+     * because it was replaced by another path, this method will be called to let the path know
-     * method will be called to let the path know that it is no longer
+     * that it is no longer associated with this pathable.
-     * associated with this pathable.
      */
     public void wasRemoved (Pathable pable);
 }

src/java/com/threerings/media/util/PathSequence.java

@@ -46,14 +46,23 @@ public class PathSequence
 
     /**
      * Construct a path sequence with the list of paths.
-     * Note: Paths may be added to the end of the list while
+     *
-     * the pathable is still traversing earlier paths!
+     * Note: Paths may be added to the end of the list while the pathable is still traversing
+     * earlier paths!
      */
     public PathSequence (List<Path> paths)
     {
         _paths = paths;
     }
 
+    /**
+     * Add a new path to the end of our current list.
+     */
+    public void addPath (Path path)
+    {
+        _paths.add(path);
+    }
+
     // documentation inherited from interface Path
     public void init (Pathable pable, long tickStamp)
     {
@@ -62,9 +71,8 @@ public class PathSequence
             @Override
             public void pathCompleted (long timeStamp) {
                 long initStamp;
-                // if we just finished a timed path, we can figure out how
+                // if we just finished a timed path, we can figure out how long ago it really
-                // long ago it really finished and init the next path at
+                // finished and init the next path at that time in the past.
-                // that time in the past.
                 if (_curPath instanceof TimedPath) {
                     initStamp = _lastInit + ((TimedPath) _curPath)._duration;
                 } else {
@@ -81,8 +89,7 @@ public class PathSequence
     public boolean tick (Pathable pable, long tickStamp)
     {
         if (pable != _pable) {
-            log.warning("PathSequence ticked with different path than " +
+            log.warning("PathSequence ticked with different path than it was inited with.");
-                "it was inited with.");
         }
         return _curPath.tick(_pableRep, tickStamp);
     }