MIDP3.0

javax.microedition.lcdui
Class AnimatedImage

java.lang.Object
  extended by javax.microedition.lcdui.Image
      extended by 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

MIDP3.0

Send a comment or suggestionVersion 3.0 of Mobile Information Device Profile Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries. Copyright 2002-2009 Motorola Inc. Portions copyright 1993-2002 Sun Microsystems, Inc. and Motorola, Inc. All Rights Reserved.