Properties | Methods
flash.external

Class ExternalInterface

Object

public class ExternalInterface
extends Object

Player version: Flash Player 8

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.



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

Properties inherited from class Object
__proto__, __resolve, constructor, prototype


Method Summary
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, hasOwnProperty, isPropertyEnumerable, isPrototypeOf, registerClass, toString, unwatch, valueOf, watch


Property Detail

available Property

public static available : Boolean  [read-only]

Player version: Flash Player 8

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.

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);



Method Detail

addCallback Method

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

Player version: Flash Player 8

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.

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 allowScriptAccess OBJECT 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 consistently 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>

call Method

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

Player version: Flash Player 8

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.

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>

Properties | Methods

Copyright © 2005 Macromedia Inc. All rights reserved.
Tue Sep 13 2005, 16:15 PDT