MovieClip.beginGradientFill() 501
Returns
Nothing.
Description
Method; indicates the beginning of a new drawing path. If the first parameter is
undefined,
or if
no parameters are passed, the path has no fill. If an open path exists (that is if the current drawing
position does not equal the previous position specified in a
MovieClip.moveTo()
method), and
it has a fill associated with it, that path is closed with a line and then filled. This is similar to what
happens when you call
MovieClip.endFill()
.
This method fails if any of the following conditions exist:
•
The number of items in the
colors
,
alphas
, and
ratios
parameters are not equal.
•
The
fillType
parameter is not
"linear"
or
"radial"

lineTo(100, 310);
502 Chapter 2: ActionScript Language Reference
endFill();
}
See also
MovieClip.beginFill(), MovieClip.endFill(), MovieClip.lineStyle(),
MovieClip.lineTo(), MovieClip.moveTo()
MovieClip.clear() 503
MovieClip.clear()
Availability
Flash Player 6.
Usage
my_mc.clear() : Void
Parameters
None.
Returns
Nothing.
Description
Method; removes all the graphics created during runtime using the movie clip draw methods,
including line styles specified with
MovieClip.lineStyle()
. Shapes and lines that are manually
drawn during authoring time (with the Flash drawing tools) are unaffected.
Example
The following example draws a box on the Stage. When the user clicks the box graphic, it removes
the graphic from the Stage.
this.createEmptyMovieClip("box_mc", this.getNextHighestDepth());
box_mc.onRelease = function() {
this.clear();
};

