com.flagstone.transform
Class FSMovie

java.lang.Object
  extended by com.flagstone.transform.FSMovie
All Implemented Interfaces:
java.lang.Cloneable

public class FSMovie
extends java.lang.Object
implements java.lang.Cloneable

FSMovie is a container class for the objects that represents the data structures in a Flash file. FSMovie is the core class of the Transform package. It is used to parse and generate Flash files, translating the binary format of the Flash file into an array objects that can be inspected and updated. An FSMovie object also contains the attributes that make up the header information of the Flash file, identifying the version support, size of the Flash Player screen, etc.:

Attributes
signature The signature is a three character code that identifies that the file contains Flash encoded data. For Flash versions 1 to 5 this was 'F', 'W', 'S' ("SWF" reversed). In Flash 6, zlib compressed files were introduced to reduce file sizes. Compressed files are identified by the signature, 'C', 'W', 'S'.
version The version of Flash that is contained in the file.
frameSize An FSBounds object that define the size of the Flash Player's screen when playing the movie.
frameRate The number of frames per second that the movie will be played at.
objects An array of FSMovieObjects that define the shapes, buttons, images etc to be displayed along with the commands that control how the movie is animated.
The header information defined in the Macromedia Flash (SWF) File Format Specification also identifies the length of the (uncompressed) movie and the number of frames. These attributes are derived when the FSMovie object is encoded to a file.

Generating a Flash File

Flash files can be built from scratch by simply constructing instances of objects that represent the respective Flash data structure and adding them to an FSMovie object in the order they will be executed by the Flash player.
  FSMovie movie = new FSMovie();
 
  // Define a shape to be displayed
  FSDefineShape rectangle = new FSDefineShape(movie.newIdentifier(), ....);
 
  // Set the size of the Flash Player screen 400x400 and the number of
  // frames displayed per second.
  movie.setFrameSize(new FSBounds(0, 0, 400, 400));
  movie.setFrameRate(1.0);
 
  // Set the background colour for the movie
  movie.add(new FSSetBackgroundColor(FSColor.lightblue()));
 
  // Add the shape to the movie. All objects must be defined before
  // they can be used.
  movie.add(rectangle);
 
  // Place the shape in the centre of the screen (200,200) on the first layer
  // in the Flash Player's display list.
  movie.add(new FSPlaceObject2(FSPlaceObject2.New, rectangle.getIdentifier(), 1, 200, 200));
 
  // Display the frame
  movie.add(new FSShowFrame());
 
Note that when the shape was defined a call was made to the newIdentifier() method on the movie. Each object that defines either a shape, button, sound etc., is assigned a unique identifier to allow the object to be referenced in objects such as FSPlaceObject which places the shape on the Flash Player's display list. The identifier is unique only within a movie so the FSMovie class maintains a counter that is used to generate values for the identifiers that are assigned to objects derived from the Definition class. To generate a Flash file use the encodeToFile(String fileName) method:
  try {
  aMovie.encodeToFile(filename);
  }
  catch (Exception e) {
  ... Process Exception ...
  }
 

Parsing a Flash File

To parse a Flash file simply create an instance using the FSMovie(String fileName) constructor:

  FSMovie aMovie = null;
  String fileName = "aFlashFile.swf";
 
  try {
  aMovie = new FSMovie(filename);
  }
  catch (Exception e) {
  ... Process Exception ...
  }
 
The objects array of the movie will contain an instance of the respective package class for each data structure decoded from the file. The objects may be inspected and their attributes changed accordingly. The FSMovie object keeps track of the identifiers assigned to objects that define the shapes, buttons, sounds etc. that make up a Flash file. If a new object is added to the movie then the call to newIdentifier() is guaranteed to return a value that is unique within the movie. Multiple Language Support
Formal support for Unicode strings was added in Flash 6, providing a unified mechanism for supporting different languages. Previously Macromedia released different versions of the Flash authoring tool that supported a character set unique to a given language, for example SJIS for the Japanese language edition. The FSMovie class includes the encoding attribute that identifies the character set used to encode the strings found in objects such as FSFrameLabel and FSDefineTextField. Note this does not include the characters in font definitions. The default value of UTF8 is the same encoding scheme used by Macromedia so files containing Flash 6 or later may be decoded from any source. For earlier version of Flash the encoding attribute may be set to match the character set of the application used to encoded the Flash file.

