fsplaceobject2.java

利用opensource的开源jar实现生成flash文件

/*
 * FSPlaceObject2.java
 * Transform
 * 
 * Copyright (c) 2001-2006 Flagstone Software Ltd. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification, 
 * are permitted provided that the following conditions are met:
 *
 *  * Redistributions of source code must retain the above copyright notice, this
 *    list of conditions and the following disclaimer.
 *  * Redistributions in binary form must reproduce the above copyright notice, 
 *    this list of conditions and the following disclaimer in the documentation 
 *    and/or other materials provided with the distribution.
 *  * Neither the name of Flagstone Software Ltd. nor the names of its contributors 
 *    may be used to endorse or promote products derived from this software 
 *    without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 
 * IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 
 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 
 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 
 * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 
 * OF THE POSSIBILITY OF SUCH DAMAGE.
 */

package com.flagstone.transform;

import java.util.*;

/**
FSPlaceObject2 is used to add and manipulate objects (shape, button, etc.) on the Flash 
Player's display list. 
 
<p>FSPlaceObject2 supersedes the FSPlaceObject class providing more functionality and easier manipulation of  objects in the display list through the following operations:</p>

<ul>
<li>Place a new shape on the display list.</li>
<li>Change an existing shape by moving it to new location or changing its appearance.</li>
<li>Replace an existing shape with a another.</li>
<li>Define clipping layers to mask objects displayed in front of a shape.</li>
<li>Control the morphing process that changes one shape into another.</li>
<li>Assign names to objects rather than using their identifiers.</li>
<li>Define the sequence of actions that are executed when an event occurs in movie clip.</li>
</ul>

<p><b>Clipping Depth</b><br/>
With the introduction of Flash 3 the display list supported a clipping layer. This 
allowed the outline of an object to define a clipping path that is used to mask 
other objects placed in front of it. The clipping depth can be set to mask objects 
between the layer containing the clipping path and a specified layer.</p>

<p<b>Shape Morphing</b><br/>
Shapes that will be morphed are defined using the FSDefineMorphShape class which defines a start and end shape. The Flash Player performs the interpolation that transforms one shape into another. The progress of the morphing process is controlled by a ratio which ranges from 0.0 to 1.0, where 0 generates a shape identical to the starting shape in the FSDefineMorphShape object and 1.0 generates the shape at the end of the morphing process.</p>

<p<b>Movie Clip Events</b><br/>
With the introduction of Flash 5, movie clips (defined using the FSDefineMovieClip class) could specify sequences of actions that would be performed in response to mouse or keyboard events. The actions are specified using FSClipEvent objects and the FSPlaceObject2 class is used to register the actions in response to a particular event with the Flash player. Multiple events can be handled by defining an FSClipEvent for each type of event. For more information see the FSClipEvent class.</p>

<table class="datasheet">

<tr><th align="left" colspan="2">Attributes</th></tr>

<tr>
<td><a name="FSPlaceObject2_0">type</a></td>
<td>Identifies the data structure when it is encoded. Read-only.</td>
</tr>

<tr>
<td><a name="FSPlaceObject2_1">place</a></td>
<td>Indicates whether a new object is being placed in the display list or an existing object is being modified or replaced.</td>
</tr>

<tr>
<td><a name="FSPlaceObject2_2">identifier</a></td>
<td>The identifier of the object to added to the display list.</td>
</tr>

<tr>
<td><a name="FSPlaceObject2_3">layer</a></td>
<td>Defines the order in which objects are displayed.</td>
</tr>

<tr>
<td><a name="FSPlaceObject2_4">transform</a></td>
<td>Optional. A coordinate transform defines the position, scale and rotation of the object.</td>
</tr>

<tr>
<td><a name="FSPlaceObject2_5">colorTransform</a></td>
<td>Optional. A colour transform defines any colour changes such as transparency effects.</td>
</tr>

<tr>
<td><a name="FSPlaceObject2_6">depth</a></td>
<td>Optional. The layer number up to which objects will be clipped by this object's outline.</td>
</tr>

<tr>
<td><a name="FSPlaceObject2_7">ratio</a></td>
<td>Optional. The point for the morphing process of a shape.</td>
</tr>

<tr>
<td><a name="FSPlaceObject2_8">name</a></td>
<td>Optional. A name to assign to the object.</td>
</tr>

<tr>
<td><a name="FSPlaceObject2_9">events</a></td>
<td>Optional. An array of FSClipEvent objects that define the actions that are performed when a specific movie clip event occurs.</td>
</tr>

<tr><td><a name="FSPlaceObject2_10">encodedEvents</a></td>
<td>An array of bytes containing encoded clip events can also be set. The encoded objects are typically generated by the parser in the Translate framework. The events array and encodedEvents cannot both be valid at the same time. Accessor methods used to set either of the attributes will set the other to null.</td>
</tr>

</table>

<p>Since only one object can be placed on a given layer an existing object on the display list can be identified by the layer it is displayed on rather than its identifier. Therefore Layer is the only required attribute. The remaining attributes are optional according to the different operation being performed:</p>

<ul>
<li>If an existing object on the display list is being modified then only the layer number is required. Previously in the FSPlaceObject class both the identifier and the layer number were required.</li>
<li>If no coordinate transform is applied to the shape (the default is a unity transform that does not change the shape) then it is not encoded.</li>
<li>Similarly if no colour transform is applied to the shape (the default is a unity transform that does not change the shape's colour) then it is not encoded.</li>
<li>If a shape is not being morphed then the ratio attribute may be left at its default value (-1.0).</li>
<li>If a shape is not used to define a clipping area then the depth attribute may be left at its default value (0).</li>
<li>If a name is net assigned to an object the name attribute may be left its default value (an empty string).</li>
<li>If no events are being defined for a movie clip then the array of FSClipEvent object may be left empty.</li>
</ul>

<p>The class provides a range of constructors which define different subsets of the attributes according to the type of operation that will be performed on an object in the Flash Player's display list. If an attribute is not specified in a constructor then it will be assigned a default value and will be omitted when the object is encoded.</p>

<h1 class="datasheet">Examples</h1>

<p>The following code samples illustrate how to use the FSPlaceObject2 class to manipulate objects on the display list. These examples use constructors with the most convenient (simplest) arguments. To define more complex place operations constructors are provided that take larger numbers of arguments and allow more complex transformations to be specified.</p>

<p>1. Display an object.<br/>
To display an object at a given location the placeType, identifier, layer number and x,y coordinates are required.</p>

<pre>
// Add the shape to the display list - on layer 1 at coordinates (400, 400)
// The constructor allows just the x and y coordinate to be defined, the
// FSCoordTransform object is constructed internally.

FSDefineShape shape = new FSDefineShape(movie.newIdentifier(), ......);

movie.add(new FSPlaceObject2(shape.getIdentifier(), 1, 400, 400));
movie.add(new FSShowFrame());
</pre>

<p>2. Move an object.<br/>
To move an object only the layer number is required. This simplifies the code required to manipulate existing objects when compared to the original FSPlaceObject class.</p>

<pre>
// Add the shape to the display list.
movie.add(new FSPlaceObject2(shape.getIdentifier(), 1, 400, 400));
movie.add(new FSShowFrame());

// Move shape to a new location.
movie.add(new FSPlaceObject2(1, 250, 300));
movie.add(new FSShowFrame());
</pre>

<p>3. Replace an existing object with another.<br/>
To move an object only the layer number is required. This simplifies the code required to manipulate existing objects when compared to the original FSPlaceObject class.</p>

<pre>
// Add the shape to the display list.
movie.add(new FSPlaceObject2(shape.getIdentifier(), 1, 400, 400));
movie.add(new FSShowFrame());

// Replace the shape.
movie.add(new FSPlaceObject2(newShape.getIdentifier(), 1));
movie.add(new FSShowFrame());
</pre>

<p>4. Defining a clipping layer.<br/>
The number of layers to clip using the outline of the shape as a path can be specified when placing the shape on the display list.</p>

<pre>
// Add the shape to the display list and clip objects on the next two layers

currentLayer = 1;
clipTo = currentLayer + 2;

movie.add(new FSPlaceObject2(shape.getIdentifier(), currentLayer, clipTo, 400, 400));
movie.add(new FSShowFrame());
</pre>

<p>5. Controlling the morphing process.<br/>
The ratio attribute controls the progress as an FSDefineMorphShape object changes from one shape into another.</p>

<pre>
FSShape triangle = new FSShape(....);
FSShape hexagon = new FSShape(....);

FSDefineMorphShape shape = new FSDefineMorphShape(movie.newIdentifier(), ...., triangle, hexagon);

movie.add(new FSPlaceObject2(shape.getIdentifier(), 1, 0.0, 400, 400));

// Morph the shapes over 10 frames

for (float i=0.1; i&lt;1.0; i+= 0.1)
{
    movie.add(new FSPlaceObject(1, i));
    movie.add(new FSShowFrame());
}
</pre>

<p>6. Defining a movie clip event.<br/>
FSClipEvent objects are ONLY used to define the sequence of actions executed when a particular event occurs in a movie clip.</p>

<pre>
// Define an array of clip events that will contain one event that defines the
// behaviour of the movie clip in response to a mouse down event.

ArrayList events = new ArrayList();

FSClipEvent clipEvent = new FSClipEvent(FSClipEvent.MouseDown);

// Add one or more actions for the mouse down event.

clipEvent.add(...);
...

// Add the clip event to the array of events for the movie clip.

events.add(clipEvent);

// Create the commands to animate the movie clip.

ArrayList commands = new ArrayList();

commands.add(...);

FSDefineMovieClip movieClip = new FSDefineMovieClip(movie.newIdentifier(), commands);

// Now place the movie clip on the screen on layer 1 at (400, 400).

movie.add(new FSPlaceObject2(movieClip.getIdentifier(), 1, events, 400, 400));
</pre>

<h1 class="datasheet">History</h1>

<p>The FSPlaceObject2 class represents the PlaceObject2 tag from the Macromedia Flash (SWF) File Format Specification. It was introduced in Flash 3.</p>
 */  
public class FSPlaceObject2 extends FSMovieObject
{
    /* Update an existing object on the display list */
    public static final int Modify = 1;
    /* Add a new object to the display list */
    public static final int New = 2;
    /* Replace an existing object on the display list with a new one */
    public static final int Replace = 3;
    
    private int place = New;
    private int layer = 0;
    private int identifier = 0;

    private FSCoordTransform transform = null;
    private FSColorTransform colorTransform = null;

    private float ratio = -1.0f;
    private int clippingDepth = 0;

    private String name = null;
    private ArrayList clipEvents = null;
    private byte[] encodedEvents = null;
        
    /**
     * Construct an FSPlaceObject2 object, initalizing it with values decoded 
     * from an encoded object.
     * 
     * @param coder an FSCoder containing the binary data.
     */
    public FSPlaceObject2(FSCoder coder)
    {
        super(PlaceObject2);
        decode(coder);
    }
    /** Constructs an FSPlaceObject2 object to place a new object on the display list at the coordinates on the screen.

        @param anIdentifier the identifier of a new object to be displayed.
        @param aLayer the layer number on which an object is being displayed.
        @param xLocation the x-coordinate where the object will be displayed.
        @param yLocation the y-coordinate where the object will be displayed.
        */
    public FSPlaceObject2(int anIdentifier, int aLayer, int xLocation, int yLocation)
    {
        super(PlaceObject2);
        setPlaceType(FSPlaceObject2.New);
        setIdentifier(anIdentifier);
        setLayer(aLayer);
        setTransform(new FSCoordTransform(xLocation, yLocation));
    }

    /** Constructs an FSPlaceObject2 object to place new morphing shape on the display list at the coordinates on the screen.

        @param anIdentifier the identifier of a new object to be displayed.
        @param aLayer the layer number on which an object is being displayed.
        @param aRatio the ratio of the progress in morphing the shape.
        @param xLocation the x-coordinate where the object will be displayed.
        @param yLocation the y-coordinate where the object will be displayed.
        */
    public FSPlaceObject2(int anIdentifier, int aLayer, float aRatio, int xLocation, int yLocation)
    {
        super(PlaceObject2);
        setPlaceType(FSPlaceObject2.New);
        setIdentifier(anIdentifier);
        setLayer(aLayer);
        setRatio(aRatio);
        setTransform(new FSCoordTransform(xLocation, yLocation));
    }

    /** Constructs an FSPlaceObject2 object to place a new shape on the display list with the specified coordinate and optional colour transform.

        @param anIdentifier the identifier of a new object to be displayed.
        @param aLayer the layer number on which an object is being displayed.
        @param aTransform an FSCoordTransform object that will be applied to the object displayed in the display list at layer, aLayer.
        */
    public FSPlaceObject2(int anIdentifier, int aLayer, FSCoordTransform aTransform)
    {
        super(PlaceObject2);
        setPlaceType(FSPlaceObject2.New);
        setIdentifier(anIdentifier);
        setLayer(aLayer);
        setTransform(aTransform);
    }

    /** Constructs an FSPlaceObject2 object to place a new shape on the display list with the specified coordinate and optional colour transform.

        @param anIdentifier the identifier of a new object to be displayed.
        @param aLayer the layer number on which an object is being displayed.
        @param aTransform an FSCoordTransform object that will be applied to the object displayed in the display list at layer, aLayer.
        @param aColorTransform a FSColorTransform object that will be applied to the object displayed in the display list at layer, aLayer.
        */
    public FSPlaceObject2(int anIdentifier, int aLayer, FSCoordTransform aTransform, FSColorTransform aColorTransform)
    {
        super(PlaceObject2);
        setPlaceType(FSPlaceObject2.New);
        setIdentifier(anIdentifier);
        setLayer(aLayer);
        setTransform(aTransform);
        setColorTransform(aColorTransform);
    }

    /** Constructs an FSPlaceObject2 object to place a new shape on the display list at the coordinates on the screen that defines a clipping path that will clip objects for the specified number of layers.