<?xml version="1.0"?>
<apiPackage id="flash.external"><apiName>flash.external</apiName><apiDetail/><apiClassifier id="flash.external:ExternalInterface"><apiName>ExternalInterface</apiName><shortdesc>
 The ExternalInterface class is the External API, an application programming interface
 that enables straightforward communication between ActionScript and the Flash Player
 container&amp;#8211; for example, an HTML page with JavaScript.</shortdesc><prolog><asMetadata><apiVersion><apiLanguage version="3.0"/><apiPlatform description="" name="Flash" version="9"/><apiPlatform description="" name="AIR" version="1.0"/></apiVersion></asMetadata><asCustoms><internal>Verify table is still correct and paragraph below the table still applies.
 </internal></asCustoms></prolog><apiClassifierDetail><apiClassifierDef><apiAccess value="public"/><apiStatic/><apiFinal/><apiTipTexts><apiTipText>Enables communications between ActionScript and the container.
 
 </apiTipText></apiTipTexts><apiBaseClassifier>Object</apiBaseClassifier></apiClassifierDef><apiDesc>
 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. Adobe recommends using
 ExternalInterface for all JavaScript-ActionScript communication.
 
 <p>You can call an ActionScript function in
 Flash Player, 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.</p>
 
 <p>This functionality replaces the  
 <codeph>fscommand()</codeph> method.</p>
 
 <p>Use the ExternalInterface class in the following combinations of browser and
 operating system:</p>
 <adobetable class="innertable">
 
 
 
 
 
 
 <tgroup cols="3"><thead><row><entry>Browser</entry><entry>Operating System</entry><entry>Operating System</entry></row></thead><tbody><row>
   <entry>Internet Explorer 5.0 and later</entry>
   <entry> Windows </entry>
   <entry> </entry>
 </row><row>
   <entry>Netscape 8.0 and later</entry>
   <entry> Windows </entry>
   <entry> MacOS </entry>
 </row><row>
   <entry>Mozilla 1.7.5 and later</entry>
   <entry> Windows </entry>
   <entry> MacOS </entry>
 </row><row>
   <entry>Firefox 1.0 and later</entry>
   <entry> Windows </entry>
   <entry> MacOS </entry>
 </row><row>
   <entry>Safari 1.3 and later</entry>
   <entry> </entry>
   <entry> MacOS </entry>
 </row></tbody></tgroup></adobetable>
 
 <p>Flash Player for Linux version 9.0.31.0 and later supports the ExternalInterface class in the following browsers:</p>
  <adobetable class="innertable">
    
    
    
    
  <tgroup cols="1"><thead><row><entry>Browser</entry></row></thead><tbody><row>
      <entry>Mozilla 1.7.x and later</entry>
    </row><row>
      <entry>Firefox 1.5.0.7 and later</entry>
    </row><row>
      <entry>SeaMonkey 1.0.5 and later </entry>
    </row></tbody></tgroup></adobetable>
 <p>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 <xref href="http://www.mozilla.org/projects/plugins/npruntime.html" scope="external">http://www.mozilla.org/projects/plugins/npruntime.html</xref>.</p>
 <p><b>Note:</b> When embedding SWF files within an HTML page, make sure that the <codeph>id</codeph> attribute is set and the
 <codeph>id</codeph> and <codeph>name</codeph> attributes of the <codeph>object</codeph> and <codeph>embed</codeph>
 tags do not include the following characters:</p>
 <pre>
 . - + ~~ / \
 </pre>
 <p><b>Note:</b> Flash Player version 9.0.115.0 and later allows the <codeph>.</codeph> (period) character
 within the <codeph>id</codeph> and <codeph>name</codeph> attributes.</p>
 
 <p>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.)</p>
 
 <p>From ActionScript, you can do the following on the HTML page:
 <ul> 
   <li>Call any JavaScript function.</li>
   <li>Pass any number of arguments, with any names.</li>
   <li>Pass various data types (Boolean, Number, String, and so on).</li>
   <li>Receive a return value from the JavaScript function.</li>
 </ul>
 </p>
 
 <p>From JavaScript on the HTML page, you can:
 <ul>
   <li>Call an ActionScript function.</li>
   <li>Pass arguments using standard function call notation.</li>
   <li>Return a value to the JavaScript function.</li>
 </ul>
 </p>
 
 <p>Flash Player does not currently support SWF files embedded within HTML forms.</p>
 
 <p><i>Note:</i> 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.</p>
 
 </apiDesc><example conref="examples\ExternalInterfaceExample.as"> The following example demonstrates sending data between Flash Player and an HTML container.
<codeblock>

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);
            }
        }
    }
}


</codeblock> In order to test the previous ActionScript code, embed the generated SWF file using the following HTML template:
 <codeblock rev="2.0">
 &lt;!-- saved from url=(0014)about:internet --&gt;
 &lt;html lang="en"&gt;
 &lt;head&gt;
 &lt;meta http-equiv="Content-Type" content="text/html; charset=utf-8" /&gt;
 &lt;title&gt;ExternalInterfaceExample&lt;/title&gt;
 &lt;script language="JavaScript"&gt;
     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";
     }
 &lt;/script&gt;
 &lt;/head&gt;
 &lt;body onload="pageInit();"&gt;
 
     &lt;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"&gt;
         &lt;param name="movie" value="ExternalInterfaceExample.swf" /&gt;
         &lt;param name="quality" value="high" /&gt;
         &lt;param name="bgcolor" value="#869ca7" /&gt;
         &lt;param name="allowScriptAccess" value="sameDomain" /&gt;
         &lt;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"&gt;
         &lt;/embed&gt;
     &lt;/object&gt;
 
     &lt;form name="form1" onsubmit="return false;"&gt;
         &lt;input type="text" name="input" value="" /&gt;
         &lt;input type="button" value="Send" onclick="sendToActionScript(this.form.input.value);" /&gt;&lt;br /&gt;
         &lt;textarea cols="60" rows="20" name="output" readonly="true"&gt;Initializing...&lt;/textarea&gt;
     &lt;/form&gt;
 
 &lt;/body&gt;
 &lt;/html&gt;
 </codeblock>
