Index: openacs-4/packages/ajaxhelper/www/resources/dojo-ajax/src/flash.js =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/ajaxhelper/www/resources/dojo-ajax/src/Attic/flash.js,v diff -u -r1.1 -r1.2 --- openacs-4/packages/ajaxhelper/www/resources/dojo-ajax/src/flash.js 6 Nov 2006 14:37:20 -0000 1.1 +++ openacs-4/packages/ajaxhelper/www/resources/dojo-ajax/src/flash.js 25 Dec 2006 16:39:51 -0000 1.2 @@ -14,285 +14,289 @@ dojo.require("dojo.uri.*"); dojo.require("dojo.html.common"); -/** - The goal of dojo.flash is to make it easy to extend Flash's capabilities - into an AJAX/DHTML environment. Robust, performant, reliable - JavaScript/Flash communication is harder than most realize when they - delve into the topic, especially if you want it - to work on Internet Explorer, Firefox, and Safari, and to be able to - push around hundreds of K of information quickly. Dojo.flash makes it - possible to support these platforms; you have to jump through a few - hoops to get its capabilites, but if you are a library writer - who wants to bring Flash's storage or streaming sockets ability into - DHTML, for example, then dojo.flash is perfect for you. - - Dojo.flash provides an easy object for interacting with the Flash plugin. - This object provides methods to determine the current version of the Flash - plugin (dojo.flash.info); execute Flash instance methods - independent of the Flash version - being used (dojo.flash.comm); write out the necessary markup to - dynamically insert a Flash object into the page (dojo.flash.Embed; and - do dynamic installation and upgrading of the current Flash plugin in - use (dojo.flash.Install). - - To use dojo.flash, you must first wait until Flash is finished loading - and initializing before you attempt communication or interaction. - To know when Flash is finished use dojo.event.connect: - - dojo.event.connect(dojo.flash, "loaded", myInstance, "myCallback"); - - Then, while the page is still loading provide the file name - and the major version of Flash that will be used for Flash/JavaScript - communication (see "Flash Communication" below for information on the - different kinds of Flash/JavaScript communication supported and how they - depend on the version of Flash installed): - - dojo.flash.setSwf({flash6: "src/storage/storage_flash6.swf", - flash8: "src/storage/storage_flash8.swf"}); - - This will cause dojo.flash to pick the best way of communicating - between Flash and JavaScript based on the platform. - - If no SWF files are specified, then Flash is not initialized. - - Your Flash must use DojoExternalInterface to expose Flash methods and - to call JavaScript; see "Flash Communication" below for details. - - setSwf can take an optional 'visible' attribute to control whether - the Flash object is visible or not on the page; the default is visible: - - dojo.flash.setSwf({flash6: "src/storage/storage_flash6.swf", - flash8: "src/storage/storage_flash8.swf", - visible: false}); - - Once finished, you can query Flash version information: - - dojo.flash.info.version - - Or can communicate with Flash methods that were exposed: - - var results = dojo.flash.comm.sayHello("Some Message"); - - Only string values are currently supported for both arguments and - for return results. Everything will be cast to a string on both - the JavaScript and Flash sides. - - ------------------- - Flash Communication - ------------------- - - dojo.flash allows Flash/JavaScript communication in - a way that can pass large amounts of data back and forth reliably and - very fast. The dojo.flash - framework encapsulates the specific way in which this communication occurs, - presenting a common interface to JavaScript irrespective of the underlying - Flash version. - - There are currently three major ways to do Flash/JavaScript communication - in the Flash community: - - 1) Flash 6+ - Uses Flash methods, such as SetVariable and TCallLabel, - and the fscommand handler to do communication. Strengths: Very fast, - mature, and can send extremely large amounts of data; can do - synchronous method calls. Problems: Does not work on Safari; works on - Firefox/Mac OS X only if Flash 8 plugin is installed; cryptic to work with. - - 2) Flash 8+ - Uses ExternalInterface, which provides a way for Flash - methods to register themselves for callbacks from JavaScript, and a way - for Flash to call JavaScript. Strengths: Works on Safari; elegant to - work with; can do synchronous method calls. Problems: Extremely buggy - (fails if there are new lines in the data, for example); performance - degrades drastically in O(n^2) time as data grows; locks up the browser while - it is communicating; does not work in Internet Explorer if Flash - object is dynamically added to page with document.writeln, DOM methods, - or innerHTML. - - 3) Flash 6+ - Uses two seperate Flash applets, one that we - create over and over, passing input data into it using the PARAM tag, - which then uses a Flash LocalConnection to pass the data to the main Flash - applet; communication back to Flash is accomplished using a getURL - call with a javascript protocol handler, such as "javascript:myMethod()". - Strengths: the most cross browser, cross platform pre-Flash 8 method - of Flash communication known; works on Safari. Problems: Timing issues; - clunky and complicated; slow; can only send very small amounts of - data (several K); all method calls are asynchronous. - - dojo.flash.comm uses only the first two methods. This framework - was created primarily for dojo.storage, which needs to pass very large - amounts of data synchronously and reliably across the Flash/JavaScript - boundary. We use the first method, the Flash 6 method, on all platforms - that support it, while using the Flash 8 ExternalInterface method - only on Safari with some special code to help correct ExternalInterface's - bugs. - - Since dojo.flash needs to have two versions of the Flash - file it wants to generate, a Flash 6 and a Flash 8 version to gain - true cross-browser compatibility, several tools are provided to ease - development on the Flash side. - - In your Flash file, if you want to expose Flash methods that can be - called, use the DojoExternalInterface class to register methods. This - class is an exact API clone of the standard ExternalInterface class, but - can work in Flash 6+ browsers. Under the covers it uses the best - mechanism to do communication: - - class HelloWorld{ - function HelloWorld(){ - // Initialize the DojoExternalInterface class - DojoExternalInterface.initialize(); - - // Expose your methods - DojoExternalInterface.addCallback("sayHello", this, this.sayHello); - - // Tell JavaScript that you are ready to have method calls - DojoExternalInterface.loaded(); - - // Call some JavaScript - var resultsReady = function(results){ - trace("Received the following results from JavaScript: " + results); - } - DojoExternalInterface.call("someJavaScriptMethod", resultsReady, - someParameter); - } - - function sayHello(){ ... } - - static main(){ ... } - } - - DojoExternalInterface adds two new functions to the ExternalInterface - API: initialize() and loaded(). initialize() must be called before - any addCallback() or call() methods are run, and loaded() must be - called after you are finished adding your callbacks. Calling loaded() - will fire the dojo.flash.loaded() event, so that JavaScript can know that - Flash has finished loading and adding its callbacks, and can begin to - interact with the Flash file. - - To generate your SWF files, use the ant task - "buildFlash". You must have the open source Motion Twin ActionScript - compiler (mtasc) installed and in your path to use the "buildFlash" - ant task; download and install mtasc from http://www.mtasc.org/. - - - - buildFlash usage: - - ant buildFlash -Ddojo.flash.file=../tests/flash/HelloWorld.as - - where "dojo.flash.file" is the relative path to your Flash - ActionScript file. - - This will generate two SWF files, one ending in _flash6.swf and the other - ending in _flash8.swf in the same directory as your ActionScript method: - - HelloWorld_flash6.swf - HelloWorld_flash8.swf - - Initialize dojo.flash with the filename and Flash communication version to - use during page load; see the documentation for dojo.flash for details: - - dojo.flash.setSwf({flash6: "tests/flash/HelloWorld_flash6.swf", - flash8: "tests/flash/HelloWorld_flash8.swf"}); - - Now, your Flash methods can be called from JavaScript as if they are native - Flash methods, mirrored exactly on the JavaScript side: - - dojo.flash.comm.sayHello(); - - Only Strings are supported being passed back and forth currently. - - JavaScript to Flash communication is synchronous; i.e., results are returned - directly from the method call: - - var results = dojo.flash.comm.sayHello(); - - Flash to JavaScript communication is asynchronous due to limitations in - the underlying technologies; you must use a results callback to handle - results returned by JavaScript in your Flash AS files: - - var resultsReady = function(results){ - trace("Received the following results from JavaScript: " + results); - } - DojoExternalInterface.call("someJavaScriptMethod", resultsReady); - - - - ------------------- - Notes - ------------------- - - If you have both Flash 6 and Flash 8 versions of your file: - - dojo.flash.setSwf({flash6: "tests/flash/HelloWorld_flash6.swf", - flash8: "tests/flash/HelloWorld_flash8.swf"}); - - but want to force the browser to use a certain version of Flash for - all platforms (for testing, for example), use the djConfig - variable 'forceFlashComm' with the version number to force: - - var djConfig = { forceFlashComm: 6 }; - - Two values are currently supported, 6 and 8, for the two styles of - communication described above. Just because you force dojo.flash - to use a particular communication style is no guarantee that it will - work; for example, Flash 8 communication doesn't work in Internet - Explorer due to bugs in Flash, and Flash 6 communication does not work - in Safari. It is best to let dojo.flash determine the best communication - mechanism, and to use the value above only for debugging the dojo.flash - framework itself. - - Also note that dojo.flash can currently only work with one Flash object - on the page; it and the API do not yet support multiple Flash objects on - the same page. - - We use some special tricks to get decent, linear performance - out of Flash 8's ExternalInterface on Safari; see the blog - post - http://codinginparadise.org/weblog/2006/02/how-to-speed-up-flash-8s.html - for details. - - Your code can detect whether the Flash player is installing or having - its version revved in two ways. First, if dojo.flash detects that - Flash installation needs to occur, it sets dojo.flash.info.installing - to true. Second, you can detect if installation is necessary with the - following callback: - - dojo.event.connect(dojo.flash, "installing", myInstance, "myCallback"); - - You can use this callback to delay further actions that might need Flash; - when installation is finished the full page will be refreshed and the - user will be placed back on your page with Flash installed. - - Two utility methods exist if you want to add loading and installing - listeners without creating dependencies on dojo.event; these are - 'addLoadingListener' and 'addInstallingListener'. - - ------------------- - Todo/Known Issues - ------------------- +dojo.flash = function(){ + // summary: + // The goal of dojo.flash is to make it easy to extend Flash's capabilities + // into an AJAX/DHTML environment. + // description: + // The goal of dojo.flash is to make it easy to extend Flash's capabilities + // into an AJAX/DHTML environment. Robust, performant, reliable + // JavaScript/Flash communication is harder than most realize when they + // delve into the topic, especially if you want it + // to work on Internet Explorer, Firefox, and Safari, and to be able to + // push around hundreds of K of information quickly. Dojo.flash makes it + // possible to support these platforms; you have to jump through a few + // hoops to get its capabilites, but if you are a library writer + // who wants to bring Flash's storage or streaming sockets ability into + // DHTML, for example, then dojo.flash is perfect for you. + // + // Dojo.flash provides an easy object for interacting with the Flash plugin. + // This object provides methods to determine the current version of the Flash + // plugin (dojo.flash.info); execute Flash instance methods + // independent of the Flash version + // being used (dojo.flash.comm); write out the necessary markup to + // dynamically insert a Flash object into the page (dojo.flash.Embed; and + // do dynamic installation and upgrading of the current Flash plugin in + // use (dojo.flash.Install). + // + // To use dojo.flash, you must first wait until Flash is finished loading + // and initializing before you attempt communication or interaction. + // To know when Flash is finished use dojo.event.connect: + // + // dojo.event.connect(dojo.flash, "loaded", myInstance, "myCallback"); + // + // Then, while the page is still loading provide the file name + // and the major version of Flash that will be used for Flash/JavaScript + // communication (see "Flash Communication" below for information on the + // different kinds of Flash/JavaScript communication supported and how they + // depend on the version of Flash installed): + // + // dojo.flash.setSwf({flash6: "src/storage/storage_flash6.swf", + // flash8: "src/storage/storage_flash8.swf"}); + // + // This will cause dojo.flash to pick the best way of communicating + // between Flash and JavaScript based on the platform. + // + // If no SWF files are specified, then Flash is not initialized. + // + // Your Flash must use DojoExternalInterface to expose Flash methods and + // to call JavaScript; see "Flash Communication" below for details. + // + // setSwf can take an optional 'visible' attribute to control whether + // the Flash object is visible or not on the page; the default is visible: + // + // dojo.flash.setSwf({flash6: "src/storage/storage_flash6.swf", + // flash8: "src/storage/storage_flash8.swf", + // visible: false}); + // + // Once finished, you can query Flash version information: + // + // dojo.flash.info.version + // + // Or can communicate with Flash methods that were exposed: + // + // var results = dojo.flash.comm.sayHello("Some Message"); + // + // Only string values are currently supported for both arguments and + // for return results. Everything will be cast to a string on both + // the JavaScript and Flash sides. + // + // ------------------- + // Flash Communication + // ------------------- + // + // dojo.flash allows Flash/JavaScript communication in + // a way that can pass large amounts of data back and forth reliably and + // very fast. The dojo.flash + // framework encapsulates the specific way in which this communication occurs, + // presenting a common interface to JavaScript irrespective of the underlying + // Flash version. + // + // There are currently three major ways to do Flash/JavaScript communication + // in the Flash community: + // + // 1) Flash 6+ - Uses Flash methods, such as SetVariable and TCallLabel, + // and the fscommand handler to do communication. Strengths: Very fast, + // mature, and can send extremely large amounts of data; can do + // synchronous method calls. Problems: Does not work on Safari; works on + // Firefox/Mac OS X only if Flash 8 plugin is installed; cryptic to work with. + // + // 2) Flash 8+ - Uses ExternalInterface, which provides a way for Flash + // methods to register themselves for callbacks from JavaScript, and a way + // for Flash to call JavaScript. Strengths: Works on Safari; elegant to + // work with; can do synchronous method calls. Problems: Extremely buggy + // (fails if there are new lines in the data, for example); performance + // degrades drastically in O(n^2) time as data grows; locks up the browser while + // it is communicating; does not work in Internet Explorer if Flash + // object is dynamically added to page with document.writeln, DOM methods, + // or innerHTML. + // + // 3) Flash 6+ - Uses two seperate Flash applets, one that we + // create over and over, passing input data into it using the PARAM tag, + // which then uses a Flash LocalConnection to pass the data to the main Flash + // applet; communication back to Flash is accomplished using a getURL + // call with a javascript protocol handler, such as "javascript:myMethod()". + // Strengths: the most cross browser, cross platform pre-Flash 8 method + // of Flash communication known; works on Safari. Problems: Timing issues; + // clunky and complicated; slow; can only send very small amounts of + // data (several K); all method calls are asynchronous. + // + // dojo.flash.comm uses only the first two methods. This framework + // was created primarily for dojo.storage, which needs to pass very large + // amounts of data synchronously and reliably across the Flash/JavaScript + // boundary. We use the first method, the Flash 6 method, on all platforms + // that support it, while using the Flash 8 ExternalInterface method + // only on Safari with some special code to help correct ExternalInterface's + // bugs. + // + // Since dojo.flash needs to have two versions of the Flash + // file it wants to generate, a Flash 6 and a Flash 8 version to gain + // true cross-browser compatibility, several tools are provided to ease + // development on the Flash side. + // + // In your Flash file, if you want to expose Flash methods that can be + // called, use the DojoExternalInterface class to register methods. This + // class is an exact API clone of the standard ExternalInterface class, but + // can work in Flash 6+ browsers. Under the covers it uses the best + // mechanism to do communication: + // + // class HelloWorld{ + // function HelloWorld(){ + // // Initialize the DojoExternalInterface class + // DojoExternalInterface.initialize(); + // + // // Expose your methods + // DojoExternalInterface.addCallback("sayHello", this, this.sayHello); + // + // // Tell JavaScript that you are ready to have method calls + // DojoExternalInterface.loaded(); + // + // // Call some JavaScript + // var resultsReady = function(results){ + // trace("Received the following results from JavaScript: " + results); + // } + // DojoExternalInterface.call("someJavaScriptMethod", resultsReady, + // someParameter); + // } + // + // function sayHello(){ ... } + // + // static main(){ ... } + // } + // + // DojoExternalInterface adds two new functions to the ExternalInterface + // API: initialize() and loaded(). initialize() must be called before + // any addCallback() or call() methods are run, and loaded() must be + // called after you are finished adding your callbacks. Calling loaded() + // will fire the dojo.flash.loaded() event, so that JavaScript can know that + // Flash has finished loading and adding its callbacks, and can begin to + // interact with the Flash file. + // + // To generate your SWF files, use the ant task + // "buildFlash". You must have the open source Motion Twin ActionScript + // compiler (mtasc) installed and in your path to use the "buildFlash" + // ant task; download and install mtasc from http://www.mtasc.org/. + // + // + // + // buildFlash usage: + // + // ant buildFlash -Ddojo.flash.file=../tests/flash/HelloWorld.as + // + // where "dojo.flash.file" is the relative path to your Flash + // ActionScript file. + // + // This will generate two SWF files, one ending in _flash6.swf and the other + // ending in _flash8.swf in the same directory as your ActionScript method: + // + // HelloWorld_flash6.swf + // HelloWorld_flash8.swf + // + // Initialize dojo.flash with the filename and Flash communication version to + // use during page load; see the documentation for dojo.flash for details: + // + // dojo.flash.setSwf({flash6: "tests/flash/HelloWorld_flash6.swf", + // flash8: "tests/flash/HelloWorld_flash8.swf"}); + // + // Now, your Flash methods can be called from JavaScript as if they are native + // Flash methods, mirrored exactly on the JavaScript side: + // + // dojo.flash.comm.sayHello(); + // + // Only Strings are supported being passed back and forth currently. + // + // JavaScript to Flash communication is synchronous; i.e., results are returned + // directly from the method call: + // + // var results = dojo.flash.comm.sayHello(); + // + // Flash to JavaScript communication is asynchronous due to limitations in + // the underlying technologies; you must use a results callback to handle + // results returned by JavaScript in your Flash AS files: + // + // var resultsReady = function(results){ + // trace("Received the following results from JavaScript: " + results); + // } + // DojoExternalInterface.call("someJavaScriptMethod", resultsReady); + // + // + // + // ------------------- + // Notes + // ------------------- + // + // If you have both Flash 6 and Flash 8 versions of your file: + // + // dojo.flash.setSwf({flash6: "tests/flash/HelloWorld_flash6.swf", + // flash8: "tests/flash/HelloWorld_flash8.swf"}); + // + // but want to force the browser to use a certain version of Flash for + // all platforms (for testing, for example), use the djConfig + // variable 'forceFlashComm' with the version number to force: + // + // var djConfig = { forceFlashComm: 6 }; + // + // Two values are currently supported, 6 and 8, for the two styles of + // communication described above. Just because you force dojo.flash + // to use a particular communication style is no guarantee that it will + // work; for example, Flash 8 communication doesn't work in Internet + // Explorer due to bugs in Flash, and Flash 6 communication does not work + // in Safari. It is best to let dojo.flash determine the best communication + // mechanism, and to use the value above only for debugging the dojo.flash + // framework itself. + // + // Also note that dojo.flash can currently only work with one Flash object + // on the page; it and the API do not yet support multiple Flash objects on + // the same page. + // + // We use some special tricks to get decent, linear performance + // out of Flash 8's ExternalInterface on Safari; see the blog + // post + // http://codinginparadise.org/weblog/2006/02/how-to-speed-up-flash-8s.html + // for details. + // + // Your code can detect whether the Flash player is installing or having + // its version revved in two ways. First, if dojo.flash detects that + // Flash installation needs to occur, it sets dojo.flash.info.installing + // to true. Second, you can detect if installation is necessary with the + // following callback: + // + // dojo.event.connect(dojo.flash, "installing", myInstance, "myCallback"); + // + // You can use this callback to delay further actions that might need Flash; + // when installation is finished the full page will be refreshed and the + // user will be placed back on your page with Flash installed. + // + // Two utility methods exist if you want to add loading and installing + // listeners without creating dependencies on dojo.event; these are + // 'addLoadingListener' and 'addInstallingListener'. + // + // ------------------- + // Todo/Known Issues + // ------------------- + // + // There are several tasks I was not able to do, or did not need to fix + // to get dojo.storage out: + // + // * When using Flash 8 communication, Flash method calls to JavaScript + // are not working properly; serialization might also be broken for certain + // invalid characters when it is Flash invoking JavaScript methods. + // The Flash side needs to have more sophisticated serialization/ + // deserialization mechanisms like JavaScript currently has. The + // test_flash2.html unit tests should also be updated to have much more + // sophisticated Flash to JavaScript unit tests, including large + // amounts of data. + // + // * On Internet Explorer, after doing a basic install, the page is + // not refreshed or does not detect that Flash is now available. The way + // to fix this is to create a custom small Flash file that is pointed to + // during installation; when it is finished loading, it does a callback + // that says that Flash installation is complete on IE, and we can proceed + // to initialize the dojo.flash subsystem. + // + // Author- Brad Neuberg, bkn3@columbia.edu +} - There are several tasks I was not able to do, or did not need to fix - to get dojo.storage out: - - * When using Flash 8 communication, Flash method calls to JavaScript - are not working properly; serialization might also be broken for certain - invalid characters when it is Flash invoking JavaScript methods. - The Flash side needs to have more sophisticated serialization/ - deserialization mechanisms like JavaScript currently has. The - test_flash2.html unit tests should also be updated to have much more - sophisticated Flash to JavaScript unit tests, including large - amounts of data. - - * On Internet Explorer, after doing a basic install, the page is - not refreshed or does not detect that Flash is now available. The way - to fix this is to create a custom small Flash file that is pointed to - during installation; when it is finished loading, it does a callback - that says that Flash installation is complete on IE, and we can proceed - to initialize the dojo.flash subsystem. - - @author Brad Neuberg, bkn3@columbia.edu -*/ - dojo.flash = { flash6_version: null, flash8_version: null, @@ -301,9 +305,18 @@ _loadedListeners: new Array(), _installingListeners: new Array(), - /** Sets the SWF files and versions we are using. */ - setSwf: function(fileInfo){ - //dojo.debug("setSwf"); + setSwf: function(/* Object */ fileInfo){ + // summary: Sets the SWF files and versions we are using. + // fileInfo: Object + // An object that contains two attributes, 'flash6' and 'flash8', + // each of which contains the path to our Flash 6 and Flash 8 versions + // of the file we want to script. + // + // Example- + // var swfloc6 = dojo.uri.dojoUri("Storage_version6.swf").toString(); + // var swfloc8 = dojo.uri.dojoUri("Storage_version8.swf").toString(); + // dojo.flash.setSwf({flash6: swfloc6, flash8: swfloc8, visible: false}); + if(fileInfo == null || dojo.lang.isUndefined(fileInfo)){ return; } @@ -324,8 +337,9 @@ this._initialize(); }, - /** Returns whether we are using Flash 6 for communication on this platform. */ - useFlash6: function(){ + useFlash6: function(){ /* Boolean */ + // summary: Returns whether we are using Flash 6 for communication on this platform. + if(this.flash6_version == null){ return false; }else if (this.flash6_version != null && dojo.flash.info.commVersion == 6){ @@ -337,8 +351,9 @@ } }, - /** Returns whether we are using Flash 8 for communication on this platform. */ - useFlash8: function(){ + useFlash8: function(){ /* Boolean */ + // summary: Returns whether we are using Flash 8 for communication on this platform. + if(this.flash8_version == null){ return false; }else if (this.flash8_version != null && dojo.flash.info.commVersion == 8){ @@ -350,26 +365,36 @@ } }, - /** Adds a listener to know when Flash is finished loading. - Useful if you don't want a dependency on dojo.event. */ - addLoadedListener: function(listener){ + addLoadedListener: function(/* Function */ listener){ + // summary: + // Adds a listener to know when Flash is finished loading. + // Useful if you don't want a dependency on dojo.event. + // listener: Function + // A function that will be called when Flash is done loading. + this._loadedListeners.push(listener); }, - /** Adds a listener to know if Flash is being installed. - Useful if you don't want a dependency on dojo.event. */ - addInstallingListener: function(listener){ + addInstallingListener: function(/* Function */ listener){ + // summary: + // Adds a listener to know if Flash is being installed. + // Useful if you don't want a dependency on dojo.event. + // listener: Function + // A function that will be called if Flash is being + // installed + this._installingListeners.push(listener); }, - /** - A callback when the Flash subsystem is finished loading and can be - worked with. To be notified when Flash is finished loading, connect - your callback to this method using the following: - - dojo.event.connect(dojo.flash, "loaded", myInstance, "myCallback"); - */ loaded: function(){ + // summary: Called back when the Flash subsystem is finished loading. + // description: + // A callback when the Flash subsystem is finished loading and can be + // worked with. To be notified when Flash is finished loading, connect + // your callback to this method using the following: + // + // dojo.event.connect(dojo.flash, "loaded", myInstance, "myCallback"); + //dojo.debug("dojo.flash.loaded"); dojo.flash.ready = true; if(dojo.flash._loadedListeners.length > 0){ @@ -379,23 +404,24 @@ } }, - /** - A callback to know if Flash is currently being installed or - having its version revved. To be notified if Flash is installing, connect - your callback to this method using the following: - - dojo.event.connect(dojo.flash, "installing", myInstance, "myCallback"); - */ installing: function(){ - //dojo.debug("installing"); - if(dojo.flash._installingListeners.length > 0){ + // summary: Called if Flash is being installed. + // description: + // A callback to know if Flash is currently being installed or + // having its version revved. To be notified if Flash is installing, connect + // your callback to this method using the following: + // + // dojo.event.connect(dojo.flash, "installing", myInstance, "myCallback"); + + //dojo.debug("installing"); + if(dojo.flash._installingListeners.length > 0){ for(var i = 0; i < dojo.flash._installingListeners.length; i++){ dojo.flash._installingListeners[i].call(null); } } }, - /** Initializes dojo.flash. */ + // Initializes dojo.flash. _initialize: function(){ //dojo.debug("dojo.flash._initialize"); // see if we need to rev or install Flash on this platform @@ -417,19 +443,20 @@ }; -/** - A class that helps us determine whether Flash is available, - it's major and minor versions, and what Flash version features should - be used for Flash/JavaScript communication. Parts of this code - are adapted from the automatic Flash plugin detection code autogenerated - by the Macromedia Flash 8 authoring environment. - - An instance of this class can be accessed on dojo.flash.info after - the page is finished loading. - - This constructor must be called before the page is finished loading. -*/ dojo.flash.Info = function(){ + // summary: A class that helps us determine whether Flash is available. + // description: + // A class that helps us determine whether Flash is available, + // it's major and minor versions, and what Flash version features should + // be used for Flash/JavaScript communication. Parts of this code + // are adapted from the automatic Flash plugin detection code autogenerated + // by the Macromedia Flash 8 authoring environment. + // + // An instance of this class can be accessed on dojo.flash.info after + // the page is finished loading. + // + // This constructor must be called before the page is finished loading. + // Visual basic helper required to detect Flash Player ActiveX control // version information on Internet Explorer if(dojo.render.html.ie){ @@ -452,45 +479,54 @@ } dojo.flash.Info.prototype = { - /** The full version string, such as "8r22". */ + // version: String + // The full version string, such as "8r22". version: -1, - /** - The major, minor, and revisions of the plugin. For example, if the - plugin is 8r22, then the major version is 8, the minor version is 0, - and the revision is 22. - */ + // versionMajor, versionMinor, versionRevision: String + // The major, minor, and revisions of the plugin. For example, if the + // plugin is 8r22, then the major version is 8, the minor version is 0, + // and the revision is 22. versionMajor: -1, versionMinor: -1, versionRevision: -1, - /** Whether this platform has Flash already installed. */ + // capable: Boolean + // Whether this platform has Flash already installed. capable: false, - /** - The major version number for how our Flash and JavaScript communicate. - This can currently be the following values: - 6 - We use a combination of the Flash plugin methods, such as SetVariable - and TCallLabel, along with fscommands, to do communication. - 8 - We use the ExternalInterface API. - -1 - For some reason neither method is supported, and no communication - is possible. - */ + // commVersion: int + // The major version number for how our Flash and JavaScript communicate. + // This can currently be the following values: + // 6 - We use a combination of the Flash plugin methods, such as SetVariable + // and TCallLabel, along with fscommands, to do communication. + // 8 - We use the ExternalInterface API. + // -1 - For some reason neither method is supported, and no communication + // is possible. commVersion: 6, - /** Set if we are in the middle of a Flash installation session. */ + // installing: Boolean + // Set if we are in the middle of a Flash installation session. installing: false, - /** - Asserts that this environment has the given major, minor, and revision - numbers for the Flash player. Returns true if the player is equal - or above the given version, false otherwise. - - Example: To test for Flash Player 7r14: - - dojo.flash.info.isVersionOrAbove(7, 0, 14) - */ - isVersionOrAbove: function(reqMajorVer, reqMinorVer, reqVer){ + isVersionOrAbove: function( + /* int */ reqMajorVer, + /* int */ reqMinorVer, + /* int */ reqVer){ /* Boolean */ + // summary: + // Asserts that this environment has the given major, minor, and revision + // numbers for the Flash player. + // description: + // Asserts that this environment has the given major, minor, and revision + // numbers for the Flash player. + // + // Example- To test for Flash Player 7r14: + // + // dojo.flash.info.isVersionOrAbove(7, 0, 14) + // returns: + // Returns true if the player is equal + // or above the given version, false otherwise. + // make the revision a decimal (i.e. transform revision 14 into // 0.14 reqVer = parseFloat("." + reqVer); @@ -541,12 +577,10 @@ } } }, - - /** - JavaScript helper required to detect Flash Player PlugIn version - information. Internet Explorer uses a corresponding Visual Basic - version to interact with the Flash ActiveX control. - */ + + // JavaScript helper required to detect Flash Player PlugIn version + // information. Internet Explorer uses a corresponding Visual Basic + // version to interact with the Flash ActiveX control. _JSFlashInfo: function(testVersion){ // NS/Opera version >= 3 check for Flash plugin in plugin array if(navigator.plugins != null && navigator.plugins.length > 0){ @@ -574,13 +608,11 @@ return -1; }, - /** - Detects the mechanisms that should be used for Flash/JavaScript - communication, setting 'commVersion' to either 6 or 8. If the value is - 6, we use Flash Plugin 6+ features, such as GetVariable, TCallLabel, - and fscommand, to do Flash/JavaScript communication; if the value is - 8, we use the ExternalInterface API for communication. - */ + // Detects the mechanisms that should be used for Flash/JavaScript + // communication, setting 'commVersion' to either 6 or 8. If the value is + // 6, we use Flash Plugin 6+ features, such as GetVariable, TCallLabel, + // and fscommand, to do Flash/JavaScript communication; if the value is + // 8, we use the ExternalInterface API for communication. _detectCommunicationVersion: function(){ if(this.capable == false){ this.commVersion = null; @@ -607,28 +639,30 @@ } }; -/** A class that is used to write out the Flash object into the page. */ dojo.flash.Embed = function(visible){ + // summary: A class that is used to write out the Flash object into the page. + this._visible = visible; } dojo.flash.Embed.prototype = { - /** - The width of this Flash applet. The default is the minimal width - necessary to show the Flash settings dialog. - */ + // width: int + // The width of this Flash applet. The default is the minimal width + // necessary to show the Flash settings dialog. Current value is + // 215 pixels. width: 215, - /** - The height of this Flash applet. The default is the minimal height - necessary to show the Flash settings dialog. - */ + // height: int + // The height of this Flash applet. The default is the minimal height + // necessary to show the Flash settings dialog. Current value is + // 138 pixels. height: 138, - /** The id of the Flash object. */ + // id: String + // The id of the Flash object. Current value is 'flashObject'. id: "flashObject", - /** Controls whether this is a visible Flash applet or not. */ + // Controls whether this is a visible Flash applet or not. _visible: true, protocol: function(){ @@ -642,15 +676,17 @@ } }, - /** - Writes the Flash into the page. This must be called before the page - is finished loading. - @param flashVer The Flash version to write. - @param doExpressInstall Whether to write out Express Install - information. Optional value; defaults to false. - */ - - write: function(flashVer, doExpressInstall){ + write: function(/* String */ flashVer, /* Boolean? */ doExpressInstall){ + // summary: Writes the Flash into the page. + // description: + // This must be called before the page + // is finished loading. + // flashVer: String + // The Flash version to write. + // doExpressInstall: Boolean + // Whether to write out Express Install + // information. Optional value; defaults to false. + //dojo.debug("write"); if(dojo.lang.isUndefined(doExpressInstall)){ doExpressInstall = false; @@ -748,17 +784,19 @@ document.writeln(objectHTML); }, - /** Gets the Flash object DOM node. */ - get: function(){ + get: function(){ /* Object */ + // summary: Gets the Flash object DOM node. + //return (dojo.render.html.ie) ? window[this.id] : document[this.id]; // more robust way to get Flash object; version above can break // communication on IE sometimes return document.getElementById(this.id); }, - /** Sets the visibility of this Flash object. */ - setVisible: function(visible){ + setVisible: function(/* Boolean */ visible){ + // summary: Sets the visibility of this Flash object. + var container = dojo.byId(this.id + "Container"); if(visible == true){ container.style.visibility = "visible"; @@ -770,8 +808,9 @@ } }, - /** Centers the flash applet on the page. */ center: function(){ + // summary: Centers the flash applet on the page. + var elementWidth = this.width; var elementHeight = this.height; @@ -790,15 +829,19 @@ }; -/** - A class that is used to communicate between Flash and JavaScript in - a way that can pass large amounts of data back and forth reliably, - very fast, and with synchronous method calls. This class encapsulates the - specific way in which this communication occurs, - presenting a common interface to JavaScript irrespective of the underlying - Flash version. -*/ dojo.flash.Communicator = function(){ + // summary: + // A class that is used to communicate between Flash and JavaScript in + // a way that can pass large amounts of data back and forth reliably, + // very fast, and with synchronous method calls. + // description: + // A class that is used to communicate between Flash and JavaScript in + // a way that can pass large amounts of data back and forth reliably, + // very fast, and with synchronous method calls. This class encapsulates the + // specific way in which this communication occurs, + // presenting a common interface to JavaScript irrespective of the underlying + // Flash version. + if(dojo.flash.useFlash6()){ this._writeFlash6(); }else if (dojo.flash.useFlash8()){ @@ -836,9 +879,9 @@ // happens automatically }, - /** Flash 6 communication. */ + //Flash 6 communication. - /** Handles fscommand's from Flash to JavaScript. Flash 6 communication. */ + // Handles fscommand's from Flash to JavaScript. Flash 6 communication. _handleFSCommand: function(command, args){ //dojo.debug("fscommand, command="+command+", args="+args); // Flash 8 on Mac/Firefox precedes all commands with the string "FSCommand:"; @@ -857,7 +900,7 @@ } }, - /** Handles registering a callable Flash function. Flash 6 communication. */ + // Handles registering a callable Flash function. Flash 6 communication. _fscommandAddCallback: function(command, args){ var functionName = args; @@ -872,7 +915,7 @@ dojo.flash.obj.get().SetVariable("_succeeded", true); }, - /** Handles Flash calling a JavaScript function. Flash 6 communication. */ + // Handles Flash calling a JavaScript function. Flash 6 communication. _fscommandCall: function(command, args){ var plugin = dojo.flash.obj.get(); var functionName = args; @@ -907,16 +950,14 @@ plugin.SetVariable("_returnResult", results); }, - /** Reports that fscommands are ready to run if executed from Flash. */ + // Reports that fscommands are ready to run if executed from Flash. _fscommandReady: function(){ var plugin = dojo.flash.obj.get(); plugin.SetVariable("fscommandReady", "true"); }, - /** - The actual function that will execute a JavaScript to Flash call; used - by the Flash 6 communication method. - */ + // The actual function that will execute a JavaScript to Flash call; used + // by the Flash 6 communication method. _call: function(functionName, args){ // we do JavaScript to Flash method calls by setting a Flash variable // "_functionName" with the function name; "_numArgs" with the number @@ -950,12 +991,10 @@ return results; }, - /** Flash 8 communication. */ + // Flash 8 communication. - /** - Registers the existence of a Flash method that we can call with - JavaScript, using Flash 8's ExternalInterface. - */ + // Registers the existence of a Flash method that we can call with + // JavaScript, using Flash 8's ExternalInterface. _addExternalInterfaceCallback: function(methodName){ var wrapperCall = function(){ // some browsers don't like us changing values in the 'arguments' array, so @@ -970,10 +1009,8 @@ dojo.flash.comm[methodName] = wrapperCall; }, - /** - Encodes our data to get around ExternalInterface bugs. - Flash 8 communication. - */ + // Encodes our data to get around ExternalInterface bugs. + // Flash 8 communication. _encodeData: function(data){ // double encode all entity values, or they will be mis-decoded // by Flash when returned @@ -998,10 +1035,8 @@ return data; }, - /** - Decodes our data to get around ExternalInterface bugs. - Flash 8 communication. - */ + // Decodes our data to get around ExternalInterface bugs. + // Flash 8 communication. _decodeData: function(data){ if(data == null || typeof data == "undefined"){ return data; @@ -1026,11 +1061,9 @@ return data; }, - /** - Sends our method arguments over to Flash in chunks in order to - have ExternalInterface's performance not be O(n^2). - Flash 8 communication. - */ + // Sends our method arguments over to Flash in chunks in order to + // have ExternalInterface's performance not be O(n^2). + // Flash 8 communication. _chunkArgumentData: function(value, argIndex){ var plugin = dojo.flash.obj.get(); @@ -1067,10 +1100,8 @@ } }, - /** - Gets our method return data in chunks for better performance. - Flash 8 communication. - */ + // Gets our method return data in chunks for better performance. + // Flash 8 communication. _chunkReturnData: function(){ var plugin = dojo.flash.obj.get(); @@ -1104,11 +1135,9 @@ return results; }, - /** - Executes a Flash method; called from the JavaScript wrapper proxy we - create on dojo.flash.comm. - Flash 8 communication. - */ + // Executes a Flash method; called from the JavaScript wrapper proxy we + // create on dojo.flash.comm. + // Flash 8 communication. _execFlash: function(methodName, methodArgs){ var plugin = dojo.flash.obj.get(); @@ -1136,24 +1165,23 @@ plugin.endExec(); return results; - } } -/** - Figures out the best way to automatically install the Flash plugin - for this browser and platform. Also determines if installation or - revving of the current plugin is needed on this platform. -*/ dojo.flash.Install = function(){ + // summary: Helps install Flash plugin if needed. + // description: + // Figures out the best way to automatically install the Flash plugin + // for this browser and platform. Also determines if installation or + // revving of the current plugin is needed on this platform. } dojo.flash.Install.prototype = { - /** - Determines if installation or revving of the current plugin is - needed. - */ - needed: function(){ + needed: function(){ /* Boolean */ + // summary: + // Determines if installation or revving of the current plugin is + // needed. + // do we even have flash? if(dojo.flash.info.capable == false){ return true; @@ -1175,8 +1203,9 @@ return false; }, - /** Performs installation or revving of the Flash plugin. */ install: function(){ + // summary: Performs installation or revving of the Flash plugin. + //dojo.debug("install"); // indicate that we are installing dojo.flash.info.installing = true; @@ -1202,10 +1231,8 @@ } }, - /** - Called when the Express Install is either finished, failed, or was - rejected by the user. - */ + // Called when the Express Install is either finished, failed, or was + // rejected by the user. _onInstallStatus: function(msg){ if (msg == "Download.Complete"){ // Installation is complete.