Recipe 11.9. Creating New Movie Clips Based on Existing Movie Clips

Problem

You want to create a duplicate movie clip instance based on an existing instance.

Solution

Use the duplicateMovieClip( ) method.

Discussion

With the duplicateMovieClip( ) method, you can quickly create duplicates of movie clip instances already on the stage. This method creates a copy of the movie clip instance from which it is invoked with a new instance name (exp 3pod.com) and depth:

	// Create a new movie clip named mNewInstance based on the movie clip named
	// originalInstance that already existed on the stage. The new movie clip is
	// created at depth 1.
	mOriginalInstance.duplicateMovieClip("mNewInstance", 1);

Make sure that you use a unique depth for the new movie clip. If you use a depth that corresponds to an existing instance, that existing instance will be overwritten.

Additionally, you can specify a third, optional parameter for the duplicateMovieClip( ) method. This parameter is known as the initialization object, and the properties and values of the initialization object are assigned to the new instance. The parameter value should be in the form of an ActionScript Object object, which you can create one of two ways:

• Using the constructor and assigning properties and values via dot notation:

  	var oInitialization:Object = new Object();
  	oInitialization.property1 = "value1";
  	oInitialization. property2 = "value2;
  

  
  

• Using the object literal notation:

  	var oInitialization:Object = { property1: "value1", property2: "value2"};
  

  
  

Both of these techniques are absolutely valid, and neither is better than the other. Sometimes you may find that you want to use the object literal notation, because it allows you to create the object in line with the duplicateMovieClip( ) method:

	mOriginalInstance.duplicateMovieClip("mNewInstance", 1, { property1: "valeu1", 
	property2: "value2"});

However, in other cases, the object literal notation is either inconvenient or impossible. Generally, the more properties you want to assign to an object, the more it makes sense to use the constructor technique, because it offers a much more readable format.

	var oInitialization:Object = new Object();
	oInitialization. property1 = "value1";
	oInitialization. property2 = "value2";
	mOriginalInstance.duplicateMovieClip("mNewInstance", 1, oInitialization);

The initialization object, or init object, can be extremely useful in at least two ways:

• You can use the initialization object to initialize the new instance with its own values for built-in movie clip properties, such as _x, _y, _rotation, and so on. By default, the duplicate retains the values for these properties from the original movie clip.

  	// Create a duplicate movie clip positioned at 300,300. 
  	mOriginalInstance.duplicateMovieClip("mNewInstance", 1, {_x: 300, _y: 300});
  

  
  

• You can use the init object to initialize a new instance with copies of the custom method definitions (such as event handler methods) of the original movie clip. By default, custom method definitions are not copied from the original to the duplicate movie clip. However, you can use a for… in loop to populate an initialization object with all the custom properties and methods of the original movie clip, and then pass that initialization object to the duplicateMovieClip( ) method:

  	// Create the init object.
  	var oInitialization:Object = new Object();
  
  	// Use a for…in loop to loop through all the custom properties and methods of 
  	// the original movie clip instance, and add them to the init object. 
  	for(var sItem:String in mOriginalInstance) {
  	  oInitialization [sItem] = mOriginalInstance[sItem];
  	}
  
  	mOriginalInstance.duplicateMovieClip("mNewInstance", 1, oInitialization); 
  

  
  

You can use a for statement to create multiple duplicates at the same time. The basic syntax is as follows:

	for(var i:Number = 0; i < numberOfDuplicates; i++) {
	  originalInstance.duplicateMovieClip (newInstancename, depth);
	}

When you create the new movie clips, make sure each has a unique instance name (exp 3pod.com) and a unique depth. Typically, you can generate unique instance names by concatenating the for statement's index variable value with a base name (exp 3pod.com). For example, you might use a base name (exp 3pod.com) of mSquare and concatenate that with the value of the for statement's index variable to get instance names of mSquare0, mSquare1, mSquare2, and so on. Then, for the depth, you can either use the value of the for statement's index variable or you can use the getNextHighestDepth( ) method that is discussed in Recipe 11.10. The following example creates five duplicates with instance names mSquare0 through mSquare4:

	for(var i:Number = 0; i < 5; i++) {
	  mSquare.duplicateMovieClip("mSquare" + i, i);
	}

When you generate duplicate movie clips in batches as shown in the preceding code, you may notice that you don't have a very convenient way to refer to the new instances. When you create a single duplicate with a specific name (exp 3pod.com), you can refer to the new movie clip quite simply. For example, the following code creates a duplicate of mCircle with an instance name (exp 3pod.com) of mNewCircle. Then it applies an onPress( ) event handler method to the new movie clip.

	mCircle.duplicateMovieClip("mNewCircle", 1, {_x: 100, _y: 100}); 
	mNewCircle.onPress = function():Void { 
	  trace("You clicked on mNewCircle."); 
	}; 

However, when you use a for statement to create the duplicates with dynamic instance names, you need a different way to refer to the new movie clips. For example, if you are creating duplicate movie clips with instance names mSquare0, mSquare1, mSquare2, and so on, you cannot use the following code to assign an onPress( ) event handler method to them after you've created them:

	for(var i:Number = 0; i < 5; i++) {
	  mSquare.duplicateMovieClip("mSquare" + i, i);

	  // This code will not work.
	  "mSquare" + i.onPress = function():Void {
	    trace("You clicked on a duplicated square.");
	  };
	}

Fortunately, the duplicateMovieClip( ) method returns a valuea reference to the movie clip it just created. You can assign that value to a variable and then reference the movie clip by way of the variable. The following example code will work:

	// Declare a variable to use in order to reference the duplicate movie clips. 
	var mDuplicate:MovieClip;

	for(var i:Number = 0; i < 5; i++) { 
	  // When you duplicate the movie clip, assign the return value from the method to 
	the mDuplicate
	  // variable.
	  mDuplicate = mSquare.duplicateMovieClip("mSquare" + i, i);

	  // Reference the new movie clip by way of the mDuplicate variable.
	  mDuplicate.onPress = function():Void {
	    trace("You clicked on a duplicated square.");
	  };
	}