</example></apiClassifierDetail><related-links><link href="flash.system.xml#/fscommand()"><linktext>flash.system.fscommand()</linktext></link></related-links><apiOperation id="flash.external:ExternalInterface:addCallback"><apiName>addCallback</apiName><shortdesc>
     Registers an ActionScript method as callable from the container.</shortdesc><prolog><asMetadata><apiVersion><apiLanguage version="3.0"/><apiPlatform description="" name="Flash" version="9"/><apiPlatform description="" name="AIR" version="1.0"/></apiVersion></asMetadata></prolog><apiOperationDetail><apiOperationDef><apiAccess value="public"/><apiStatic/><apiException><apiDesc>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.
     
     </apiDesc><apiItemName>Error</apiItemName><apiOperationClassifier>Error</apiOperationClassifier></apiException><apiException><apiDesc>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 <codeph>addCallback()</codeph> method so that it also
     calls the <codeph>Security.allowDomain()</codeph> method.
     
     </apiDesc><apiItemName>SecurityError</apiItemName><apiOperationClassifier>SecurityError</apiOperationClassifier></apiException><apiException><apiDesc>The containing environment belongs to a security sandbox
     to which the calling code does not have access. To fix this problem, follow these steps:
     
     <ol>
     
      <li>In the <codeph>object</codeph> tag for the SWF file in the containing HTML page,
      set the following parameter:
     
      <p><codeph>&lt;param name="allowScriptAccess" value="always" /&gt;</codeph></p>
     
      </li>
     
      <li>In the SWF file, add the following ActionScript:
     
      <p><codeph>flash.system.Security.allowDomain(<i>sourceDomain</i>)</codeph></p>
     
      </li>
     
     </ol>
     
      
      </apiDesc><apiItemName>SecurityError</apiItemName><apiOperationClassifier>SecurityError</apiOperationClassifier></apiException><apiReturn><apiType value="void"/></apiReturn><apiParam><apiItemName>functionName</apiItemName><apiOperationClassifier>String</apiOperationClassifier><apiDesc>The name by which the container can invoke
                         the function.
     </apiDesc></apiParam><apiParam><apiItemName>closure</apiItemName><apiOperationClassifier>Function</apiOperationClassifier><apiDesc>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.
                    <p><b>Note:</b> Repeating <codeph>addCallback()</codeph> on an existing callback function 
                    with a <codeph>null</codeph> closure value removes the callback.</p>
     
     
     </apiDesc></apiParam></apiOperationDef><apiDesc>
     Registers an ActionScript method as callable from the container.
     After a successful invocation of <codeph>addCallBack()</codeph>, the registered function in
     Flash Player can be called by JavaScript or ActiveX code in the container.
     
     <p><b>Note:</b> For <i>local</i> content running in a browser, calls to the
     <codeph>ExternalInterface.addCallback()</codeph> 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: <xref href="http://www.adobe.com/go/devnet_security_en" scope="external">Security</xref>.</p>
     
     </apiDesc></apiOperationDetail><related-links><link href="flash.system.xml#Security/allowDomain()"><linktext>flash.system.Security.allowDomain()</linktext></link></related-links></apiOperation><apiOperation id="flash.external:ExternalInterface:call"><apiName>call</apiName><shortdesc> 
     Calls a function exposed by the Flash Player container, passing zero or
     more arguments.</shortdesc><prolog><asMetadata><apiVersion><apiLanguage version="3.0"/><apiPlatform description="" name="Flash" version="9"/><apiPlatform description="" name="AIR" version="1.0"/></apiVersion></asMetadata><asCustoms><internal>Should probably provide a link for the 4th paragraph above for info on Netscape.
     
     </internal></asCustoms></prolog><apiOperationDetail><apiOperationDef><apiAccess value="public"/><apiStatic/><apiException><apiDesc>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.
     
     </apiDesc><apiItemName>Error</apiItemName><apiOperationClassifier>Error</apiOperationClassifier></apiException><apiException><apiDesc>The containing environment belongs to a security sandbox
                           to which the calling code does not have access. To fix this problem, follow these steps:
     
     <ol>
     
      <li>In the <codeph>object</codeph> tag for the SWF file in the containing HTML page,
      set the following parameter:
     
      <p><codeph>&lt;param name="allowScriptAccess" value="always" /&gt;</codeph></p>
     
      </li>
     
      <li>In the SWF file, add the following ActionScript:
     
      <p><codeph>flash.system.Security.allowDomain(<i>sourceDomain</i>)</codeph></p>
     
      </li>
     
     </ol>
      
      </apiDesc><apiItemName>SecurityError</apiItemName><apiOperationClassifier>SecurityError</apiOperationClassifier></apiException><apiReturn><apiDesc>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– <codeph>null</codeph> is returned and an error is thrown.
     
     </apiDesc><apiType value="any"/></apiReturn><apiParam><apiItemName>functionName</apiItemName><apiOperationClassifier>String</apiOperationClassifier><apiDesc>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 <codeph>try..catch</codeph> block to handle the error.
     </apiDesc></apiParam><apiParam><apiItemName>arguments</apiItemName><apiType value="restParam"/><apiDesc>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.
      
     </apiDesc></apiParam><apiTipTexts><apiTipText>Calls a function in the container.
     
     </apiTipText></apiTipTexts></apiOperationDef><apiDesc> 
     Calls a function exposed by the Flash Player container, passing zero or
     more arguments.  If the function is not available, the call returns
     <codeph>null</codeph>; otherwise it returns the value provided by the function. 
     Recursion is <i>not</i> permitted on Opera or Netscape browsers; on these browsers a recursive call 
     produces a <codeph>null</codeph> response. (Recursion is supported on Internet Explorer and Firefox browsers.)
     
     <p>If the container is an HTML page, this method invokes a JavaScript function
     in a <codeph>script</codeph> element.</p>
     
     <p>If the container is another ActiveX container, this method dispatches the
     FlashCall ActiveX event with the specified name, and the container processes the event.</p>
     
     <p>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 to the native container application.</p>
     
     <p><b>Note:</b> For <i>local</i> content running in a browser, calls to the
     <codeph>ExternalInterface.call()</codeph> 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  <codeph>allowNetworking</codeph> 
     parameter of the <codeph>object</codeph> and <codeph>embed</codeph> tags in the HTML 
     page that contains the SWF content. For more information, see the Flash Player Developer Center Topic: 
     <xref href="http://www.adobe.com/go/devnet_security_en" scope="external">Security</xref>.</p>
     
     <p>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).</p>
     
     </apiDesc></apiOperationDetail></apiOperation><apiValue id="flash.external:ExternalInterface:marshallExceptions"><apiName>marshallExceptions</apiName><shortdesc>
     Indicates whether the external interface should attempt to pass ActionScript exceptions to the 
     current browser and JavaScript exceptions to Flash Player.</shortdesc><prolog><asMetadata><apiVersion><apiLanguage version="3.0"/><apiPlatform description="" name="Flash" version="9.0.115.0"/><apiPlatform description="" name="AIR" version="1.0"/></apiVersion></asMetadata></prolog><apiValueDetail><apiValueDef><apiProperty/><apiAccess value="public"/><apiStatic/><apiData>false</apiData><apiValueClassifier>Boolean</apiValueClassifier><apiTipTexts><apiTipText>Passes exceptions between AS and JS.     
     </apiTipText></apiTipTexts></apiValueDef><apiDesc>
     Indicates whether the external interface should attempt to pass ActionScript exceptions to the 
     current browser and JavaScript exceptions to Flash Player. You must explicitly set this property
     to <codeph>true</codeph> to catch JavaScript exceptions in ActionScript and to catch ActionScript exceptions
     in JavaScript.
     
     </apiDesc><example conref="examples\ExternalInterface.marshallExceptions.1.as"> The following example creates an ActionScript function and registers it with 
 the containing browser by using the <codeph>addCallback()</codeph> method. The new function throws 
 an exception so that JavaScript code running in the browser can catch it. This example also
 contains a <codeph>try..catch</codeph> statement to catch any exceptions thrown by the browser
 when the <codeph>throwit()</codeph> function is called.
