javax.microedition.lcdui
Class AnimatedImage

java.lang.Object
  javax.microedition.lcdui.Image
      javax.microedition.lcdui.AnimatedImage

public class AnimatedImage
extends Image

An AnimatedImage is a special type of Image that encapsulates a series frames and the length of time that each frame should be shown.

An AnimatedImage is obtained by calling Image.createImage with animated image data from a named resource, byte array, or input stream. GIF89a image data format MUST be supported. The returned object will be an instance of an AnimatedImage and can be cast accordingly. The Image.isAnimated() method can be called on any Image instance to determine whether or not it is animated and can be cast to an AnimatedImage.

An immutable Image representing an individual frame may be retrieved by calling getFrame with the desired frame index. The index of the first frame is zero. To reduce file size, some formats may store partial frames that need to be overlaid on top of prior frames in order to create a complete rendered frame. For these formats, the implementation is responsible for combining partial frames with prior frames as needed, and each Image returned by getFrame must contain a complete frame that can be rendered as-is.

As a subclass of Image, an AnimatedImage may itself be used as an argument for various methods that render, copy, or retrieve pixel data from an Image. When used in this manner, the first frame of the AnimatedImage is used. For example, the operation

 g.drawImage(myAnimatedImage, 0, 0, Graphics.LEFT + Graphics.TOP);
 

is equivalent to

 g.drawImage(myAnimatedImage.getFrame(0), 0, 0, Graphics.LEFT + Graphics.TOP);
 

When used with an ImageItem, List, or other high-level UI element, the implementation may automatically animate an AnimatedImage when the UI element is shown. The implementation may stop animations after a period of time to reduce power consumption. If animations are not supported by the device's UI, the first frame of the animation is shown instead.

Applications using Canvas or CustomItem are responsible for triggering frame changes and the corresponding repaint requests. For example, a TimerTask or dedicated background thread may be used for this purpose. However, to avoid excessive power consumption, care should be taken to ensure that animations are not run indefinitely or while the Canvas or CustomItem is not visible.

The following example illustrates how an AnimatedImage may be shown on a Canvas. This example restarts the animation each time the Canvas is shown, but it is also possible to pause and resume the animation instead.

 
  public class MyCanvas extends Canvas implements Runnable {

  AnimatedImage img = (AnimatedImage)Image.createImage("MyAnimatedLogo.gif");

  int currentFrame = 0;
  int updateCount = 0;
  boolean loopForever = false;
  boolean canvasIsShown = false;

  public void paint(Graphics g) {
      // Render the current frame
      g.drawImage(img.getFrame(currentFrame), 0,0, Graphics.TOP + Graphics.LEFT);
  }

  public void showNotify() {
      // Start the animation at the first frame
      canvasIsShown = true;
      currentFrame = 0;
      new Thread(this).start();
  }

  public synchronized void hideNotify() {
      // End the animation
      canvasIsShown = false;
      notify();
  }

  public void run() {

      // Determine if the animation should run for a finite number of frames
      int loopCount = img.getLoopCount();
      if (loopCount == -1)
          loopForever = true;
      else
          updateCount = (loopCount + 1) * img.getFrameCount();

      synchronized (this) {
          // Run the animation while the Canvas is shown
          while (canvasIsShown) {

              // Paint the current frame
              repaint();

              // Wait until the next frame should be painted
              try {
                  wait(img.getFrameDelay(currentFrame));
              } catch (Exception e) { }

              // Move to the next frame
              currentFrame = (currentFrame + 1) % img.getFrameCount();

              // Check if the animation should end
              if ((!loopForever) && (--updateCount == 0)) return;
          }
      }
  }

  }

 
 

Since:

MIDP 3.0

Method Summary

Image	getFrame(int index) Gets the Image for the specified frame.
int	getFrameCount() Gets the number of frames in this AnimatedImage.
int	getFrameDelay(int index) Gets the frame delay for the specified frame.
int	getLoopCount() Gets the number of times that the animation loop should be repeated.

Methods inherited from class javax.microedition.lcdui.Image

createImage, createImage, createImage, createImage, createImage, createImage, createImage, createImage, createRGBImage, getARGB16, getGraphics, getHeight, getRGB, getRGB16, getWidth, hasAlpha, isAnimated, isMutable, isScalable

Methods inherited from class java.lang.Object

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

Method Detail

getFrameCount

public int getFrameCount()

Gets the number of frames in this AnimatedImage.

Returns:

the number of frames

getFrame

public Image getFrame(int index)

Gets the Image for the specified frame. To avoid the creation of garbage objects, the same Image object is returned when this method is called with the same index value. The index of the first frame is 0.

Parameters:

index - the index of the frame

Returns:

An Image containing the pixel data for the frame

Throws:

java.lang.IndexOutOfBoundsException - if the index is invalid

getFrameDelay

public int getFrameDelay(int index)

Gets the frame delay for the specified frame. The delay indicates the amount of time that the specified frame should be shown before being replaced with the next frame.

Parameters:

index - the index of the frame

Returns:

The frame delay, in milliseconds

Throws:

java.lang.IndexOutOfBoundsException - if the index is invalid

getLoopCount

public int getLoopCount()

Gets the number of times that the animation loop should be repeated. A value of 0 indicates that the sequence of frames should be animated only once and then stop. A value of 1 indicates that the sequence of frames should be repeated once, resulting in 2 complete frame sequences. A value of -1 indicates that the animation should be repeated indefinitely.

Returns:

the loop count for this animation