Recipe 11.17. Adding Movie Clips at Runtime

Problem

You want to be able to add movie clips to your movie at runtime.

Solution

Set the movie clip symbol to export, and use attachMovie( ) to add the instance to the movie.

Discussion

You can add movie clips to your Flash movie at runtime using ActionScript. Previously, you read about how to use duplicateMovieClip( ) to create duplicates of an existing movie clip. However, you can actually add new instances to the stage using ActionScript without even having any prior instances that you created during authoring time. This is a really powerful technique, because it allows you to construct your Flash movies almost entirely with ActionScript.

In order to add movie clip instances to the stage at runtime without any previous instances, you need to do two things:

1. Export the movie clip symbol. Flash does not include all symbols from your library in the exported SWF. In order to ensure the smallest file size, Flash exports only those symbols that are used in the movie. Therefore, if you don't create any authoring time instances of a movie clip symbol, Flash will not export it in the final SWF unless you tell it to do so. You can tell it to do this by using the Linkage settings from the library:

   1. Open the library by choosing Window Library or by pressing Ctrl-L.

   2. In the Linkage Properties dialog box that displays, check Export for ActionScript and Export in First Frame.

   3. When you check Export for ActionScript, the Identifier field will become enabled. Flash automatically fills the field with the same name as the library symbol.

   4. Click OK.

2. Within your ActionScript code, at the point at which you want the new movie clip instance to be created, add a call to attachMovie( ). The attachMovie( ) method creates a new movie clip instance nested within the movie clip from which it is called. The method requires at least three parameters: the name of the symbol's linkage identifier, the name of the new movie clip instance to create, and a depth at which to create the new movie clip. The first two parameters should be strings, and the third parameter should be numeric.

The following creates a new movie clip instance named mCircle. The instance is based on the symbol in the library with a linkage identifier of Circle. With the assumption that you place the code on a keyframe on the main timeline, mCircle will be created within the main timeline.

 this.attachMovie("Circle", "mCircle", 1); 

The preceding code creates mCircle with a depth of 1. You can use the getNextHighestDepth( ) method to get a valid depth without having to hardcode a value.

 this.attachMovie("Circle", "mCircle", this.getNextHighestDepth()); 

You can read more about depths in Recipe 11.9. You can read more about the getNextHighestDepth( ) method in Recipe 11.10.

Most of the concepts that apply to duplicating movie clips also apply to attaching movie clips. Refer to Recipe 11.9 for more details.