| Package | flash.external |
| Class | public final class ExternalInterface |
| Inheritance | ExternalInterface  Object |
Using 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.
This functionality is a replacement for the older
fscommand() method.
ExternalInterface is supported in the following combinations of browser and operating system:
| Browser | Operating System | |
|---|---|---|
| Internet Explorer 5.0 and later | Windows | |
| Netscape 8.0 and later | Windows | Macintosh |
| Mozilla 1.7.5 and later | Windows | Macintosh |
| Firefox 1.0 and later | Windows | Macintosh |
| Safari 1.3 and later | Macintosh | |
Flash Player versions 9.0.31.0 and newer running on Linux supports the ExternalInterface class in the following browsers:
| Browser |
|---|
| Mozilla 1.7.x and later |
| Firefox 1.5.0.7 and later |
| SeaMonkey 1.0.5 and later |
The ExternalInterface class requires the user's web browser to support either ActiveX or the NPRuntime API that is exposed by some browsers for plug-in scripting. Even if a browser and operating system combination are not listed above, they should support the ExternalInterface class if they support the NPRuntime API. See http://www.mozilla.org/projects/plugins/npruntime.html.
[added information about supported Linux browsers and possible others supporting the NPRuntime API: 7/11/07]
Note: When embedding SWF files within an HTML page, make sure that the
id and name attributes of the <object> and <embed>
tags do not include characters such as: . (period), -, +, *, /, and \.
From ActionScript, you can do the following on the HTML page:
From JavaScript on the HTML page, you can:
Note: Flash Player does not currently support SWF files embedded within HTML forms.
See also
| Property | Defined by | ||
|---|---|---|---|
| available : Boolean
[static][read-only]
Indicates whether this player is in a container that offers an external interface.
| ExternalInterface | ||
 | constructor : Object
A reference to the class object or constructor function for a given object instance.
| Object | |
| objectID : String
[static][read-only]
Returns the
id attribute of the <object> tag in Internet Explorer,
or the name attribute of the <embed> tag in Netscape. | ExternalInterface | ||
| prototype : Object
[static]
A reference to the prototype object of a class or function object.
| Object | |
| Method | Defined by | ||
|---|---|---|---|
|
[static]
Registers an ActionScript method as callable from the container.
| ExternalInterface | ||
|
[static]
Calls a function exposed by the Flash Player container, passing zero or
more arguments.
| ExternalInterface | ||
|
Indicates whether an object has a specified property defined.
| Object | |
|
Indicates whether an instance of the Object class is in the prototype chain of the object specified
as the parameter.
| Object | |
|
Indicates whether the specified property exists and is enumerable.
| Object | |
|
Sets the availability of a dynamic property for loop operations.
| Object | |
|
Returns the string representation of the specified object.
| Object | |
|
Returns the primitive value of the specified object.
| Object | |
| available | property |
Hide Inherited Public Properties
Show Inherited Public Propertiesavailable: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.
Note: When using the External API with HTML, you should always check that the HTML has fully loaded before attempting to call any JavaScript methods.
Implementation public static function get available():Boolean
See also
available property to
determine whether the player is in a container that offers an external interface.
package {
import flash.text.TextField;
import flash.display.MovieClip;
import flash.external.ExternalInterface;
public class extint_test extends MovieClip {
public function extint_test() {
var isAvailable:Boolean = ExternalInterface.available;
var availTxt:TextField = new TextField();
availTxt.text = isAvailable.toString();
addChild(availTxt);
}
}
}
| objectID | property |
objectID:String [read-only]
Returns the id attribute of the <object> tag in Internet Explorer,
or the name attribute of the <embed> tag in Netscape.
public static function get objectID():String
See also
| addCallback | () | method |
public static function addCallback(functionName:String, closure:Function):void
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.
Security note: For local content running in a browser, calls to the
ExternalInterface.addCallback() method will only work if the SWF file and the
containing web page are in the local-trusted security sandbox. For more information,
see the following:
functionName:String — The name by which the container can invoke
the function.
|
|
closure:Function — The function closure to invoke. This could be a
free-standing function, or it could be a method closure
referencing a method of an object instance. By passing
a method closure, the callback can actually be directed
at a method of a particular object instance.
|
Error — An error is thrown if the container does not support incoming calls.
This is supported only in Internet Explorer for Windows and browsers
that use the NPRuntime API such as Mozilla 1.7.5 and later or Firefox 1.0 and later.
|
|
SecurityError — A callback with the specified name has already been
added by ActionScript in a sandbox to which you do not have access; you
cannot overwrite that callback. You can work around this by having the
ActionScript that originally called the addCallback() method also call the Security.allowDomain() method.
|
|
SecurityError — The containing environment belongs to a security sandbox
to which the calling code does not have access. To fix this problem:
|
See also
| call | () | method |
public static function call(functionName:String, ... arguments):*
Calls a function exposed by the Flash Player container, passing zero 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 fires the FlashCall ActiveX 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.
Security note: For local content running in a browser, calls to the
ExternalInterface.call() method are only permitted if the SWF file and the
containing web page (if there is one) are in the local-trusted security sandbox. Also, 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. For more information, see the following:
functionName:String — The name of the function to call in the container.
|
|
... arguments — The arguments to pass to the function in the
container. You can specify zero or more parameters, separating them by commas.
They may be of any ActionScript data type.
When the call is to a JavaScript function, the ActionScript
types are automatically marshaled into JavaScript types; when the call is to some other
ActiveX container, the parameters are encoded in the request message.
|
* — The response received from the container. If the call failed -- for example, if there is no such
function in the container, or the interface is not available, or a recursion occurred, or there
is a security issue, null is returned and an error is thrown.
|
Error — An error is thrown if the container does not support outgoing calls.
This is supported only in Internet Explorer for Windows and browsers
that use the NPRuntime API such as Mozilla 1.7.5 and later or Firefox 1.0 and later.
|
|
SecurityError — The containing environment belongs to a security sandbox
to which the calling code does not have access. You can work around this by
setting an appropriate value for allowScriptAccess in the containing
environment (usually by using the allowScriptAccess
<object>/<embed> tags in HTML).
|
See also
package {
import flash.display.Sprite;
import flash.events.*;
import flash.external.ExternalInterface;
import flash.text.TextField;
import flash.utils.Timer;
import flash.text.TextFieldType;
import flash.text.TextFieldAutoSize;
public class ExternalInterfaceExample extends Sprite {
private var input:TextField;
private var output:TextField;
private var sendBtn:Sprite;
public function ExternalInterfaceExample() {
input = new TextField();
input.type = TextFieldType.INPUT;
input.background = true;
input.border = true;
input.width = 350;
input.height = 18;
addChild(input);
sendBtn = new Sprite();
sendBtn.mouseEnabled = true;
sendBtn.x = input.width + 10;
sendBtn.graphics.beginFill(0xCCCCCC);
sendBtn.graphics.drawRoundRect(0, 0, 80, 18, 10, 10);
sendBtn.graphics.endFill();
sendBtn.addEventListener(MouseEvent.CLICK, clickHandler);
addChild(sendBtn);
output = new TextField();
output.y = 25;
output.width = 450;
output.height = 325;
output.multiline = true;
output.wordWrap = true;
output.border = true;
output.text = "Initializing...\n";
addChild(output);
if (ExternalInterface.available) {
try {
output.appendText("Adding callback...\n");
ExternalInterface.addCallback("sendToActionScript", receivedFromJavaScript);
if (checkJavaScriptReady()) {
output.appendText("JavaScript is ready.\n");
} else {
output.appendText("JavaScript is not ready, creating timer.\n");
var readyTimer:Timer = new Timer(100, 0);
readyTimer.addEventListener(TimerEvent.TIMER, timerHandler);
readyTimer.start();
}
} catch (error:SecurityError) {
output.appendText("A SecurityError occurred: " + error.message + "\n");
} catch (error:Error) {
output.appendText("An Error occurred: " + error.message + "\n");
}
} else {
output.appendText("External interface is not available for this container.");
}
}
private function receivedFromJavaScript(value:String):void {
output.appendText("JavaScript says: " + value + "\n");
}
private function checkJavaScriptReady():Boolean {
var isReady:Boolean = ExternalInterface.call("isReady");
return isReady;
}
private function timerHandler(event:TimerEvent):void {
output.appendText("Checking JavaScript status...\n");
var isReady:Boolean = checkJavaScriptReady();
if (isReady) {
output.appendText("JavaScript is ready.\n");
Timer(event.target).stop();
}
}
private function clickHandler(event:MouseEvent):void {
if (ExternalInterface.available) {
ExternalInterface.call("sendToJavaScript", input.text);
}
}
}
}
<!-- saved from url=(0014)about:internet -->
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>ExternalInterfaceExample</title>
<script language="JavaScript">
var jsReady = false;
function isReady() {
return jsReady;
}
function pageInit() {
jsReady = true;
document.forms["form1"].output.value += "\n" + "JavaScript is ready.\n";
}
function thisMovie(movieName) {
if (navigator.appName.indexOf("Microsoft") != -1) {
return window[movieName];
} else {
return document[movieName];
}
}
function sendToActionScript(value) {
thisMovie("ExternalInterfaceExample").sendToActionScript(value);
}
function sendToJavaScript(value) {
document.forms["form1"].output.value += "ActionScript says: " + value + "\n";
}
</script>
</head>
<body onload="pageInit();">
<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
id="ExternalInterfaceExample" width="500" height="375"
codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab">
<param name="movie" value="ExternalInterfaceExample.swf" />
<param name="quality" value="high" />
<param name="bgcolor" value="#869ca7" />
<param name="allowScriptAccess" value="sameDomain" />
<embed src="ExternalInterfaceExample.swf" quality="high" bgcolor="#869ca7"
width="500" height="375" name="ExternalInterfaceExample" align="middle"
play="true" loop="false" quality="high" allowScriptAccess="sameDomain"
type="application/x-shockwave-flash"
pluginspage="http://www.macromedia.com/go/getflashplayer">
</embed>
</object>
<form name="form1" onsubmit="return false;">
<input type="text" name="input" value="" />
<input type="button" value="Send" onclick="sendToActionScript(this.form.input.value);" /><br />
<textarea cols="60" rows="20" name="output" readonly="true">Initializing...</textarea>
</form>
</body>
</html>
Send me an e-mail when comments are added to this page | Comment Report
Current page: http://livedocs.adobe.com/flex/201/langref/flash/external/ExternalInterface.html