openfl

declare namespace openfl.external { /** * 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<sup>®</sup> 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](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. */ /*@:final*/ export class ExternalInterface { /** * 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. */ public static readonly available:boolean; /** * 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. */ public static marshallExceptions:boolean; /** * Returns the `id` attribute of the `object` tag in * Internet Explorer, or the `name` attribute of the * `embed` tag in Netscape. */ public static readonly objectID:string; /** * 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](http://www.adobe.com/go/devnet_security_en). * * @param functionName The name by which the container can invoke the * function. * @param 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. * @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. * @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. * To work around this problem, rewrite the * ActionScript that originally called the * `addCallback()` method so that it also * calls the `Security.allowDomain()` * method. * @throws 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: * * 1. In the `object` tag for the SWF * file in the containing HTML page, set the following * parameter: * * `<param name="allowScriptAccess" * value="always" />` * * 2. In the SWF file, add the following * ActionScript: * * * `flash.system.Security.allowDomain(_sourceDomain_)` */ public static addCallback (functionName:string, closure:any):void; /** * 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](http://www.adobe.com/go/devnet_security_en). * * **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). * * @param 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. * @return 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. * @throws 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: * * 1. In the `object` tag for the SWF * file in the containing HTML page, set the following * parameter: * * `<param name="allowScriptAccess" * value="always" />` * * 2. In the SWF file, add the following * ActionScript: * * * `flash.system.Security.allowDomain(_sourceDomain_)` */ public static call (functionName:string, ...args:any[]):any; } } export default openfl.external.ExternalInterface;