For awhile I’d been using an approach that involved a small preloader movie that displayed a loading animation and progress bar, and used loadMovie() to load the content movie (with components) into an empty clip. This worked in many cases, but it turns out that there are some v2 components, such as ComboBox and Window, that don’t work properly when they’re loaded into a sub-clip in this manner. Basically, those components contain code that makes explicit references to the _root timeline, which is a no-no. The Macromedia docs suggest using the _lockroot property on the target clip in order to trick the components into seeing the proper timeline as _root, but in my experiments I have found that this does not always work.

Recently, thanks to an entry in Jesse Warden’s blog, have been able to create a preloader that works with movies that use v2 components. As an added bonus, the preloader does not need to reside in a separate swf file, and thus doesn’t need to mess with _lockroot — it can be implemented as part of the main movie. I’ll describe the steps needed to accomplish this below, if for no other purpose than to remind myself of what I did!

Start with a movie that uses v2 components. Open up the library and identify these two types of symbols:

1. all component symbols (Button, ComboBox, Label, Window, etc.)
2. all compiled clips and/or movie clips that will be dynamically instantiated at runtime; this includes View symbols for window and accordion contents, component skin symbols, etc.

I usually keep these types of symbols in a separate folder in the library. For each of these symbols, right click and open the “Linkage…” dialog, and deselect “Export in first frame”. This prevents the code and assets for those symbols from being loaded at the very beginning of the movie, which means we’ll be able to put up a preloader before those start loading. It’s very imporant to indentify all components and dynamically instantiated symbols used in the movie and edit their library symbol entries in this way.

One important exception to this is the DataBindingClasses symbol that gets added to the library automatically whenever you use a v2 component in a movie. This symbol needs to have “Export in first frame” checked. I think the reason for this is that it needs to load before any components do. At any rate, even though we’re leaving it as one of the things that gets loaded at the very beginning of the movie, it’s not very large so it shouldn’t affect the preloader loading time too much.

The next step is to add three blank keyframes to the very beginning of the main timeline. There should initially be nothing at all on the stage on these frames; in other words, all your main movie content needs to be shifted three frames to the right. At this point I also usually add a new movie layer called “preloader”, and I’m also assuming that you already have a “script” or “code” layer that contains only frame actions.

The first two of the three new frames will be used for the preloader loop. Frame 1 actions should look like this:

// Frame 1 actions
trace(getBytesLoaded()+" of "+getBytesTotal());
if (getBytesLoaded() > 0 && getBytesLoaded() >= getBytesTotal()) gotoAndPlay(3);

Of course the trace is optional, and could be replaced with a line that sets the percentage loaded value on a progress bar or other indicator. Next, set this line as the frame 2 action:

// Frame 2 actions
gotoAndPlay(1);

These two frame actions are just the typical way to “pause” a movie until the whole swf file has loaded on the client machine. Once the entire movie has loaded, the playhead is allowed to proceed to frame 3. Your lightweight preloader animation and/or loading indicator can be put on the stage on the “preloader” layer spanning frames 1 and 2, so that they are visible during the preloading process.

The next step is to create a special frame on frame 3, which contains instances of all the symbols for which we unchecked “Export in first frame” in the first step (this is why we organized them into a special library folder earlier). Create a blank keyframe at frame 3 on the preloader layer and drag one instance of each such component onto the stage but outside the movie’s viewable area. What we’re doing here is telling the Flash compiler that it will indeed need to load these assets for use on frame 3 and beyond (since it’s not going to load them at the beginning of the movie as usual). These component instances don’t have to stay on the stage past frame 3; a brief appearance on this single frame is enough to tell the compiler when they need to be loaded.

The observant reader will note that it’s not actually necessary for each and every one of these clips to be instantiated on frame 3, since many of them probably appear on the timeline later on past frame 3 anyway. Technically this is true — all we really need is for each symbol that gets dynamically instantiated by application ActionScript code, and therefore isn’t statically placed on the timeline in the authoring environment — to be instantiated in this way on frame 3. This includes some components, namely Window, which tends to be instantiated at runtime using the PopupManager class. However, it doesn’t hurt just to instantiate everything on frame 3, so I’m recommending that as a less error-prone approach.

The final — and quite critical — step is to tell the compiler that ActionScript classes should be loaded on frame 3 instead of frame 1. This can be done by going to the dialog at File Publish Settings… Flash (ActionScript) Settings… and setting the “Export Frame for Classes” value to 3. This prevents the huge chunk of ActionScript class code that comes along with the v2 components from being loaded at the beginning of the movie and thus trumping the preloader. The important thing is that the class export frame be no later than the frame on which the symbols that use those classes first appear.

At this point your timeline should look something like this:

In the above image, the frame colors correspond to:

• orange: the two script frames with the preloader loop actions described above
• green: any lightweight preloader animation and/or loading indicator clips
• yellow: the special frame on which any dynamically instantiated symbols are manually instantiated on the stage but outside the viewable area
• blue: the main movie that is being preloaded

You should be able to verify that the loading sequence is working as intended by selecting “generate size report” on the Flash Publish Settings dialog, and examining the report to ensure that the bulk of the movie doesn’t get loaded until frame 3.

Say we have a class called ActionManager that needs the event handling mix-in methods. One approach would be to invoke EventDispatcher.initialize(this) in ActionManager’s constructor method; however, this approach suffers from the drawback that the EventDispatcher initializer could be invoked multiple times (each time a new ActionManger instance is created), when it really only should be invoked once.

If we were programming in Java, we’d be able to do something like this, using the static initializer syntax:

public class ActionManager {
static {
mx.events.EventDispatcher.initialize(ActionManager.class);
}
public ActionManager() {
...
}
...
}

Now, ActionScript doesn’t have this sort of static block syntax, but fortunately there is a way to accomplish the same thing:

class ActionManager {
private var staticInitialized:Boolean = staticInitializer();
private static function staticInitializer(Void):Boolean {
mx.events.EventDispatcher.initialize(ActionManager.prototype);
return true;
}
public function ActionManager(Void) {
...
}
}

The ActionScript pattern illustrated above does the same thing as Java’s static initializer block syntax — the staticInitializer() method will only be called once, the first time the class is referenced, and before the constructor method is invoked.

Although this pattern is typically used to set up mix-in classes such as EventDispatcher, it is also useful for setting up arbitrary static class memebers such as lookup tables, etc., which only need to be calculated once across all instances of a class.

Static Classes

Although AS2.0 does support static classes, a crucial difference from Java is that static members cannot be accessed through instance variables. For example, if we have a Java class Foo that defines a public static field BAR, the following would output the value of BAR:

Foo myFoo = new Foo();
System.out.println("BAR is "+myFoo.BAR);


However, this will not work in AS2.0 since static members can’t be accessed through instance variables. Instead, we’d only be able to access BAR through the static reference Foo.BAR. In my opinion, this is a significant shortcoming that breaks some important design patterns that rely on static members.

No Multithreading

ActionScript is not multithreaded. This relieves us from having to worry about thread management with synchronized blocks. For example, a Singleton can be implemented without concern for multiple threads inadvertently creating more than one initial instance. However, there are still cases in which one must watch out for race conditions, since ActionScript is full of event-driven callback mechanisms in which execution order cannot be known ahead of time (loading external assets and XML data, for example). In other words, while we don’t have to worry about two methods (or statements, for that matter) executing at the same time, or two threads executing the same method at the same time, we do still need to be concerned about the order in which methods execute. As far as I can tell, methods themselves can be guaranteed to execute atomically.

No Method Overloading

In Java, it’s possible to define more than one signature for a given method, varying based on the number, type, and ordering of parameters. In AS2.0, only one signature is allowed per method (including constructors). However, this disadvantage is offset somewhat by the fact that the AS compiler does not require that all parameters be specified when invoking a method; this allows us to write a method in which optional parameters follow required ones. For example, consider the constructor for the built-in Date object:

new Date(year, month [, date [, hour [, minute [, second [, millisecond ]]]]])

The Date constructor is written to accept seven parameters, but they are optional from least to most specific (right to left); that is, one could construct a Date by specifying only year, month, and date. In that case, the constructor would only see values for the first three parameters, and the rest would be undefined.

I’ll add more items to this list as I think of them.

listener = new Object();
listener.click = function(evtObj) {
trace("Button clicked: "+evt.target);
}
myButton.addEventListener("click", listener);

The myButton component generates a “click” event when pressed using the following code:

this.dispatchEvent({type:"click", target:this});

which creates a new (anonymous) event object (with the requisite type and target properties) and submits it to the event handling framework. The event framework then passes the event along to the listener object, which itself was previously registered as a listener for events of type “click” coming from myButton.

One very nice feature of the new event framework is that it is also possible to use it outside the context of v2 components. This can be useful, for example, when creating a modular application in which various elements need to communicate with one another yet making those elements into full-fledged components would be overkill.

Any object can be made into an event producer by invoking the EventDispatcher mix-in. A mix-in is a special class that dynamically adds methods and fields to a given object in order to expand its functionality. Such constructs are used liberally throughout the core classes in Flash MX 2004. Using the EventDispatcher mix-in adds the following methods to a given object:

dispatchEvent(evtObj):Void

Dispatches the given event object to the event framework, allowing it to be sent to any attached listeners

addEventListener(eventType:String, handler):Void

Registers the specified handler object as a listener for the specified event type coming from the current object

