com.flagstone.transform
Class FSClipEvent

java.lang.Object
  extended by com.flagstone.transform.FSTransformObject
      extended by com.flagstone.transform.FSClipEvent
All Implemented Interfaces:
java.lang.Cloneable

public class FSClipEvent
extends FSTransformObject

FSClipEvent is used to define the actions that a movie clip will execute in response to a particular event.

FSClipEvent objects are added to an FSPlaceObject2 object and the actions are registered with the Flash Player when the movie clip is added to the display list.

Attributes
event A code representing one or more events that the movie clip will respond to.
actions An array of actions that will be executed when one or more of the specified events occur.
encodedActions An array of bytes containing encoded actions can also be set. The encoded actions are typically generated by the parser in the Translate framework. The actions array and encodedActions cannot both be valid at the same time. Accessor methods used to set either of the attributes will set the other to null.

The events that a movie clip responds to are:

Event Description
Load occurs when the movie clip is finished loading.
Unload occurs when the movie clip is unloaded from the parent movie.
EnterFrame occurs when each frame in the movie clip is played.
MouseMove occurs when the mouse pointer is moved.
MouseDown occurs when the left mouse button is pressed while the cursor is outside of the bounding rectangle of the movie clip.
MouseUp occurs when the left mouse button is pressed and released while the cursor is outside of the bounding rectangle of the movie clip.
KeyDown occurs when any key is pressed on the keyboard. From Flash 6 a key code can be specified to identify a specific key rather than testing for the value inside the actions that are executed in response to the event.
KeyUp occurs when any key being pressed on the keyboard is released.
Data occurs when an FSGetUrl2 action is executed with the movie clip specified as a target.

Starting with Flash 6 movie clips also respond to the same set of events that buttons do:

RollOver occurs when the mouse cursor moves over the movie clip.
RollOut occurs when the mouse cursor moves out of the bounding rectangle of the movie clip.
Press occurs when the mouse button is clicked while the mouse cursor is inside bounding rectangle of the movie clip.
Release occurs when the mouse button is clicked and released while the mouse cursor is inside bounding rectangle of the movie clip.
ReleaseOut occurs when the mouse button is clicked and the mouse cursor is released outside of the bounding rectangle of the movie clip.
DragOut occurs when the mouse button is clicked and the mouse cursor is dragged out of the bounding rectangle of the movie clip.
DragOver occurs when the mouse button is clicked, the mouse cursor is dragged into the bounding rectangle of the movie clip and the mouse button is released.
Initialize occurs when a movie clip is initialized using the FSInitialize class.

Movie clips now also respond to keys being pressed on the keyboard. Keyboard events are defined by the character key being pressed, e.g. "t", "T", "$", etc. The ASCII code for the key is used to identify which key was pressed. Note that while multiple mouse events can be defined for a button only one keyboard event can be defined.

In Flash 7 a new construct event was added.

Construct The function of this event is undocumented.

IMPORTANT: The FSClipEvent object supports both the Flash 5, Flash 6 and Flash 7 event models. The events that are encoded to a file are determined by the version of the FSMovie in which the object is contained. The codes assigned to the different types of event ensure that the same value can be used to encode the object for each version of Flash.

For the KeyDown and KeyUp events, Flash ActionScript provides the Key object which contains the getCode() and isDown() functions that allow code to be written to test which key was pressed. Note that ActionScript is a high-level interpreted language similar to JavaScript. Transform supports actions that represent the compiled version of the ActionScript code. To create and compile ActionScript code then use Transform's sister product, Translate.

Each type of event is defined by a constant, for example, Load, EnterFrame, etc. An FSClipEvent object can define the actions that will be executed in response to multiple events. There are two ways to respond to multiple events. If the same set of actions should be executed then the event code that flags which events should be responded to can be generated by bitwise OR-ing together the individual constants:

 int loadAndMouseMove = FSClipEvent.Load | FSClipEvent.MouseMove;
 

If different actions should be executed then an FSClipEvent object is created for each different set of events. The FSPlaceObject2 object that is used to register the actions for a movie clip with the Flash Player supports an array of FSClipEvent objects.