<codeblock>

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!!!!") }
    }
}
</codeblock></example></apiValueDetail><related-links><link href="flash.external.xml#ExternalInterface/addCallBack()"><linktext>addCallBack()</linktext></link><link href="../../statements.html#try..catch..finally"><linktext>try..catch..finally statement</linktext></link></related-links></apiValue><apiValue id="flash.external:ExternalInterface:available:get"><apiName>available</apiName><shortdesc>
     Indicates whether this player is in a container that offers an external interface.</shortdesc><prolog><asMetadata><apiVersion><apiLanguage version="3.0"/><apiPlatform description="" name="Flash" version="9"/><apiPlatform description="" name="AIR" version="1.0"/></apiVersion></asMetadata></prolog><apiValueDetail><apiValueDef><apiProperty/><apiAccess value="public"/><apiStatic/><apiValueAccess value="read"/><apiValueClassifier>Boolean</apiValueClassifier><apiTipTexts><apiTipText>Indicates if the Flash Player is in a container that offers an external interface.
     
     </apiTipText></apiTipTexts></apiValueDef><apiDesc>
     Indicates whether this player is in a container that offers an external interface.
     If the external interface is available, this property is <codeph>true</codeph>; otherwise,
     it is <codeph>false</codeph>.
     
     <p><b>Note:</b> When using the External API with HTML, always check that the HTML 
     has finished loading before you attempt to call any JavaScript methods.</p>
     
     </apiDesc><example>The following example uses the <codeph>available</codeph> property to
     determine whether the player is in a container that offers an external interface.
     <codeblock rev="3.0">
     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);
         }
       }
     }
     </codeblock>
     
      
      </example></apiValueDetail></apiValue><apiValue id="flash.external:ExternalInterface:objectID:get"><apiName>objectID</apiName><shortdesc>
     Returns the id attribute of the object tag in Internet Explorer,
     or the name attribute of the embed tag in Netscape.</shortdesc><prolog><asMetadata><apiVersion><apiLanguage version="3.0"/><apiPlatform description="" name="Flash" version="9"/><apiPlatform description="" name="AIR" version="1.0"/></apiVersion></asMetadata></prolog><apiValueDetail><apiValueDef><apiProperty/><apiAccess value="public"/><apiStatic/><apiValueAccess value="read"/><apiValueClassifier>String</apiValueClassifier></apiValueDef><apiDesc>
     Returns the <codeph>id</codeph> attribute of the <codeph>object</codeph> tag in Internet Explorer,
     or the <codeph>name</codeph> attribute of the <codeph>embed</codeph> tag in Netscape.
     </apiDesc></apiValueDetail></apiValue></apiClassifier></apiPackage>