Introduction to using the external API

Although in some cases a SWF file can run on its own (for example, if you create a SWF projector), in the majority of cases a SWF application runs as an element inside of another application. Commonly, the container that includes the SWF is an HTML file; somewhat less frequently, a SWF file is used for all or part of the user interface of a desktop application.

As you work on more advanced applications, you may find a need to set up communication between the SWF file and the container application. For instance, it's common for a web page to display text or other information in HTML, and include a SWF file to display dynamic visual content such as a chart or video. In such a case, you might want to make it so that when users click a button on the web page, it changes something in the SWF file. ActionScript contains a mechanism, known as the external API, that facilitates this type of communication between ActionScript in a SWF file and other code in the container application.

Common external API tasks

The following common external API tasks are explained in this chapter:

• Getting information about the container application
• Using ActionScript to call code in a container application, including a web page or desktop application
• Calling ActionScript code from code in a container application
• Creating a proxy to simplify calling ActionScript code from a container application

Important concepts and terms

The following reference list contains important terms used in this chapter:

• ActiveX container: A container application (not a web browser) that includes an instance of the Flash Player ActiveX control to display SWF content within the application.
• Container application: The application within which Flash Player is running a SWF file, such as a web browser and HTML page that includes Flash Player content.
• Projector: A SWF file that has been converted into a standalone executable file including Flash Player as well as the SWF file's content. A projector can be created in Adobe Flash CS3 Professional or using the standalone Flash Player. Projectors are commonly used to distribute SWF files by CD-ROM or in similar situations where download size is not an issue and the SWF author wants to be certain the user will be able to run the SWF file, regardless of whether Flash Player is installed on the user's computer.
• Proxy: A go-between application or code that calls code in one application (the "external application") on behalf of another application (the "calling application"), and returns values to the calling application. A proxy can be used for various reasons, including:
  • To simplify the process of making external function calls by converting native function calls in the calling application into the format understood by the external application
  • To work around security or other restrictions that prevent the caller from communicating directly with the external application
• Serialize: To convert objects or data values into a format that can be used to pass the values in messages between two programming systems, such as over the Internet or between two different applications running on a single computer.