class flash.external.ExternalInterface

Available on all platforms

The ExternalInterface class is an application programming interface that * enables straightforward communication between ActionScript and the SWF * container– for example, an HTML page with JavaScript or a desktop * application that uses Flash Player to display a SWF file. *

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:

*

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 <a * href="http://www.mozilla.org/projects/plugins/npruntime.html" * scope="external">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.

Class Fields

static var available:Bool

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.

static var marshallExceptions:Bool

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.

static var objectID:String

Returns the id attribute of the object tag in * Internet Explorer, or the name attribute of the * embed tag in Netscape.

static function addCallback(functionName:String, closure:Dynamic):Void

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: <a href="http://www.adobe.com/go/devnetsecurityen" * scope="external">Security.

* *

functionName

The name by which the container can invoke the function.

closure

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 addCallback() * on an existing callback function with a * null closure value removes the * callback.

*

static function call(functionName:String, ?p1:Dynamic, ?p2:Dynamic, ?p3:Dynamic, ?p4:Dynamic, ?p5:Dynamic):Dynamic

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: <a * href="http://www.adobe.com/go/devnetsecurityen" * scope="external">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).

* *

functionName

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.

returns

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. *