------------------------------------------------- Release Notes for Transform SWF, Version 3.0. ------------------------------------------------- IMPORTANT: This document contains the set of implemented in version 3.0 of the Transform SWF framework. For the com.flagstone.transform package the same philosophy of providing a low- level API which exposes all the data structures in a Flash file as objects is maintained. Files will still be generated and parsed in the same way. Porting code from Transform 2 should be very simple and extensive rewrites will not be necessary. The utilities package, com.flagstone.transform.util, has been completely refactored to create a completely new set of classes. The original code is mostly unchanged but the ways the classes are used has changed so the porting effort will be greater but will not be too significant. New Features 1. Code uses Java 1.5 2. New plug-in architecture for adding classes 3. Collections are now passed by interface 4. New Displayable interface for all visible objects Renamed Classes 1. The FSDefineObject was renamed to Definition. 2. Renamed FSButton to ButtonShape. 3. Renamed FSText to Span 4. Renamed FSSound to SoundInfo 5. Renamed FSSolidLine to LineStyle 6. Renamed FSMorphSolidLine to MorphLineStyle. Class Changes 1. The "FS" prefix on all classes has been dropped. 2. Set methods now throw exception if the arguments are invalid. 3. toString() now returns a simple description, appendDescription is deleted. 4. Simplified constructors on FSPlaceObject2. 5. Context was factored out of FSCoder. 6. Constants are now defined in base classes. 7. DefineButton2 no longer support encoded FSButtonEvent objects. 8. PlaceObject2 no longer supports encoded FSClipEvents. 9. Transform removed VALUE_NOT_SET. 10. name() method deleted. 11. Action: static Action getInstance(int type) is now public 12. Coder: public FSCoder(byte[] bytes) default bye order little endian 13. Movie supports File and String path arguments. 14. Movie: public int newIdentifier() no longer synchronized 15. Push now handles encoding and decoding of primitive types. Internal Changes 1. Code was optimized to eliminate unnecessary assignments. 2. Base classes support methods for encoding decoding object. Package Changes 1. FSHeader, FSFrame and FSLayer are now in com.flagstone.transform.util. ---------------- New Features ---------------- 1. Code uses java 1.5. The code was updated change so all the Collection classes now use parameterised types. A new class ShapeObject was added so the Collections in Shape could also be parameterised. 2. New plug-in architecture for adding classes. When a movie is decoded if an unsupported data structure is encountered then it was decoded as either FSUnknownAction or FSUnknownObject. Three methods have been added to ActionObject, MovieObject and FillStyle respectively: public static void registerClass(int type, Class aClass) public static void registerClass(int type, Class aClass) public static void registerClass(int type, Class aClass) allowing developers to add classes for data structures not supported in the framework. Now when the code performing the decoding encounters a data structure it does not support it will use the type to perform a table lookup for any registered class. If a class is found an object will be instantiated and then the data structure will be decoded by calling the decode() method. Otherwise the data structure will be decoded as FSUnknownAction or FSUnknownObject as before. 3. Collections are now passed by interface. All the methods that have Collection classes as arguments or return Collection classes now return an Interface to the class. For example: public void setObjects(ArrayList anArray) now passes a List as an argument: public void setObjects(ArrayList anArray) The framework uses Iterators to step through the collections so the exact types passed to the classes is not important. 4. New Displayable interface for all visible objects. The Displayable interface contains two methods: public int getWidth(); public int getHeight(); which return the width and height of an object. For image definitions then the width is returned in pixels, For other visible objects the dimensions will be twips. The interface is useful when iterating through a movie to gather size information on objects rather than casting to the appropriate type. ------------------- Renamed Classes ------------------- 1. The FSDefineObject was renamed to Definition. The class was renamed to distinguish it from the base classes: ActionObject, MovieObject, etc. The name change also makes it clearer that inheriting classes now define things as opposed to performing actions in a Flash file. 2. Renamed FSButton to ButtonShape. The class was renamed to make its purpose clearer. 3. Renamed FSText to FSSpan FSText defined a set of FSCharacters which are positioned within an FSDefineText object so the class was renamed to make it more accurate - the name was chosen after the HTML span element to its purpose is clear. 4. Renamed FSSound to FSSoundInfo The class was renamed to avoid naming conflict with the FsSoundConstructor class in the com.flagstone.transform.util package which was renamed to Sound. The name also matches the one used in the File Format Specification from Adobe. 5. Renamed FSSolidLine to LineStyle The class was renamed to match the one used in the File Format Specification from Adobe. The LineStyle data structure added in Flash 8 can use different fill styles to paint the line so the name used in the framework was no longer accurate. 6. Renamed FSMorphSolidLine to MorphLineStyle. Renamed for the same reasons as FSSolidLine. ----------------- Class Changes ----------------- 1. The "FS" prefix on all classes has been dropped. The prefix was a hangover from the original Objective-C code way back at the dawn of time. There are collisions with class names in the java.awt package but these apply to classes in com.flagstone.transform.util and so there should not be many times were you have to write java.awt.Image, etc. in order to distinguish between classes. 2. Set methods now throw exception if the arguments are invalid. Accessor methods that set object attributes now perform simple checks on the arguments passed and throw either IllegalArgumentException or NullPointerException if the state of the object would become invalid. 3. toString() now returns a simple description, appendDescription is deleted. appendDescription() which returns a detailed description of the entire object tree for a given object has been dropped and the toString() method now returns a simple description of the object it is called on. The rationale is that when viewing the state of objects in an IDE it is easy to traverse the object tree and get information on each object. 4. Simplified constructors on FSPlaceObject2. Since FSLayer supports provides an API for manipulating the display list the number of constructors on FSPlaceObject2 was reduced to reduce the complexity of the class and make it easier to use. The following constructors were removed: public FSPlaceObject2(int id, int layer, float aRatio, int x, int y) public FSPlaceObject2(int id, int layer, FSCoordTransform tx) public FSPlaceObject2(int id, int layer, int aDepth, int x, int y) public FSPlaceObject2(int id, int layer, ArrayList events, String aName, int x, int y) public FSPlaceObject2(int id, int layer, byte[] encodedEvents, String name, int x, int y) public FSPlaceObject2(int id, int layer) public FSPlaceObject2(int layer, FSCoordTransform tx) public FSPlaceObject2(int layer, FSColorTransform cx) public FSPlaceObject2(int layer, float ratio, int x, int y) public FSPlaceObject2(int layer, float ratio, FSCoordTransform tx) public FSPlaceObject2(int type, int id, int layer, FSCoordTransform tx, FSColorTransform cx) 5. Context was factored out of FSCoder. The context attributes in FSCoder were refactored into a separate Context class. The context contains different attributes for the different types of information passed between objects during encoding and decoding which makes debugging easier. The methods signatures for length(), encode() and decode() were changed accordingly. 6. Constants are now defined in base classes All types are defined in the base classes or in a definition class is there is no suitable base class. Types for action objects were moved from FSaction to ActionObject. No change required since Action inherits from ActionObject. Constants for sound formats was moved from FSSound to DefineSound. Constants for different character encodings and languages was moved from FSText to FSDefineText. 7. DefineButton2 no longer support encoded FSButtonEvent objects. The class allowed ActionScript code compiled using Translate to be directly added. This is no longer possible. Until Translate is updated the workaround is to decode the binary data generated by Translate to obtain the ButtonEvent objects then add them to the button object. 8. PlaceObject2 no longer supports encoded FSClipEvents. As with DefineButton2 the methods used to add binary encoded ClipEvents generated by Translate have been removed. The workaround is the same. 9. Transform removed VALUE_NOT_SET. This package level constant was used to signify that an attribute in an object was not set and so would not be encoded. In all cases it is possible to assign a default value and the constant was unused. 10. name() method deleted. The name() method, defined in FSTransformObject which returned the name of the class has been deleted. Originally it was used for logging events and in toString(). The class name is not included directly in the toString() method and so the extra method call is not longer needed. 11. Action: static Action getInstance(int type) is now public. This change allows singletons for any byte-code action, including new types added in Flash 8 and beyond to be created. 12. Movie supports File and String path arguments. Movie originally had methods that passed a String path to a file for encoding and decoding. New methods that use a File object were also added in this release. 13. Movie: public int newIdentifier() no longer synchronized. The method does not need the synchronization keyword since it is only practical for one thread to generate a file. 14. Push now handles encoding and decoding of primitive types. The Push class handles the encoding and decoding of the primitive types used to push values onto the Flash Player stack. The classes RegisterIndex, TableIndex, Null and Void had methods that supported encoding and decoding. Since these methods were not used they were removed. -------------------- Internal Changes -------------------- 1. Code was optimized to eliminate unnecessary assignments. When an object was instantiated all the attributes were set. If an object was created during the process of decoding a movie then the attributes values would all be overwritten. Now the attributes are only initialized within the constructors to speed up the code. 2. Base classes support methods for encoding decoding object. Code was refactored so the base classes: MovieObject, ActionObject and FillStyle now contains the methods used when encoding and decoding objects in a movie. Conveniences methods can also be found in the base classes to make writing plug-in classes easier. ------------------- Package Changes ------------------- 1. FSHeader, FSFrame and FSLayer are now in com.flagstone.transform.util. The classes were moved to com.flagstone.transform.util so that all the classes com.flagstone.transform deal with the basic encoding and decoding of files while com.flagstone.transform.util contains factory classes for generating objects that are added to movies.