removeEventListener(eventType:String, handler):Void

Unregisters the specified handler for the specified event type

An additional method called dispatchQueue is also added, but that method is for internal use by the event framework.

In order to add these events to an object, simply invoke EventDispatcher.initialize:

class MyCalendar extends MovieClip {

public function MyCalendar(Void) {
...
// this adds (mixes in) the dispatchEvent, etc. methods
mx.events.EventDispatcher.initialize(this);
}
...
}

Once the initialize method is invoked at runtime, the MyCalendar class will have dispatchEvent and the add/remove listener methods, and will work just like any other event producer in the event framework.

One problem with the fact that the event methods are added through a mix-in at runtime is that the compiler won’t know about those methods while it is compiling the class. Therefore, if we just invoke dispatchEvent within the example class above, the compiler will generate an error since dispatchEvent isn’t defined within MyCalendar or within MovieClip, its superclass.

There are two ways to get around this problem. The easiest is just to define three additional class fields of type Function, one for each method that’s going to be added by the mixin:

class MyCalendar extends MovieClip {

var dispatchEvent:Function;
var addEventListener:Function;
var removeEventListener:Function;

public function MyCalendar(Void) {
...
// this adds (mixes in) the dispatchEvent, etc. methods
mx.events.EventDispatcher.initialize(this);
}
...
}

A slightly more rigorous method is to add a “stub” for each of the mix-in methods, which will be overridden once the mix-in attaches the real methods at runtime but will satisfy the compiler in the meantime. Write the stubs to throw Errors by default, just to make sure that the mix-in did in fact override those methods as expected:

class MyCalendar extends MovieClip {

public function MyCalendar(Void) {
...
// this adds (mixes in) the dispatchEvent, etc. methods
mx.events.EventDispatcher.initialize(this);
}

public function dispatchEvent(evtObj):Void {
throw new Error("dispatchEvent method not overridden!");
}

public function addEventListener(eventType:String, listener) {
throw new Error("addEventListener method not overridden!");
}

public function removeEventListener(eventType:String, listener) {
throw new Error("removeEventListener method not overridden!");
}

...
}

By doing this, the compiler will see that MyCalendar does in fact define the event methods, even though those methods will be overridden at runtime by the EventDispatcher class.

Example:

var loadListener = new Object();
loadListener.handleEvent = function(evt) {
if (evt.type == "progress") {
trace("PROGRESS: "+evt.current+" of "+evt.total);
}
};
myFormOrSlideOrWhatever.addEventListener("progress", loadListener);
myFormOrSlideOrWhatever.load();

Looks like the Loader component is probably based on the MovieClipLoader AS object. The MovieClipLoader.onLoadProgress entry in the docs mention the current and total properties of that event.

_global.styles.RadioButton.setStyle("color", "blue");

What’s not quite clear from this is that before doing that, you’d need to create the style object for the RadioButton class first:

_global.styles.RadioButton = new mx.styles.CSSStyleDeclaration();

Otherwise you’re calling setStyle on a null reference.

Also interesting to note is the fact that setStyle is not actually a method of CSSStyleDeclaration. I don’t know where it comes from, actually (UIObject? Some kind of mixin?). Therefore you can’t use strict typing on style objects if you’re going to call setStyle on them.

Update: Got some more information on this from a response on FlashCoders. Turns out that setStyle does indeed come from a mixin — in short, UIComponent loads in UIComponentExtensions, which calls mx.styles.CSSSetStyle.enableRunTimeCSS(), which in turn causes the CSSSetStyle methods to be mixed in to CSSStyleDeclaration.

Math.log(x)/Math.LN10

which divides ln x by ln 10.

tree.dispatchEvent({target:tree, type:"change"});

In general it’s best to use the event dispatching framework to manually fire the event from the component as shown here as opposed to just invoking the handler(s) directly. That way you don’t have to worry about keeping track of what handlers are listening to the component. Also, manually invoking a handler will cause the handler code to see a different value for “this” than if the handler had been invoked by the event framework, which may produce unexpected results.

For example:

var tfmt = new TextFormat();
tfmt.font = "MyEmbeddedFontSymbol";
myTextField.embedFonts = true; // < -- critical!
myTextField.setTextFormat(tfmt);

This also applies to fonts set through style properties. For example, if we have something like

_global.style.setStyle("fontFamily", "MyEmbeddedFontSymbol");

intended to set the global fontFamily style property for all components to use a custom font symbol, it’s necessary to set the embedFonts property as well:

_global.style.setStyle("embedFonts", true);

Without the above line, the specified font symbol will not be used in components as desired.

Also, if there’s already a filter in place when the data loads in (modelChanged/updateAll), the filter won’t be applied until filtered is set to false and then back to true again (even if on immediately successive lines).