The array of actions may be empty. Although this situation does not perform any useful operation it is valid and may be encountered when parsing Flash files generated by a third party.

Examples

The following simplified code fragments illustrate how the FSClipEvent class can be used.

1. Defining the actions for a single event.

  FSDefineMovieClip movieClip = new FSDefineMovieClip(movie.newIdentifier(), commands);
 
  FSClipEvent clipEvent(FSClipEvent.MouseDown);
 
  clipEvent.add(anAction);
  ...
 
  FSPlaceObject2 placeClip = new FSPlaceObject2(movieClip.getIdentifier(), 1, events, 400, 400);
 
  placeClip.add(clipEvent);
 
  movie.add(movieClip);
  movie.add(placeClip);
 

2. Defining the actions for a compound event.
If a movie clip should execute the same set of actions for different types of event then the code for the compound event can be created by bitwise-OR'ing individual event codes.

  FSDefineMovieClip movieClip = new FSDefineMovieClip(movie.newIdentifier(), commands);
 
  FSClipEvent clipEvent(FSClipEvent.MouseDown | FSClipEvent.KeyDown, actions);
  ...
  FSPlaceObject2* placeClip = new FSPlaceObject2(movieClip.getIdentifier(), 1, events, 400, 400)
 
  placeClip.add(clipEvent);
 
  movie.add(movieClip);
  movie.add(placeClip);
 

3. Defining different sets of actions for events.
An FSClipEvent object is created for each set of events that a movie clip must respond to.

  FSDefineMovieClip* movieClip = new FSDefineMovieClip(movie.newIdentifier(), commands);
  FSPlaceObject2* placeClip = new FSPlaceObject2(movieClip.getIdentifier(), 1, events, 400, 400)
 
  FSClipEvent mouseEvent(FSClipEvent.MouseDown, mouseActions);
  ...
  placeClip.add(clipEvent);
 
  FSClipEvent keyEvent(FSClipEvent.KeyDown, keyActions);
  ...
  placeClip.add(keyEvent);
 
  movie.add(movieClip);
  movie.add(placeClip);
 

History

The FSClipEvent class represents the ClipEvent data structure tag from the Macromedia Flash (SWF) File Format Specification. It was introduced in Flash 5. The event model was extended in Flash 6 to support the set of events that Buttons respond to. In Flash 7 the Construct event was added.


Field Summary
static int Construct
          Code for a construct event.
static int Data
          Code for a data event.
static int DragOut
          Code for a drag out event.
static int DragOver
          Code for a drag over event.
static int EnterFrame
          Code for an enter frame event.
static int Initialize
          Code for an initialise event.
static int KeyDown
          Code for a key down event.
static int KeyPress
          Code for a key press event, where the code for the key is specified.
static int KeyUp
          Code for a key up event.
static int Load
          Code for a load event.
static int MouseDown
          Code for a mouse down event.
static int MouseMove
          Code for a mouse move event.
static int MouseUp
          Code for a mouse up event.
static int Press
          Code for a press event.
static int Release
          Code for a release event.
static int ReleaseOut
          Code for a release outside event.
static int RollOut
          Code for a roll out event.
static int RollOver
          Code for a roll over event.
static int Unload
          Code for an unload event.
 
Constructor Summary
FSClipEvent(FSClipEvent obj)
          Constructs an FSCall object by copying values from an existing object.
FSClipEvent(FSCoder coder)
          Construct an FSClipEvent object, initialising it with values decoded from an encoded object.
FSClipEvent(int eventCode, java.util.ArrayList anArray)
          Constructs an FSClipEvent object that defines the array of actions that will be executed when a particular event occurs.
FSClipEvent(int eventCode, byte[] bytes)
          Constructs an FSClipEvent object that defines the array of actions that will be executed when a particular event occurs.
FSClipEvent(int eventCode, int keyCode, java.util.ArrayList anArray)
          Constructs an FSClipEvent object that defines the array of actions that will be executed when a particular event occurs or when the specified key is pressed.
FSClipEvent(int eventCode, int keyCode, byte[] bytes)
          Constructs an FSClipEvent object that defines the array of actions that will be executed when a particular event occurs or when the specified key is pressed.
 
