13.5 Referring to Instances and Main Movies

If you know your movie will be loaded into a movie clip, you should not use _root to refer to the main timeline. Instead, define a global reference to the main timeline by placing the following code on your movie's main timeline:

_global.


myApp


Main = this;

where myApp is the name of your application and Main is used, by convention, to denote the main timeline. Then use myApp Main in place of _root .

13.5.4.2 Referencing other documents in the Player using _leveln

If we have loaded multiple .swf files into the document stack of the Flash Player using loadMovie( ) , we can refer to the main movie timelines of the various documents using the built-in series of global properties _level0 through _level n , where n represents the level of the document we want to reference.

Therefore, _level0 represents the document in the lowest level of the document stack (documents in higher levels will be rendered in the foreground). Unless a movie has been loaded into _level0 via loadMovie( ) , _level0 is occupied by the movie that was initially loaded when the Player started.

Here is an example that plays the main movie timeline of the document in level 3 of the Player's document stack:

_level3.play();

Like the _root property, the _level n property can be combined with ordinary instance references via the dot operator:

_level1.clipA.stop();

As with references to _root , references to _level n properties are called absolute references because they lead to the same destination from any point in a document.

Note that _level n and _root are not synonymous. The _root property is always the current document's main timeline, regardless of the level on which the current document resides, whereas the _level n property is a reference to the main timeline of a specific document level. For example, suppose we place the code _root.play( ) in myMovie.swf . When we load myMovie.swf onto level 5, our code plays _level5 's main movie timeline. In contrast, if we place the code _level2.play( ) in myMovie.swf and load myMovie.swf into level 5, our code plays _level2 's main movie timeline, not _level5 's. Of course, from within level 2, _root and _level2 are equivalent.

13.5.5 Authoring Instance References with Insert Target Path

When the instance structure of a movie gets very complicated, composing references to movie clips and main movies can be laborious. We may not always recall the exact hierarchy of a series of clips and, hence, may end up frequently selecting and editing clips in the authoring tool just to determine their nested structure. The Actions panel's Insert Target Path tool generates clip references visually, relieving the burden of creating them manually. The Insert Target Path button is shown in Figure 13-6.

Figure 13-6. The Insert Target Path button

To use Insert Target Path, follow these steps:

1. Position the cursor in your code where you want a clip reference to be inserted.

2. Click the Insert Target Path button, shown in Figure 13-6.

3. In the Insert Target Path dialog box, select the clip to which you want to refer.

4. Choose whether to insert an absolute reference , which begins with _root , or a relative reference , which expresses the reference to the target clip in relation to the clip that contains your code ( this ).

5. If you are exporting to Flash 4 format, choose the Slashes Notation button for Flash 4 compatibility. (The Dot Notation button, selected by default, composes references that won't work in Flash 4).

The Insert Target Path tool cannot generate relative references that ascend a hierarchy of clips. That is, the tool cannot be used to refer to a clip that contains the current clip (unless you want to begin the path from _root and proceed downward). To create references that ascend the clip hierarchy, we must either use absolute references starting with _root (which therefore become descending references) or manually enter the appropriate relative references in our code using the _parent property.

13.5.6 Dynamic References to Clip Objects

Normally, we know the name of the specific instance or movie we are manipulating, but there are times when we'd like to control a clip whose name we don't know. We may, for example, want to scale down a whole group of clips using a loop or create a button that refers to a different clip each time it is clicked. To handle these situations, we must create our clip references dynamically at runtime.

13.5.6.1 Using the array-element access operator

As we saw in Chapter 5 and Chapter 12, the properties of an object can be retrieved via the dot operator or through the array-element access operator, [ ] . For example, the following two statements are equivalent:

someObject.myProperty = 10;
someObject["myProperty"] = 10;

The array-element access operator has one important feature that the dot operator does not; it lets us (indeed requires us to) refer to a property using a string expression rather than an identifier . For example, here's a string concatenation expression that acts as a valid reference to the property propertyX :

someObject["prop" + "ertyX"];

We can apply the same technique to create our instance and movie references dynamically. We already saw that clip instances are stored as properties of their parent clips. Earlier, we used the dot operator to refer to those instance properties. For example, from the main timeline we can refer to clipB — which is nested inside of another instance, clipA — as follows:

clipA.clipB;                      // Refer to


clipB


inside


clipA


clipA.clipB.stop();               // Invoke a method on


clipB

Because instances are properties, we can also legitimately refer to them with the [ ] operator, as in:

clipA["clipB"];                   // Refer to


clipB


inside


clipA


clipA["clipB"].stop();            // Invoke a method on


clipB

Notice that when we use the [ ] operator to refer to clipB , we provide the name of clipB as a string, not an identifier. That string reference can be any valid string-yielding expression. For example, here's a reference to clipB that involves a string concatenation:

var clipCount = "B";
clipA["clip" + clipCount];         // Refer to


clipB


inside


clipA


clipA["clip" + clipCount].stop();  // Invoke a method on


clipB

We can create clip references dynamically to refer to a series of sequentially named clips:

// Here's a loop that stops


clip1


,


clip2


,


clip3


,


and clip4


for (var i = 1; i <= 4; i++) {
  _root["clip" + i].stop( );
}

Now that's powerful!

13.5.6.2 Storing references to clips in data containers

We began this chapter by saying that though movie clips are technically their own datatype, they are treated as objects in ActionScript. Hence, we can store a reference to a movie clip instance in a variable, an array element, or an object property.

Recall our earlier example of a nested instance hierarchy ( clipC nested inside clipB nested inside clipA ) placed on the main timeline of a document. If we store these various clips in data containers, we can control them dynamically using the containers instead of explicit references to the clips. Example 13-2, which shows code that is placed on a frame in the main timeline, uses data containers to store and control instances.

Example 13-2. Storing clip references in variables and arrays

var x = clipA.clipB;   // Store a reference to


clipB


in the variable


x


x.play();              // Play


clipB


// Now let's store our clips in the elements of an array
var theClips = [clipA, clipA.clipB, clipA.clipB.clipC];
theClips[0].play();    // Play


clipA


theClips[1]._x = 200;  // Place


clipB


200 pixels from


clipA


's registration point
// Stop all the clips in our array using a loop
for (var i = 0; i < myClips.length; i++) {  
  myClips[i].stop();
}

By storing clip references in data containers, we can manipulate the clips (such as playing, rotating, or stopping them) without knowing or affecting the document's clip hierarchy. Storing clip references in variables also make our code more legible. You can use a shorter, simpler variable name instead of a lengthy absolute or relative path through the movie clip hierarchy.

13.5.6.3 Using for-in to access movie clips

In Chapter 8, we saw how to enumerate an object's properties using a for-in loop. Recall that a for-in loop's iterator variable automatically cycles through all the properties of the object, so that the loop is executed once for each property:

for (var prop in someObject) {
  trace("the value of someObject." + prop + " is " + someObject[prop]);
}

Example 13-3 shows how to use a for-in loop to enumerate all the clips that reside on a given timeline.

Example 13-3. Finding movie clips on a timeline

for (var property in someClip) {
  // Check if the current property of


someClip


is a movie clip
  if (typeof someClip[property] =  = "movieclip") {
    trace("Found instance: " + someClip[property]._name);
    // Now do something to the clip
    someClip[property]._x = 300;
    someClip[property].play( );
  }
}

The for-in loop gives us convenient access to the clips contained by a specific clip instance or main movie. Using for-in , we can control any clip on any timeline, whether or not we know the clip's name and whether the clip was created manually or programmatically.

Example 13-4 shows a recursive version of Example 13-3. It finds all the clip instances on a timeline, plus the clip instances on all nested timelines.

Example 13-4. Finding all movie clips on a timeline recursively

function findClips (theClip, indentSpaces) {
  // Use spaces to indent the child clips on each successive tier
  var indent = " ";
  for (var i = 0; i < indentSpaces; i++) {
    indent += " ";
  }
  for (var property in theClip) {
    // Check if the current property of


theClip


is a movie clip
    if (typeof theClip[property] =  = "movieclip") {
      trace(indent + theClip[property]._name);
      // Check if this clip is parent to any other clips
      findClips(theClip[property], indentSpaces + 4);
    }
  }
}
findClips(_root, 0); // Find all clip instances descended from main timeline

For more information on recursion, see Section 9.9 in Chapter 9.

13.5.6.4 The _name property

As we saw earlier in this chapter under Section 13.3.3, every instance's name is stored as a string in the built-in property _name . We can use that property, as we saw in Example 13-1, to determine the name of the current clip or the name of some other clip in an instance hierarchy:

this._name;        // The current instance's name
_parent._name      // The name of the clip that contains the current clip

The _name property comes in handy when we want to perform conditional operations on clips according to their identities. For example, here we duplicate the seedClip clip when it loads:

onClipEvent (load) {
  if (this._name =  = "seedClip") {
    this.duplicateMovieClip("clipCopy", 0);
  }
}

By checking explicitly for the seedClip name, we prevent infinite recursion—without our conditional statement, the load handler of each duplicated clip would cause the clip to duplicate itself.

13.5.6.5 The _target property

Every movie clip instance has a built-in _target property, which is a string that specifies the clip's absolute path using the deprecated Flash 4 "slash" notation. For example, if clipB is placed inside clipA , and clipA is placed on the main timeline, the _target property of these clips is as follows:

_root._target                    // Contains: "/"
_root.clipA._target              // Contains: "/clipA"
_root.clipA.clipB._target        // Contains: "/clipA/clipB"

13.5.6.6 The targetPath( ) function

The targetPath( ) function returns a string that contains the clip's absolute reference path, expressed using dot notation. The targetPath( ) function is the modern, object-oriented equivalent of _target . It takes the form:

targetPath(


theClip


)

where theClip is the identifier of the clip whose absolute reference we wish to retrieve. Here are some examples, using our familiar example hierarchy:

targetPath(_root);              // Contains: "_level0"
targetPath(_root.clipA);        // Contains: "_level0.clipA"
targetPath(_root.clipA.clipB);  // Contains: "_level0.clipA.clipB"

The targetPath( ) function gives us the complete path to a clip, whereas the _name property gives us only the name of the clip. (This is analogous to having a complete file path versus just the filename.) So, we can use targetPath( ) to compose code that controls clips based not only on their name but also on their location. For example, we might create a generic navigational button that, by examining its targetPath( ) , sets its own color to match the section of content within which it resides. See the example under the Selection object in the ActionScript Language Reference for a demonstration of targetPath( ) in action.