Recipe 15.8 Getting the Percentage of an Asset That Has Loaded

15.8.1 Problem

You want to determine what percentage of an asset has loaded.

15.8.2 Solution

Use the getBytesLoaded( ) and getBytesTotal( ) methods. Alternatively, you can create a custom percentLoaded property for the Sound and MovieClip classes.

15.8.3 Discussion

You can use the getBytesLoaded( ) and getBytesTotal( ) methods to determine the percentage of an asset that has loaded. The percentage is calculated by determining the ratio of the bytes loaded to the total bytes:

ratio = myObj.getBytesLoaded() / myObj.getBytesTotal(  );

The ratio is always between 0 and 1. Therefore, to format the percentage for display, you can multiply the ratio by 100. If you want the percentage to be a whole number, you can round the result as well:

percentLoaded = Math.round(ratio * 100);

The only caveat is that before any information about the asset has been retrieved (such as its file size), the getBytesLoaded( ) and getBytesTotal( ) methods both return 0, and 0 divided by 0 does not yield a valid number. Therefore, you should also use the isNaN( ) (is Not-a-Number) function to catch if the percentage is not a valid number and set it to 0 instead:

if (isNaN(percentLoaded)) {
  percentLoaded = 0;
}

You can encapsulate this process by defining a custom percentLoaded property for the Sound and MovieClip classes. The following code should be added to the Sound.as file created in Chapter 13:

// The getPercentLoaded(  ) method returns the percent that has loaded as a whole
// number. It also makes sure that the returned value is always a valid number.
Sound.prototype.getPercentLoaded = function (  ) {
  var pLoaded = Math.round((this.getBytesLoaded() / this.getBytesTotal(  )) * 100);
  if (isNaN(pLoaded)) {
    pLoaded = 0;
  }
  return pLoaded;
};

// The percentLoaded property is created for all Sound objects using the
// addProperty(  ) method. This code configures the Sound class so that whenever the
// percentLoaded property is accessed, the getPercentLoaded(  ) method is called
// automatically.
Sound.prototype.addProperty("percentLoaded", 
                            Sound.prototype.getPercentLoaded, null);

You should add the following code to the MovieClip.as file created in Chapter 7:

MovieClip.prototype.getPercentLoaded = function (  ) {
  var pLoaded = Math.round((this.getBytesLoaded() / this.getBytesTotal(  )) * 100);
  if (isNaN(pLoaded)) {
    pLoaded = 0;
  }
  return pLoaded;
};
MovieClip.prototype.addProperty("percentLoaded",
                                 MovieClip.prototype.getPercentLoaded, null);

Once you have defined the percentLoaded property for the Sound and MovieClip classes, you can get the percentage that has loaded using a single call to the property:

trace(myObj.percentLoaded);

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.8.4 See Also

Recipe 15.7. Also refer to Recipe 12.6 for an explanation of the techniques used in this recipe with regard to the addProperty( ) method and the percentLoaded 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.