danger.ui
Class AnimatedBitmap

java.lang.Object
  danger.ui.AnimatedBitmap

public class AnimatedBitmap
extends Object

An AnimatedBitmap contains the data for an animated bitmap. Currently, only animated GIF data can be decoded. You can alternatively create an animation consisting of a series of Bitmap objects. An AnimatedBitmap may be obtained from resources by using ResourceDatabase.getAnimatedBitmap(int, int). Use AnimatedBitmapView to actually display the AnimatedBitmap.

Field Summary

static int	CREATE_FLAG_CONSERVE_MEM Flag that can be passed to create(byte[], int).
static int	CREATE_FLAG_PRE_DECODE Flag that can be passed to create(byte[], int).
static int	FLAG_DO_NOT_RESTORE Flag that can be passed to addFrame(danger.ui.Bitmap, int, int).
static int	FLAG_RESTORE_BACKGROUND Flag that can be passed to addFrame(danger.ui.Bitmap, int, int).
static int	FLAG_RESTORE_PREVIOUS Flag that can be passed to addFrame(danger.ui.Bitmap, int, int).
static int	FLAG_USER_INPUT_EXPECTED Flag that can be passed to addFrame(danger.ui.Bitmap, int, int).

Constructor Summary

AnimatedBitmap()
Construct an instance.

Method Summary

void	addFrame(Bitmap bitmap, int delay, int flags) Add a frame to the animation.
void	convertToScreenColorSpace() Convert this animation to the native screen format.
static AnimatedBitmap	create(byte[] data, int decodeFlags) Create an AnimatedBitmap object from image data.
boolean	decodedFrame(int frameNum) Returns true if the specified frame number has been decoded.
int	decodingFrameNum() Returns the number of the frame currently being decoded.
void	doneAddingFrames() This method needs to be called if you add manually frames using addFrame(danger.ui.Bitmap, int, int).
void	drawFrame(Pen pen, int frameNum, int x, int y) Draw the specified frame at the specified coordinates, using the specified pen.
Bitmap	getBlankBitmap() Get a blank bitmap for decoding into.
Point	getDimensions() Get the dimensions of the animated bitmap.
int	getFrameDelay(int frameNum) Get the delay (in milliseconds) for the specified frame.
int	getFrameNum(int frameNum) If the number of frames has been determined, then this returns a valid frame number (the specified frame number modulo the actual number of frames).
int	getNumFrames() Returns the number of frames in this animation.
void	releaseFrames() Free up the memory used by the frames.
void	scaleTo(int width, int height) Scale this animation to the specified dimensions.
void	waitForFrame(Listener listener, int eventType, int frameNum) Wait for the specified frame to be decoded.

Methods inherited from class java.lang.Object

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

Field Detail

CREATE_FLAG_PRE_DECODE

public static final int CREATE_FLAG_PRE_DECODE

Flag that can be passed to create(byte[], int). Specifies that the animated bitmap should be completely decoded before being displayed. A particular frame has been decoded if decodingFrameNum() is -1 or is greater than the frame number. A value of -1 indicates that all frames have been decoded. By default, the animated bitmap is decoded in a separate thread and frames are displayed when they are ready, or at the appropriate time, whichever is later. Animations may play slower than normal the first time through, but will play at normal speed after that. This flag cannot be used with CREATE_FLAG_CONSERVE_MEM.

See Also:

Constant Field Values

CREATE_FLAG_CONSERVE_MEM

public static final int CREATE_FLAG_CONSERVE_MEM

Flag that can be passed to create(byte[], int). Specifies that the animated bitmap should only keep up to two frames in memory -- the last one drawn (via drawFrame(danger.ui.Pen, int, int, int)), and the frame after it. Use decodingFrameNum() as above to determine if a frame is ready to be displayed. Note that using this option may cause animations to play slower than normal. By default, all frames are kept in memory at once. This flag cannot be used with CREATE_FLAG_PRE_DECODE.

See Also:

Constant Field Values

FLAG_DO_NOT_RESTORE

public static final int FLAG_DO_NOT_RESTORE

Flag that can be passed to addFrame(danger.ui.Bitmap, int, int). Specifies that the background should not be restored before displaying the frame.

See Also:

Constant Field Values

FLAG_RESTORE_BACKGROUND

public static final int FLAG_RESTORE_BACKGROUND