';


Constructor Summary
FSMovie()
          Constructs an FSMovie object with no objects.
FSMovie(byte[] data)
          Constructs an FSMovie object and decodes the binary data presented in the byte array to generate an array of objects representing the Flash data.
FSMovie(byte[] data, FSMovieListener listener)
          Deprecated. using the constructor FSMovie(byte[]) which throws an exception if an error is detected.
FSMovie(FSBounds aBounds, float framesPerSecond)
          Constructs an FSMovie object with the specified bounding rectangle, frame rate and no objects.
FSMovie(java.lang.String fileName)
          Constructs an FSMovie object and decodes the contents of the specified file to generate an array of objects representing the Flash file.
FSMovie(java.lang.String fileName, FSMovieListener listener)
          Deprecated.  
FSMovie(java.lang.String encoding, java.lang.String signature, int version, FSBounds aBounds, float framesPerSecond, java.util.ArrayList anArray)
          Constructs an FSMovie object with the specified signature, version, bounding rectangle, frame rate and array of objects.
 
Method Summary
 void add(java.util.ArrayList array)
          Adds all of the objects in the array to the Movie.
 void add(FSMovieObject anObject)
          Adds the object to the Movie.
 void appendDescription(java.lang.StringBuffer buffer, int depth)
          AppendDescription is used to present a string description of the object including all nested objects up to a specified depth.
 java.lang.Object clone()
          Creates a deep copy of the entire movie.
 void decodeFromData(byte[] bytes)
          Decodes the binary Flash data stored in the byte array.
 void decodeFromData(byte[] bytes, FSMovieListener listener)
          Deprecated. use the decodeFromData(bytep[]) method which throws an exception if an error is detected.
 void decodeFromFile(java.lang.String fileName)
          Decodes the contents of the specified file.
 void decodeFromFile(java.lang.String fileName, FSMovieListener listener)
          Deprecated. use the decodeFromFile(String) method which throws an exception if an error is detected.
 byte[] encode()
          Returns the encoded representation of the array of objects that this Movie contains.
 byte[] encode(FSMovieListener listener)
          Deprecated. use the encode() method which throws an exception if an error is detected.
 void encodeToFile(java.lang.String fileName)
          Encodes the array of objects and writes the data to the specified file.
 void encodeToFile(java.lang.String fileName, FSMovieListener listener)
          Deprecated. use the encodeToFile(String) method which throws an exception if an error is detected.
 boolean equals(java.lang.Object anObject)
          Returns true if anObject is equal to this one.
 java.lang.String getEncoding()
          Gets the encoding scheme for strings encoded and decoded from Flash files.
 float getFrameRate()
          Gets the number of frames played per second that the movie will be displayed at.
 FSBounds getFrameSize()
          Gets the bounding rectangle that defines the size of the player screen.
 int getIdentifier()
          Gets the current value for the unique identifier that will be assigned to definition objects (classes derived from the FSDefineObject class).
 java.util.ArrayList getObjects()
          Gets the array of objects contained in the Movie.
 java.util.ArrayList getObjectsOfType(int aType)
          Gets an array of objects from the Movie with the specified type.
 java.lang.String getSignature()
          Gets the signature identifying that the movie contains Flash.
 int getVersion()
          Gets the number representing the version of Flash that the movie represents.
 int newIdentifier()
          Returns a unique identifier for an object derived from the FSDefineObject class.
 void setDecodeActions(boolean decode)
           
 void setDecodeGlyphs(boolean decode)
           
 void setDecodeShapes(boolean decode)
           
 void setEncoding(java.lang.String encoding)
          Sets the encoding scheme for strings encoded and decoded from Flash files.
 void setFrameRate(float aNumber)
          Sets the number of frames played per second that the Player will display the coder.
 void setFrameSize(FSBounds aBounds)
          Sets the bounding rectangle that defines the size of the player screen.
 void setIdentifier(int aValue)
          Sets the initial value for the unique identifier assigned to definition objects.
 void setObjects(java.util.ArrayList anArray)
          Sets the array of objects contained in the Movie.
 void setSignature(java.lang.String aString)
          Sets the signature for the Flash data when it is encoded.
 void setVersion(int aNumber)
          Sets the Flash version supported in this Movie.
 boolean willDecodeActions()
           
 boolean willDecodeGlyphs()
           
 boolean willDecodeShapes()
           
 
Methods inherited from class java.lang.Object
finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

FSMovie

public FSMovie()
Constructs an FSMovie object with no objects. The Flash version defaults to the package constant Transform.VERSION. From VERSION = 6 onwards the signature attribute defaults to "CWS" indicating that the binary data generated when a movie is encoded movie will be compressed using the zlib algorithm.


FSMovie

public FSMovie(FSBounds aBounds,
               float framesPerSecond)
Constructs an FSMovie object with the specified bounding rectangle, frame rate and no objects. The Flash version defaults to the package constant Transform.VERSION. From VERSION = 6 onwards the signature attribute defaults to "CWS" indicating that the binary data generated when a movie is encoded movie will be compressed using the zlib algorithm.

Parameters:
aBounds - the bounding rectangle that defines the size of each frame in the coder.
framesPerSecond - the number of frames per second that the Player plays the movie at.

FSMovie

public FSMovie(java.lang.String encoding,
               java.lang.String signature,
               int version,
               FSBounds aBounds,
               float framesPerSecond,
               java.util.ArrayList anArray)
Constructs an FSMovie object with the specified signature, version, bounding rectangle, frame rate and array of objects. The signature controls whether the file will be compressed when encoded. If the signature is "FWS" the file will not be compressed. If the signature is "CWS" then the file will be compressed using the zlib algorithm after encoding. Note that compressed Flash files are only readable by a Flash Player that supports Flash from version 6 onwards.

Parameters:
encoding - the format used to encode or decode strings.
signature - a string indicating that the file contains Flash data, either "FWS" for uncompressed files or "CWS" for compressed files.
version - the version number of Flash implemented in this coder.
aBounds - the bounding rectangle that defines the size of each frame in the coder.
framesPerSecond - the number of frames per second that the Player plays the movie at.
anArray - the array of objects that define the coder.

FSMovie

public FSMovie(java.lang.String fileName)
        throws java.io.IOException,
               java.util.zip.DataFormatException
Constructs an FSMovie object and decodes the contents of the specified file to generate an array of objects representing the Flash file. If an error occurs while reading and parsing the file then an exception is thrown.

Parameters:
fileName - the path to the Flash file that will be parsed.
Throws:
java.io.FileNotFoundException - - if an error occurs while reading the file.
java.util.zip.DataFormatException - - if the file does not contain Flash data.
FSCoderException - - if an error occurs while decoding the file.
java.io.IOException - - if an I/O error occurs while reading the file.

FSMovie

public FSMovie(java.lang.String fileName,
               FSMovieListener listener)
Deprecated. 

Constructs an FSMovie object and decodes the contents of the specified file to generate an array of objects representing the Flash file. If an error occurs while reading and parsing the file a message is sent to the registered movie listener object.

Parameters:
fileName - the path to the Flash file that will be parsed.
listener - an FSMovieListener object where errors messages are sent.

FSMovie

public FSMovie(byte[] data)
        throws java.util.zip.DataFormatException,
               java.io.IOException
Constructs an FSMovie object and decodes the binary data presented in the byte array to generate an array of objects representing the Flash data. If an error occurs while parsing the data then an Exception is thrown.

Parameters:
data - an array of bytes containing the Flash binary data.
Throws:
java.util.zip.DataFormatException - - if the file does not contain Flash data.
FSCoderException - - if an error occurs while decoding the file.
java.io.IOException - - if an I/O error occurs while reading the file.

FSMovie

public FSMovie(byte[] data,
               FSMovieListener listener)
Deprecated. using the constructor FSMovie(byte[]) which throws an exception if an error is detected.

Constructs an FSMovie object and decodes the binary data presented in the byte array to generate an array of objects representing the Flash data. If an error occurs while parsing the data then a message is sent to the movie listener.

Parameters:
data - an array of bytes containing the Flash binary data.
listener - an FSMovieListener object where errors messages are sent.
Method Detail

newIdentifier

public int newIdentifier()
Returns a unique identifier for an object derived from the FSDefineObject class. In order to reference objects that define items such as shapes, sounds, etc. each must be assigned an identifier that is unique for a given Movie. When binary data is decoded into a sequence of objects, the Movie class tracks each Define tag decoded, recording the highest value. If a new Define tag is added to the array of decoded objects the identifier assigned to the new tag will be guaranteed to be unique.

Returns:
an unique identifier for objects that define shapes, sounds, etc. in a Flash file.

getIdentifier

public int getIdentifier()
Gets the current value for the unique identifier that will be assigned to definition objects (classes derived from the FSDefineObject class). The value returned is the last value requested using the newIdentifier() method.

Returns:
current value for the unique identifier.

setIdentifier

public void setIdentifier(int aValue)
Sets the initial value for the unique identifier assigned to definition objects. When a new identifier is requested the identifier is incremented before being returned. For most situations the method argument will be zero. This method should be used with caution as generating definition object with duplicate identifiers will most probably crash the program displaying the Flash file generated.

Parameters:
aValue - the initial value for the unique identifier.

getEncoding

public java.lang.String getEncoding()
Gets the encoding scheme for strings encoded and decoded from Flash files. The default encoding format is UTF8 which provides backward compatibility for Flash files that contain ASCII encoded string. For files generated by internationalized versions of the Flash authoring tool any string recognised by the Java environment as identifying a character encoding scheme may be used. For example, "SJIS" may be used to decode files generated using the Japanese language version of Flash - Version 5 or earlier. With the introduction of Flash 6 support for Unicode strings was added so the default encoding of UTF8 will be useful for most applications.

Returns:
the string identifying the format for strings. Any string recognised by the Java environment may be used, "ASCII", "SJIS" and UTF8" will be the three most commonly used.

setEncoding

public void setEncoding(java.lang.String encoding)
Sets the encoding scheme for strings encoded and decoded from Flash files. For files generated by internationalized versions of the Flash authoring tool any string recognised by the Java environment as identifying a character encoding scheme may be used. For example, "SJIS" may be used to decode files generated using the Japanese language version of Flash - Version 5 or earlier.

Parameters:
encoding - string identifying the format for strings. Any string recognised by the Java environment may be used, "ASCII", "SJIS" and UTF8" will be the three most commonly used.

setDecodeActions

public void setDecodeActions(boolean decode)

willDecodeActions

public boolean willDecodeActions()

setDecodeShapes

public void setDecodeShapes(boolean decode)

willDecodeShapes

public boolean willDecodeShapes()

setDecodeGlyphs

public void setDecodeGlyphs(boolean decode)

willDecodeGlyphs

public boolean willDecodeGlyphs()

getSignature

public java.lang.String getSignature()
Gets the signature identifying that the movie contains Flash. Up to version 5 the string "FWS" identifies that data is encoded using the Flash file format. From Flash version 6 onwards Flash data could also be compressed using the zlib algorithm to reduce the file size. A signature of "CWS" is used to denote that a file contain compressed Flash data. The original signature "FWS" is still used to denote that a file contains uncompressed data. When encoding a FSMovie object the signature also determines whether the data generated will be compressed.

Returns:
the string identifying the format for the encoded Flash data.

setSignature

public void setSignature(java.lang.String aString)
Sets the signature for the Flash data when it is encoded. The signature is used to control whether the encoded data will be compressed. If the signature is "CWS" then the movie data will be compressed. If the signature is "FWS" then the data will not be compressed.

