Flash: Instance names vs. variable names

There is some confusion as to the nature of instance names in AS3. This is because in AS2, you could use a string of actual text to create an instance name, using the createEmptyMovieClip method (if you were creating a MovieClip object from scratch) or the attachMovie method (if you were dynamically loading an instance of a MovieClip symbol from the library). In either case, the string of text that you supplied to the method for the "instance name" parameter became the instance name of that instance. Internally, Flash was taking that string of text and somehow creating a variable name for you with the same name. This variable name was available for use immediately, on the very next line of code. At the same time, the supplied string of text was assigned to the instance's _name property (note the underscore, this is AS2, remember?).

I have written about this issue before [Click Here], but to recap, in AS3 you can no longer generate variable names from a simple string like this. You can create as many variable names as you want or need, you just can't generate them from a string of text any more. In AS2, there was a popular technique where you would generate instance names in a for loop, and just append the loop counter to the string to make them unique. Click the link I just gave you above for more information (if you haven't already read it).

So why am I writing about this issue again? Well, this time, I want to delve into the nature of variables in AS3, and I thought I would begin by discussing how variables differ from instance names. Or are they the same thing? Just what is an instance name, anyway? It winds up being all very simple, after all. But let's get it straight right up front, an "instance name" is a feature of the Flash authoring tool, and it actually has no meaning in terms of programming. An instance name is just that string of text that you type into the properties panel to give a variable name to a MovieClip instance that you have created on the stage. Flash takes that value that you type into the box and, behind the scenes, creates a variable name for you. At the same time, Flash also sets the _name (AS2) or name (AS3) property for the instance to that same string of text. But it's important to understand that this property is still just a simple string, it is not a variable name that can be used in your programming statements. The fact that Flash turns this string into a variable name for you behind the scenes gives the illusion that you are using the instance name itself in your programming, but actually you are not.

But the fact that Flash does this also perpetuates a kind of feeling that might be described as "one name per object," or the idea that each object has one instance name, and that's that. I am going to show you that that's not the case, but we'll get to that in a bit.

The bottom line is that having a variable name that you can use to refer to the instance is the important part. The fact that Flash does this for you behind the scenes for your manually created stage instances is kind of a convenience, but it can also be doing you a disservice if you are coming from AS2 and don't exactly understand what's really going on. Flash automatically generates these variable names as part of creating a class for you that represents your fla's main timeline. This class is known as the document class. You can make your own document class, but if you don't, Flash automatically makes one for you.

In the publish settings for your fla, there is a very special checkbox labelled "automatically declare stage instances." This box is checked by default. If you uncheck it, and you don't write your own document class, Flash will still perform this service for you anyway as part of generating your document class. If you uncheck the setting, and you do write your own document class, you have to declare all the stage instances yourself manually in your document class. If you have classes linked to library symbols, and those symbols contain nested instances of their own, those instances will have to be declared manually, too, in the linked classes. That is, if you uncheck the box.

To get to this setting, go to File, Publish Settings, and you will get the Publish Settings dialog box. Now in the box, click the Flash tab, and on the second line where it says Script: Actionscript 3.0, click the Settings.... button to the immediate right of that:

This will lead you to the following dialog box, where the "automatically declare stage instances" checkbox can be found:

Leaving this box checked or not is totally up to you, but I'll give you a few general rules of thumb: If you write your code on the main timeline of your fla and not your own document class, leave the box checked, as unchecking it will make no difference anyway. Secondly, if you know that any given project is going to be strictly a Flash project, you might as well leave the box checked and let Flash declare your stage instances for you, even if you always write your own document class. If, however, you use Flex or can foresee that you might eventually bring your project into Flex, then you should uncheck the box and declare your stage instances manually.

How variables contain information

Now we can proceed to discuss variables and how they store information. In Actionscript 3.0, there are two types of variables, "simple" and "complex." The simple variable types are also sometimes called "primitive." The simple variable types are String, Boolean, Number, int, and uint. The complex variable types are everything else: arrays, classes that come with flash, custom classes that you write yourself, third-party classes that other people write. In other words, if it isn't a simple type, it's a complex type.

I mention this difference between simple and complex types because there is also a difference in the way that variables share their information with each other, depending on which category they fall into. This difference is important to know, especially when you are creating objects from classes.

Simple variables pass information by value:

Let's create a couple of simple string variables:

var fruit1:String = "apple";
var fruit2:String = "pear";

fruit2 = fruit1;

trace(fruit1); // apple
trace(fruit2); // apple

fruit1 = "banana";

trace(fruit1); // banana
trace(fruit2); // apple

Notice that we create a string variable called fruit1 and give it a value ("apple"). On the second line, we create another variable called fruit2, and give it a value ("pear"). Next, on line 4, we set fruit2 equal to fruit1. Not surprisingly, when the values are traced, they are both the same. Next, on line 9, we change fruit1's value to something else ("banana"). Now when we trace out both values, they are different. Changing fruit1's value did not affect fruit2's value. So, obviously, the two variables are pointing to two different storage locations. When fruit2 was set equal to fruit1, fruit2 was given a copy of the information being held by fruit1. Another way of saying it is that fruit2 was assigned the value of fruit1. This is probably the sort of behavior you would expect, especially if you have been taught that variables are like containers. But this sort of behavior is only true of the simple variable types (the three Number types and the Boolean type behave this way, too, but I thought the String type made a decent enough demonstration of it). And this behavior can be thought of as being assigned by value:

Complex variables pass information by reference:

To illustrate this concept, create a new FLA file in flash. Choose the Oval tool and draw a red circle with a black stroke. This can be any size you want. Select the circle, stroke and all, and convert it to a MovieClip symbol. Name it "Circle" and check off "export for actionscript." Let the export name be "Circle" also. Once the Circle symbol is in your library, you may delete the instance you just drew (that's still on the stage).

Next, click on the first frame of the timeline. Press F9 to get the actions panel. In the actions panel, enter the following:

var circle1:Circle = new Circle();
addChild(circle1);

Press CTRL-ENTER to run. You should see an instance of your Circle MovieClip instance appear on the stage. Next, let's add to the code, creating a second variable and setting it equal to the first one, so that the whole code now looks like this:

var circle1:Circle = new Circle();
addChild(circle1);
var circle2:Circle = circle1;
circle2.x = 150;
addChild(circle2);

Here we see that a variable called circle1 is declared, and assigned a new instance of circle. Then it is added to the display list. Next, another variable is created called circle2, and this variable is set equal to circle1. circle2 is then given an x value of 150 and added to the display list. If these variables behaved like our previous fruit1 and fruit2 variables, we should see two circles on the screen, because circle2 would get a copy of circle1. But guess what? It doesn't work that way, there is still only one circle instance, so when circle2 was told to go to an x location of 150, circle1 went there too, because both names were referring to the same object! See, when circle2 was set equal to circle1, instead of circle2 getting a copy of circle1's value, it got circle1's reference instead. Here's an illustration of this type of behavior, which may be thought of as being assigned by reference:

Don't be confused that I illustrated the "new Circle()" with a rectangle. I know that a rectangle is not a circle, but that blue rectangle is meant to represent a block of memory. Of course, it doesn't even accurately depict that, I'm sure. But I'm just trying to give you a way to picture it in your mind. Whenever the "new" keyword is used, a section of memory is set aside and the new object is created and fills this block. The variable name is just a handle, or a pointer that refers to it. Without this handle or pointer, we couldn't tell the object what to do (manipulate its properties or run its methods).

What all of this means is that only the "new" keyword actually creates any objects. You can't create a new object by assignment of one variable to another, because that only passes a reference. Also, any number of references can be made to refer to the same object. Remember my earlier discussion of instance names on the previous page? Do you see now why it's not really a valid concept to believe that there is (or can be) only one instance name for each object? Flash takes the instance names you type into the properties panel and makes variable names out of them as a service to you. Variable names for objects are simply references. The same object can have any number of references pointing at it, and can be manipulated by using any of them.

Here is another case where the same object has another reference pointing to it. Maybe you are familiar with this one but just never thought of it in these terms before:

Notice that in the above example, circle1 and event.currentTarget point to the exact same object! They are one and the same. Okay, here is yet one more example:

By now I am sure you are beginning to see the pattern here. Once a reference is established it refers back to the object itself. That being the case, one reference is as good as another. So what is the object's "real" name? I'll let you be the judge, I don't think it really has a "real" name at all. Man! To keep track of all these names you need a scorecard, don't you? Well, you have one--it's called the code window.... haha!

Finally, here is one of my favorite uses of this feature. This involves the creation of a variable whose name I invariably (no pun intended, really!) wind up calling currentClip:

In this scenario, the variables circle1 and circle2 each refer to (separate) new instances of the Circle class. A third variable called currentClip is declared. Rather then being set to a new instance itself, it is instead set equal to circle1. However, later in the code, we may decide to make it equal to circle2. In this way, circle1 and circle2 can effectively take turns "being" the current clip. Bear in mind that when currentClip is set equal to one of the circle instances, for all practical purposes it becomes that instance (and no longer refers to the previous one). Think of the currentClip variable like a chameleon that can take on the identity of the other movie clips, only literally! This is a kind of polymorphism that can be very powerful indeed!