com.flagstone.transform
Class FSLayer

java.lang.Object
  extended by com.flagstone.transform.FSLayer

public final class FSLayer
extends java.lang.Object

The Layer class can be used to simplify the creation of movies. It provides a series of methods that can be used to control how an object is displayed and provides an API that is easier to use when compared to creating the commands (FSPlaceObject, FSRemoveObject, etc.) used to manipulate the Flash Player's display list directly. The following code:

 FSLayer layer = new Layer(1);
 
 layer.select(shape);
 layer.move(x1, y1);
 layer.show();
 layer.move(x2, y2);
 layer.show();
 
 movie.add(layer.getObjects());
 
is equivalent to:
 movie.add(shape);
 movie.add(new FSPlaceObject2(shape.getIdentifier, 1, x1, y1));
 movie.add(FSShowFrame.getInstance());
 movie.add(new FSPlaceObject2(1, x2, y2));
 movie.add(FSShowFrame.getInstance());
 
After each set of commands the display list is updated by executing the show() method - this adds a ShowFrame instruction to the final movie which tells the Flash Player to render the display list on the screen. The select() method is only used when displaying an object for the first time or re-displaying it after it was deleted from the display list. The commands that manipulate the display list can also be combined to apply several operations at once:
 layer.select(shape);
 layer.move(x, y);
 layer.morph(0.9);
 layer.color(r, g, b);
 layer.show();
 
is equivalent to:
 FSCoordTransform coord = new FSCoordTransform(x, y);
 FSColorTransform color = new FSColorTransform(r, g, b);
 FSPlaceObject2 place = new FSPlaceObject2(shape.getIdentifier, 1, coord, color)
 place.setRatio(0.9);
 
 movie.add(shape);
 movie.add(place);
 movie.add(FSShowFrame.getInstance());
 
An operation is use to set the attributes on either an FSPlaceObject2 or FSRemoveObject2 object so operations of the same type cannot be combined to create a cumulative effect. For example:
 layer.move(x1, y1);
 layer.move(x2, y2);
 
is the same as:
 layer.move(x2, y2);
 
and not:
 layer.move(x1 + x2, y1 + y2);
 
The most obvious benefit is code that is easier to write and read however the benefits of using layers come to the fore when creating movies with multiple objects. Currently the movie object represents the main time-line and the commands to control and display each object must be interleaved together. This quickly becomes unwieldy and error prone if several objects are involved. With layers, each can be regarded as the time-line for a single object. The object can then be manipulated more easily and the final set of Layers merged together to create a single time-line. The only limitation in the merging process is that all the Layers must start at the same point in time. Each Layer object created must be assigned a unique number. In Flash an object to be displayed is assigned to a given layer with (typically) only one object displayed on a given layer. The layer number is used to control the order in which the objects are displayed. Objects placed on a higher layer number are displayed in front of object placed on a lower layer number.


Constructor Summary
FSLayer(int number)
          Create a new Layer object.
 
Method Summary
 void add(FSDefineObject definition)
          Add an object to the layer.
 void change(FSColorTransform color)
          Change the colour of the object by applying a color transform.
 void change(FSCoordTransform coord)
          Change the position, orientation and scaling of the object by applying a 2D coordinate transform.
 void clip(int depth)
          Set the number of layers that the outline of the object will clip when placed on the display list.
 void color(int r, int g, int b)
          Change the colour of the object to the values (r,g,b).
 void color(int r, int g, int b, int a)
          Change the colour of the object to the values (r,g,b,a).
 int getIdentifier()
          Return the identifier of the object on the layer.
 int getLayer()
          Return the layer number.
 java.util.ArrayList getObjects()
          Return the array of commands used to manipulate the object on the display list.
static java.util.ArrayList merge(java.util.ArrayList layers)
          Merge layers together to create a single time-line.
 void morph(float ratio)
          Set the point in the morphing process for a morph shape in the range 0.0 to 1.0.
 void move(int x, int y)
          Set the coordinates where the object will be displayed.
 void name(java.lang.String name)
          Assign a name to the object.
 void remove()
          Remove the object from the display list.
 void replace(int id)
          Replace the object on the display list.
 void select(FSDefineObject definition)
          Add an object to the later and select it to be added on the display list.
 void select(int id)
          Select the object previously added to the layer to be added on the display list.
 void show()
          Instruct the Flash Player to display a frame and render the contents of the display list, applying the commands previously set.
 void show(int count)
          Display one or more frames.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

