Table of Contents

xmlDoc.getBytesLoaded()

Returns

An integer representing the number of bytes that have finished downloading to the Player. Divide by 1024 to convert bytes to kilobytes (KB).

Description

The getBytesLoaded( ) method tells us the number of bytes of an external XML file that have downloaded into the Flash Player due to an earlier call to load( ) or sendAndLoad( ). The specified xmlDoc must be the top-level node in an XML object hierarchy (i.e., an instance of the XML class, not of the XMLnode class).

For a new XML object, getBytesLoaded( ) returns undefined. Immediately after load( ) or sendAndLoad( ) is called, getBytesLoaded( ) returns 0. As data arrives, getBytesLoaded( ) returns the number of bytes transferred so far, until the entire XML file has loaded. From then on, it returns the total number of bytes last transferred, until the next call to load( ) or sendAndLoad( ).

The getBytesLoaded( ) and getBytesTotal( ) methods are used together to determine (and, normally, display) the load progress of a downloading XML file. However, merely detecting the completion of a load operation does not require getBytesLoaded( ); the onLoad( ) event handler is automatically executed when an XML file finishes loading. The success of the load attempt should be checked from the onLoad( ) handler.

Example

The following code, available at the online Code Depot, adds two new methods to all XML document objects: preload( ) and sendAndPreload( ). They function the same as load( ) and sendAndLoad( ), except that they use getBytesLoaded( ) to report the progress while the XML file is loading. Any XML object that invokes preload( ) or sendAndPreload( ) is expected to define a custom onBytesLoaded( ) callback that will be invoked every 200 milliseconds and supplied with load progress information (bytes loaded, percent complete, etc.). Typically, the code in onBytesLoaded( ) displays the load progress on screen. The XML object should also define an onLoad( ) handler to respond to completion of the load operation. When used with preload( ) or sendAndPreload( ), the onLoad( ) function has the added responsibility of canceling any failed preload attempts, as shown in the following example:

/*
 * Method: XML.checkLoadProgress()
 *   Desc: Checks progress of a load() or sendAndLoad() operation.
 *         Called only by preload() or sendAndPreload(). Reports progress
 *         by invoking a custom XML.onBytesLoaded() handler.
 */
XML.prototype.checkLoadProgress = function () {
  // Check how many KB have loaded.
  var kbLoaded = Math.floor(this.getBytesLoaded()/1024);
  // Check the size of the file loading, in KB.
  var kbTotal = Math.floor(this.getBytesTotal()/1024);
  // Calculate the percent complete.
  var percentDone = isNaN(Math.floor(kbLoaded/kbTotal * 100)) ?
                    0 : Math.floor(kbLoaded/kbTotal * 100);
  // Execute onBytesLoaded(), which typically would display load progress.
  this.onBytesLoaded(this.getBytesLoaded(),
                     this.getBytesTotal(),
                     kbLoaded,
                     kbTotal,
                     percentDone);
  // If the amount loaded is equal to the total file size,
  // the file is finished loading. However, we must ensure
  // that getBytesLoaded() returns a value greater than 0
  // because both getBytesLoaded() and getBytesTotal()
  // return 0 until the first bit of data arrives.
  if (this.getBytesLoaded() > 5
      && this.getBytesLoaded() =  = this.getBytesTotal()) {
    // ...stop calling checkLoadProgress().
    this.clearLoadCheck();
  }
}
   
/*
 * Method: XML.clearLoadCheck()
 *   Desc: Cancels an interval calling checkLoadProgress().
 */
XML.prototype.clearLoadCheck = function () {
  // If there is a load interval for this XML object...
  if (this.loaderID) {
    // ...stop calling it.
    clearInterval(this.loaderID);
  }
}
   
/*
 * Method: XML.preload()
 *   Desc: Begins the download of an XML file and executes
 *         checkLoadProgress() every 200 ms until the file has loaded.
 */
XML.prototype.preload = function (url) {
  // Always stop any previous preload before proceeding.
  this.clearLoadCheck();
   
  // Load the XML file.
  this.load(url);
  // Call checkLoadProgress() every 200 ms.
  this.loaderID = setInterval(this, "checkLoadProgress", 200);
}
   
/*
 * Method: XML.sendAndPreload()
 *   Desc: Sends XML to the server, and downloads the response. Executes
 *         checkLoadProgress() every 200 ms until the file has loaded.
 */
XML.prototype.sendAndPreload = function (url, resultXML) {
  // Always stop any previous preload before proceeding.
  this.clearLoadCheck();
   
  // If the target XML object is valid...
  if (resultXML instanceof XML) {
    // ...send and load the XML file.
    this.sendAndLoad(url, resultXML);
    // Call checkLoadProgress() every 200 ms.
    this.loaderID = setInterval(this, "checkLoadProgress", 200);
  }  else {
    // ...otherwise quit without performing the load.
    return false;
  }
}
   
// Usage:
// Create an XML object.
doc = new XML();
// Assign an onLoad() callback.
doc.onLoad = function (success) {
  // If the load was successful...
  if (success) {
    // ...process the new XML.
    trace("done loading!");
  } else {
    // ...otherwise, perform failure operations and
    // cancel the preload interval (REQUIRED!).
    trace("load failed");
    this.clearLoadCheck();
  }
}
// Assign an onBytesLoaded() callback. This is where each XML document
// can decide what to do with the preload information.
doc.onBytesLoaded = function (bytesLoaded, bytesTotal,
                              kbLoaded, kbTotal, percentLoaded) {
  trace("Loading: " + kbLoaded +  " of " + kbTotal);
  trace(percentLoaded + " percent complete.");
}
// Preload the XML file.
doc.preload("http://www.yoursite.org/datafiles/someInfo.xml");

See Also

setInterval( ), XML.getBytesTotal( ), XML.load( ), XML.onLoad( ), XML.sendAndLoad( )

Table of Contents