Recipe 7.11 Getting Unique Depths

7.11.1 Problem

You want to easily ensure that you always get a unique depth when creating a new movie clip using createEmptyMovieClip( ), attachMovie( ), or duplicateMovieClip( ).

7.11.2 Solution

Create and use a custom MovieClip.getNewDepth( ) method.

7.11.3 Discussion

Only one movie clip can exist at each depth within a parent clip, so if you specify an existing depth when using createEmptyMovieClip( ), attachMovie( ), or duplicateMovieClip( ), the movie clip already on that depth is overwritten. Unless you want to overwrite an existing movie clip, you must always use a unique depth when using these methods.

ActionScript does not provide native support for generating a unique movie clip depth. You must keep track of all the used depths yourself. When you add only a few movie clips programmatically, this does not pose a problem; however, if you programmatically generate many movie clips, it becomes difficult to track which depths are already used. Fortunately, you can solve this problem easily with a few lines of code.

You can add a getNewDepth( ) method to the MovieClip class so that every movie clip inherits it, as shown in the following code block. The process is not complex. If the movie clip does not yet have a custom currentDepth property defined, we define it and initialize it to the value of 1. The value 1 is used because that is the first depth you want to assign to any programmatically generated nested movie clip in most cases. Once the method ensures that the currentDepth property exists, it returns that property's value and increments it by 1 so that the next time the method is called, a new depth value is returned.

MovieClip.prototype.getNewDepth = function (  ) {
  // If no currentDepth is defined, initialize it to 1.
  if (this.currentDepth == undefined) {
    this.currentDepth = 1;
  }
  // Return the new depth and increment it by 1 for next time.
  return this.currentDepth++;
};

Here is an example of the getNewDepth( ) method being used:

// This assumes our custom getNewDepth(  ) method is defined in MovieClip.as.
#include "MovieClip.as"

// Create two new movie clips in _root and assign them unique depths using the
// getNewDepth(  ) method.
_root.createEmptyMovieClip("circle_mc", _root.getNewDepth(  ));
_root.createEmptyMovieClip("square_mc", _root.getNewDepth(  ));

The getNewDepth( ) method defaults the currentDepth property to a value of 1 when it is initialized. There are some cases in which you want to use depths starting below 1. For example, movie clips placed on the Stage at authoring time begin with a depth of -16383. You can programmatically create movie clips that appear below manually created movie clips if you assign them a depth less than -16383. You can still use the getNewDepth( ) method in these cases by assigning a value to the movie clip's currentDepth property before invoking getNewDepth( ).

// Include MovieClip.as from this chapter and DrawingMethods.as from Chapter 4.
#include "MovieClip.as"
#include "DrawingMethods.as"

// Set the currentDepth property so that the next programmatically created movie clip
// can be made to appear below any manually created instance.
_root.currentDepth = -16384;

// Create a movie clip using getNewDepth(  ) to retrieve a depth value. The value 
// -16384 is used. Be aware that the value is then incremented to -16383, which is
// the depth of the first manually created instance.
_root.createEmptyMovieClip("circle_mc", _root.getNewDepth(  ));
circle_mc.lineStyle(1, 0x000000, 0);
circle_mc.beginFill(0, 100);
circle_mc.drawCircle(100, 100, 100);
circle_mc.endFill(  );

When you use this technique of setting the currentDepth property, be aware that it can overwrite manually created movie clips if you are not careful. For example, in the preceding code block, the depth of the circle_mc movie clip is -16384. The first manually created movie clip always has a depth of -16383; therefore, if you use getNewDepth( ) again and it assigns a depth of -16383, the new programmatic clip overwrites the first manually created clip in your movie. You can solve this dilemma by again setting the value of currentDepth. For example, the following code block programmatically creates a movie clip below any manually created instances. It then sets the currentDepth to 1 so that future programmatically created instances are placed above all manually created instances.

#include "MovieClip.as"

_root.currentDepth = -16384;
_root.createEmptyMovieClip("circle_mc", _root.getNewDepth(  ));
_root.currentDepth = 1;

7.11.4 See Also

Recipe 7.16