Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.flagstone.transform
Class FSClipEvent

    java.lang.Object
      com.flagstone.transform.FSTransformObject
          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`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD