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
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.
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 |
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
* If the container is an HTML page, this method invokes a JavaScript
* function in a 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.)
* 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
|
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–
|