| duplicateMovieClip( ) Global Function | Flash 4 |
| create a copy of a movie clip |
A string indicating the path to the movie clip to duplicate (known as the seed clip). Nested clips can be referred to with dot syntax, as in duplicateMovieClip ("_root.myClip", "myClip2", 0). Because a movie clip reference is converted to a path when used in a string context, target can also be a movie clip object reference, as in duplicateMovieClip(_root.myClip, "myClip2", 0).
A string that becomes the instance name of the duplicated clip. The string used must adhere to the rules for creating an identifier outlined in Section 15.5 in Chapter 15.
An integer, between -16384 and 1048575 (inclusive), specifying the depth on which to place the duplicated clip inside target's parent. 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 duplicateMovieClip( ). However, when creating dynamic content that you want to appear beneath all author-time content in target (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 duplicateMovieClip( ). For important details, see Section 13.4.
The global duplicateMovieClip( ) function is one way to create a new movie clip during movie playback—others are MovieClip.attachMovie( ), MovieClip.createEmptyMovieClip( ), and MovieClip.duplicateMovieClip( ). The duplicateMovieClip( ) function creates an identical copy of target and places the copy in target's parent's clip stack on layer depth. The duplicated clip begins playing at frame 1, no matter which frame target is at when duplication occurs.
A duplicated clip inherits any transformations (rotation, scale, etc.) that had been applied to target, but it does not inherit the timeline variables of target. Callback functions assigned to target's event handler properties (e.g., onEnterFrame( )) are not copied to the duplicated clip. However, Flash 5-style onClipEvent( ) handlers are copied to the duplicate. The global duplicateMovieClip( ) function is also available as a movie clip method, though when used in that form, the target argument is not used.
To delete a duplicated clip, use removeMovieClip( ) (see the global removeMovieClip( ) function description for more important details).
The global form of duplicateMovieClip( ) lacks the following abilities added to MovieClip.duplicateMovieClip( ) in Flash 6:
The global form does not include support for the initObject parameter (used to initialize properties of the newly created clip).
The global form does not return a reference to the duplicated clip.
// Copy the ball_mc clip and name the copy ball2_mc duplicateMovieClip(ball_mc, "ball2_mc", 0); // Move the new ball2_mc clip over so we can see it ball2_mc._x += 100;
MovieClip.duplicateMovieClip( ), removeMovieClip( ); "Creating instances with duplicateMovieClip( )," "How clips generated via duplicateMovieClip( ) are added to the stack," and "Method versus global function overlap issues," in Chapter 13