ProLoader  - AS3 Flash

Contains the root display object of the SWF file or image (JPG, PNG, or GIF) file that was loaded by using the load() or loadBytes() methods.

Returns a ProLoaderInfo object corresponding to the object being loaded. ProLoaderInfo objects are shared between the ProLoader object and the loaded content object. The ProLoaderInfo object supplies loading progress information and statistics about the loaded file.

Events related to the load are dispatched by the ProLoaderInfo object referenced by the contentLoaderInfo property of the ProLoader object. The contentLoaderInfo property is set to a valid ProLoaderInfo object, even before the content is loaded, so that you can add event listeners to the object prior to the load.

To detect uncaught errors that happen in a loaded SWF, use the ProLoader.uncaughtErrorEvents property, not the ProLoader.contentLoaderInfo.uncaughtErrorEvents property.

Note The contentLoaderInfo property returns a ProLoaderInfo object. ProLoaderInfo is not a subclass of LoaderInfo and hence does not give you the advantage of an implicit cast to the super-class. Therefore, be sure to change your type declarations from LoaderInfo to ProLoaderInfo.

An object that dispatches an uncaughtError event when an unhandled error occurs in code in this ProLoader object's SWF file. An uncaught error happens when an error is thrown outside of any try..catch blocks or when an ErrorEvent object is dispatched with no registered listeners.

This property is created when the SWF associated with this object has finished loading. Until then the uncaughtErrorEvents property is null. In an ActionScript-only project, you can access this property during or after the execution of the constructor function of the main class of the SWF file.

Accessing this ProLoader property in a player that does not support it results in an error. Returns an EventDispatcher object instead of an UncaughtErrorEvents object to avoid generating errors in unsupporting players.

Related API Elements

Creates a ProLoader object that you can use to load files, such as SWF, JPEG, GIF, or PNG files. Call the load() method to load the asset as a child of the ProLoader instance. You can then add the ProLoader object to the display list (for instance, by using the addChild() method of a DisplayObjectContainer instance). The asset appears on the stage as it loads.

You can also use a ProLoader instance "offlist," that is without adding it to a display object container on the display list. In this mode, the Loader instance might be used to load a SWF file that contains additional modules of an application.

To detect when the SWF file is finished loading, you can use the events of the ProLoaderInfo object associated with the contentLoaderInfo property of the ProLoader object. At that point, the code in the module SWF file can be executed to initialize and start the module. In the offlist mode, a ProLoader instance might also be used to load a SWF file that contains components or media assets. Again, you can use the ProLoaderInfo object event notifications to detect when the components are finished loading. At that point, the application can start using the components and media assets in the library of the SWF file by instantiating the ActionScript 3.0 classes that represent those components and assets.

To determine the status of a ProLoader object, monitor the following events that the ProLoaderInfo object associated with the contentLoaderInfo property of the ProLoader object:

• The open event is dispatched when loading begins.
• The ioError or securityError event is dispatched if the file cannot be loaded or if an error occured during the load process.
• The progress event fires continuously while the file is being loaded.
• The complete event is dispatched when a file completes downloading, but before the loaded movie clip's methods and properties are available. If the loaded SWF file uses RSL preloading, this event is dispatched after RSL preloading completes. At this point, real content is available in the content property.
• The init event is dispatched after the properties and methods of the loaded SWF file are accessible, so you can begin manipulating the loaded SWF file. This event is dispatched before the complete handler. In streaming SWF files, the init event can occur significantly earlier than the complete event. For most purposes, use the init handler. If the loaded SWF file uses RSL preloading, this event is dispatched after RSL preloading completes. At this point, real content is available in the content property.

Related API Elements

Cancels a load() method operation that is currently in progress for the ProLoader instance.

Loads a SWF, JPEG, progressive JPEG, unanimated GIF, or PNG file into an object that is a child of this ProLoader object. If you load an animated GIF file, only the first frame is displayed. As the ProLoader object can contain only a single child, issuing a subsequent load() request terminates the previous request, if still pending, and commences a new load.

Note: In AIR 1.5 and Flash Player 10, the maximum size for a loaded image is 8,191 pixels in width or height, and the total number of pixels cannot exceed 16,777,215 pixels. (So, if an loaded image is 8,191 pixels wide, it can only be 2,048 pixels high.) In Flash Player 9 and earlier and AIR 1.1 and earlier, the limitation is 2,880 pixels in height and 2,880 pixels in width.

A SWF file or image loaded into a ProLoader object inherits the position, rotation, and scale properties of the parent display objects of the ProLoader object.

Use the unload() method to remove movies or images loaded with this method, or to cancel a load operation that is in progress.

You can prevent a SWF file from using this method by setting the allowNetworking parameter of the the object and embed tags in the HTML page that contains the SWF content.

When you use this method, consider the Flash Player security model, which is described in the ProLoader class description.

In Flash Player 10 and later, if you use a multipart Content-Type (for example "multipart/form-data") that contains an upload (indicated by a "filename" parameter in a "content-disposition" header within the POST body), the POST operation is subject to the security rules applied to uploads:

• The POST operation must be performed in response to a user-initiated action, such as a mouse click or key press.
• If the POST operation is cross-domain (the POST target is not on the same server as the SWF file that is sending the POST request), the target server must provide a URL policy file that permits cross-domain access.

Also, for any multipart Content-Type, the syntax must be valid (according to the RFC2046 standard). If the syntax appears to be invalid, the POST operation is subject to the security rules applied to uploads.

For more information related to security, see the Flash Player Developer Center Topic: Security.

Parameters

Related API Elements

Loads from binary data stored in a ByteArray object.

The loadBytes() method is asynchronous. You must wait for the "init" event before accessing the properties of a loaded object.

When you use this method, consider the Flash Player security model, which is described in the ProLoader class description.

Parameters

Related API Elements

Loads an IFilePromise instance through the promise parameter. The type of the promise parameter uses the Object superclass instead of IFilePromise to avoid errors in other players.

The loadFilePromise method takes an IFilePromise object and loads the binary data. If the data is a progressive stream, such as a video wait for the "init" or progress events before accessing the properties of the loaded object. Otherwise, wait for the complete event to make sure that the data is fully loaded.

When you use this method, consider the Flash Player security model, which is described in the ProLoader class description.

Parameters

Related API Elements

Removes a child of this ProLoader object that was loaded by using the load() method. The property of the associated ProLoaderInfo object is reset to null. The child is not necessarily destroyed because other objects might have references to it; however, it is no longer a child of the ProLoader object.

As a best practice, before you unload a child SWF file, you should explicitly close any streams in the child SWF file's objects, such as LocalConnection, NetConnection, NetStream, and Sound objects. Otherwise, audio in the child SWF file might continue to play, even though the child SWF file was unloaded. To close streams in the child SWF file, add an event listener to the child that listens for the unload event. When the parent calls ProLoader.unload(), the unload event is dispatched to the child. The following code shows how you might do this:

function closeAllStreams(evt:Event) { 
    myNetStream.close();
    mySound.close();
    myNetConnection.close();
    myLocalConnection.close();
}

myMovieClip.loaderInfo.addEventListener(Event.UNLOAD, closeAllStreams);

Related API Elements