| Package | flash.external |
| Class | public final class ExternalInterface |
| Inheritance | ExternalInterface  Object |
| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Using the ExternalInterface class, you can call an ActionScript function in the Flash runtime, using JavaScript in the HTML page. The ActionScript function can return a value, and JavaScript receives it immediately as the return value of the call.
This functionality replaces the
fscommand() method.
Use the ExternalInterface class in the following combinations of browser and operating system:
| Browser | Operating System | Operating System |
|---|---|---|
| Internet Explorer 5.0 and later | Windows | |
| Netscape 8.0 and later | Windows | MacOS |
| Mozilla 1.7.5 and later | Windows | MacOS |
| Firefox 1.0 and later | Windows | MacOS |
| Safari 1.3 and later | MacOS |
Flash Player for Linux version 9.0.31.0 and later 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.
Note: When embedding SWF files within an HTML page, make sure that the id attribute is set and the
id and name attributes of the object and embed
tags do not include the following characters:
. - + * / \
Note for Flash Player applications: Flash Player version 9.0.115.0 and later allows the . (period) character
within the id and name attributes.
Note for Flash Player applications: In Flash Player 10 and later running in a browser, using this class programmatically to open a pop-up window may not be successful. Various browsers (and browser configurations) may block pop-up windows at any time; it is not possible to guarantee any pop-up window will appear. However, for the best chance of success, use this class to open a pop-up window only in code that executes as a direct result of a user action (for example, in an event handler for a mouse click or key-press event.)
From ActionScript, you can do the following on the HTML page:
- Call any JavaScript function.
- Pass any number of arguments, with any names.
- Pass various data types (Boolean, Number, String, and so on).
- Receive a return value from the JavaScript function.
From JavaScript on the HTML page, you can:
- Call an ActionScript function.
- Pass arguments using standard function call notation.
- Return a value to the JavaScript function.
Note for Flash Player applications: Flash Player does not currently support SWF files embedded within HTML forms.
Note for AIR applications: In Adobe AIR, the ExternalInterface class can be used to communicate between JavaScript in an HTML page loaded in the HTMLLoader control and ActionScript in SWF content embedded in that HTML page.
More examples
Accessing Flex from JavaScript
External API requirements and advantages
Using the ExternalInterface class
Controlling outbound URL access
Learn more
Related API Elements
Hide Inherited Public Properties
Show Inherited Public Properties| 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 | |
| marshallExceptions : Boolean = false [static]
Indicates whether the external interface should attempt to pass ActionScript exceptions to the
current browser and JavaScript exceptions to the player. | ExternalInterface | ||
| 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 SWF 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 this object, formatted according to locale-specific conventions. | Object | |
|
Returns the string representation of the specified object. | Object | |
|
Returns the primitive value of the specified object. | Object | |
available | property |
available:Boolean [read-only] | Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
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, always check that the HTML has finished loading before you attempt to call any JavaScript methods.
Implementation
public static function get available():BooleanMore examples
Example ( How to use this example )
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);
}
}
}
marshallExceptions | property |
public static var marshallExceptions:Boolean = false| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9.0.115.0, Flash Lite 4 |
Indicates whether the external interface should attempt to pass ActionScript exceptions to the
current browser and JavaScript exceptions to the player. You must explicitly set this property
to true to catch JavaScript exceptions in ActionScript and to catch ActionScript exceptions
in JavaScript.
Related API Elements
Example ( How to use this example )
addCallback() method. The new function throws
an exception so that JavaScript code running in the browser can catch it. This example also
contains a try..catch statement to catch any exceptions thrown by the browser
when the throwit() function is called.
package
{
import flash.external.*
import flash.net.*;
import flash.display.*;
import flash.system.System;
public class ext_test extends Sprite {
function ext_test():void {
ExternalInterface.marshallExceptions = true;
ExternalInterface.addCallback("g", g);
try {
ExternalInterface.call("throwit");
} catch(e:Error) {
trace(e)
}
}
function g() { throw new Error("exception from actionscript!!!!") }
}
}
objectID | property |
objectID:String [read-only] | Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Returns the id attribute of the object tag in Internet Explorer,
or the name attribute of the embed tag in Netscape.
Implementation
public static function get objectID():StringMore examples
addCallback | () | method |
public static function addCallback(functionName:String, closure:Function):void| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Registers an ActionScript method as callable from the container.
After a successful invocation of addCallback(), the registered function in
the player can be called by JavaScript or ActiveX code in the container.
Note: For local content running in a browser, calls to the
ExternalInterface.addCallback() method work only if the SWF file and the
containing web page are in the local-trusted security sandbox. For more information,
see the Flash Player Developer Center Topic: Security.
Parameters
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, you can direct the callback
at a method of a particular object instance.
Note: Repeating |
Throws
Error — The container does not support incoming calls.
Incoming calls are 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. To work around this problem, rewrite the
ActionScript that originally called the addCallback() method so that it also
calls 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, follow these steps:
|
More examples
Related API Elements
call | () | method |
public static function call(functionName:String, ... arguments):*| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4 |
Calls a function exposed by the SWF container, passing zero or
more arguments. If the function is not available, the call returns
null; otherwise it returns the value provided by the function.
Recursion is not permitted on Opera or Netscape browsers; on these browsers a recursive call
produces a null response. (Recursion is supported on Internet Explorer and Firefox browsers.)
If the container is an HTML page, this method invokes a JavaScript function
in a script element.
If the container is another ActiveX container, this method dispatches 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 the player within the HTML control. If you embed an HTML control, you can communicate with the player through a JavaScript interface to the native container application.
Note: For local content running in a browser, calls to the
ExternalInterface.call() method are permitted only 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 object and embed tags in the HTML
page that contains the SWF content. For more information, see the Flash Player Developer Center Topic:
Security.
Note for Flash Player applications: In Flash Player 10 and Flash Player 9 Update 5, some web browsers restrict this method if a pop-up blocker is enabled. In this scenario, you can only call this method successfully in response to a user event (for example, in an event handler for a mouse click or keypress event).
Parameters
functionName:String — The alphanumeric name of the function to call in the container. Using a non-alphanumeric function name
causes a runtime error (error 2155). You can use a try..catch block to handle the error.
| |
... arguments — The arguments to pass to the function in the
container. You can specify zero or more parameters, separating them with commas.
They can be of any ActionScript data type.
When the call is to a JavaScript function, the ActionScript
types are automatically converted 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, the interface is not available, a recursion occurred (with a Netscape
or Opera browser), or there is a security issue– null is returned and an error is thrown.
|
Throws
Error — The container does not support outgoing calls.
Outgoing calls are 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. To fix this problem, follow these steps:
|
More examples
Calling external code from ActionScript
Controlling outbound URL access
Example ( How to use this example )
//
// Requires:
// - A Flash Professional Label component on the Stage with an instance name of "lbl".
// - A Flash Professional Button component on the Stage with an instance name of "button".
//
var xmlResponse:String = "<invoke name=\"isReady\" returntype=\"xml\"><arguments><number>1</number><number>" + stage.stageWidth + "</number><number>" + stage.stageHeight + "</number></arguments></invoke>";
lbl.text = "ExternalInterface.available: " + ExternalInterface.available;
lbl.width = 200;
button.enabled = ExternalInterface.available;
button.addEventListener(MouseEvent.CLICK, button_click);
function button_click(evt:MouseEvent):void {
ExternalInterface.call("alert", xmlResponse);
}
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>
Mon Nov 28 2011, 06:48 AM -08:00