Class AnimatedPanelGraphics

java.lang.Object
org.bzdev.swing.AnimatedPanelGraphics
All Implemented Interfaces:
ISWriterOps

public class AnimatedPanelGraphics extends Object implements ISWriterOps
Animation-panel class implementing the ISWriterOps interface. While instances of this class can be created directly, it is usually more convenient to use the method newFramedInstance(ISWriterOps.AnimationParameters,String,boolean,boolean,AnimatedPanelGraphics.Mode), newFramedInstance(ISWriterOps.AnimationParameters,String,boolean,AnimatedPanelGraphics.ExitAccessor,AnimatedPanelGraphics.Mode), newFramedInstance(int,int,double,String,boolean,boolean,AnimatedPanelGraphics.Mode). or newFramedInstance(int,int,double,String,boolean,AnimatedPanelGraphics.ExitAccessor,AnimatedPanelGraphics.Mode). The interface ISWriterOps.AnimationParameters is implemented by the class Animation2D.

Once an instance is created directly, one must call addMetadata(int,int,double) or addMetadata(int,int,String,double,String), which instances of Animation2D will do when the user calls its Animation2D.initFrames(int,ISWriterOps) method (the preferred initFrames method for this case), and which the newFramedInstance methods of AnimatedPanelGraphics will also do.

To create an image to display, one will call nextOutputStreamGraphics() or nextOutputStreamGraphics(int) to create an output-stream-graphics object. This object's OSGraphicsOps.createGraphics() method will then be called to create a graphics context. That graphics context will be used for drawing the image. once done, the output-stream-graphics method OSGraphicsOps.imageComplete() must be called before creating the next image. This sequence of operations is handled automatically by the Animation2D class.

Once all the images are created, the method close() must be called. This method indicates that no more images will be generated, and any progress bar displayed as a result of calling newFramedInstance will be removed.

As an example, one can create an animation and display it immediately in a window as follows:


     Animation2D a2d = new Animation2D(400, 250, 1000.0, 40);
     AnimatedPanelGraphics apg =
      AnimatedPanelGraphics.newFramedInstance
          (animation, "Example", true, true, null);
     // create and configure the animation objects
     ...
     // get number of frames for an animation running for 30 seconds
     int maxframes = a2d.estimateFrameCount(30.0);
     a2d.initFrames(maxframes, apg);
     a2d.scheduleFrames(0, maxframes);
     a2d.run();
     apg.close();
 