Parameters:
aString - the signature used for the encoded Flash file.

getVersion

public int getVersion()
Gets the number representing the version of Flash that the movie represents.

Returns:
an integer defining the Flash version number for the coder.

setVersion

public void setVersion(int aNumber)
Sets the Flash version supported in this Movie. Note that there are no restrictions on the objects that can be used in a coder. Using objects that are not supported by an earlier version of the Flash file format may cause the Player to not display the movie correctly or even crash the Player.

Parameters:
aNumber - the version of the Flash file format that this movie utilises.

getFrameSize

public FSBounds getFrameSize()
Gets the bounding rectangle that defines the size of the player screen.

Returns:
the FSBounds object that defines the bounding rectangle that describes the size of each frame in the coder.

setFrameSize

public void setFrameSize(FSBounds aBounds)
Sets the bounding rectangle that defines the size of the player screen. The coordinates of the bounding rectangle are also used to define the coordinate range. For example if a 400 x 400 pixel rectangle is defined, specifying the values for the x and y coordinates the range -200 to 200 sets the centre of the screen at (0,0), if the x and y coordinates are specified in the range 0 to 400 then the centre of the screen will be at (200, 200).

Parameters:
aBounds - the FSBounds object that defines the frame size.

getFrameRate

public float getFrameRate()
Gets the number of frames played per second that the movie will be displayed at.

Returns:
the speed the movie will be played at.

setFrameRate

public void setFrameRate(float aNumber)
Sets the number of frames played per second that the Player will display the coder.

Parameters:
aNumber - the number of frames per second that the movie is played.

getObjects

public java.util.ArrayList getObjects()
Gets the array of objects contained in the Movie.

Returns:
the array of objects that describe a coder.

setObjects

public void setObjects(java.util.ArrayList anArray)
Sets the array of objects contained in the Movie.

Parameters:
anArray - the array of objects that describe a coder.

add

public void add(FSMovieObject anObject)
Adds the object to the Movie.

Parameters:
anObject - the object to be added to the movie.

add

public void add(java.util.ArrayList array)
Adds all of the objects in the array to the Movie.

Parameters:
array - an array of FSMovieObjects.

getObjectsOfType

public java.util.ArrayList getObjectsOfType(int aType)
Gets an array of objects from the Movie with the specified type. For example to retrieve all the FSDefineShape objects specified in a movie:
 ArrayList allShapes = aMovie.getObjectsOfType(FSMovieObject.DefineShape);
 
Note that only objects at the "top-level" in the movie are checked, namely movie or definition objects. Objects "owned" by another object such as Action objects inside FSDoAction, FSButtonEvent or FSClipEvent objects cannot be retrieved using this method.

Parameters:
aType - the type to search the movie for.

decodeFromFile

public void decodeFromFile(java.lang.String fileName)
                    throws java.io.FileNotFoundException,
                           java.util.zip.DataFormatException,
                           java.io.IOException
Decodes the contents of the specified file. An object for each tag decoded from the file is placed in the Movie's object array in the order they were decoded from the file. If an error occurs while reading and parsing the file then an exception is thrown.

Parameters:
fileName - the path to the Flash file that will be parsed.
Throws:
java.io.FileNotFoundException - - if an error occurs while reading the file.
java.util.zip.DataFormatException - - if the file does not contain Flash data.
FSCoderException - - if an error occurs while decoding the file.
java.io.IOException - - if an I/O error occurs while reading the file.

decodeFromFile

public void decodeFromFile(java.lang.String fileName,
                           FSMovieListener listener)
Deprecated. use the decodeFromFile(String) method which throws an exception if an error is detected.

Decodes the contents of the specified file. An object for each tag decoded from the file is placed in the Movie's object array in the order they were decoded from the file. If an error occurs while reading and parsing the file then a message is sent to the movie listener.

Parameters:
fileName - the path to the Flash file that will be parsed.
listener - an FSMovieListener object where errors messages are sent.

decodeFromData

public void decodeFromData(byte[] bytes)
                    throws java.util.zip.DataFormatException,
                           java.io.IOException
Decodes the binary Flash data stored in the byte array. If an error occurs while the data is being decoded an exception is thrown. The array of objects in the Movie will contain the last tag successfully decoded.

Parameters:
bytes - an array of bytes that contain the encoded Flash objects.
Throws:
java.util.zip.DataFormatException - - if the file does not contain Flash data.
FSCoderException - - if an error occurs while decoding the file.
java.io.IOException - - if an I/O error occurs while reading the file.

decodeFromData

public void decodeFromData(byte[] bytes,
                           FSMovieListener listener)
Deprecated. use the decodeFromData(bytep[]) method which throws an exception if an error is detected.

Decodes the binary Flash data stored in the byte array. If an error occurs while the data is being decoded a message is sent to the movie listner object. The array of objects in the Movie will contain the last tag successfully decoded.

Parameters:
bytes - an array of bytes that contain the encoded Flash objects.
listener - an FSMovieListener object where errors messages are sent.

encodeToFile

public void encodeToFile(java.lang.String fileName)
                  throws java.io.FileNotFoundException,
                         java.io.IOException
Encodes the array of objects and writes the data to the specified file. If an error occurs while encoding the file then an exception is thrown.

Parameters:
fileName - the path to the Flash file that the movie will be encoded to.
Throws:
java.io.FileNotFoundException - - if an error occurs while opening the file.
FSCoderException - - if an error occurs while encoding the file.
java.io.IOException - - if an I/O error occurs while writing the file.

encodeToFile

public void encodeToFile(java.lang.String fileName,
                         FSMovieListener listener)
Deprecated. use the encodeToFile(String) method which throws an exception if an error is detected.

Encodes the array of objects and writes the data to the specified file. If an error occurs while encoding the file then a message is sent to the movie listener.

Parameters:
fileName - the path to the Flash file that the movie will be encoded to.
listener - an FSMovieListener object where errors messages are sent.

encode

public byte[] encode()
              throws java.io.IOException
Returns the encoded representation of the array of objects that this Movie contains. If an error occurs while encoding the file then an exception is thrown.

Returns:
the array of bytes representing the encoded objects.
Throws:
FSCoderException - - if an error occurs while encoding the file.
java.io.IOException - - if an I/O error occurs while encoding the file.

encode

public byte[] encode(FSMovieListener listener)
Deprecated. use the encode() method which throws an exception if an error is detected.

Returns the encoded representation of the array of objects that this Movie contains. If an error occurs while encoding the file then a message is sent to the movie listner.

Parameters:
listener - an FSMovieListener object where errors messages are sent.
Returns:
the array of bytes representing the encoded objects.

clone

public java.lang.Object clone()
Creates a deep copy of the entire movie.

Overrides:
clone in class java.lang.Object
Returns:
a copy of the movie.

equals

public boolean equals(java.lang.Object anObject)
Returns true if anObject is equal to this one. The comparison is performed on all the objects contained in the movie. Objects are considered equal if they would generate identical binary data when they are encoded to a Flash file.

Overrides:
equals in class java.lang.Object
Returns:
true if this object would be identical to anObject when encoded.

appendDescription

public void appendDescription(java.lang.StringBuffer buffer,
                              int depth)
AppendDescription is used to present a string description of the object including all nested objects up to a specified depth. This method provide a more controlled way of creating a string representation of an object since large objects such as font or shape definitions can contain dozens of nested objects. The representation of the object is appended to the StringBuffer, showing the name of the class and values of the attributes it contains. If the object contains any attributes that are objects then the object graph will be traversed up to the specified depth. If objects are nested at a level less than specified depth then the full string representation of the object is displayed. For objects at the specified depth only the name of the class is displayed. Any objects below this depth are not displayed.

Parameters:
buffer - a StringBuffer to which the description of each object is appended.
depth - the maximum level of nesting up to which objects will be displayed.