Class Animation

  • All Implemented Interfaces:
    FrameComposer

    public class Animation
    extends java.lang.Object
    implements FrameComposer
    A simple framework for basic animation effects in a user interface. This is intended for brief, noninteractive animations. Construct a new instance with the desired time to complete the animation, in seconds. Override composeFrame(float) to update the interface to a state between the initial (position=0) and final (position=1) conditions. (Alternatively, use the constructor that takes a FrameComposer parameter.)
    Author:
    Chris Jennings
    • Constructor Summary

      Constructors 
      Constructor Description
      Animation​(float timeToComplete)
      Creates a new animation that calls the built-in compose method and runs for the specified time at a target frame rate of approximately 30 fps.
      Animation​(float timeToComplete, int maxFrames)
      Creates a new animation that calls the built-in compose method and runs for the specified time.
      Animation​(float timeToComplete, int maxFrames, FrameComposer composer)
      Creates a new animation that calls the specified frame composer and runs for the specified time.
      Animation​(float timeToComplete, FrameComposer composer)
      Creates a new animation that calls the built-in compose method and runs for the specified time.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addFinishAction​(java.awt.event.ActionListener li)
      Adds an action listener that will be called when this animation finishes playing or is stopped.
      void composeFrame​(float position)
      This method is called with a value between 0 (start) and 1 (end) if no other composer has been set on this animation.
      protected void fireFinishAction()
      Called when the animation finishes or stops to fire off action events to registered listeners.
      FrameComposer getComposer()
      Returns the composer that will be used to create frames for this animation.
      float getDuration()
      Returns the ideal play time for the animation.
      int getMaxFrames()
      Returns the limit on the number of frames that will be composed.
      boolean isPlaying()
      Returns true if the animation is still playing.
      boolean isStopped()
      Returns true if the animation is stopped or stopping.
      void play()
      Starts playing the animation.
      void play​(java.lang.Object interruptTag)
      Starts playing the animation after stopping any other animations started with the same interrupt tag.
      void removeFinishAction​(java.awt.event.ActionListener li)
      Removes a previously added finish action.
      void setComposer​(FrameComposer composer)
      Sets the composer that will be user to create frames for this animation.
      void setDuration​(float timeToComplete)
      Sets the ideal play time for the animation.
      void setMaxFrames​(int maxFrames)
      Sets a limit on the number of frames that will be composed.
      void stop()
      This method can be called from within composeFrame(float) or from elsewhere.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • Animation

        public Animation​(float timeToComplete)
        Creates a new animation that calls the built-in compose method and runs for the specified time at a target frame rate of approximately 30 fps.
        Parameters:
        timeToComplete - the duration of the animation
        See Also:
        setDuration(float)
      • Animation

        public Animation​(float timeToComplete,
                         int maxFrames)
        Creates a new animation that calls the built-in compose method and runs for the specified time.
        Parameters:
        timeToComplete - the duration of the animation
        maxFrames - a hint describing the maximum number of frames to display
        See Also:
        setDuration(float), setMaxFrames(int)
      • Animation

        public Animation​(float timeToComplete,
                         FrameComposer composer)
        Creates a new animation that calls the built-in compose method and runs for the specified time.
        Parameters:
        timeToComplete - the duration of the animation
        See Also:
        setDuration(float)
      • Animation

        public Animation​(float timeToComplete,
                         int maxFrames,
                         FrameComposer composer)
        Creates a new animation that calls the specified frame composer and runs for the specified time.
        Parameters:
        timeToComplete - the duration of the animation
        maxFrames - a hint describing the maximum number of frames to display
        See Also:
        setDuration(float), setMaxFrames(int)
    • Method Detail

      • composeFrame

        public void composeFrame​(float position)
        This method is called with a value between 0 (start) and 1 (end) if no other composer has been set on this animation. It should set up the animation state accordingly.
        Specified by:
        composeFrame in interface FrameComposer
        Parameters:
        position - the animation position
      • play

        public void play()
        Starts playing the animation.
      • play

        public void play​(java.lang.Object interruptTag)
        Starts playing the animation after stopping any other animations started with the same interrupt tag. This can be used to ensure that two animations on the same object don't counteract each other. For example, suppose a button darkens when the pointer moves over it and lightens when the pointer moves off again. If the pointer moved quickly over and then off of the button, then the darkening and lightening animations would play overtop of each other. By playing these animations using the same tag, such as the button instance, this effect would be prevented.
        Parameters:
        interruptTag - the mutual exclusion tag that will mark this playthrough
      • stop

        public void stop()
        This method can be called from within composeFrame(float) or from elsewhere.
      • isStopped

        public boolean isStopped()
        Returns true if the animation is stopped or stopping.
        Returns:
        true if the animation is or will be stopped
      • isPlaying

        public boolean isPlaying()
        Returns true if the animation is still playing. (This will still be true after calling stop() until the animation actually halts.)
        Returns:
        true if the animation is playing
      • getDuration

        public float getDuration()
        Returns the ideal play time for the animation.
        Returns:
        the time for the animation to complete, in seconds
      • setDuration

        public void setDuration​(float timeToComplete)
        Sets the ideal play time for the animation. Actual play time will usually be close to, but not exactly match, this value. Note that the animation will always display positions 0 and 1; if composition is slow this may take significantly longer than the play time.
        Parameters:
        timeToComplete - the time for the animation to complete, in seconds
      • getComposer

        public FrameComposer getComposer()
        Returns the composer that will be used to create frames for this animation.
        Returns:
        the composer
      • setComposer

        public void setComposer​(FrameComposer composer)
        Sets the composer that will be user to create frames for this animation.
        Parameters:
        composer - the animation composer to set
      • getMaxFrames

        public int getMaxFrames()
        Returns the limit on the number of frames that will be composed.
        Returns:
        the maxCalls
      • setMaxFrames

        public void setMaxFrames​(int maxFrames)
        Sets a limit on the number of frames that will be composed.
        Parameters:
        maxFrames - the maximum number of frames
      • addFinishAction

        public void addFinishAction​(java.awt.event.ActionListener li)
        Adds an action listener that will be called when this animation finishes playing or is stopped.
        Parameters:
        li - the listener to call
        Throws:
        java.lang.NullPointerException - if the listener is null
      • removeFinishAction

        public void removeFinishAction​(java.awt.event.ActionListener li)
        Removes a previously added finish action.
        Parameters:
        li - the listener to remove
      • fireFinishAction

        protected void fireFinishAction()
        Called when the animation finishes or stops to fire off action events to registered listeners.