Handy ActionScript Toolset

The HATClip class is the Handy Toolset base class for displayed clips. It fixes the "off-by-1-frame" bug that Flash has. This is when you have child clips on the stage of a clip that are associated with a class other than MovieClip and you attach that clip. Right after attaching, the children are still simple MovieClips and not objects of the classes they were associated with and only on the next frame do they become those objects. If you are subclassing HATClip you can safely assume that any children placed on the stage are objects of the correct classes right in the constructor of your subclass. It also eliminates the needs for depth management and replaces depths with z-order.

The API for managing z-order of children is:

 // Changes the z-order of a child object. If there is already a child at
 // that z-order it and anything above it get moved to higher z-orders.
 setZOrder( child : Object, zOrder : Number )

 // Returns the z-order index of a child object.
 getZOrder( child : Object ) : Number

 // Returns a child at a particular z-order index.
 getChildAt( zOrder : Number ) : Object

It is important to note that z-order is not the same as depth. Z-order indexes start at 0 always and never have any gaps in between. So for example if you change the z-order of a child at index 0 to 2, the child that was at index 1 will now be at index 0. If you try to set the z-order to a number that's higher than the number of children then the z-order will default to the number of children and the child will be on top.

You can also change the z-order of a HATClip by using the zOrder property as such:

 hatClip.zOrder--;

HATClip also provides a more generic way of managing children that also helps track children for z-ordering. This is the API:

 // Attaches a child clip from the library using a linkage identifier.
 addChild( type : String [, initParams : Object] [, zOrder : Number] ) : MovieClip

 // Attaches an empty HATClip object.
 addClip( [zOrder : Number] ) : HATClip

 // Attaches a HATText object, which is the equivalent of TextField object but can also change depths.
 addText( [zOrder : Number] ) : HATText

 // Attaches a HATBitmap object that allows a bitmap to be displayed and to change its depth.
 addBitmap( bitmap : BitmapData, [zOrder : Number] ) : HATBitmap 

 // Removes a child.
 removeChild( child : Object )

The zOrder parameter in all of these is optional, if left out the child will be placed on top of everything. The type parameter in addChild specifies a linkage identifier for the clip to attach and the optional initParams can be used to set any properties of the clip right after attaching. addClip method is the way to create empty movieclips inside a HATClip. The movieclip returned is an instance of HATClip, so it has all the helpful utilities all HATClips have. addText is what you'd use to add a TextField, except TextField objects don't have swapDepths. So in the toolset HATText is used instead which is a wrapper for a TextField and can be used like one, but it can also swap depths and also has the stuff from HATObject because it subclasses it. I left out the x, y, width, and height parameters that createTextField method has because I don't see a need for those if you can simply set these after adding the textfield. That's what is usually done after attaching clips anyway. addBitmap can be used in place of attachBitmap. It gives you the ability to treat a displayed bitmap as a display object and set its x, y, width, height and z-order. You can use removeChild method to remove any child or you're free to use removeMovieClip or removeTextField methods on the children as well.