FSLayer

public FSLayer(int number)
Create a new Layer object. Layers are used to define the order in which objects are displayed. Objects placed on a high layer number are displayed in front of those on a lower layer.

Parameters:
number - the layer number on the display list.
Method Detail

merge

public static java.util.ArrayList merge(java.util.ArrayList layers)
Merge layers together to create a single time-line. Each layer is assumed to start at the same point in time. The process steps through each of the layers, frame by frame, adding all the commands used to manipulate the Flash Player's display list into a single group.

Parameters:
layers - and array of FSLayer objects.
Returns:
an array of all the objects contained in each layer. This array can then be added to the movie.

getLayer

public int getLayer()
Return the layer number. The Flash Player assumes that there is only one object placed on each layer and so each must have a unique number.

Returns:
the layer number.

getIdentifier

public int getIdentifier()
Return the identifier of the object on the layer. Note: it is possible to place more than one object on a layer however only one should be visible on the display list at a given time.

Returns:
the unique identifier used to reference the object.

getObjects

public java.util.ArrayList getObjects()
Return the array of commands used to manipulate the object on the display list.

Returns:
an array of FSMovieObject containing the definition of the object (shape, text, etc) to be displayed and the associated commands that update the position of the object on the screen.

add

public void add(FSDefineObject definition)
Add an object to the layer. The object may be selected later for display.

Parameters:
definition - an object defining an image, shape, text, sound or video.

select

public void select(int id)
Select the object previously added to the layer to be added on the display list. The object will be placed at the default coordinates (0,0). IMPORTANT: You only need to use this method when adding an object to the display list for the first time or when re-adding it after it has been deleted. Since the display list has one layer per object then the layer number can be used to identify which object to update.

Parameters:
id - an object definition, FSDefineShape, FSDefineImage, etc. that will be added to the display list.

select

public void select(FSDefineObject definition)
Add an object to the later and select it to be added on the display list.

Parameters:
definition - an object definition, FSDefineShape, FSDefineImage, etc. that will be added to the display list.

move

public void move(int x,
                 int y)
Set the coordinates where the object will be displayed.

Parameters:
x - the x-coordinate, expressed in twips.
y - the y-coordinate, expressed in twips.

color

public void color(int r,
                  int g,
                  int b)
Change the colour of the object to the values (r,g,b). The colour will be opaque so you cannot use this method to change only the colour of a transparent object.

Parameters:
r - the red component of the colour.
g - the green component of the colour.
b - the blue component of the colour.

color

public void color(int r,
                  int g,
                  int b,
                  int a)
Change the colour of the object to the values (r,g,b,a).

Parameters:
r - the red component of the colour.
g - the green component of the colour.
b - the blue component of the colour.
a - the transparency component.

clip

public void clip(int depth)
Set the number of layers that the outline of the object will clip when placed on the display list.

Parameters:
depth - the number of layers that will be clipped.

morph

public void morph(float ratio)
Set the point in the morphing process for a morph shape in the range 0.0 to 1.0. May be set to zero if the shape being placed is not being morphed.

Parameters:
ratio - the ratio between the starting shape and the end shape.

name

public void name(java.lang.String name)
Assign a name to the object.

Parameters:
name - a string that can be used to reference the object.

remove

public void remove()
Remove the object from the display list.


replace

public void replace(int id)
Replace the object on the display list.


change

public void change(FSColorTransform color)
Change the colour of the object by applying a color transform.

Parameters:
color - the color transform to apply to the shape.

change

public void change(FSCoordTransform coord)
Change the position, orientation and scaling of the object by applying a 2D coordinate transform. Use this method to apply more complex coordinate transforms to an object for example that composite move, scaling and rotation operations in a single step.

Parameters:
coord - the coordinate transform to apply to the object.

show

public void show()
Instruct the Flash Player to display a frame and render the contents of the display list, applying the commands previously set. You must use this method for any of the other operations to take effect.


show

public void show(int count)
Display one or more frames. The state (position, orientation, visibility, etc.) of the object will remain unchanged for the duration of the added frames.

Parameters:
count - the number of frames to be displayed.
Throws:
java.lang.IllegalArgumentException - is the number of frames is less than 1.