Documentation of 'vmm3d.core.ThreadedAnimation' Java class
ThreadedAnimation
Skip navigation links
vmm3d.core

Class ThreadedAnimation

  • All Implemented Interfaces:
    Animation
    Direct Known Subclasses:
    OsculatingCircleAnimation, ParallelCurveAnimation

    public abstract class ThreadedAnimation
extends java.lang.Object
implements Animation
    An animation that runs in its own thread, separate from the Swing user interface thread. Because Swing is not thread-safe and the animation runs in its own thread, it is not safe to call arbitrary Swing and org.freehep.graphics2d.VectorGraphics methods. (If it is necessary to call them, the invokeAndWait or invokeLater methods from class javax.swing.SwingUtilities can be used.) However, calling repaint is OK. Since setting parameter values and adding or removing decorations generate calls to repaint, they are also safe. Note that an animation does not start running automatically, but only when its start() method is called.

    To create a ThreadedAnimation, it is usually only necessary to create a subclass and implement runAnimation(), the single abstract method defined in this class. This method is a script for the animation, which is run from beginning to end. When this method returns, the animation ends; if the method never returns, then the animation must be canceled by some external agent that calls its cancel method.

    The runAnimation method can call the pause(int) method to insert a pause into the animation. Behind the scenes, this method also checks to see whether the animation has been canceled. If so, it throws an exception that aborts the animation. To avoid delays between the time when the animation's cancel method is called and tha time when the animation actually stops, it is important that pause be called regularly. If no delay is desired, pause can be called with a parameter of zero.

    Some animations will have some "clean-up" to do when the animation ends, whether it ends because the runAnimation method returns or because it has been canceled. to make sure that the clean-up is done in all cases, it is advisable to do the clean-up in a finally clause in the runAnimation method. For a simple example of this, see OsculatingCircleAnimation.runAnimation().

    A ThreadedAnimation emits ChangeEvents when it is started and when it ends. A ChangeListener can tell which event generated the ChangeEvent by calling the isRunning method of the animation. Note that in some circumstances, an alternative method for doing set-up and clean-up for the animation is to install a ChangeListener that does the set-up/clean-up in response to ChangeEvents.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method and Description
      void addChangeListener(javax.swing.event.ChangeListener listener)
      Add a ChangeListener to this animation.
      void cancel()
      Cancels the animation.
      java.lang.String getStatusText(boolean running)
      Returns null to indicate that the default text ("Animation Running" or "Animation Paused" in the English version) should be shown in the display's status bar.
      double getTimeDilation()
      Returns the time dilation factor that is currently set for this animation.
      boolean isPaused()
      Tests whether the animation is paused.
      boolean isRunning()
      Tests whether the animation is running.
      void removeChangeListener(javax.swing.event.ChangeListener listener)
      Remove a ChangeListener from the animation, if it is currently registered as a listener.
      void setPaused(boolean paused)
      Pauses or unpauses a running animation.
      void setTimeDilation(double dilationFactor)
      Slows down or speeds up the animation by multiplying all delay times (as specified in the parameter the pause method) by a time dilation factor.
      void start()
      This method must be called to start the animation running.
      boolean wasCanceled()
      Tests whether the animation has been canceled.

      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • ThreadedAnimation

        public ThreadedAnimation()

    • Method Detail

      • start

        public void start()
        This method must be called to start the animation running. An animation does not start automatically, but only when this method is called. If the animation is already running, this has no effect. If the animation has already run and ended, this will restart thea animation from the beginning. The animation will run until the runAnimation ends or until the animation is canceled.
        Specified by:
        start in interface Animation

      • setPaused

        public void setPaused(boolean paused)
        Pauses or unpauses a running animation. If the animation is not running, this has no effect.
        Specified by:
        setPaused in interface Animation
        Parameters:
        paused - if true, then the animation is paused; if false, then the animation is unpaused

      • isPaused

        public boolean isPaused()
        Tests whether the animation is paused. Only a running animation can be paused.
        Specified by:
        isPaused in interface Animation
        Returns:
        returns true if the animation is running but is in a paused state; returns false if it is not running or if it is running but is not paused.

      • cancel

        public void cancel()
        Cancels the animation. The animation will be stopped as soon as possible (that is, the next time the pause(int) method is called by runAnimation()). If the animation is not running, this has no effect.
        Specified by:
        cancel in interface Animation

      • isRunning

        public boolean isRunning()
        Tests whether the animation is running.
        Specified by:
        isRunning in interface Animation

      • wasCanceled

        public boolean wasCanceled()
        Tests whether the animation has been canceled. This can be called after the animation ends to determine whether the animation ended on its own or because it was canceled.

      • setTimeDilation

        public void setTimeDilation(double dilationFactor)
        Slows down or speeds up the animation by multiplying all delay times (as specified in the parameter the pause method) by a time dilation factor. Note that the dilation applies only to delay times, not to processing times, so the animation speed is only approximately multiplied by the dilation factor. In particular, only a limited amout of speed-up can be obtained, no matter how close to zero you make the dilation factor. The default value of the time dilation factor is 1, which corresponds to normal run speed.
        Specified by:
        setTimeDilation in interface Animation
        Parameters:
        dilationFactor - delay times for the pause method are multiplied by this factor to give the actual time delay. A dilationFactor less than zero is treated as zero.
        See Also:
        pause(int)

      • addChangeListener

        public void addChangeListener(javax.swing.event.ChangeListener listener)
        Add a ChangeListener to this animation. Change events are sent when the animation stops and when it stops for any reason. The ChangeListener can distinguish the two events by calling the isRunning method, which will retrun true if the animation is starting and false if the animation has ended.
        Specified by:
        addChangeListener in interface Animation
        Parameters:
        listener - a ChangeListener that is registered to receive change events from this animation.

      • removeChangeListener

        public void removeChangeListener(javax.swing.event.ChangeListener listener)
        Remove a ChangeListener from the animation, if it is currently registered as a listener.
        Specified by:
        removeChangeListener in interface Animation
        Parameters:
        listener - to be de-registered as a ChangeListener from this animation.

      • getStatusText

        public java.lang.String getStatusText(boolean running)
        Returns null to indicate that the default text ("Animation Running" or "Animation Paused" in the English version) should be shown in the display's status bar. This can be overridden in a subclass to show a different status message.
        Specified by:
        getStatusText in interface Animation
        Parameters:
        running - tells whether the animation is currently running.
        Returns:
        the text to displayed, or null to use the default text "Animation Running" or "Animation Paused"
Skip navigation links

DMelt 3.0 © DataMelt by jWork.ORG

You see the box below because you did not login.