-------------------------------------------------
  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<ActionObject> aClass)
    	public static void registerClass(int type, Class<MovieObject> aClass)
    	public static void registerClass(int type, Class<FillStyle> 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<FSMovieObject> anArray)
   
   now passes a List as an argument:
   
 	   public void setObjects(ArrayList<FSMovieObject> 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.
