flash.external.ExternalInterface (ActionScript 3.0)

Package	flash.external
Class	public final class ExternalInterface
Inheritance	ExternalInterface 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. Use of ExternalInterface is recommended for all JavaScript-ActionScript communication.

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 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 plug-in scripting. See http://www.mozilla.org/projects/plugins/npruntime.html.

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.

See also

flash.system.fscommand()

Public Properties

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

Public Methods

Hide Inherited Public Methods

Show Inherited Public Methods

	Function		Defined by
		addCallback(functionName:String, closure:Function):void [static] Registers an ActionScript method as callable from the container.	ExternalInterface
		call(functionName:String, ... arguments):* [static] Calls a function exposed by the Flash Player container, passing zero or more arguments.	ExternalInterface
		hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined.	Object
		isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.	Object
		propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable.	Object
		setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations.	Object
		toString():String Returns the string representation of the specified object.	Object
		valueOf():Object Returns the primitive value of the specified object.	Object

Property detail

available property

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.

Implementation
public static function get available():Boolean

Example
The following example uses the 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.

Implementation
public static function get objectID():String

Method detail

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.

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, the callback can actually be directed at a method of a particular object instance.

Throws

	`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. This may be worked around 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: In the `<object>` tag for the SWF file in the containing HTML page, set the following parameter: `<param name = "allowScriptAccess" value = "always" />` In the SWF file, add the following ActionScript: `System.security.allowDomain(sourceDomain)`

See also

flash.system.Security.allowDomain()

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.

Parameters

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

Returns

* — The response received from the container. If the call failed, such as when 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 and an error is thrown.

Throws

	`Error` — An error will be 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. This may be worked around by setting an appropriate value for `allowScriptAccess` in the containing environment (usually using the `allowScriptAccess` OBJECT/EMBED parameter in HTML).

Current page: http://livedocs.adobe.com/labs/flashauthoringpreview/flash/external/ExternalInterface.html

ActionScript 3.0 Language Reference	All Packages \| All Classes \| Language Elements \| Index \| Appendixes \| Conventions \| Frames No Frames
Class ExternalInterface	Constants \| Constants \| Properties \| Properties \| Styles \| Effects \| Events \| Constructor \| Methods \| Functions \| Interfaces \| Classes \| Use \| Examples