Position

_x

MC

RW

RW

RW

The horizontal distance between a Movie Clip's center point and the top-left corner of the stage upon which it resides. It increases as the clip moves to the right, and is measured in pixels.

Movie

RW

RW

RW

_y

MC

RW

RW

RW

The vertical distance between a Movie Clip's center point and the top-left corner of the stage upon which it resides. It increases as the clip moves downward, and is measured in pixels.

Movie

RW

RW

RW

_xmouse

MC

N/A

R

R

The horizontal distance (in pixels) between the zero point of a Movie Clip (or the Movie) and the current position of the mouse pointer.

Movie

R

R

_ymouse

MC

N/A

R

R

The vertical distance (in pixels) between the zero point of a Movie Clip (or the Movie) and the current position of the mouse pointer.

Movie

R

R

_rotation

MC

RW

RW

RW

The amount (in degrees) that a Movie Clip is rotated off plumb. It returns values set both by the Transform panel (or Transform tool) and by ActionScript.

Movie

RW

RW

RW

_xscale

MC

RW

RW

RW

The width of a Movie Clip instance (or Movie) as a percentage of the parent symbol's actual size.

Movie

RW

RW

RW

Size

_yscale

MC

RW

RW

RW

The height of a Movie Clip instance (or Movie) as a percentage of the parent symbol's actual size.

Movie

RW

RW

RW

_width

MC

R

RW

RW

The width (in pixels) of a Movie Clip or the main Movie Stage. It is determined not by the width of the canvas but by the width of the space occupied by elements on the Stage (meaning it can be less than or greater than the canvas width set in Movie Properties).

Movie

R

R

R

_height

MC

R

RW

RW

The height (in pixels) of a movie clip or the main movie. It is determined not by the height of the canvas but by the height of the space occupied by elements on the Stage.

Movie

R

R

R

Appearance

_alpha

MC

RW

RW

RW

The amount of transparency of a Movie Clip or Movie. It is measured as a percentage: 100 percent is completely opaque; 0 percent is completely transparent.

Movie

RW

RW

RW

_visible

MC

RW

RW

RW

A Boolean value that indicates whether a Movie Clip instance is shown or hidden. It is set to 1 (or true) to show; 0 (or false) to hide. Buttons in "hidden" movies are not active.

Movie

RW

RW

RW

filters

MC

N/A

N/A

RW

This property in Flash Player 8 or higher enables you to add visual effects to MovieClip objects. The filters property uses an array to describe which filters have been applied to the clip.

Movie

N/A

N/A

RW

transform

MC

N/A

RW

RW

This property in Flash Player 8 or higher enables you to control physical characteristics of a MovieClip object via transformation object. In Chapter 27, "Interacting with Movie Clips," we discuss the ColorTransform class, which can control the color properties of a MovieClip object.

Movie

N/A

N/A

RW

Internal Path

_name

MC

RW

RW

RW

This property returns or reassigns the Movie Clip instance's name (as listed in the Property inspector).

Movie

R

R

R

_target

MC

R

R

R

This property returns the exact string in Slash notation that you'd use to refer to the Movie Clip instance. To retrieve the dot syntax path, use eval(_target).

Movie

R

R

R

_droptarget

MC

R

R

R

This property returns the name (in Slash notation) of the last Movie Clip upon which a draggable Movie Clip was dropped. To retrieve the dots syntax path, use eval(_droptarget). For usage, see "Creating Draggable Movie Clips" in this chapter.

Movie

R

R

R

_lockroot

MC

RW

RW

RW

This property, only available to Flash Player 7 or higher -compatible movies, enables you to control how a _root reference is interpreted. If the _lockroot property of a MovieClip object is set to true, then any child assets (nested MovieClip objects) will see the parent MovieClip object as _root. For example, if you load an .swf file into a MovieClip object, any _root target in the loaded .swf will point to the MovieClip object.

Movie

RW

RW

RW

_parent

MC

N/A

R

R

This property returns a reference to the parent timeline of the current MovieClip object. For example, if an instance named bird_1 exists within another instance named flock_mc, then bird_1._parent refers to the flock_mc instance.

Movie

N/A

R

R

* _parent will return only a valid reference from the Main Timeline if the Flash movie is loaded into a MovieClip instance of another Flash movie.

External Path

_url

MC

R

R

R

This property returns the complete path to the Flash movie (.swf) in which the action is executed, including the name of the Flash movie file (.swf) itself. It can be used to prevent a movie from being viewed if it is not on a particular server.

Movie

R

R

R

Timeline

_currentframe

MC

R

R

R

This property returns the number of the current frame (for example, the frame on which the Playhead currently resides) of the Movie or a Movie Clip instance.

Movie

R

R

R

_totalframes

MC

R

R

R

This property returns the number of total frames in a Movie or Movie Clip instance's timeline.

Movie

R

R

R

_framesloaded

MC

R

R

R

This property returns the number of frames that have downloaded over the network.

Movie

R

R

R

Global

_quality

Movie

N/A

RW

RW

The visual quality of the movie. The value is a string equal to: "LOW" (no antialiasing, no bitmap smoothing), "MEDIUM" (antialiasing on a 2 × 2 grid, no bitmap smoothing), "HIGH" (antialiasing on a 4 × 4 grid, bitmap smoothing on static frames), "BEST" (antialiasing on a 4 × 4 grid, bitmap smoothing on all frames).

_focusrect

Movie

RW

RW

RW

A Boolean value that indicates whether a yellow rectangle is shown around buttons when accessed via the Tab key. The default is to show. When set to 0, the Up state of the button is shown instead of the yellow rectangle.

_soundbuftime

Movie

RW

RW

RW

The number of seconds a sound should preload before it begins playing. The default is five seconds.

Position

hitTest

No

Determines if a MovieClip object overlaps with the boundaries of another MovieClip object, or if an X-Y coordinate intersects with a MovieClip instance. For more information on this method, see Chapter 27, "Interacting with Movie Clips."

timeline.hitTest(MovieClip object);

OR

timeline.hitTest(x coordinate, y coordinate, shapeFlag);

M

myMC.hitTest(myOther_mc);

myMC.hitTest(_root._xmouse, _root._ymouse, true);

startDrag

Yes

Enables the user to move a Movie Clip instance on the Stage. The Movie Clip moves (or drags) in tandem with the movements of the mouse. You can specify whether the mouse pointer locks to the center of the Movie Clip instance and if the drag area is constrained to a range of X and Y coordinates (in the parent symbol or timeline space). Constraining the drag area is useful for slider controls.

timeline.startDrag(lock, min X, min Y, max X, max Y);

M, A

myMC.startDrag(false, 200,0,200,200);

stopDrag

Yes

Stops any startDrag action currently in progress. No target needs to be specified with this action.

timeline.stopDrag();

M, A

myMC.stopDrag();

Playback

play

Yes

Starts playback from the current position of the Playhead on a specified timeline.

timeline.play();

M, A

_root.play(); // plays the Main Timeline

_root.myMC.play(); // plays myMC

stop

Yes

Stops playback on a specified timeline.

timeline.stop();

M, A

_root.stop(); // stops the Main Timeline

_root.myMC.stop(); // stops myMC

gotoAndPlay

Yes

Jumps the Playhead of a specified timeline to a label, frame number, or expression, and starts playing from there.

timeline.gotoAndPlay(position);

M, A

_root.myMC.gotoAndPlay("start");

// plays from the "start" label of the myMC timeline

gotoAndStop

Yes

Jumps the Playhead of a specified timeline to a label, frame number, or expression, and stops playback.

timeline.gotoAndStop(position);

M, A

_root.myMC.gotoAndStop("mute");

// stops playback on the "mute" label of myMC

nextFrame

Yes

Moves the Playhead of the specified timeline to the next frame.

