MovieClip.attachMovie( ) Method

	ActionScript for Flash MX: The Definitive Guide, 2nd Edition By Colin Moock

	Chapter 18. ActionScript Language Reference

MovieClip.attachMovie( ) Method

Flash 6

create a new movie clip instance from an exported Library symbolFlash 5; initObject and return value added in

mc.attachMovie(symbolIdentifier, newName, depth) mc.attachMovie(symbolIdentifier, newName, depth, initObject)

Arguments

symbolIdentifier: A string specifying the linkage identifier of an exported movie clip symbol, as set in the Library under Options Linkage.
newName: A string specifying the new instance name of the clip being created. The name must adhere to the rules for creating an identifier, outlined under Section 15.5.
depth: An integer between -16384 and 1048575 (inclusive), specifying the level on which to place the new clip inside mc. Higher depths obscure lower depths, so a depth of 6 is in front of 5, which is in front of 4, and so on. Depths above -1 are reserved for dynamically generated content. Therefore, in most cases, you should use a depth between 0 and 1048575 with attachMovie( ). However, when creating dynamic content that you want to appear beneath all author-time content in mc (e.g., a run-time background), use depth -16384. Depths from -16383 to -1 (inclusive) are reserved for author-time content and shouldn't be used with attachMovie( ). For important details, see Section 13.4.
initObject: An optional object whose properties are copied to the new movie clip instance. Not supported in Flash 5.

Returns

In Flash 6, attachMovie( ) returns an object reference to the attached movie clip, or undefined if creation fails (in Flash 5, it always returns undefined).

Description

The attachMovie( ) method creates a new instance, called newName, based on the exported movie clip symbol specified by symbolIdentifier. If mc is the main movie, the new instance is placed in the top-left corner of the Stage. If mc is a movie clip instance, the new instance is placed at mc's registration point. In either case, the new instance is placed inside mc's visual content stack on the level specified by depth. For example, the following code attaches a movie clip exported from the Library with a linkage identifier of "ball_symbol". It names the new instance tennisBall_mc and places it inside court_mc on depth 1, above all author-time content in court_mc:

court_mc.attachMovie("ball_symbol", "tennisBall_mc", 1);

We can then control the new instance as follows:

// Double the ball's width court_mc.tennisBall_mc._xscale = 200;

As of Flash 6, attachMovie( ) returns a reference to the new instance, so this code can be shortened to:

tBall = court_mc.attachMovie("ball_symbol", "tennisBall_mc", 1); tBall_mc._xscale = 200;

or, even more succinctly (but cryptically):

court_mc.attachMovie("ball_symbol", "tennisBall_mc", 1)._xscale = 200;

To delete an attached instance, use MovieClip.removeMovieClip( ) (see the global removeMovieClip( ) function description for further important details).

In Flash 5, all exported movie clips are loaded before the first frame of the movie, causing a delay before the movie loads. As of Flash 6, exported clips can be loaded on other frames as follows:

In the Library's upper-right corner, select Linkage from the pop-up Options menu.
In the Linkage Properties dialog box, uncheck "Export in first frame," and then choose OK.
On the main timeline, at the frame where the exported clip should load, create a keyframe and place an instance of the clip on it.

A movie clip is not available to attachMovie( ) until the frame at which it is exported.

When the optional initObject parameter is provided, its direct properties (properties attached directly to initObject, not those retrieved via the prototype chain) are copied into the new clip and become immediately accessible. For example:

// Create a generic object to transfer properties to the new tennisBall_mc instance var tempObj = new Object(); // Add a speed property for transfer to tennisBall_mc tempObj.speed = 200; // Pass tempObj to attachMovie() court_mc.attachMovie("ball_symbol", "tennisBall_mc", 1, tempObj); // Check the value of speed on tennisBall_mc trace(court_mc.tennisBall_mc.speed);  // Displays: 200

However, properties inherited through initObject's prototype chain are not copied to the clip. Only direct properties are transferred. To determine whether a property is inherited or direct, use Object.hasOwnProperty( ). Built-in movie clip properties, such as _x and _rotation, and event handlers, such as onEnterFrame( ), can be set (i.e., copied to the newly created movie clip instance) via initObject. For example:

var tempObj = new Object(); // Set _rotation tempObj._rotation = 200; // Assign an onEnterFrame() callback tempObj.onEnterFrame = function () {   this._x++ }; // Once attached, tennisBall_mc will be rotated by 200 degrees and will // start moving one pixel right per frame due to the onEnterFrame() handler court_mc.attachMovie("ball_symbol", "tennisBall_mc", 1, tempObj);

In Flash 6, the initObject parameter is used to set properties in newName that will be used by its class constructor (effectively the same as passing arguments to the constructor). A movie clip symbol's class constructor is defined by the Object.registerClass( ) method. For convenience, initObject can be specified as an anonymous object. For example:

court_mc.attachMovie("ball_symbol", "tennisBall_mc", 1, {speed: 200, _x: 165} );

The initObject parameter is not supported prior to Flash 6.

Arguments

Returns

Description

See Also