Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.flagstone.transform
Class FSMovie

    java.lang.Object
      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.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD