Table of Contents

mc._framesloaded

Description

The integer _framesloaded property indicates how many frames of mc have been loaded into the Player. It is normally used to create preloaders that pause playback until a sufficient number of frames have downloaded. For a movie clip, the _framesloaded property will equal _totalframes (because clips are loaded in their entirety before playing) unless the instance is in the process of loading an external .swf file due to a loadMovie( ) invocation. Therefore, the _framesloaded property is useful only with main movies or external .swf files loading into instances or levels. To monitor load progress in bytes rather than frames, use getBytesLoaded( ) and getBytesTotal( ).

Preloader code is traditionally placed directly on the main timeline of the movie being preloaded. A simple approach is to loop between frames 1 and 2 until the movie has loaded, at which point we send the playhead to the movie's start frame. For example:

// CODE ON FRAME 1
if (_framesloaded > 0 && _framesloaded =  = _totalframes) {
  gotoAndPlay("beginMovie");
}
   
// CODE ON FRAME 2
gotoAndPlay(1);

As of Flash 6, we can alternatively use the onEnterFrame( ) movie clip event handler to build a more portable preloader. In the movie we wish to preload, at the frame where we want preloading to start, we invoke the stop( ) function. Then, on that movie's timeline, we create a movie clip with the following onEnterFrame( ) handler:

stop();
this.createEmptyMovieClip("loader", 1);
loader.onEnterFrame = function () {
  this.loaded = this._parent._framesloaded;
  if (this.loaded > 0 && this.loaded =  = this._parent._totalframes) {
    this._parent.gotoAndPlay("beginMovie");
    this.removeMovieClip();
  }
}

In this example, the clip tracks its parent's load progress and starts its parent playing when loading has finished. By using a movie clip as a preloader, we avoid the need for a loop on the preloading movie's timeline. A movie clip preloader can even be turned into a component, providing easier workflow for less experienced developers.

Notice that in our preloader examples we checked whether _framesloaded > 0 in addition to whether _framesloaded = = _totalframes. This is necessary because when a movie is unloaded from a clip, that clip has a _totalframes of 0. Hence, if _framesloaded is 0 (as it might be on a very slow connection), the comparison _framesloaded = = _totalframes can return true even when no frames have yet loaded. Our check prevents the movie from skipping ahead before the appropriate content has loaded. This precaution is not necessary with preloaders placed on the main timeline of loading .swf files, because their _totalframes property is never 0.

The loadMovie( ) and unloadMovie( ) functions are executed asynchronously. Hence, the value of _framesloaded varies according to when it is called and the value of mc, as follows:

• If mc is undefined, _framesloaded returns undefined.

• After a loadMovie( ) or unloadMovie( ) statement occurs in source code, but before it executes, and before any of the external file has been retrieved, _framesloaded returns the number of frames in the old mc (that existed prior to the loadMovie( ) or unloadMovie( ) statement).

• Once part of the new .swf file has been retrieved, _framesloaded returns the number of frames loaded so far, from 0 to _totalframes, unless the file at url is not found.

• If the file at url is not found and mc is a movie clip, _framesloaded returns -1 and mc._totalframes stores 0. However, if mc is a document _level, then _framesloaded and _totalframes both return undefined.

• After an unloadMovie( ) command executes, _framesloaded returns 0 if mc is a movie clip, and it returns undefined if mc is a document level, such as _level0.

Example

Preloaders often include a horizontal loading bar and a text field indicating the percentage of a movie that has downloaded. Loading bars are implemented as clips, resized with either the _width property or the _xscale property. However, note that a clip scales proportionately on the right and left sides of its registration point. Therefore, to resize a clip from one side only, we must place all of the clip's content on one side of the registration point in the clip's symbol. The following example shows how to add a loading bar and a status text field to our preceding clip handler code. It draws the preload bar using the MovieClip Drawing API, but the loading code would also work with manually drawn movie clips.

// A Portable Preloader with a Status Bar
// Stop the loading movie
stop();
// Create a container clip to do the preloading
this.createEmptyMovieClip("loader", 1);
// Create load bar clips
this.loader.createEmptyMovieClip("totalBar", 2);
this.loader.createEmptyMovieClip("loadedBar", 3);
// Create a text field for output
this.loader.createTextField("loadProgress_txt", 4, 80, 10, 200, 20);
// In the load bar clips, draw a red line on top of a thicker black line
this.loader.loadedBar.lineStyle(5, 0xFF0000);
this.loader.totalBar.lineStyle(8, 0x000000);
this.loader.loadedBar.lineTo(250, 0);
this.loader.totalBar.lineTo(250, 0);
// Assign the onEnterFrame() handler that will do the preloading work
this.loader.onEnterFrame = function () {
  // Determine the percentage of bytes that have loaded
  this.percentDone = Math.floor((this._parent.getBytesLoaded()
                          / this._parent.getBytesTotal()) * 100);
  // Display the percentage of loaded bytes in our text field
  this.loadProgress_txt.text =  this.percentDone + "% complete";
  // Set the size of our loadedBar clip
  this.loadedBar._xscale = this.percentDone;
  // Check how many frames have loaded
  this.loaded = this._parent._framesloaded;
  // If loading is complete...
  if (this.loaded > 0 && this.loaded =  = this._parent._totalframes) {
    // ...start the movie, and...
    this._parent.gotoAndPlay("beginMovie");
    // ...delete the loader.
    this.removeMovieClip();
  }
}

Use the View Bandwidth Profiler command in Test Movie mode to simulate movie download for preloader testing.

See Also

MovieClip.getBytesLoaded( ), MovieClip.onData( ), MovieClip._totalframes; "The Bandwidth Profiler," in the online technote http://www.moock.org/asdg/technotes

Table of Contents