Recipe 11.10. Generating Unique Depths

Problem

You want to generate unique depth values so that you don't accidentally overwrite existing content when you use methods such as duplicateMovieClip( ), attachMovie( ), createEmptyMovieClip( ), or createTextField( ).

Solution

Use the getNextHighestDepth( ) method.

Discussion

The getNextHighestDepth( ) method is a particularly useful method when you are creating movie clips (or text fields) programmatically. If you add a lot of content programmatically, it can start to get somewhat difficult to keep track of which depths have been used and which have not. And if you accidentally use a depth that was already used, you will overwrite the content that had previously been placed within that depth. The getNextHighestDepth( ) method, as the name suggests, returns the next unused depth within a movie clip. That means you don't need to worry about keeping track of which depths have been used.

To use the getNextHighestDepth( ) method, call it from a movie clip using standard dot-syntax. The method doesn't require any parameters, and it returns the next unused depth within the movie clip. The following example uses a trace( ) statement to output the next unused depth within a movie clip named mClip:

 trace(mClip.getNextHighestDepth()); 

You can get the next available depth within the main timeline by using the self-referencing this. For example, on the main timeline you can use the following code to write the next available depth to the Output panel:

 trace(this.getNextHighestDepth()); 

Typically you'll want to use the getNextHighestDepth( ) method in conjunction with one of the methods that creates movie clips (or text fields) such as duplicateMovieClip( ) or attachMovie( ). The following example duplicates mSquare and creates a new instance named mNewSquare:

 mSquare.duplicateMovieClip("mNewSquare", this.getNextHighestDepth());