ExternalInterface (flash.external.ExternalInterface)

Object   |   +-flash.external.ExternalInterface public class ExternalInterface extends Object

The ExternalInterface class is the External API, an application programming interface that enables straightforward communication between ActionScript and the Flash Player container; for example, an HTML page with JavaScript, or a desktop application with Flash Player embedded.

ExternalInterface is similar in functionality to the fscommand(), CallFrame() and CallLabel() methods, but is more flexible and more generally applicable. Use of ExternalInterface is recommended for JavaScript-ActionScript communication.

From ActionScript, you can call any JavaScript function on the HTML page, passing any number of arguments of any data type, and receive a return value from the call.

From JavaScript on the HTML page, you can call an ActionScript function in Flash Player. The ActionScript function can return a value, and JavaScript receives it immediately as the return value of the call.

ExternalInterface is supported in the following combinations of browser and operating system:

Browser	Operating System
Internet Explorer 5.0 and higher	Windows
Netscape 8.0 and higher	Windows	Macintosh
Mozilla 1.7.5 and higher	Windows	Macintosh
Firefox 1.0 and higher	Windows	Macintosh
Safari 1.3 and higher		Macintosh

ExternalInterface requires the user's web browser to support either ActiveX or the NPRuntime API that is exposed by some browsers for plugin scripting. See http://www.mozilla.org/projects/plugins/npruntime.html.

Availability: ActionScript 1.0; Flash Player 8

Property summary

Modifiers	Property	Description
static	available:Boolean [read-only]	Indicates whether this player is in a container that offers an external interface.

Properties inherited from class Object

constructor (Object.constructor property),  __proto__ (Object.__proto__ property), prototype (Object.prototype property),  __resolve (Object.__resolve property)

Method summary

Modifiers	Signature	Description
static	addCallback(methodName:String, instance:Object, method:Function) : Boolean	Registers an ActionScript method as callable from the container.
static	call(methodName:String, [parameter1:Object]) : Object	Calls a function exposed by the Flash Player container, passing 0 or more arguments.

Methods inherited from class Object

addProperty (Object.addProperty method),  hasOwnProperty (Object.hasOwnProperty method), isPropertyEnumerable (Object.isPropertyEnumerable method),  isPrototypeOf (Object.isPrototypeOf method), registerClass (Object.registerClass  method), toString (Object.toString method), unwatch (Object.unwatch  method), valueOf (Object.valueOf method), watch (Object.watch method)

addCallback (ExternalInterface.addCallback method)

public static addCallback(methodName:String, instance:Object,   method:Function) : Boolean

Registers an ActionScript method as callable from the container. After a successful invocation of addCallBack(), the registered function in Flash Player can be called by JavaScript or ActiveX code in the container.

Availability: ActionScript 1.0; Flash Player 8

Parameters

methodName:String - The name by which the ActionScript function can be called from JavaScript. This name does not need to match the actual name of the ActionScript method.

instance:Object - The object to which this resolves in the method. This object is not necessarily the object on which the method can be found you can specify any object (or null).

method:Function - The ActionScript method to be called from JavaScript.

Returns

Boolean - If the call succeeded, returns TRue. If it failed because the instance was not available, a security restriction was encountered, there was no such function object, a recursion occurred, or something similar, returns false.

A return value of false may also mean that the containing environment belongs to a security sandbox to which the calling code does not have access. You can work around this problem by setting an appropriate value for the allowScriptAccessOBJECT tag or EMBED tag in the HTML of the containing environment.

Example

The following example registers the goToMacromedia() function as callable from the container with the name goHome.

import flash.external.*; var methodName:String = "goHome"; var instance:Object = null; var method:Function = goToMacromedia; var wasSuccessful:Boolean = ExternalInterface.addCallback(methodName,   instance, method); var txtField:TextField = this.createTextField("txtField",   this.getNextHighestDepth(), 0, 0, 200, 50); txtField.border = true; txtField.text = wasSuccessful.toString(); function goToMacromedia() {   txtField.text = "http://www.macromedia.com";   getURL("http://www.macromedia.com", "_self"); }

For the previous example to work properly, you should copy and paste the following code into the containing HTML page. This code relies on the id attribute of the OBJECT tag and the name attribute of the EMBED tag to have the value externalInterfaceExample. The function thisMovie returns the appropriate syntax depending on the browser, since Internet Explorer and Netscape refer to the movie object differently. Unless the HTML page is hosted on a server, your browser may alert you with a security warning.

Note

Avoid using other methods of accessing the plug-in object, such as document.getElementByID ("pluginName") or document.all.pluginName, because these other methods do not work consistantly across all browsers.

<form>   <input type="button" onclick="callExternalInterface()" value="Call   ExternalInterface" />   </form>   <script>   function callExternalInterface() {     thisMovie("externalInterfaceExample").goHome(); } function thisMovie(movieName) {   if (navigator.appName.indexOf("Microsoft") != -1) {     return window[movieName]   }   else {     return document[movieName]   } } </script>

available (ExternalInterface.available property)

public static available : Boolean [read-only]

Indicates whether this player is in a container that offers an external interface. If the external interface is available, this property is true; otherwise, it is false.

Availability: ActionScript 1.0; Flash Player 8

Example

The following example uses ExternalInterface.available to determine whether the player is in a container that offers an external interface.

import flash.external.*; var isAvailable:Boolean = ExternalInterface.available; trace(isAvailable);

call (ExternalInterface.call method)

public static call(methodName:String, [parameter1:Object]) : Object

Calls a function exposed by the Flash Player container, passing 0 or more arguments. If the desired function is not available, the call returns null; otherwise it returns the value provided by the function. Recursion is not permitted; a recursive call produces a null response.

If the container is an HTML page, this method invokes a JavaScript function in a <script> element.

If the container is some other ActiveX container, this method broadcasts an event with the specified name, and the container processes the event.

If the container is hosting the Netscape plug-in, you can either write custom support for the new NPRuntime interface or embed an HTML control and embed Flash Player within the HTML control. If you embed an HTML control, you can communicate with Flash Player through a JavaScript interface that talks to the native container application.

Availability: ActionScript 1.0; Flash Player 8

Parameters

methodName:String - The name of the function to call in the container. If the function accepts parameters, they must appear following the methodName parameter.

parameter1:Object [optional] - Any parameters to be passed to the function. You can specify zero or more parameters, separating them by commas. The parameters can be of any ActionScript data type. When the call is to a JavaScript function, the ActionScript types are automatically marshalled into JavaScript types. When the call is to some other ActiveX container, the parameters are encoded in the request message.

Returns

Object - The response received from the container. If the call failed (for example if there is no such function in the container, or the interface was not available, or a recursion occurred, or there was a security issue) null is returned.

Example

The following example calls the JavaScript function sayHello() in the HTML page that contains the SWF. The call is made by using the ExternalInterface.call() method.

import flash.external.*; var greeting:String; var btn:MovieClip = createButton(100, 30, 0xCCCCCC); btn.onPress = function() {   greeting = String(ExternalInterface.call("sayHello", "browser"));   this.mcTxt.text = greeting; // >> Hi Flash. } function createButton(width:Number, height:Number, color:Number):MovieClip   {   var depth:Number = this.getNextHighestDepth();   var mc:MovieClip = this.createEmptyMovieClip("mc_" + depth, depth);   var mcFmt:TextFormat;   mc.beginFill(color);   mc.lineTo(0, height);   mc.lineTo(width, height);   mc.lineTo(width, 0);   mc.lineTo(0, 0);   mcFmt = new TextFormat();   mcFmt.align = "center";   mcFmt.bold = true;   mc.createTextField("mcTxt", depth, 0, 0, width, height);   mc.mcTxt.text = "Call JS Function";   mc.mcTxt.setTextFormat(mcFmt);   return mc; }

For the previous example to work properly, you should be copy and paste the following code into the containing HTML page. Unless the HTML page is hosted on a server, your browser may alert you with a security warning.

<script>   function sayHello(name) {     alert(">> Hello " + name + ".");     return ">> Hi Flash.";   } </script>