timeline.nextFrame();

M, A

_root.myMC.nextFrame();

prevFrame

Yes

Moves the Playhead of the specified timeline to the previous frame.

timeline.prevFrame();

M, A

_root.myMC.prevFrame();

Internal Assets

createEmptyMovieClip

No

Makes a blank (empty) Movie Clip instance on the Stage (or nested in another Movie Clip instance). The new instance is placed directly above the parent instance, at a specified depth. Higher depth numbers appear above lower depth numbers (for example, a Movie Clip at depth 2 is stacked above a Movie Clip at depth 1).

This method works in Flash Player 6 or higher.

timeline.createEmptyMovieClip(new name*, depth);

M

_root.createEmptyMovieClip("myMC", 1);

myMC._x = 50;

*You should only specify an instance name for the new MovieClip object—not a new path. You can only create new instances relative to the instance invoking the method.

duplicateMovieClip

Yes

Makes a copy of an existing Movie Clip instance on the Stage (or nested in another Movie Clip). The new copy is placed directly above the parent instance, at a specified depth. Higher depth numbers appear above lower depth numbers (for example, a Movie Clip at depth 2 is stacked above a Movie Clip at depth 1).

timeline.duplicateMovieClip(new name*, depth);

M, A

myMC.duplicateMovieClip("myMC_2", 20);

myMC_2._x = 200;

*See note for the createEmptyMovieClip() method.

removeMovieClip

Yes

Deletes a previously duplicated Movie Clip instance. When used as a method, you do not need to specify a target. You cannot remove a Movie Clip instance that is manually inserted on any timeline frame from the Library.

timeline.removeMovieClip();

M, A

myMC_2.removeMovieClip();

attachMovie

No

Places an instance of a Movie Clip symbol from the Library into the specified timeline. Each attached instance requires a unique name and depth. Attached Movie Clip instances can be deleted with removeMovieClip.

timeline.attachMovie(ID*, new name, depth);

M

_root.attachMovie("eye", "eye_1", 1);

*You need to specify a unique identifier to linked Movie Clip symbols in the Library, using the Linkage Properties.

getDepth

No

Returns the current depth of a duplicated (or attached) MovieClip object.

This method only works in Flash 6 movies played in Flash Player 6.

timeline.getDepth();

M

_root.attachMovie("eye", "eye_1", 1);

trace(eye_1.getDepth());

*If you attempt to retrieve the depth of a Movie Clip instance that you manually placed on the Stage, then ActionScript will return −16383 as the value of getDepth().

swapDepths

No

Switches the depth placement of two duplicated or attached Movie Clips. This method is useful for placing one Movie Clip instance in front of (or behind) another instance.

timeline.swapDepths(depth);

M

timeline.swapDepths(target);

eye_1.swapDepths(10); // depth

eye_1.swapDepths(eye_2); // target

getNextHighestDepth

No

Determines if any objects currently exist within depth slots of the current MovieClip object, and returns a depth number one higher than an occupied slot. For example, if you duplicated a MovieClip object to a depth count of 2, this method would return 3. You can use this method in conjunction with any of the Movie Clip methods that require a depth parameter.

This method works only when issued from a Flash Player 7 or higher movie.

timeline.getNextHighestDepth();

M

var nextSlot = myMC.getNextHighestDepth();

getInstanceAtDepth

No

Returns the name of an object occupying the specified depth slot. If no object exists at the slot, undefined is returned.

This method works only when issued from a Flash Player 7 or higher movie.

timeline.getInstanceAtDepth(depthSlot);

M

var isOccupied = myMC.getInstanceAtDepth(1);

createTextField

No

Adds a new TextField object (that is, a dynamic or input text field) to the MovieClip object. This method enables you to add new text fields to your movie at runtime.

This method works only when issued from a Flash Player 6 or higher movie.

timeline.createTextField(name, depth, x position, y position, width, height);

M

myMC.createTextField("display_txt", 1, 10, 10, 300, 50);

setMask

No

Assigns a MovieClip object to be used as the mask for another MovieClip object.

This method works only when issued from a Flash Player 6 or higher movie.

timeline.setMask(instanceName);

M

myMC.setMask(clip_mc);

External Assets

loadMovie

Yes

Loads an external movie file (.swf) or image file into the main movie. As one of the most powerful features of Flash, this method enables you to break up your Flash movie into several smaller components, and load them as needed. This method can load movie files (.swf) or standard JPEG image files (.jpg) into Flash Player 6 or higher movies. Flash Player 8 or higher movies can also load GIF, PNG, and progressive JPEG images into Movie Clip targets.

timeline.loadMovie(path, send variables*);

M, A

myMC.loadMovie("menu.swf");

OR

myMC.loadMovie("image.jpg");

*You can also send Flash variables to the newly loaded .swf file with an optional "GET" or "POST" parameter. We discuss this in Chapter 24, "Knowing the Nuts and Bolts of Code."

unloadMovie

Yes

Removes an externally loaded movie file (.swf) or image file from the main movie. This method enables you to dump movie assets when they are no longer needed. Use this method for assets loaded into Movie Clip targets.

timeline.unloadMovie();

M, A

myMC.unloadMovie();

loadVariables

Yes

Loads external text-based data into the movie. This method enables you to access data (in the form of variable name/value pairs) from server-side scripts or text files, and place it in a Movie Clip target.

timeline.loadVariables(path, send variables*);

M, A

myMC.loadVariables("info.txt");

*See note in loadMovie. We discuss loadVariables() and the LoadVars object in Chapter 29, "Sending Data In and Out of Flash."

getBytesLoaded

No

Returns the number of bytes that have streamed into the Flash Player for a specified Movie Clip (or movie).

timeline.getBytesLoaded();

M

loadBytes = myMC.getBytesLoaded();

getBytesTotal

No

Returns the total file size (in bytes) for a loading movie or Movie Clip. Combined with getBytesLoaded(), you can use this method to calculate the movie's loaded percentage.

timeline.getBytesTotal();

M

totalBytes = myMC.getBytesTotal();

loadBytes = myMC.getBytesLoaded();

newPercent = (loadBytes/totalBytes)*100;

getSWFVersion

No

Returns the version of the Flash movie as a number. For example, if you create a Flash movie (.swf) to be Flash Player 4–compatible, you can check the version number of that .swf from a Flash Player 7–compatible movie file (.swf).

This method can only be invoked from Flash movies created for Flash Player 7 or higher.

timeline.getSWFVersion();

M

myMC.getSWFVersion();

Playback

load

onLoad

This event is triggered when (A) a Movie Clip instance first appears on the Stage; (B) a new instance is added with attachMovie or duplicateMovieClip; or (C) an external Flash movie file (.swf) is loaded into a Movie Clip target.

Note: The onLoad method does not function properly on individual instances. When a Flash movie file (.swf) loads into a level or a Movie Clip target, any existing methods will be overwritten, including onLoad. See the Usage example to see how onLoad can be used. The onLoad method, however, is useful for setting parameters for components that are added via ActionScript.

onClipEvent(load){
 trace( _name + " has
 loaded.");
 }

OR

MovieClip.prototype.
onLoad = function(){
 trace("A movie or Movie
Clip has loaded.");
};

unload

onUnload

This event occurs when (A) a Movie Clip instance exits the Stage (just after the last frame has played on the Main Timeline), or (B) an external Flash movie file (.swf) is unloaded from a Movie Clip target. Actions within this handler type will be executed before any actions in the keyframe immediately after the Movie Clip's departure keyframe.

onClipEvent(unload){
 trace( _name + " has
unloaded.");
}

OR

mcHolder.onUnload =
function(){
 trace(this._name + " has
unloaded.");
};

enterFrame

onEnterFrame

This event executes when each frame on a Movie Clip instance's timeline is played. The actions within this event handler will be processed after any actions that exist on the keyframes of the Movie Clip Timeline. Note that enterFrame events will execute repeatedly (at the same rate as the movie's frame rate), regardless of whether any timelines within the movie are actually playing frames.

onClipEvent(enterFrame){
 trace( _name + " is
playing.");
}

OR

mcHolder.onEnterFrame =
 function(){
 trace(_name + " is
playing.");
};

User Input

mouseMove

onMouseMove

This event is triggered each time the mouse moves anywhere on the Stage. All Movie Clip instances with this event handler defined receive this event. Combined with the hitTest() method, this event can be used to detect mouse movements over Movie Clip instances.

onClipEvent(mouseMove){
 var myX = _root._xmouse;
 var myY = _root._ymouse;
 if(this.hitTest(myX, myY,
true) == true){
 trace("Mouse move over
MC.");
 }
}

OR

mcHolder.onMouseMove =
function(){
 var myX:Number  =
 _root._xmouse;
 var myY:Number=
 _root._ymouse;
  if(this.hitTest(myX, myY,
 true)){
  trace("Mouse move over " +
 this._name);
  }
  updateAfterEvent();
  };

mouseDown

onMouseDown

This event occurs each time the left mouse button is pressed (or down) anywhere on the Stage. All Movie Clip instances with this event handler receive this event.

onClipEvent(mouseDown){
 myX = _root._xmouse;
 myY = _root._ymouse;
 if(this.hitTest(myX, myY,
true)){
 trace("Mouse press on
MC.");
 }
}

OR

mcHolder.onMouseDown =
function(){
var myX:Number =
_root._xmouse;
var myY:Number =
_root._ymouse;
 if(this.hitTest(myX, myY,
true)){
 trace("Mouse press on " +
this._name);
 }
};

mouseUp

onMouseUp

This event is triggered each time the left mouse button is released (when the user lets up on the mouse button). All Movie Clip instances with this handler receive this event.

onClipEvent(mouseUp){
 myX = _root._xmouse;
 myY = _root._ymouse;
 if(this.hitTest(myX, myY,
true)){
 trace("Mouse release on
MC.");
 }
}

OR

mcHolder.onMouseUp=
function(){
var myX:Number =
_root._xmouse;
var myY:Number =
_root._ymouse;
if(this.hitTest(myX, myY,
true)){
 trace("Mouse release on "
+ this._name);
 }
};

keyDown

onKeyDown

This event occurs when the user presses a key. Combined with the Key.getCode method, you can use this event handler to detect unique key presses.

Note: It's better to use Key.addListener() with a listener object to detect key down events.

onClipEvent(keyDown){
 newKey = Key.getCode();
 myKey = Key.UP;
 if(newKey == myKey){
 trace("UP arrow is
pressed.");
 }
}

keyUp

onKeyUp

This event happens when the user releases a key (when the finger leaves the key). It provides the same functionality as the keyDown event.

Note: It's preferable to use Key.addListener() with a listener object to detect key down events. We discuss this advanced use of the Key class in the Flash ActionScript Bible series by Robert Reinhardt and Joey Lott (Wiley).

onClipEvent(keyUp){
 newKey = Key.getCode();
 myKey = Key.LEFT;
 if(newKey == myKey){
 trace("LEFT arrow
released.");
 }
}

External Input

data

onData

This event is triggered when (A) the loadMovie action retrieves an external Flash movie file (.swf) and puts it in a Movie Clip target, or (B) the data from a file or script with the loadVariables action (targeted at a Movie Clip instance) is finished loading.

Note: If you're building Flash Player 6 or higher movies, use the LoadVars class to load URL-encoded variables into a Flash movie. Learn more about the LoadVars class in Chapter 30, "Sending Data In and Out of Flash."

onClipEvent(data){
trace("New data
received.");
}

OR

mcHolder.onData =
function(){
trace("New data
received.");
}