Returns
A reference to the newly created movie clip.
Description
Method; creates an empty movie clip as a child of an existing movie clip. This method behaves
similarly to the
attachMovie()
method, but you don’t need to provide an external linkage
identifier for the new movie clip. The registration point for a newly created empty movie clip is
the upper left corner. This method fails if any of the parameters are missing.
You can extend the methods and event handlers of the MovieClip class by creating a subclass. For
more information, see “Assigning a class to a movie clip symbol” in Using ActionScript in Flash.
Example
The following ActionScript creates a new movie clip at runtime and loads a JPEG image into the
movie clip.
this.createEmptyMovieClip("logo_mc", this.getNextHighestDepth());
logo_mc.loadMovie("http://www.macromedia.com/images/shared/product_boxes/
80x92/studio_flashpro.jpg");
See also
MovieClip.attachMovie()
MovieClip.createTextField() 505
MovieClip.createTextField()
Availability
Flash Player 6.
Usage
my_mc.createTextField(instanceName:String,

depth:Number,

x:Number,


contain only one object. If you create a new text field on a depth that already has a text field, the
new text field will replace the existing text field. To avoid overwriting existing text fields, use the
MovieClip.getInstanceAtDepth()
to determine whether a specific depth is already occupied,
or
MovieClip.getNextHighestDepth()
, to determine the highest unoccupied depth. The text
field is positioned at (
x
,
y
) with dimensions
width
by
height
. The
x
and
y
parameters are relative
to the container movie clip; these parameters correspond to the
_x
and
_y
properties of the text
field. The
width
and
height
parameters correspond to the

italic = false
underline = false
url = ""
target = ""
align = "left"
leftMargin = 0
rightMargin = 0
indent = 0
leading = 0
blockIndent = 0
bullet = false
display = block
tabStops = [] (empty array)
You can extend the methods and event handlers of the MovieClip class by creating a subclass. For
more information, see “Assigning a class to a movie clip symbol” in Using ActionScript in Flash.
Example
The following example creates a text field with a width of 300, a height of 100, an x coordinate of
100, a y coordinate of 100, no border, red, and underlined text:
this.createTextField("my_txt", 1, 100, 100, 300, 100);
my_txt.multiline = true;
my_txt.wordWrap = true;
var my_fmt:TextFormat = new TextFormat();
my_fmt.color = 0xFF0000;
my_fmt.underline = true;
my_txt.text = "This is my first test field object text.";
my_txt.setTextFormat(my_fmt);
An example is also in the animations.fla file in the HelpExamples folder. The following list gives
typical paths to this folder:
•
Windows: \Program Files\Macromedia\Flash MX 2004\HelpExamples\


anchorX:Number, anchorY:Number)
: Void
Parameters
controlX
An integer that specifies the horizontal position of the control point relative to the
registration point of the parent movie clip.
controlY
An integer that specifies the vertical position of the control point relative to the
registration point of the parent movie clip.
anchorX
An integer that specifies the horizontal position of the next anchor point relative to the
registration. point of the parent movie clip.
anchorY
An integer that specifies the vertical position of the next anchor point relative to the
registration point of the parent movie clip.
Returns
Nothing.
Description
Method; draws a curve using the current line style from the current drawing position to
(
anchorX
,
anchorY
) using the control point specified by (
controlX
,
controlY
). The current
drawing position is then set to (

The curve drawn in this example is a quadratic bezier curve. Quadratic bezier curves consist of
two anchor points and a control point. The curve interpolates the two anchor points, and curves
toward the control point.
The following ActionScript creates a circle using
MovieClip.curveTo()
and the Math class:
this.createEmptyMovieClip("circle2_mc", 2);
circle2_mc.lineStyle(0, 0x000000);
drawCircle(circle2_mc, 10, 10, 100);
function drawCircle(mc:MovieClip, x:Number, y:Number, r:Number):Void {
mc.moveTo(x+r, y);
mc.curveTo(r+x, Math.tan(Math.PI/8)*r+y, Math.sin(Math.PI/4)*r+x,
Math.sin(Math.PI/4)*r+y);
mc.curveTo(Math.tan(Math.PI/8)*r+x, r+y, x, r+y);
mc.curveTo(-Math.tan(Math.PI/8)*r+x, r+y, -Math.sin(Math.PI/4)*r+x,
Math.sin(Math.PI/4)*r+y);
mc.curveTo(-r+x, Math.tan(Math.PI/8)*r+y, -r+x, y);
mc.curveTo(-r+x, -Math.tan(Math.PI/8)*r+y, -Math.sin(Math.PI/4)*r+x, -
Math.sin(Math.PI/4)*r+y);
mc.curveTo(-Math.tan(Math.PI/8)*r+x, -r+y, x, -r+y);
mc.curveTo(Math.tan(Math.PI/8)*r+x, -r+y, Math.sin(Math.PI/4)*r+x, -
Math.sin(Math.PI/4)*r+y);
mc.curveTo(r+x, -Math.tan(Math.PI/8)*r+y, r+x, y);
}
An example is also in the drawingapi.fla file in the HelpExamples folder. The following list gives
typical paths to this folder:
•
Windows: \Program Files\Macromedia\Flash MX 2004\Samples\HelpExamples\
•
Macintosh: HD/Applications/Macromedia Flash MX 2004/Samples/HelpExamples/

garbage_mc
movie clip
instance and uses
eval()
to convert it from slash syntax to a dot syntax reference. The
garbage_mc
reference is then compared to the reference to the
trashcan_mc
movie clip instance.
If the two references are equivalent, the visibility of
garbage_mc
is set to
false
. If they are not
equivalent, the
garbage
instance resets to its original position.
origX = garbage_mc._x;
origY = garbage_mc._y;
garbage_mc.onPress = function() {
this.startDrag();
};
garbage_mc.onRelease = function() {
this.stopDrag();
if (eval(this._droptarget) == trashcan_mc) {
this._visible = false;
} else {
this._x = origX;
this._y = origY;
}

movie clips always start playing at Frame 1, no matter what frame the original movie clip is on
when the
duplicateMovieClip()
method is called. Variables in the parent movie clip are not
copied into the duplicate movie clip. Movie clips that have been created using
duplicateMovieClip()
are not duplicated if you call
duplicateMovieClip()
on their parent.
If the parent movie clip is deleted, the duplicate movie clip is also deleted. If you have loaded a
movie clip using
MovieClip.loadMovie()
or the MovieClipLoader class, the contents of the
SWF file are not duplicated. This means that you cannot save bandwidth by loading a JPEG or
SWF file and then duplicating the movie clip.
Example
The following example duplicates the
circle_mc
movie clip. The code creates the movie clip,
called
circle1_mc
, at the x, y coordinates 20,20.
circle_mc.duplicateMovieClip("circle1_mc", this.getNextHighestDepth(), {_x:20,
_y:20});
See also
duplicateMovieClip(), MovieClip.removeMovieClip()
512 Chapter 2: ActionScript Language Reference
MovieClip.enabled
Availability
Flash Player 6.

property only governs the button-like properties of a movie clip. You can change
the
enabled
property at any time; the modified movie clip is immediately enabled or disabled.
The
enabled
property can be read out of a prototype object. If
enabled
is set to
false
, the
object is not included in automatic tab ordering.
Example
The following example disables the
circle_mc
movie clip when the user clicks it.
circle_mc.onRelease = function() {
trace("disabling the "+this._name+" movie clip.");
this.enabled = false;
};
MovieClip.endFill() 513
MovieClip.endFill()
Availability
Flash Player 6.
Usage
my_mc.endFill() : Void
Parameters
None.
Returns
Nothing.

See Also
MovieClip.beginFill(), MovieClip.beginGradientFill(), MovieClip.moveTo()
514 Chapter 2: ActionScript Language Reference
MovieClip.focusEnabled
Availability
Flash Player 6.
Usage
my_mc.focusEnabled:Boolean
Description
Property; if the value is
undefined
or
false
, a movie clip cannot receive input focus unless it is a
button. If the
focusEnabled
property value is
true
, a movie clip can receive input focus even if it
is not a button.
Example
The following example sets the
focusEnabled
property for the movie clip
my_mc
to
false
:
my_mc.focusEnabled = false;
MovieClip._focusrect 515

property controls the global
_focusrect
property. It is a Boolean value. This behavior was changed in Flash Player 6 and later
to permit the customization of
_focusrect
on an individual movie clip basis.
Example
This example demonstrates how to hide the yellow rectangle around a specified movie clip
instance in a SWF file when it has focus in a browser window. Create three movie clips called
mc1_mc
,
mc2_mc
, and
mc3_mc
, and add the following ActionScript in Frame 1 of the Timeline:
mc1_mc._focusrect = true;
mc2_mc._focusrect = false;
mc3_mc._focusrect = true;
mc1_mc.onRelease = traceOnRelease;
mc3_mc.onRelease = traceOnRelease;
function traceOnRelease() {
trace(this._name);
}
Test the SWF file in a browser window by selecting File > Publish Preview > HTML. Give the
SWF focus by clicking it in the browser window, and press Tab to focus each instance. You will
not be able to execute code for this movie clip in the browser by pressing Enter or the Spacebar
when
_focusrect
is disabled.
Additionally, you can test your SWF file in the test environment. Select Control > Disable

bar_mc._xscale = pctLoaded;
Add the following code to Frame 2:
if (this._framesloaded<this._totalframes) {
this.gotoAndPlay(1);
} else {
this.gotoAndStop(3);
}
Place your content on or after Frame 3. Then add the following code to Frame 3:
stop();
See also
MovieClipLoader class
MovieClip.getBounds() 517
MovieClip.getBounds()
Availability
Flash Player 5.
Usage
my_mc.getBounds(targetCoordinateSpace:Object) : Object
Parameters
targetCoordinateSpace
The target path of the Timeline whose coordinate system you want
to use as a reference point.
Returns
An object with the properties
xMin
,
xMax
,
yMin
, and
yMax.

square_mc.lineTo(0, 100);
square_mc.lineTo(0, 0);
square_mc.endFill();
var bounds_obj:Object = square_mc.getBounds(this);
for (var i in bounds_obj) {
trace(i+" --> "+bounds_obj[i]);
}
The following information displays in the Output panel:
yMax --> 110
yMin --> 10
xMax --> 110
xMin --> 10
518 Chapter 2: ActionScript Language Reference
See also
MovieClip.globalToLocal(), MovieClip.localToGlobal()
MovieClip.getBytesLoaded() 519
MovieClip.getBytesLoaded()
Availability
Flash Player 5.
Usage
my_mc.getBytesLoaded() : Number
Parameters
None.
Returns
An integer indicating the number of bytes loaded.
Description
Method; returns the number of bytes that have already loaded (streamed) for the movie clip
specified by
my_mc
. You can compare this value with the value returned by

Availability
Flash Player 5.
Usage
my_mc.getBytesTotal() : Number
Parameters
None.
Returns
An integer indicating the total size, in bytes, of
my_mc
.
Description
Method; returns the size, in bytes, of the movie clip specified by
my_mc
. For movie clips that are
external (the root SWF file or a movie clip that is being loaded into a target or a level), the return
value is the size of the SWF file.
You can extend the methods and event handlers of the MovieClip class by creating a subclass. For
more information, see “Assigning a class to a movie clip symbol” in Using ActionScript in Flash.
Example
The following example uses the
_framesloaded
property to start a SWF file when all the frames
are loaded. If all the frames aren’t loaded, the
_xscale
property of the movie clip instance
loader

is increased proportionally to create a progress bar.
Enter the following ActionScript in Frame 1 of the Timeline:
var pctLoaded:Number = Math.round(this.getBytesLoaded()/

if (typeof (this[i]) == "movieclip") {
trace("movie clip '"+this[i]._name+"' is at depth "+this[i].getDepth());
}
}
See also
MovieClip.getInstanceAtDepth(), MovieClip.getNextHighestDepth(),
MovieClip.swapDepths()
522 Chapter 2: ActionScript Language Reference
MovieClip.getInstanceAtDepth()
Availability
Flash Player 7.
Usage
my_mc.getInstanceAtDepth(depth:Number) : MovieClip
Parameters
depth
An integer that specifies the depth level to query.
Returns
A reference to the MovieClip instance located at the specified depth, or
undefined
if there is no
movie clip at that depth.
Description
Method; lets you determine if a particular depth is already occupied by a movie clip. You can use
this method before using
MovieClip.attachMovie()
,
MovieClip.duplicateMovieClip()
, or
MovieClip.createEmptyMovieClip()
to determine if the depth parameter you want to pass to

MovieClip.attachMovie()
,
MovieClip.duplicateMovieClip()
, or
MovieClip.createEmptyMovieClip()
to ensure that
Flash renders the movie clip in front of all other objects on the same level and layer in the current
movie clip. The value returned is 0 or higher (that is, negative numbers are not returned).
For more information, see “Managing movie clip depths” in Using ActionScript in Flash.
You can extend the methods and event handlers of the MovieClip class by creating a subclass. For
more information, see “Assigning a class to a movie clip symbol” in Using ActionScript in Flash.
Example
The following example creates a new movie clip instance,
logo_mc
, at the next highest depth
available. At runtime,
logo_mc
renders in front of all other instances at the same level.
this.createEmptyMovieClip("logo_mc", this.getNextHighestDepth());
var logo_mcl:MovieClipLoader = new MovieClipLoader();
var mclListener:Object = new Object();
mclListener.onLoadInit = function(target_mc:MovieClip) {
target_mc.onPress = function() {
this.startDrag();
};
target_mc.onRelease = function() {
this.stopDrag();
};
};
logo_mcl.addListener(mclListener);

that loads into a movie clip instance called
fp6_mc
.
trace(this.getSWFVersion()); // output: 7
fp6_mc.loadMovie("flashplayer6.swf");
my_btn.onRelease = function(){
trace("Loaded Flash Player " + fp6_mc.getSWFVersion() + " file.");
//output: Loaded Flash Player 6 file.
};
MovieClip.getTextSnapshot() 525
MovieClip.getTextSnapshot()
Availability
Authoring: Flash MX 2004.
Playback: SWF files published for Flash Player 6 or later, playing in Flash Player 7 or later.
Usage
my_mc.getTextSnapshot() : TextSnapshot
Parameters
None.
Returns
A TextSnapshot object that contains the static text from
my_mc
.
Description
Method; returns a TextSnapshot object that contains the text in all the static text fields in the
specified movie clip; text in child movie clips is not included. This method always returns a
TextSnapshot object.
Flash concatenates text and places it in the TextSnapshot object in an order that reflects the tab
index order of the static text fields in the movie clip. Text fields that don’t have tab index values
are placed in a random order in the object, and precede any text from fields that do have tab index
values. No line breaks or formatting indicates where one field ends and the next begins.