com.flagstone.transform
Class Place2

java.lang.Object
  com.flagstone.transform.Place2

All Implemented Interfaces:

Copyable<MovieTag>, SWFEncodeable, MovieTag

public final class Place2
extends Object
implements MovieTag

Place2 is used to add and manipulate objects (shape, button, etc.) on the Flash Player's display list.

Place2 supersedes the Place class providing more functionality and easier manipulation of objects in the display list through the following operations:

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

Clipping Depth
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.

Shape Morphing
Shapes that will be morphed are defined using the DefineMorphShape 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 DefineMorphShape object and 1.0 generates the shape at the end of the morphing process.

Event Handlers
With the introduction of Flash 5, movie clips (defined using the DefineMovieClip class) could specify sequences of actions that would be performed in response to mouse or keyboard events. The actions are specified using EventHandler objects and the Place2 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 EventHandler for each type of event. For more information see the EventHandler and Event which defines the set of events that a movie clip responds to.

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:

• If an existing object on the display list is being modified then only the layer number is required. Previously in the Place class both the identifier and the layer number were required.
• 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.
• 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.
• If a shape is not being morphed then the ratio attribute may be left at its default value (-1.0).
• If a shape is not used to define a clipping area then the depth attribute may be left at its default value (0).
• If a name is net assigned to an object the name attribute may be left its default value (an empty string).
• If no events are being defined for a movie clip then the list of ClipEvent object may be left empty.

The Layer class provides a simple API for manipulating objects on the display list. While it is relatively simple to create instances of Place2 object that perform the same steps the API provided by Player is easier to use and much more readable.

See Also:

Layer

Constructor Summary

Place2()
Creates an uninitialised Place2 object.

Place2(Place2 object)
Creates and initialises a Place2 object using the values copied from another Place2 object.

Place2(SWFDecoder coder, Context context)
Creates and initialises a Place2 object using values encoded in the Flash binary format.

Method Summary

Place2	add(EventHandler aClipEvent) Adds a clip event to the list of clip events.
Place2	copy() Creates a complete copy of this object.
void	encode(SWFEncoder coder, Context context) Encode an object to the Flash binary format.
ColorTransform	getColorTransform() Get the colour transform.
Integer	getDepth() Get the number of layers that will be clipped by the object placed on the layer specified in this object.
List<EventHandler>	getEvents() Get the list of event handlers that define the actions that will be executed in response to events that occur in the movie clip being placed.
int	getIdentifier() Get the identifier of the object to be placed.
int	getLayer() Get the Layer on which the object will be displayed in the display list.
String	getName() Get the name of the object.
Integer	getRatio() Get the morph ratio, in the range 0..65535 that defines the progress in the morphing process performed by the Flash Player from the defined start and end shapes.
CoordTransform	getTransform() Get the coordinate transform.
PlaceType	getType() Get the type of place operation being performed, either adding a new object, replacing an existing one with another or modifying an existing object.
static Place2	move(int layer, int xCoord, int yCoord) Change the position of a displayed object.
int	prepareToEncode(Context context) Prepare an object for encoding, returning the expected size of an object when it is encoded.
static Place2	replace(int identifier, int layer) Replace an existing object with another.
static Place2	replace(int identifier, int layer, int xCoord, int yCoord) Replace an existing object with another.
Place2	setColorTransform(ColorTransform cxform) Sets the colour transform that defines the colour effects applied to the object.
Place2	setDepth(Integer aNumber) Sets the number of layers that this object will mask.
void	setEvents(List<EventHandler> list) Set the list of Clip events.
Place2	setIdentifier(int uid) Sets the identifier of the object.
Place2	setLayer(int aLayer) Sets the layer at which the object will be placed.
Place2	setLocation(int xCoord, int yCoord) Sets the location where the object will be displayed.
Place2	setName(String aString) Set the name of an object to be displayed.
Place2	setRatio(Integer aNumber) Sets point of the morphing process for a morph shape in the range 0..65535.
Place2	setTransform(CoordTransform matrix) Sets the coordinate transform that defines the position where the object will be displayed.
Place2	setType(PlaceType aType) Sets the type of placement.
static Place2	show(int identifier, int layer, int xCoord, int yCoord) Place a new object on the display list.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Place2

public Place2(SWFDecoder coder,
              Context context)
       throws IOException

Creates and initialises a Place2 object using values encoded in the Flash binary format.

Parameters:

coder - an SWFDecoder object that contains the encoded Flash data.

context - a Context object used to manage the decoders for different type of object and to pass information on how objects are decoded.

Throws:

IOException - if an error occurs while decoding the data.

Place2

public Place2()

Creates an uninitialised Place2 object.

Place2

public Place2(Place2 object)

Creates and initialises a Place2 object using the values copied from another Place2 object.

Parameters:

object - a Place2 object from which the values will be copied.

Method Detail

show

public static Place2 show(int identifier,
                          int layer,
                          int xCoord,
                          int yCoord)

Place a new object on the display list.

Parameters:

identifier - the unique identifier for the object.

layer - the layer where it will be displayed.

xCoord - the x-coordinate where the object's origin will be.

yCoord - the y-coordinate where the object's origin will be.

Returns:

the Place2 object to update the display list.

move

public static Place2 move(int layer,
                          int xCoord,
                          int yCoord)

Change the position of a displayed object.

Parameters:

layer - the display list layer where the object is displayed.

xCoord - the x-coordinate where the object's origin will be moved.

yCoord - the y-coordinate where the object's origin will be moved.

Returns:

the Place3 object to change the position of the object.

replace

public static Place2 replace(int identifier,
                             int layer)

Replace an existing object with another.

Parameters:

identifier - the unique identifier of the new object.

layer - the display list layer of the existing object.

Returns:

the Place3 object to update the display list.

replace

public static Place2 replace(int identifier,
                             int layer,
                             int xCoord,
                             int yCoord)

Replace an existing object with another.

Parameters:

identifier - the unique identifier of the new object.

layer - the display list layer of the existing object.

xCoord - the x-coordinate where the new object's origin will be.

yCoord - the y-coordinate where the new object's origin will be.

Returns:

the Place3 object to update the display list.

add

public Place2 add(EventHandler aClipEvent)

Adds a clip event to the list of clip events.

Parameters:

aClipEvent - a clip event object.

Returns:

this object.

getEvents

public List<EventHandler> getEvents()

Get the list of event handlers that define the actions that will be executed in response to events that occur in the movie clip being placed.

Returns:

the set of event handlers for the movie clip.

setEvents

public void setEvents(List<EventHandler> list)

Set the list of Clip events. Clip Events are only valid for movie clips and the argument should be set to null when placing other types of object. If the object already contains a set of encoded clip event objects they will be deleted.

Parameters:

list - a list of ClipEvent objects.

getType

public PlaceType getType()

Get the type of place operation being performed, either adding a new object, replacing an existing one with another or modifying an existing object.

Returns:

the way the object will be placed.

getLayer

public int getLayer()

Get the Layer on which the object will be displayed in the display list.

Returns:

the layer where the object will be displayed.

getIdentifier

public int getIdentifier()

Get the identifier of the object to be placed. This is only required when placing an object for the first time. Subsequent references to the object on this layer can simply use the layer number.

Returns:

the unique identifier of the object to be displayed.

getTransform

public CoordTransform getTransform()

Get the coordinate transform. May be null if no coordinate transform was defined.

Returns:

the coordinate transform that will be applied to the displayed object.

getColorTransform

public ColorTransform getColorTransform()

Get the colour transform. May be null if no colour transform was defined.

Returns:

the colour transform that will be applied to the displayed object.

getRatio

public Integer getRatio()

Get the morph ratio, in the range 0..65535 that defines the progress in the morphing process performed by the Flash Player from the defined start and end shapes. A value of 0 indicates the start of the process and 65535 the end. Returns null if no ratio was specified.

Returns:

the morphing ratio.

getDepth

public Integer getDepth()

Get the number of layers that will be clipped by the object placed on the layer specified in this object.

Returns:

the number of layers to be clipped.

getName

public String getName()

Get the name of the object. May be null if a name was not assigned to the object.

Returns:

the name of the object.

setType

public Place2 setType(PlaceType aType)

Sets the type of placement.

Parameters:

aType - the type of operation to be performed, either New, Modify or Replace.

Returns:

this object.

setLayer

public Place2 setLayer(int aLayer)

Sets the layer at which the object will be placed.

Parameters:

aLayer - the layer number on which the object is being displayed. Must be in the range 1..65535.

Returns:

this object.

setIdentifier

public Place2 setIdentifier(int uid)

Sets the identifier of the object.

Parameters:

uid - the identifier of a new object to be displayed. Must be in the range 1..65535.

Returns:

this object.

setTransform

public Place2 setTransform(CoordTransform matrix)

Sets the coordinate transform that defines the position where the object will be displayed. The argument may be null if the location of the object is not being changed.

Parameters:

matrix - an CoordTransform object that will be applied to the object displayed.

Returns:

this object.

setLocation

public Place2 setLocation(int xCoord,
                          int yCoord)

Sets the location where the object will be displayed.

Parameters:

xCoord - the x-coordinate of the object's origin.

yCoord - the x-coordinate of the object's origin.

Returns:

this object.

setColorTransform

public Place2 setColorTransform(ColorTransform cxform)

Sets the colour transform that defines the colour effects applied to the object. The argument may be null if the color of the object is not being changed.

Parameters:

cxform - an ColorTransform object that will be applied to the object displayed.

Returns:

this object.

setRatio

public Place2 setRatio(Integer aNumber)

Sets point of the morphing process for a morph shape in the range 0..65535. May be set to null if the shape being placed is not being morphed.

Parameters:

aNumber - the progress in the morphing process.

Returns:

this object.

setDepth

public Place2 setDepth(Integer aNumber)

Sets the number of layers that this object will mask. May be set to zero if the shape being placed does not define a clipping area.

Parameters:

aNumber - the number of layers clipped.

Returns:

this object.

setName

public Place2 setName(String aString)

Set the name of an object to be displayed. If a shape is not being assigned a name then setting the argument to null will omit the attribute when the object is encoded.

Parameters:

aString - the name assigned to the object.

Returns:

this object.

copy

public Place2 copy()

Creates a complete copy of this object.

Specified by:

copy in interface Copyable<MovieTag>

Returns:

a deep-copy of this object. New instances of mutable objects are copied and immutable instances are shared.

toString

public String toString()

Overrides:

toString in class Object

prepareToEncode

public int prepareToEncode(Context context)

Prepare an object for encoding, returning the expected size of an object when it is encoded. This method also used to initialise variables, such as offsets and flags that will be used when the object is encoded. Generally the method returns the size in bytes, however when called on objects that use bit fields such as shapes the methods will return the size in bits.

Specified by:

prepareToEncode in interface SWFEncodeable

Parameters:

context - an Context that allows information to be passed between objects to control how they are initialised for encoding.

Returns:

the size of the object when it is encoded.

encode

public void encode(SWFEncoder coder,
                   Context context)
            throws IOException

Encode an object to the Flash binary format.

Specified by:

encode in interface SWFEncodeable

Parameters:

coder - an SWFEncoder object.

context - an Context that allows information to be passed between objects to control how they are initialised for encoding.

Throws:

IOException - if an error occurs while encoding the object.