Flag that can be passed to addFrame(danger.ui.Bitmap, int, int). Currently not honored.

See Also:

Constant Field Values

FLAG_RESTORE_PREVIOUS

public static final int FLAG_RESTORE_PREVIOUS

Flag that can be passed to addFrame(danger.ui.Bitmap, int, int). Currently not honored.

See Also:

Constant Field Values

FLAG_USER_INPUT_EXPECTED

public static final int FLAG_USER_INPUT_EXPECTED

Flag that can be passed to addFrame(danger.ui.Bitmap, int, int). Currently not honored.

See Also:

Constant Field Values

Constructor Detail

AnimatedBitmap

public AnimatedBitmap()

Construct an instance. You can subsequently add frames to the animation by using addFrame(danger.ui.Bitmap, int, int).

Method Detail

create

public static AnimatedBitmap create(byte[] data,
                                    int decodeFlags)

Create an AnimatedBitmap object from image data. This is usually animated GIF data. However, if you pass in other supported image data (JPEG, single-image GIF, PNG, or WBMP), then a single-frame animation will be returned.

Parameters:

data - the animated GIF data

decodeFlags - flags to determine how the animation should be decode. Can be CREATE_FLAG_PRE_DECODE or CREATE_FLAG_CONSERVE_MEM, or 0.

getDimensions

public Point getDimensions()

Get the dimensions of the animated bitmap.

convertToScreenColorSpace

public void convertToScreenColorSpace()

Convert this animation to the native screen format.

scaleTo

public void scaleTo(int width,
                    int height)

Scale this animation to the specified dimensions.

getBlankBitmap

public Bitmap getBlankBitmap()

Get a blank bitmap for decoding into. AnimatedBitmap uses this when decoding with the CREATE_FLAG_CONSERVE_MEM flag. You generally will not have to use this method, since it is used automatically if necessary.

getFrameNum

public int getFrameNum(int frameNum)

If the number of frames has been determined, then this returns a valid frame number (the specified frame number modulo the actual number of frames). Otherwise, it simply returns the frame number you pass into it.

decodedFrame

public boolean decodedFrame(int frameNum)

Returns true if the specified frame number has been decoded.

decodingFrameNum

public int decodingFrameNum()

Returns the number of the frame currently being decoded. Returns -1 if no frame is being decoded.

waitForFrame

public void waitForFrame(Listener listener,
                         int eventType,
                         int frameNum)

Wait for the specified frame to be decoded. When the frame is ready, then an event with the specified eventType is sent to the specified listener.

addFrame

public void addFrame(Bitmap bitmap,
                     int delay,
                     int flags)

Add a frame to the animation. You won't need to call this if you use create(byte[], int). You would only use this if you are creating an animation by hand. When you are done adding frames, be sure to call doneAddingFrames().

Parameters:

bitmap - the bitmap specifying the frame

delay - the delay for the frame, in milliseconds

flags - can be one of FLAG_DO_NOT_RESTORE, FLAG_RESTORE_BACKGROUND, FLAG_RESTORE_PREVIOUS, or FLAG_USER_INPUT_EXPECTED.

doneAddingFrames

public void doneAddingFrames()

This method needs to be called if you add manually frames using addFrame(danger.ui.Bitmap, int, int).

getNumFrames

public int getNumFrames()

Returns the number of frames in this animation.

getFrameDelay

public int getFrameDelay(int frameNum)

Get the delay (in milliseconds) for the specified frame.

drawFrame

public void drawFrame(Pen pen,
                      int frameNum,
                      int x,
                      int y)

Draw the specified frame at the specified coordinates, using the specified pen. The frame must already have been decoded. Trying to draw a frame that hasn't been decoded yet will result in a NullPointerException.

releaseFrames

public void releaseFrames()

Free up the memory used by the frames. This does nothing if the animated bitmap was created using the CREATE_FLAG_PRE_DECODE flag. Otherwise, it releases the decoded frames for garbage collection. When they are needed again, it will decode them again. Important note: The frames will not be released until the animation has been completely decoded. Making any of the following method calls before this process is complete will cancel this releaseFrames call: decodedFrame(int), decodingFrameNum(), getNumFrames(), getFrameDelay(int), drawFrame(danger.ui.Pen, int, int, int), waitForFrame(danger.app.Listener, int, int).