Method Summary
 void add(FSActionObject anAction)
          Adds an action to the array of actions.
 void appendDescription(java.lang.StringBuffer buffer, int depth)
          AppendDescription is used to present a string description of the object including all nested objects up to a specified depth.
 java.lang.Object clone()
          Creates a deep copy of the entire object.
 void decode(FSCoder coder)
           
 void encode(FSCoder coder)
           
 boolean equals(java.lang.Object anObject)
          Returns true if anObject is equal to this one.
 java.util.ArrayList getActions()
          Gets the array of actions that are executed by the movie clip in response to specified event(s).
 byte[] getEncodedActions()
          Get the array of encoded actions that are executed when the frame is displayed.
 int getEvent()
          Gets the event code that this FSClipEvent defines actions for.
 int getKeyCode()
          Gets the code for the key that triggers the event when pressed.
 int length(FSCoder coder)
           
 void setActions(java.util.ArrayList anArray)
          Sets the array of actions that are executed by the movie clip in response to specified event(s).
 void setEncodedActions(byte[] bytes)
          Set the array of encoded actions generated by the classes in the Translate framework.
 void setEvent(int aNumber)
          Sets the event code that this FSClipEvent defines actions for.
 void setKeyCode(int code)
          Sets the code for the key that triggers the event when pressed.
 
Methods inherited from class com.flagstone.transform.FSTransformObject
name, toString
 
Methods inherited from class java.lang.Object
finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

Load

public static final int Load
Code for a load event.

See Also:
Constant Field Values

EnterFrame

public static final int EnterFrame
Code for an enter frame event.

See Also:
Constant Field Values

Unload

public static final int Unload
Code for an unload event.

See Also:
Constant Field Values

MouseMove

public static final int MouseMove
Code for a mouse move event.

See Also:
Constant Field Values

MouseDown

public static final int MouseDown
Code for a mouse down event.

See Also:
Constant Field Values

MouseUp

public static final int MouseUp
Code for a mouse up event.

See Also:
Constant Field Values

KeyDown

public static final int KeyDown
Code for a key down event.

See Also:
Constant Field Values

KeyUp

public static final int KeyUp
Code for a key up event.

See Also:
Constant Field Values

Data

public static final int Data
Code for a data event.

See Also:
Constant Field Values

Initialize

public static final int Initialize
Code for an initialise event.

See Also:
Constant Field Values

Press

public static final int Press
Code for a press event.

See Also:
Constant Field Values

Release

public static final int Release
Code for a release event.

See Also:
Constant Field Values

ReleaseOut

public static final int ReleaseOut
Code for a release outside event.

See Also:
Constant Field Values

RollOver

public static final int RollOver
Code for a roll over event.

See Also:
Constant Field Values

RollOut

public static final int RollOut
Code for a roll out event.

See Also:
Constant Field Values

DragOver

public static final int DragOver
Code for a drag over event.

See Also:
Constant Field Values

DragOut

public static final int DragOut
Code for a drag out event.

See Also:
Constant Field Values

KeyPress

public static final int KeyPress
Code for a key press event, where the code for the key is specified.

See Also:
Constant Field Values

Construct

public static final int Construct
Code for a construct event.

See Also:
Constant Field Values
Constructor Detail

FSClipEvent

public FSClipEvent(FSCoder coder)
Construct an FSClipEvent object, initialising it with values decoded from an encoded object.

Parameters:
coder - an FSCoder containing the binary data.

FSClipEvent

public FSClipEvent(int eventCode,
                   java.util.ArrayList anArray)
Constructs an FSClipEvent object that defines the array of actions that will be executed when a particular event occurs.

Parameters:
eventCode - the code representing one or more events.
anArray - the array of actions that will be executed when the specified event occurs.

FSClipEvent

public FSClipEvent(int eventCode,
                   byte[] bytes)
Constructs an FSClipEvent object that defines the array of actions that will be executed when a particular event occurs.

Parameters:
eventCode - the event code.
bytes - an array of encoded action objects.

FSClipEvent

public FSClipEvent(int eventCode,
                   int keyCode,
                   java.util.ArrayList anArray)
Constructs an FSClipEvent object that defines the array of actions that will be executed when a particular event occurs or when the specified key is pressed.

Parameters:
eventCode - the code representing one or more events.
keyCode - the ASCII code for the key pressed on the keyboard.
anArray - the array of actions that will be executed when the specified event occurs.

FSClipEvent

public FSClipEvent(int eventCode,
                   int keyCode,
                   byte[] bytes)
Constructs an FSClipEvent object that defines the array of actions that will be executed when a particular event occurs or when the specified key is pressed. The array of bytes contained the encoded actions and is typically generated using the classes in the Translate framework.

Parameters:
eventCode - the code representing one or more events.
keyCode - the ASCII code for the key pressed on the keyboard.
bytes - an array of encoded action objects.

FSClipEvent

public FSClipEvent(FSClipEvent obj)
Constructs an FSCall object by copying values from an existing object.

Parameters:
obj - an FSCall object.
Method Detail

add

public void add(FSActionObject anAction)
Adds an action to the array of actions.

Parameters:
anAction - a pointer to an action object.

setEvent

public void setEvent(int aNumber)
Sets the event code that this FSClipEvent defines actions for.

Parameters:
aNumber - the code representing one or more events.

getEvent

public int getEvent()
Gets the event code that this FSClipEvent defines actions for.

Returns:
the eventCode representing the events that the FSClipEvent object will respond to.

getKeyCode

public int getKeyCode()
Gets the code for the key that triggers the event when pressed. The code is typically the ASCII code for standard western keyboards.

Returns:
the code for the key that triggers the event.

setKeyCode

public void setKeyCode(int code)
Sets the code for the key that triggers the event when pressed. The code is typically the ASCII code for standard western keyboards.

Parameters:
code - the ASCII code for the key that triggers the event.

setActions

public void setActions(java.util.ArrayList anArray)
Sets the array of actions that are executed by the movie clip in response to specified event(s).

Parameters:
anArray - the array of actions that will be executed when the specified event occurs.

getActions

public java.util.ArrayList getActions()
Gets the array of actions that are executed by the movie clip in response to specified event(s).

Returns:
the array of actions that will be executed when the specified event occurs.

getEncodedActions

public byte[] getEncodedActions()
Get the array of encoded actions that are executed when the frame is displayed.

Returns:
the array of action objects or null if the actions have been decoded.

setEncodedActions

public void setEncodedActions(byte[] bytes)
Set the array of encoded actions generated by the classes in the Translate framework. If the object already contains an array of actions then they will be deleted.

Parameters:
bytes - the array of encoded actions.

clone

public java.lang.Object clone()
Description copied from class: FSTransformObject
Creates a deep copy of the entire object.

Overrides:
clone in class FSTransformObject
Returns:
a copy of the object.

equals

public boolean equals(java.lang.Object anObject)
Returns true if anObject is equal to this one. Objects are considered equal if they would generate identical binary data when they are encoded to a Flash file.

Overrides:
equals in class FSTransformObject
Returns:
true if this object would be identical to anObject when encoded.

appendDescription

public void appendDescription(java.lang.StringBuffer buffer,
                              int depth)
Description copied from class: FSTransformObject
AppendDescription is used to present a string description of the object including all nested objects up to a specified depth. This method provide a more controlled way of creating a string representation of an object since large objects such as font or shape definitions can contain dozens of nested objects. The representation of the object is appended to the StringBuffer, showing the name of the class and values of the attributes it contains. If the object contains any attributes that are objects then the object graph will be traversed up to the specified depth. If objects are nested at a level less than specified depth then the full string representation of the object is displayed. For objects at the specified depth only the name of the class is displayed. Any objects below this depth are not displayed.

Specified by:
appendDescription in class FSTransformObject
Parameters:
buffer - a StringBuffer to which the description of each object is appended.
depth - the maximum level of nesting up to which objects will be displayed.

length

public int length(FSCoder coder)
Specified by:
length in class FSTransformObject

encode

public void encode(FSCoder coder)
Specified by:
encode in class FSTransformObject

decode

public void decode(FSCoder coder)
Specified by:
decode in class FSTransformObject