Here are the first 5 pages of Chapter 28 of Essential ActionScript 3.0
28. Loading External Display Assets
In ActionScript, there are three ways to programmatically add an external display asset to an application:
* Use the flash.display.Loader class to load the asset at runtime
* Use the flash.net.Socket class in combination with the Loader class’s instance method loadBytes() to load the asset at runtime over a direct TCP/IP socket
* Use the [Embed] metadata tag to include the asset from the local file system at compile-time
The Loader and Socket classes are built-in to the Flash runtime API, while the [Embed] metadata tag requires the Flex framework. All three approaches support the following display asset formats:
* SWF (compiled Flash applications)
* JPEG, GIF, or PNG (bitmap images)
Additionally, the [Embed] metadata tag supports SVG-formatted display assets.
The Loader class replaces the following ActionScript 2.0 loading tools:
* MovieClipLoader class
* loadMovie() and loadMovieNum() global functions
* MovieClip class’s instance methods loadMovie() and loadMovieNum()
In this chapter, we’ll learn how to use Loader, Socket, and [Embed] to load external display assets. For information on loading fonts, see Chapter 27. For information on loading XML, see Chapter 18. For information on loading other non-display assets, such as variables, binary data, or sound, see the URLLoader, URLStream, and Sound class entries in Adobe’s ActionScript Language Reference.
Using Loader to Load Display Assets at Runtime
The Loader class loads an external display asset at runtime. The asset can be retrieved over HTTP or from the local file system. There are three basic steps to using the Loader class:
* Create the flash.display.Loader instance.
* Create a flash.net.URLRequest instance that specifies the asset’s location.
* Pass the URLRequest instance to the Loader instance’s load() method.
Over the next few sections we’ll create an example class, SunsetViewer, that demonstrates the preceding steps in detail. Our example class will load a single bitmap image, sunset.jpg. Once we’re comfortable with the basics of loading an asset, we’ll then examine how to monitor the progress of a load operation using the flash.display.LoaderInfo class. Finally, we’ll consider the code required to access the loaded asset and add it to the display list.
Load operations are subject to Flash Player security limitations. For complete coverage, see Chapter 19.
In our SunsetViewer example, we’ll presume that the application .swf file, SunsetViewer.swf, will be posted to a web site in the same directory as the image we’re loading sunset.jpg.
Creating the Loader Instance
As we just learned, the first step in loading any display asset at runtime using Loader is creating a Loader instance. The Loader instance manages the load operation and provides access to the loaded asset. We’ll create our Loader instance in SunsetViewer’s constructor method and assign it to an instance variable named loader, as shown in Example 28-1:
Example 28-1. Creating the Loader instance
package {
import flash.display.*;
public class SunsetViewer extends Sprite {
private var loader:Loader;
public function SunsetViewer () {
loader = new Loader(); // Create the Loader instance
}
}
}
Specifying the Asset’s Location
To load an external display asset using a Loader instance, we must specify the asset’s location with a flash.net.URLRequest object. Each individual URLRequest object describes the location of a single external resource, either on the network or the local file system. To create a URLRequest object that specifies an asset’s location, use the following general code, which assigns the asset’s location to the instance variable url:
var urlRequest:URLRequest = new URLRequest();
urlRequest.url = "theAssetURL";
Alternatively, the asset’s location can be passed to the URLRequest constructor, as in:
var url:URLRequest = new URLRequest("theAssetURL");
In both cases, theAssetURL is a string containing a standard URL. For example,
new URLRequest("http://www.example.com/image.jpg");
The set of network protocols allowed in the theAssetURL is dependent on the operating system. For example, http://, https://, and ftp:// are all supported by Windows, Macintosh, and UNIX, but a request for Windows help content (ms-its:) might be supported on Windows only. For security reasons, Flash Player might also block some protocols. However, Adobe does not currently publish a list of blocked protocols. Furthermore, ActionScript does not generate any security error messages relating specifically to protocol blocking. Hence, when working with unusual protocols, be aware that load operations involving some unusual protocols may fail silently.
In addition to specifying a URL, each URLRequest object can also provide supplementary information for requesting a resource over HTTP. To specify an HTTP request’s header, method, POST data, query string, and MIME content type, simply set the appropriate URLRequest variables, as documented in Adobe’s ActionScript Language Reference. For example, to specify an HTTP request’s headers, set the URLRequest class’s instance variable, requestHeaders.
An asset’s location can be specified as an absolute or relative URL. However, note that Flash Player’s system for resolving relative URLs varies depending on how Flash Player is launched:
* If Flash Player is launched in order to display a .swf file embedded in a web page via the <OBJECT> or <EMBED> tag, then all relative URLs are resolved in relation to that web page—not in relation to any .swf file. Further, if the web page was opened locally, relative URLs are resolved locally; if the web page was opened over the Internet, relative URLs are resolved over the Internet.
* If Flash Player is launched as a standalone application or by browsing directly to a .swf file in a Flash-enabled web browser, then all relative URLs are resolved in relation to the first .swf file opened by Flash Player—known as the stage owner. Further, if the stage owner was opened locally, relative URLs are resolved locally; if the stage owner was opened over the Internet, relative URLs are resolved over the Internet.
Even if the first .swf file opened by Flash Player is removed from the stage, it is still considered the stage owner, and still governs relative-URL resolution.
Let’s consider a relative-URL example that demonstrates the preceding two relative-URL-resolution systems. Suppose we embed an application, SunsetViewer.swf, on a web page, SunsetViewer.html, and we store those two files in the following separate directories:
/viewer/SunsetViewer.html
/viewer/assets/SunsetViewer.swf
Suppose also that from SunsetViewer.swf we want to load an image, sunset.jpg, which also resides in the /assets/ directory:
/viewer/assets/sunset.jpg
If we expect the user to view SunsetViewer.swf by browsing to the web page SunsetViewer.html, then we must compose our relative URL in relation to the web page, as follows:
new URLRequest("assets/sunset.jpg");
But if we expect the user to browse directly to SunsetViewer.swf, then we would compose our relative URL in relation to the .swf file, not the web page, as follows:
new URLRequest("sunset.jpg");
When distributing content for playback in Flash Player, compose all relative URLs according to how you expect your users to launch Flash Player.
Even when a .swf file loads another .swf file that, itself, loads external assets, relative URLs are still resolved in relation to either the stage owner (in the case of a direct launch) or the web page containing the embedded Flash Player (in the case of a web page launch). For example, suppose we open a hypothetical application, SlideShow.swf, directly in Flash Player. Next suppose SlideShow.swf loads the preceding SunsetViewer.swf example. In such a case, all relative URLs in SunsetViewer.swf would have to be composed relative to SlideShow.swf (notice: not relative to SunsetViewer.swf!). Similarly, if SlideShow.swf were viewed via a web page, then all relative URLs in SunsetViewer.swf would have to be composed relative to that web page.
You can completely avoid the issue of varying-relative-URL-resolution by storing all .html files, .swf files, and external-display-asset files in the same directory.
Now let’s return to our example SunsetViewer class. Earlier, in Example 28-1 we created a Loader instance. Example 28-2 updates the SunsetViewer class, adding code that creates a request for the relative URL "sunset.jpg". As mentioned earlier, for the sake of our example, we’ll assume that sunset.jpg is stored in the same directory as SunsetViewer.swf, thus avoiding any relative-URL complexity.
Example 28-2. Specifying the asset’s location
package {
import flash.display.*;
import flash.net.URLRequest; // Import the URLRequest class
public class SunsetViewer extends Sprite {
private var loader:Loader;
public function SunsetViewer () {
loader = new Loader();
// Specify asset location as "sunset.jpg"
var urlRequest:URLRequest = new URLRequest("sunset.jpg");
}
}
}
Now that we’ve specified the location of sunset.jpg, let’s actually load it.
[52 more pages...]
Posted by moock at June 15, 2007 05:56 PM