Recipe 15.7 Determining if an Asset Is Loaded

15.7.1 Problem

You want to know if an asset has completed loading into the Player.

15.7.2 Solution

Use the getBytesLoaded( ) and getBytesTotal( ) methods. Alternatively, define a custom isLoaded property for the Sound and MovieClip classes.

15.7.3 Discussion

There are three kinds of assets that can be loaded into a Flash movie using ActionScript: .swf files, JPEGs, and MP3s. The first two types are loaded into movie clips, and MP3s are loaded into Sound objects. Both the MovieClip and Sound classes have methods named getBytesLoaded( ) and getBytesTotal( ), which you can use to determine whether the asset is loaded. So, no matter which type of asset you are loading, the ActionScript is essentially the same.

The getBytesLoaded( ) method returns the number of bytes that are currently loaded into a movie clip or Sound object, and the getBytesTotal( ) method returns the number of bytes that will be loaded when the asset has been completely received. You know that the asset is completely loaded into the Player once the values returned by the two methods are equal.

The getBytesLoaded( ) and getBytesTotal( ) methods use uncompressed file sizes and thus are not necessarily accurate measurements of the compressed asset sizes. However, their ratio yields a reasonable estimate of what percentage of the asset has loaded.

There is a caveat when comparing the values returned by getBytesLoaded( ) and getBytesTotal( ). Before an object retrieves the information about the file it is loading (such as the total file size), both getBytesLoaded( ) and getBytesTotal( ) return 0. Thus, there is always a moment during which the two values are equal to 0, but the asset has not been loaded. You can address this problem by also checking whether the total bytes is also greater than zero. Therefore, we have:

if ( (myObj.getBytesLoaded() == myObj.getBytesTotal(  )) &&
     (myObj.getBytesTotal(  ) > 0) ) {
  trace("The asset has completed loading");
}

If you load many assets into your Flash movies, consider adding a custom property to the Sound and MovieClip classes that handles all this logic for you. The following code should be added to the Sound.as file created in Chapter 13:

// The getIsLoaded(  ) method returns true if the asset has loaded completely;
// otherwise, it returns false.
Sound.prototype.getIsLoaded = function (  ) {
  return ( (this.getBytesLoaded() == this.getBytesTotal(  )) && 
           (this.getBytesTotal(  ) > 0) );
};

// The isLoaded property is created for all Sound objects by calling the
// addProperty(  ) method from the Sound class's prototype. This code configures the
// isLoaded property to automatically call the getIsLoaded(  ) method.
Sound.prototype.addProperty("isLoaded", Sound.prototype.getIsLoaded, null);

You should add the following code to the MovieClip.as file created in Chapter 7. This code is exactly the same as the preceding code, except that it is applied to the MovieClip class instead of the Sound class.

MovieClip.prototype.getIsLoaded = function (  ) {
  return ( (this.getBytesLoaded() == this.getBytesTotal(  )) && 
           (this.getBytesTotal(  ) > 0) );
};
MovieClip.prototype.addProperty("isLoaded", MovieClip.prototype.getIsLoaded, null);

Once you have defined the isLoaded property, you can check to see if an asset has loaded, as follows:

if (myObj.isLoaded) {
  trace("The asset has completed loading");
}

In real-life scenarios, you monitor the load status repeatedly rather than simply checking it once. Monitoring the load status is demonstrated in Recipe 15.9 and Recipe 15.10.

15.7.4 See Also

Recipe 15.8. Also refer to Recipe 12.6 for an explanation of the techniques used in this recipe with regard to the addProperty( ) method and the isLoaded property. See Recipe 18.3 for details on detecting the loading of text variables using the LoadVars class. See Recipe 19.11 for details on monitoring XML loading progress.