Attaching Movie Clips

When you start building Flash applications it is most common to initially add all movie clips to the stage at authoring time by dragging instances of symbols from the library to the stage. That method is appropriate in many cases. However, there are many cases when it is more appropriate, and perhaps even necessary, to add movie clips programmatically. For example, you might want to build a game such as Tetris. When building something that is interactive and dynamic, such as a game like Tetris, it would be nearly impossible to add all the necessary movie clips to the stage at authoring time. Instead, it's necessary to add the movie clips (the tetragram game pieces) to the stage at runtime using ActionScript. The new movie clips can thus get added in a manner that is dynamic and dependent upon the user or completely random.

The MovieClip class defines a method called attachMovie() that enables you to programmatically add new movie clip instances to the stage at runtime. However, for attachMovie() to work you must notify Flash which symbol or symbols you want to be able to add programmatically. You can accomplish it by applying linkage settings to the symbol.

You can apply linkage settings by way of the Linkage Properties dialog box. You can open the Linkage Properties dialog box by selecting the symbol in the library and selecting Linkage from the context menu or from the library menu. By default, the Linkage Properties dialog box has no selected options. If you want to enable a movie clip symbol so that you can attach an instance programmatically you must select the Export For ActionScript option. When you select the Export For ActionScript option, Flash automatically selects the Export In First Frame option as well. You can generally let Flash apply that setting. After you select the Export For ActionScript option, the Linkage identifier field is enabled. The default value is the symbol name, which is generally okay. There is no requirement that the linkage identifier be the same as the symbol name. However, generally it's most appropriate to use the same value. The only time that's not appropriate is when you're already exporting a movie clip in the same library with the same linkage identifier. Every linkage identifier must be unique within a library.

After you apply the Export For ActionScript option to a movie clip symbol you can use the attachMovie() method to add an instance of the symbol programmatically. The attachMovie() method adds a new instance of the specified symbol as a nested movie clip of the object from which the method is called. For example, if you called attachMovie() from exampleClip, the new movie clip is a nested instance within exampleClip.

The attachMovie() method requires three parameters:

• Linkage identifierThe linkage identifier of the symbol you want to attach

• New instance nameThe name you want to assign to the new movie clip instance

• DepthAn integer specifying the z-index of the new object

Depth is an important concept that applies to every MovieClip, Button, TextField, Video, and BitmapData object. An object's depth specifies the stacking order along the z-axis. Depths are always integers, and the higher the number, the nearer the object appears. For example, an object with a depth of 2 appears in front of an object with a depth of 1. Every movie clip has its own set of depths. For example, if aClip is at depth 1 and bClip is at depth 2 (both on the main Timeline), the contents of bClip always appear in front of aClip, regardless of the depths of the contents of each.

Typically, programmatic depths ought to start with 1 and increment from there. Negative depths are permissible, but they are generally reserved for authoring time instances. Only one object can exist per depth. If you add an object to a depth already occupied by an existing object, the new object overwrites the old. If you want to add new objects to the stage without deleting existing objects, you must use unique depths. You can write custom code to keep track of the depths used by existing objects. However, the simplest way to ensure that you are using a unique depth is to use the getNextHighestDepth() method of the MovieClip class. The getNextHighestDepth() method returns the next unoccupied depth within the movie clip from which it is called. The following code illustrates how you can use attachMovie() and getNextHighestDepth() to add a new movie clip instance. The following code assumes that there is a movie clip symbol that is set to export with a linkage identifier of Example.

   this.attachMovie("Example", "exampleClip", ¬      this.getNextHighestDepth());

The attachMovie() method returns a reference to the new movie clip. That is particularly useful when adding new movie clip instances with dynamic instance names. For example, the following code adds 10 new instances of Example, each with an instance name that is dynamically determined using the index variable from the for statement:

   for(var i:Number = 0; i < 10; i++) {      this.attachMovie("Example", "exampleClip" + i, ¬        this.getNextHighestDepth());    }

That code works well until you want to reference the new movie clip. For example, you might want to add an onPress() method to the new instances as soon as they are added. If you assign the new movie clip reference to a variable, the task becomes much easier:

   var newClip:MovieClip;    for(var i:Number = 0; i < 10; i++) {      newClip = this.attachMovie("Example", exampleClip", + i, ¬        this.getNextHighestDepth());      newClip.onPress = function():Void {        trace(this);      };    }

When you call the attachMovie() method you also have the option of passing it a fourth parameter that acts as an initialization object. The initialization object is an object with properties corresponding to any valid properties of the new instance. When the new instance is attached, those properties are automatically set. For example, you can use the initialization object to assign values to the _x and _y properties, as the following example illustrates:

   this.attachMovie("Example", "exampleClip", this.getNextHighestDepth(),¬      {_x: 100, _y: 400});

In this next task you'll start to build a memory game. The first step is simply to add movie clips to the stage with the attachMovie() method.

1.	Open memory1.fla from the Lesson08/Start directory. The Flash document contains all the elements to build the memory game. The library contains two folders, one of which (MovieClips) has six movie clips that you can attach with attachMovie(). You'll add two instances of each movie clip in a random order.
2.	For each movie clip symbol in the MovieClips folder in the library, set the symbol to export for ActionScript with the default linkage identifier. To add instances of the movie clips they must be set to export for ActionScript.
3.	Select the first keyframe of the main Timeline, and open the Actions panel. Then add the following code that defines an array of linkage identifiers: var linkageArr:Array = ["A", "B", "C", "D", "E", "F", "A", "B", "C",¬ "D", "E", "F"]; The linkageArr array has elements that correspond to each of the movie clip symbols' linkage identifiers. There are two elements for each linkage identifier because you'll want to add two instances of each symbol.
4.	Next, add the following code to sort the array: linkageArr.sort(sort); function sort(a:Object, b:Object):Number { return (Math.random() < .5) ? -1 : 1; } It's necessary to sort the array in a random order so that the cards are in a different order each time. The sort() method allows you to specify a sorting function, which is automatically passed two parameters representing two elements of the array to compare. In this case you want to sort in a random order. Therefore, the sorting function returns either 1 or -1 randomly.
5.	Define an initialize() function that adds the movie clip instances to the stage. Then call the initialize() function. initialize(); function initialize():Void { var depth:Number; var clip:MovieClip; var x:Number = 10; var y:Number = 10; for(var i:Number = 0; i < linkageArr.length; i++) { depth = this.getNextHighestDepth(); clip = this.attachMovie(linkageArr[i], "clip" + depth, ¬ depth, {_x: x, _y: y}); if((i + 1) % 3 != 0) { x += clip._width + 5; } else { x = 10; y += clip._height + 5; } } } The initialize() function loops through each element of the linkageArr array, and it adds a new movie clip instance based on the current element. It uses an initialization object to set the _x and _y properties of the movie clip, and then updates the values of the x and y variables so that the movie clips are arranged in a grid.
6.	Test the movie. When you test the movie you ought to see a grid of movie clips. Each time you test the movie, the movie clips are in a different random order.