While the AnimatedPanelGraphics class has Java 'swing' components associated with it, the constructors and the newFramedInstance methods are thread safe - their use is not restricted to the event dispatch thread. Consequently, it is easy to create a command-line program that will open a window to display its output and exit when that window is closed.

  • Constructor Details

  • Method Details

    • setLocale

      public void setLocale(Locale locale)
      Set the locale.
      Parameters:
      locale - the locale
    • addMetadata

      public void addMetadata(int frameWidth, int frameHeight, double frameRate) throws IOException, IllegalStateException
      Description copied from interface: ISWriterOps
      Add the metadata entry without a media type and without a format string. Subclasses that require a format field should document any requirements on the printf string the format supplies. When needed, defaults will be provided for the media type and image-name format string.
      Specified by:
      addMetadata in interface ISWriterOps
      Parameters:
      frameWidth - the frame width in pixels
      frameHeight - the frame height in pixels
      frameRate - the number of frames per second
      Throws:
      IOException - an IO error occurred
      IllegalStateException - metadata was already added
    • addMetadata

      public void addMetadata(int frameWidth, int frameHeight, String frameMimeType, double frameRate, String format) throws IOException, IllegalStateException
      Add the metadata entry in full. Subclasses that require a format field should document any requirements on the printf string the format supplies. If not needed, the format field will be ignored. The frameMimeType and format arguments are ignored. One should use the method ISWriterOps.addMetadata(int,int,double) instead for clarity.
      Specified by:
      addMetadata in interface ISWriterOps
      Parameters:
      frameWidth - the frame width in pixels
      frameHeight - the frame height in pixels
      frameMimeType - the media type of the frames
      frameRate - the number of frames per second
      format - the printf string that will produce the name of an image given an integer; null for a default value
      Throws:
      IOException - an IO error occurred
      IllegalStateException - metadata was already added
    • setEstimatedFrameCount

      public void setEstimatedFrameCount(long count)
      Description copied from interface: ISWriterOps
      Specify the estimated number of frames as a long integer. The estimated frame count is an estimate of the number of images or frames in a sequence.
      Specified by:
      setEstimatedFrameCount in interface ISWriterOps
      Parameters:
      count - the number of frames; 0 for unknown
    • getEstimatedFrameCount

      public long getEstimatedFrameCount()
      Get the estimated frame count.
      Returns:
      the estimated frame count
    • getFrameWidth

      public int getFrameWidth()
      Description copied from interface: ISWriterOps
      Get the frame width. The frame width is the common width of all images in the sequence and is configured by a call to ISWriterOps.addMetadata(int,int,String), ISWriterOps.addMetadata(int,int,String,String), ISWriterOps.addMetadata(int,int,double), or ISWriterOps.addMetadata(int,int,String,double,String). If one of these methods has not been called, a value of zero will be returned.
      Specified by:
      getFrameWidth in interface ISWriterOps
      Returns:
      the frame width
    • getFrameHeight

      public int getFrameHeight()
      Description copied from interface: ISWriterOps
      Get the frame height. The frame height is the common width of all images in the sequence, and is configured by a call to ISWriterOps.addMetadata(int,int,String), ISWriterOps.addMetadata(int,int,String,String), ISWriterOps.addMetadata(int,int,double), or ISWriterOps.addMetadata(int,int,String,double,String). If one of these methods has not been called, a value of zero will be returned.
      Specified by:
      getFrameHeight in interface ISWriterOps
      Returns:
      the frame height
    • getPanel

      public JPanel getPanel()
      Get the JPanel associated with this instance. The JPanel associated with this instance is not available until addMetadata(int,int,double) or addMetadata(int,int,String,double,String) is called.
      Returns:
      the panel; null if the panel it not yet available
      Throws:
      IllegalStateException - the panel is not yet available
    • setBackground

      public void setBackground(Color c)
      Set the background color for the panel associated with this object. The JPanel associated with this instance is not available until addMetadata(int,int,double) or addMetadata(int,int,String,double,String) is called.
      Parameters:
      c - the color; null if the color of the panel's parent should be used
      Throws:
      IllegalStateException - the panel is not yet available
    • getBackground

      public Color getBackground()
      Get the background color for the panel associated with this object. The JPanel associated with this instance is not available until addMetadata(int,int,double) or addMetadata(int,int,String,double,String) is called.
      Returns:
      the background color
      Throws:
      IllegalStateException - the panel is not yet available
    • getPanelWindow

      public Window getPanelWindow()
      Find the top-level container for the panel associated with this object and return non-null if the container is a Window. The JPanel associated with this instance is not available until addMetadata(int,int,double) or addMetadata(int,int,String,double,String) is called.
      Returns:
      the window; null if there is none
      Throws:
      IllegalStateException - the panel is not yet available
    • setVisible

      public void setVisible(boolean visible)
      Set the visibility of the panel associated with this AnimatedPanelGraphics. This method has no effect if the panel is not contained in a window. The JPanel associated with this instance is not available until addMetadata(int,int,double) or addMetadata(int,int,String,double,String) is called.
      Parameters:
      visible - true if the panel should be visible; false otherwise
      Throws:
      IllegalStateException - the panel is not yet available
    • isVisible

      public boolean isVisible()
      Determine if the window containing the panel associated with this instance of PanelGraphics is visible. The JPanel associated with this instance is not available until addMetadata(int,int,double) or addMetadata(int,int,String,double,String) is called.
      Returns:
      true if it is visible; false if it is not visible or if the panel is not contained within a window
      Throws:
      IllegalStateException - the panel is not yet available
    • isLoaded

      public boolean isLoaded()
      Test if the video/animation has been loaded. A video/animation is considered to be loaded when the method close() has been called.
      Returns:
      true if the video/animation is loaded; false otherwise
    • play

      public void play()
      Start the video/animation. If loading is not yet complete, this method has no effect.
    • stop

      public void stop()
      Stop the video/animation.
    • adjust

      public void adjust(int incr)
      Move the current frame by a specified increment from its current location in the video/animation's time sequence. If the frame sequence is not fully loaded, this method returns without performing any action.
      Parameters:
      incr - the number of frames by which to shift the current frame
    • nextOutputStreamGraphics

      public OSGraphicsOps nextOutputStreamGraphics(String name) throws IllegalStateException
      Create a named graphics output stream for drawing graphics. To use this method, one will typically use the following design pattern:
          ISWriterOps isw = ...;
          ...
          String name = ...;
          OutputStreamGraphics osg = isw.nextOutputStreamGraphics(name);
          Graphics2D g2d = osg.createGraphics();
          // drawing operation using g2d
          ...
          g2d.displose();
          osg.imageComplete();
          osg.close();
       
      The name can be used by the object implementing this interface as a key for looking up an image or other object. How a name is interpreted is class specific. The name field is ignored by this class.
      Specified by:
      nextOutputStreamGraphics in interface ISWriterOps
      Parameters:
      name - the name for this output stream
      Returns:
      a graphics output stream for drawing an image
      Throws:
      IllegalStateException
    • nextOutputStreamGraphics

      public OSGraphicsOps nextOutputStreamGraphics() throws IllegalStateException
      Description copied from interface: ISWriterOps
      Create a graphics output stream for drawing graphics. To use this method, one will typically use the following design pattern:
          ISWriterOps isw = ...;
          ...
          OutputStreamGraphics osg = isw.nextOutputStreamGraphics();
          Graphics2D g2d = osg.createGraphics();
          // drawing operation using g2d
          ...
          g2d.displose();
          osg.imageComplete();
          osg.close();
       
      Specified by:
      nextOutputStreamGraphics in interface ISWriterOps
      Returns:
      a graphics output stream for drawing an image
      Throws:
      IllegalStateException
    • nextOutputStreamGraphics

      public OSGraphicsOps nextOutputStreamGraphics(String name, int count) throws IllegalStateException
      Create a named graphics output stream for drawing graphics, specifying a repetition count. To use this method, one will typically use the following design pattern:
          ISWriterOps isw = ...
          ...
          OSGraphicsOps osg = isw.nextOutputStreamGraphics(...);
          String name = ...;
      
          int count = ...;
          Graphics2D g2d = osg.createGraphics(name, count);
          // drawing operation using g2d
          ...
          g2d.displose();
          osg.imageComplete();
          osg.close();
       
      The name can be used by the object implementing this interface as a key for looking up an image or other object. How a name is interpreted is class specific. The name field is ignored by this class.
      Specified by:
      nextOutputStreamGraphics in interface ISWriterOps
      Parameters:
      name - the name for this output stream
      count - the repetition count for the entry corresponding to the graphics output stream that will be returned
      Returns:
      a graphics output stream for drawing graphics
      Throws:
      IllegalStateException
    • nextOutputStreamGraphics

      public OSGraphicsOps nextOutputStreamGraphics(int count) throws IllegalStateException, IllegalArgumentException
      Description copied from interface: ISWriterOps
      Create a graphics output stream for drawing graphics, specifying a repetition count. To use this method, one will typically use the following design pattern:
          ISWriterOps isw = ...
          ...
          OSGraphicsOps osg = isw.nextOutputStreamGraphics(...);
          int count = ...;
          Graphics2D g2d = osg.createGraphics(count);
          // drawing operation using g2d
          ...
          g2d.displose();
          osg.imageComplete();
          osg.close();
       
      Specified by:
      nextOutputStreamGraphics in interface ISWriterOps
      Parameters:
      count - the repetition count for the entry corresponding to the graphics output stream that will be returned
      Returns:
      a graphics output stream for drawing graphics
      Throws:
      IllegalStateException
      IllegalArgumentException
    • close

      public void close()
      Close this writer. For the case of AnimatedPanelGraphics, calling this method indicates that all the frames have been supplied. If there is a progress bar, its parent container will be made invisible and the original glass pane will be restored. The first image in the sequence will be displayed.
      Specified by:
      close in interface ISWriterOps
    • disposeFrame

      public void disposeFrame()
      Dispose this AnimatedPanelGraphic's window if that was created by a call to newFramedInstance.
    • newFramedInstance

      public static AnimatedPanelGraphics newFramedInstance(ISWriterOps.AnimationParameters ap, String title, boolean visible, boolean exitOnClose, AnimatedPanelGraphics.Mode mode) throws IOException
      Create an instance of AnimatedPanelGraphics whose JPanel is placed within a JFrame given a set of animation parameters.

      Note: the first argument can be an instance of the class Animation2D, in which case the frames created by an animation will be displayed in sequence at the specified frame rate (the frame rate determines the time between frames with a granularity of 1 millisecond - a value set by the JRE/JDK).

      The mode argument determines if controls are shown as part of the frame and if the animation will run automatically or must be manually started.

      Parameters:
      ap - the animation parameters
      title - the frame's title
      visible - true if the frame should initially be visible
      exitOnClose - true if the application should exit when the frame is closed
      mode - the mode for the AnimatedPanelGraphics that will be created; null for a default (AnimatedPanelGraphics.Mode.START_PAUSED_SELECTABLE)
      Returns:
      the new instance of AnimatedPanelGraphics
      Throws:
      IOException - - if an IO exception occurred
      See Also:
    • newFramedInstance

      public static AnimatedPanelGraphics newFramedInstance(ISWriterOps.AnimationParameters ap, String title, boolean visible, AnimatedPanelGraphics.ExitAccessor accessor, AnimatedPanelGraphics.Mode mode) throws IOException
      Create an instance of AnimatedPanelGraphics whose JPanel is placed within a JFrame given a set of animation parameters with the frame's exit mode determined by an exit accessor.

      Note: the first argument can be an instance of the class Animation2D, in which case the frames created by an animation will be displayed in sequence at the specified frame rate (the frame rate determines the time between frames with a granularity of 1 millisecond - a value set by the JRE/JDK).

      The mode argument determines if controls are shown as part of the frame and if the animation will run automatically or must be manually started.

      Parameters:
      ap - the animation parameters
      title - the frame's title
      visible - true if the frame should initially be visible
      accessor - an exit accessor that determines if the frame will ask the user if the application should exit before exiting the application; null implies that the application will exit immediately.
      mode - the mode for the AnimatedPanelGraphics that will be created; null for a default (AnimatedPanelGraphics.Mode.START_PAUSED_SELECTABLE)
      Returns:
      the new instance
      Throws:
      IOException - - if an IO exception occurred
      See Also:
    • newFramedInstance

      public static AnimatedPanelGraphics newFramedInstance(int width, int height, double frameRate, String title, boolean visible, boolean exitOnClose, AnimatedPanelGraphics.Mode mode) throws IOException
      Create an instance of AnimatedPanelGraphics whose JPanel is placed within a JFrame.

      The mode argument determines if controls are shown as part of the frame and if the animation will run automatically or must be manually started.

      Parameters:
      width - the target frame width in user-space units
      height - the target frame height in user-space units
      frameRate - the frame rate in units of frames per second
      title - the frame's title
      visible - true if the frame should initially be visible
      exitOnClose - true if the application should exit when the frame is closed
      mode - the mode for the AnimatedPanelGraphics that will be created; null for a default (AnimatedPanelGraphics.Mode.START_PAUSED_SELECTABLE)
      Returns:
      the new instance
      Throws:
      IOException - - if an IO exception occurred
      See Also:
    • newFramedInstance

      public static AnimatedPanelGraphics newFramedInstance(int width, int height, double frameRate, String title, boolean visible, AnimatedPanelGraphics.ExitAccessor accessor, AnimatedPanelGraphics.Mode mode) throws IOException
      Create an instance of AnimatedPanelGraphics whose JPanel is placed within a JFrame with the frame's exit mode determined by an exit accessor.

      The mode argument determines if controls are shown as part of the frame and if the animation will run automatically or must be manually started.

      Parameters:
      width - the target frame width in user-space units
      height - the target frame height in user-space units
      frameRate - the frame rate in units of frames per second
      title - the frame's title
      visible - true if the frame should initially be visible
      accessor - an exit accessor that determines if the frame will ask the user if the application should exit before exiting the application; null implies that the application will exit immediately.
      mode - the mode for the AnimatedPanelGraphics that will be created; null for a default (AnimatedPanelGraphics.Mode.START_PAUSED_SELECTABLE)
      Returns:
      the new instance of AnimatedPanelGraphics
      Throws:
      IOException - - if an IO exception occurred
      See Also: