com.day.image.Animation

public class Animation extends Object

The Animation class takes a series of Layers and puts them in a single output graphic stream adding animation code for the number of loops and the delay time and disposal method of the single patches.

What we do in this class is accept a series of layers, which will make up the single images. Currently layers are inserted into the animation in the succession of their addition. For each layer added, you may define the display time in 1/100th seconds and the disposal method used at the end of the display time.

In addition you may set global looping instruction, on how many times the sequence of images should be displayed. To disable setting the loop control value in the output file, set the global loop value to a negative value.

Properties

The Animation class supports the following properties, which are all backed by setter and getter methods :

loops		The number of loops to go through the animation. The default is not set byte the constructor or the setter is 0, which boils down to an endless loop.
defaultDisposal		The action the image decoder should take after the display time of an image has elapsed. This must be one of the defined DISPOSAL_* constants. The default if not set by a constructor or the setter is DISPOSAL_BACKGROUND.
backgroundColor		The background color of the animation. The default if not set by a constructor or the setter is to take the background color of the first image in the animation as the background color.

Supported Image Format

Currently the Animation class is solely implemented based on the GIF image file format, whose general structure is described here. You will also note, that the API of the Animation class is based on the functionality the GIF format offers for animated image files.

CompuServe Graphics Interchange Format (GIF)

The CompuServe Graphics Interchange Format (GIF) is a multi-image graphics format, which provides the capability for simple animations provided the image viewer is capable of interpreting the multi-image nature of the image file and the instructions for display.

Generally a GIF file is made up of the following structural elements :

GIF89a Header
Logical Screen Descriptor Block, with optional global color table
optional Netscape Application Extension Block
stream of graphics
- optional Graphic Control Block
- Image Descriptor or Plain Text Block with optional local color table
GIF Trailer

For more details, look at the GIF89 Specification. Generally this page contains many interesting information on animated GIFs.

Since:: coati

Field Summary

Fields

Modifier and Type

Field

Description

static int

DISPOSAL_BACKGROUND

Restore to background color.

static int

DISPOSAL_NO

Do not dispose.

static int

DISPOSAL_NONE

No disposal specifed.

static int

DISPOSAL_PREVIOUS

Restore to previous.
Constructor Summary

Constructors

Constructor

Description

Animation()

Creates the Animation object using the default values.

Animation(int loops)

Creates the Animation object using the given properties.

Animation(int loops, int defaultDisposal, int bgColor)

Creates the Animation object using the given properties.
Method Summary

Modifier and Type

Method

Description

void

addLayer(Layer layer, int delay)

Add a layer for display during the indicated delay time after which the image is disposed of using the default disposal method.

void

addLayer(Layer layer, int delay, int disposal)

Add a layer for display during the indicated delay time after which the image is disposed of using the disposal method.

int

getBackgroundColor()

Returns the current desired background color, -1 if undefined.

int

getDefaultDisposal()

Return the current default disposal method used for newly added Layers.

int

getLoops()

Returns the number of iterations through the images currently set.

Layer

removeLayer(int idx)

Remove the layer with the given index from the Animation.

Layer

removeLayer(Layer layer)

Removes the first layer (in chronological order) matching the given layer from the animation.

void

setBackgroundColor(int bgColor)

Sets the desired background color.

void

setDefaultDisposal(int defaultDisposal)

Sets the default disposal method for newly added Layers.

void

setLoops(int loops)

Change the number of iterations through the images to the new value.

String

toString()

Convert the Animation to some string representation for intelligent display.

void

write(String mimeType, int numColors, OutputStream outs)

Write the animation to the output indicated.

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Details
- DISPOSAL_NONE
  
  public static int DISPOSAL_NONE
  
  No disposal specifed. The decoder is not required to take any action.
- DISPOSAL_NO
  
  public static int DISPOSAL_NO
  
  Do not dispose. The graphic is to be left in place.
- DISPOSAL_BACKGROUND
  
  public static int DISPOSAL_BACKGROUND
  
  Restore to background color. The area used by the graphic must be restored to the background color.
- DISPOSAL_PREVIOUS
  
  public static int DISPOSAL_PREVIOUS
  
  Restore to previous. The decoder is required to restore the area overwritten by the graphic with what was there prior to rendering the graphic.
Constructor Details
- Animation
  
  public Animation(int loops, int defaultDisposal, int bgColor)
  
  Creates the Animation object using the given properties.
  
  Parameters:
  
  loops - Number of times the application should loop through the images. Use a negative value to prevent looping at all.
  
  defaultDisposal - default disposal method for images after the delay time has elapsed
  
  bgColor - The background color to set on the animated GIF. Only the red, green and blue values are used, the alpha value is ignored as GIF does not support alpha values.
- Animation
  
  public Animation(int loops)
  
  Creates the Animation object using the given properties. The background color is taken from the first image in the animation while the default disposal method is set to DISPOSAL_BACKGROUND.
  
  Parameters:
  
  loops - Number of times the application should loop through the images. Use a negative value to prevent looping at all.
- Animation
  
  public Animation()
  
  Creates the Animation object using the default values. The background color is taken from the first image in the animation while the default disposal method is set to DISPOSAL_BACKGROUND. The loop counter is initialized to 0, which means endless loop.
Method Details
- setLoops
  
  public void setLoops(int loops)
  
  Change the number of iterations through the images to the new value.
  
  Parameters:
  
  loops - Number of times the application should loop through the images. Use a negative value to prevent looping at all or set to 0 for endless looping.
- getLoops
  
  public int getLoops()
  
  Returns the number of iterations through the images currently set.
  
  Returns:
  
  Number of iterations through the images.
- setDefaultDisposal
  
  public void setDefaultDisposal(int defaultDisposal)
  
  Sets the default disposal method for newly added Layers. This setting does not affect Layers already added to the animation object !
  Parameters:
  
  defaultDisposal - The disposal method to use. This must be one of DISPOSAL_* constants defined above.
  
  Throws:
  
  IllegalArgumentException - if the disposal value is illegal.
  
  See Also:
  
  DISPOSAL_NONE
  
  DISPOSAL_NO
  
  DISPOSAL_BACKGROUND
  
  DISPOSAL_PREVIOUS
- getDefaultDisposal
  
  public int getDefaultDisposal()
  
  Return the current default disposal method used for newly added Layers.
  
  Returns:
  
  current default disposal method used
- setBackgroundColor
  
  public void setBackgroundColor(int bgColor)
  
  Sets the desired background color. If the desired color is -1, the background color of the first layer in the animation is taken as the animations background color.
  
  Parameters:
  
  bgColor - The new background color to set. Only the red, green and blue values are used, the alpha value is ignored as GIF does not support alpha values.
- getBackgroundColor
  
  public int getBackgroundColor()
  
  Returns the current desired background color, -1 if undefined.
  
  Returns:
  
  the current desired background color, -1 if undefined.
- addLayer
  
  public void addLayer(Layer layer, int delay)
  
  Add a layer for display during the indicated delay time after which the image is disposed of using the default disposal method.
  
  Parameters:
  
  layer - the Layer object to add
  
  delay - the display time of the image in 1/100 sec.
  
  Throws:
  
  NullPointerException - if the layer is null.
- addLayer
  
  public void addLayer(Layer layer, int delay, int disposal)
  
  Add a layer for display during the indicated delay time after which the image is disposed of using the disposal method.
  Parameters:
  
  layer - the Layer object to add
  
  delay - the display time of the image in 1/100 sec.
  
  disposal - the disposal method for the object. This must be one of the predefined DISPOSAL_* constants.
  
  Throws:
  
  NullPointerException - if the layer is null.
  
  IllegalArgumentException - if the disposal value is not one of the predefined DISPOSAL_* constants.
  
  See Also:
  
  DISPOSAL_NONE
  
  DISPOSAL_NO
  
  DISPOSAL_BACKGROUND
  
  DISPOSAL_PREVIOUS
- removeLayer
  
  public Layer removeLayer(int idx)
  
  Remove the layer with the given index from the Animation.
  
  Parameters:
  
  idx - index of the Layer in the list
  
  Returns:
  
  the layer removed from the Animation
  
  Throws:
  
  IndexOutOfBoundsException - if the index is less than zero or bigger than the number of layers in the animation.
  
  NullPointerException - if no layer is present at the given position.
- removeLayer
  
  public Layer removeLayer(Layer layer)
  
  Removes the first layer (in chronological order) matching the given layer from the animation. If a layer is contained more than once within the animation, you must use multiple calls to removeLayer.
  
  Parameters:
  
  layer - Layer object to remove from the animation
  
  Returns:
  
  the layer removed from the animation or null if the layer was not part of the animation.
- write
  
  public void write(String mimeType, int numColors, OutputStream outs) throws IOException
  
  Write the animation to the output indicated.
  
  Parameters:
  
  mimeType - MIME type indicating the graphics output file format to use. Currently only image/gif is supported.
  
  numColors - The number of colors to generate in the animated GIF, if not in the range [2 .. 256], 256 is taken as the default.
  
  outs - the OutputStream used for output
  
  Throws:
  
  IOException - got from called write methods
  
  IllegalArgumentException - or if the mimeType is not image/gif or if the OutputStream is null.
- toString
  
  public String toString()
  
  Convert the Animation to some string representation for intelligent display.
  
  Overrides:
  
  toString in class Object
  
  Returns:
  
  the string representation of the Animation object.

Class Animation

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Details

DISPOSAL_NONE

DISPOSAL_NO

DISPOSAL_BACKGROUND

DISPOSAL_PREVIOUS

Constructor Details

Animation

Animation

Animation

Method Details

setLoops

getLoops

setDefaultDisposal

getDefaultDisposal

setBackgroundColor

getBackgroundColor

addLayer

addLayer

removeLayer

removeLayer

write

toString