superwaba.ext.xplat.game
Class Animation

java.lang.Object
  |
  +--waba.ui.Control
        |
        +--superwaba.ext.xplat.game.Animation
Direct Known Subclasses:
AnimatedButton

public class Animation
extends Control

The Animation control class.

 This control displays an animation that can be loaded from indexed BMP files
 (one frame per image) or by a multi-frames BMP. This kind of BMP file contains a
 list of images having all the same size and that lay side by side.
 You may use the Gif2Bmps tool in \superwaba\apps\xplat\Gif2Bmps folder to
 convert animated gif into the convenient format.

 warning: multi-frames BMP files can't be larger than 64Kb (the palmOS record limit)
 

See Also:
Gif2Bmps

Field Summary
protected  Image background
          Background image.
protected  Graphics bgGfx
          Background graphic context.
protected  int curFrame
          Current frame of the animation.
 int drawOp
          drawOp drawing operation used when the animation images are copied to the screen buffer.
static int eventFinish
          notify animation endings
static int eventFrame
          notify animation frames
static int eventLoop
          notify animation loops
static int eventNone
          no notify at all
protected  int eventsMask
          Event notification mask, default value is eventFinish, that means that an event is posted only when the animation finishes.
 int framePeriod
          Delay between two frames.
protected  Image[] framesBuffer
          Frames buffer, all frames must have the same size.
 boolean isPaused
          Reflects the animation pause state.
 boolean isPlaying
          Reflects the animation play state.
static int LOOPS_ONE_SHOT
          start function "loops" argument special value to do one loop
static int LOOPS_UNLIMITED
          start function "loops" argument special value to loop endlessly
protected  int maxFrames
          Maximum number of frames.
protected  boolean notifyEachFrame
          Should each frame drawing be notified ?
protected  Color transColor
          Transparency color.
 
Fields inherited from class waba.ui.Control
AFTER, appId, asContainer, asWindow, backColor, backDis, BEFORE, BOTTOM, CENTER, enabled, FILL, FIT, fm, fmH, focusLess, font, foreColor, foreDis, height, LEFT, parent, PREFERRED, RANGE, RIGHT, SAME, TOP, visible, width, x, x2, y, y2
 
Constructor Summary
Animation(Image frames, int frameWidth, Color transColor, int framePeriod)
          Animation constructor.
Animation(int maxFrames, Color transColor, int framePeriod)
          Deprecated. will be removed in next release
 
Method Summary
 int addFrame(Image frame)
          Deprecated. will be removed in next release
 int addMultiFrames(Image image, int width)
          Deprecated. will be removed in next release
 int addMultiFrames(String basename)
          Deprecated. will be removed in next release
 void drawFrame(int frame)
          Display a given frame.
 void enableEvents(int mask)
          Enable the posting of events.
 int getPreferredHeight()
          Returns the prefered height of this control.
 int getPreferredWidth()
          Returns the prefered width of this control.
 boolean notifyEachFrame(boolean enable)
          Deprecated. is replaced by notifyMask
 void onPaint(Graphics gfx)
          Called by the system to draw the animation.
 void pause()
          Pauses a running animation. if the application is not playing, this call has no effect.
 void renew(int maxFrames)
          Clear the animation to add new frames.
 void resume()
          Resumes a paused animation. if the application is not playing, this call has no effect.
 int setFrames(Image[] frames)
          Deprecated. will be removed in next release
 int size()
          Number of frames in the animation.
static Image[] splitImage(Image original, int frameWidth)
          This is a static helper function that divides a multi-frames BMP into distinguished Images.
The original image size should be a multiple of the frame width.
 void start(boolean loop)
          Deprecated. replaced by : public void start(int loops)
 void start(int loops)
          Starts the animation.
 void start(int[] frameSequence, boolean loop)
          Deprecated. replaced by : public void start(int frameSequence[],int loops)
 void start(int[] frameSequence, int loops)
          Starts the animation with a non standard frame sequence.
 void start(int sFrame, int eFrame, int step, boolean loop)
          Deprecated. replaced by : public void start(final int sFrame,final int eFrame,final int step,int loops)
 void start(int sFrame, int eFrame, int step, int loops)
          Starts the animation with a frame range.
 void stop()
          Stops the animation. if the application is not playing, this call has no effect.
 
Methods inherited from class waba.ui.Control
addTimer, contains, createGraphics, getAbsoluteRect, getBackColor, getFont, getFontMetrics, getForeColor, getNext, getParent, getParentWindow, getPos, getRect, getSize, isDisplayed, isEnabled, isVisible, onBoundsChanged, onColorsChanged, onEvent, onFontChanged, onWindowPaintFinished, postEvent, removeTimer, repaint, repaintNow, requestFocus, setBackColor, setBackForeColors, setEnabled, setFocusLess, setFont, setForeColor, setRect, setRect, setRect, setVisible
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, toString, wait, wait
 

Field Detail

drawOp

public int drawOp
drawOp drawing operation used when the animation images are copied to the screen buffer.
See Also:
Graphics

framePeriod

public int framePeriod
Delay between two frames.

curFrame

protected int curFrame
Current frame of the animation.

isPlaying

public boolean isPlaying
Reflects the animation play state.

isPaused

public boolean isPaused
Reflects the animation pause state.

transColor

protected Color transColor
Transparency color.

maxFrames

protected int maxFrames
Maximum number of frames.

framesBuffer

protected Image[] framesBuffer
Frames buffer, all frames must have the same size.

notifyEachFrame

protected boolean notifyEachFrame
Should each frame drawing be notified ?

eventsMask

protected int eventsMask
Event notification mask, default value is eventFinish, that means that an event is posted only when the animation finishes.

eventNone

public static final int eventNone
no notify at all

eventFinish

public static final int eventFinish
notify animation endings

eventLoop

public static final int eventLoop
notify animation loops

eventFrame

public static final int eventFrame
notify animation frames

LOOPS_UNLIMITED

public static final int LOOPS_UNLIMITED
start function "loops" argument special value to loop endlessly

LOOPS_ONE_SHOT

public static final int LOOPS_ONE_SHOT
start function "loops" argument special value to do one loop

background

protected Image background
Background image.

bgGfx

protected Graphics bgGfx
Background graphic context.
Constructor Detail

Animation

public Animation(int maxFrames,
                 Color transColor,
                 int framePeriod)
Deprecated. will be removed in next release

Animation constructor.
Parameters:
maxImages - maximum number of frames
transColor - the transparency color
framePeriod - delay in millisecconds between two frames

Animation

public Animation(Image frames,
                 int frameWidth,
                 Color transColor,
                 int framePeriod)
Animation constructor.
Parameters:
frames - single image containing all frames in mlti-frames BMP format.
frameWidth - width in pixels of one frame.
transColor - the transparency color
framePeriod - delay in millisecconds between two frames
See Also:
Gif2Bmps
Method Detail

renew

public void renew(int maxFrames)
           throws GameEngineException
Clear the animation to add new frames.

size

public int size()
Number of frames in the animation.
Returns:
frames amount

addFrame

public int addFrame(Image frame)
             throws GameEngineException
Deprecated. will be removed in next release

Add a frame to the animation.
Parameters:
image/frame - to add
Returns:
1 if the frame has been added, else 0
Throws:
GameEngineException -  

addMultiFrames

public int addMultiFrames(String basename)
                   throws GameEngineException
Deprecated. will be removed in next release

Add several frames to the animation. This function adds a list of images loaded from indexed image files. For instance a collection of files "myFrame0.bmp, myFrame1.bmp ... myFrameN.bmp"
Parameters:
basename - of the image filenames (ie. "myFrame")
Returns:
number of frames added
Throws:
GameEngineException -  
See Also:
This tool can convert animated gif files to such a numbered collection of BMP files.

addMultiFrames

public int addMultiFrames(Image image,
                          int width)
                   throws GameEngineException
Deprecated. will be removed in next release

Add several frames to the animation. This function adds a list of images contained in a single BMP file. The different frames have the same width and lay side by side, this function extracts the frames and builds the animation.
Parameters:
image - multi-frames BMP file ( < 64K palmOS record limit)
width - of one frame
Returns:
number of frames added
Throws:
GameEngineException -  
See Also:
This tool can convert animated gif files to such a numbered collection of BMP files.

setFrames

public int setFrames(Image[] frames)
              throws GameEngineException
Deprecated. will be removed in next release

Add several frames to the animation.
Parameters:
frames - to add
Returns:
number of frames added
Throws:
GameEngineException -  

getPreferredWidth

public int getPreferredWidth()
Returns the prefered width of this control.
Overrides:
getPreferredWidth in class Control

getPreferredHeight

public int getPreferredHeight()
Returns the prefered height of this control.
Overrides:
getPreferredHeight in class Control

drawFrame

public void drawFrame(int frame)
Display a given frame.
Parameters:
frame - index to display.

onPaint

public void onPaint(Graphics gfx)
Called by the system to draw the animation.
Overrides:
onPaint in class Control
Tags copied from class: Control
Parameters:
g - the graphics object for drawing
See Also:
Graphics

notifyEachFrame

public boolean notifyEachFrame(boolean enable)
Deprecated. is replaced by notifyMask

Enable the posting of frame displayed events.
Returns:
the previous state

enableEvents

public void enableEvents(int mask)
Enable the posting of events. By default the posting of events are disabled.

pause

public void pause()
Pauses a running animation. if the application is not playing, this call has no effect.

resume

public void resume()
Resumes a paused animation. if the application is not playing, this call has no effect.

stop

public void stop()
Stops the animation. if the application is not playing, this call has no effect.

start

public void start(boolean loop)
Deprecated. replaced by : public void start(int loops)

Starts the animation. This function starts the animation with or without looping when the end is reached. If the application is playing, this call has no effect.
Parameters:
loop - indicator to restart the animation automaticaly when it ends.

start

public void start(int sFrame,
                  int eFrame,
                  int step,
                  boolean loop)
Deprecated. replaced by : public void start(final int sFrame,final int eFrame,final int step,int loops)

Starts the animation with a frame range. This function starts an animation by specifying the frame range and a loop flag. If the application is playing, this call has no effect.
Parameters:
sFrame - start frame
eFrame - end frame
loop - true means that the animations restarts automaticaly

start

public void start(int[] frameSequence,
                  boolean loop)
Deprecated. replaced by : public void start(int frameSequence[],int loops)

Starts the animation with a non standard frame sequence. You can provide a different frame sequence than the standard 0,1,2,3,4..n frame order. Use this function when you have an animation that has some identical frames. In such case, just keep one unique frame and recreate the original frame sequence by referencing the originaly identical frames several times. If the application is playing, this call has no effect.
Parameters:
frameSequence - frame numbers array which defines the frames sequence
loop - indicator to restart the animation automaticaly when it ends.

start

public void start(int loops)
Starts the animation. This function starts the animation and loops the specified amount of time. If the application is playing, this call has no effect.
Parameters:
loops - integer value specifying the number of loops or LOOPS_UNLIMITED.
See Also:
LOOPS_UNLIMITED

start

public void start(int[] frameSequence,
                  int loops)
Starts the animation with a non standard frame sequence. You can provide a different frame sequence than the standard 0,1,2,3,4..n frame order. Use this function when you have an animation that has some identical frames. In such case, just keep one unique frame and recreate the original frame sequence by referencing the originaly identical frames several times. If the application is playing, this call has no effect.
Parameters:
frameSequence - frame numbers array which defines the frames sequence
loops - integer value specifying the number of loops or LOOPS_UNLIMITED.
See Also:
LOOPS_UNLIMITED

start

public void start(int sFrame,
                  int eFrame,
                  int step,
                  int loops)
Starts the animation with a frame range. This function starts an animation by specifying the frame range and a loop flag. If the application is playing, this call has no effect.
Parameters:
sFrame - start frame
eFrame - end frame
loops - integer value specifying the number of loops or LOOPS_UNLIMITED.
See Also:
LOOPS_UNLIMITED

splitImage

public static Image[] splitImage(Image original,
                                 int frameWidth)
This is a static helper function that divides a multi-frames BMP into distinguished Images.
The original image size should be a multiple of the frame width.
Parameters:
original - multi-frames image.
frameWidth - the width of a single frame.
Returns: