The other subject that I want to discuss is timeline instances. As you should know if you are reading an advanced text like this, instances can have assigned instance names. But what is exactly an instance name?

An instance name is really only one thing; it is the value of the "name" property of the DisplayObject class. It allows you to get a reference to the instance using getChildByName from the DisplayObjectContainer class.

However, for authoring time set instance names, things suddenly get more interesting. When the Flash Player finds an instance with a set name on a timeline, it does you a service, even if you don’t want it. The player tries to set a property on the timeline object with the same name as the instance name. If nothing else was done, this would give a runtime error.

However, the authoring tool by default defines this property on the class for you. This is possible to disable in the publishing settings. Doing this can be useful if you need the definition to be done in a special way, for example, as a base type or in a base class. However, if you turn this option off, you are responsible for defining all these properties in all of your classes in the full project. Note that I used the expression "your classes". By that I intentionally exclude classes that Flash writes for you. Flash is always declaring the property in those classes.

This is quite a large undertaking and should not be done unless you are prepared on doing the work. Do note that if you try to define the property yourself when Flash also is defining it for you, you end up with a compiler error. After all, there is a duplicate property definition. On the flip side, if no one defines the property, you will get a runtime error when the player tries to set the property.

Moving the timeline

When you move the timeline, the player does a lot of things for you. One of these things includes creating new instances and putting them on the display list of the timeline. It also moves existing instances. However, there are some very common gotchas here.

The first gotcha is that the instance simply isn't created until it is needed. It is created when the keyframe is shown. This means that it is impossible to access an instance on a different frame, because the instance simply doesn't exist at this point.

Now onto the other gotcha. When does the player create a new instance? Obviously it does it if there isn't an instance to begin with. But it also does this at some keyframes. I do not myself fully understand exactly what the exact conditions are. But I do know one thing, if you can use a different instance name in the authoring tool compared to the previous frame, you got a new instance.

But what is this gotcha then? It is actually quite simple. It is mistakenly assuming that the old instance is still the instance that you see. For example, thinking that any event listeners that you have added to the old instance will apply to the new instance. This can be a potentional memory leak if you do not account for the possibility of the instance you have a reference to no longer being on the display list.