source: Dev/trunk/src/client/dojo/ready.js @ 525

define(["./_base/kernel", "./has", "require", "./has!host-browser?./domReady", "./_base/lang"], function(dojo, has, require, domReady, lang){
        // module:
        //              dojo/ready
        // note:
        //              This module should be unnecessary in dojo 2.0

        var
                // truthy if DOMContentLoaded or better (e.g., window.onload fired) has been achieved
                isDomReady = 0,

                // The queue of functions waiting to execute as soon as dojo.ready conditions satisfied
                loadQ = [],

                // prevent recursion in onLoad
                onLoadRecursiveGuard = 0,

                handleDomReady = function(){
                        isDomReady = 1;
                        dojo._postLoad = dojo.config.afterOnLoad = true;
                        onEvent();
                },

                onEvent = function(){
                        // Called when some state changes:
                        //              - dom ready
                        //              - dojo/domReady has finished processing everything in its queue
                        //              - task added to loadQ
                        //              - require() has finished loading all currently requested modules
                        //
                        // Run the functions queued with dojo.ready if appropriate.


                        //guard against recursions into this function
                        if(onLoadRecursiveGuard){
                                return;
                        }
                        onLoadRecursiveGuard = 1;

                        // Run tasks in queue if require() is finished loading modules, the dom is ready, and there are no
                        // pending tasks registered via domReady().
                        // The last step is necessary so that a user defined dojo.ready() callback is delayed until after the
                        // domReady() calls inside of dojo.       Failure can be seen on dijit/tests/robot/Dialog_ally.html on IE8
                        // because the dijit/focus.js domReady() callback doesn't execute until after the test starts running.
                        while(isDomReady && (!domReady || domReady._Q.length == 0) && (require.idle ? require.idle() : true) && loadQ.length){
                                var f = loadQ.shift();
                                try{
                                        f();
                                }catch(e){
                                        // force the dojo.js on("error") handler do display the message
                                        e.info = e.message;
                                        if(require.signal){
                                                require.signal("error", e);
                                        }else{
                                                throw e;
                                        }
                                }
                        }

                        onLoadRecursiveGuard = 0;
                };

        // Check if we should run the next queue operation whenever require() finishes loading modules or domReady
        // finishes processing it's queue.
        require.on && require.on("idle", onEvent);
        if(domReady){
                domReady._onQEmpty = onEvent;
        }

        var ready = dojo.ready = dojo.addOnLoad = function(priority, context, callback){
                // summary:
                //              Add a function to execute on DOM content loaded and all requested modules have arrived and been evaluated.
                //              In most cases, the `domReady` plug-in should suffice and this method should not be needed.
                //
                //              When called in a non-browser environment, just checks that all requested modules have arrived and been
                //              evaluated.
                // priority: Integer?
                //              The order in which to exec this callback relative to other callbacks, defaults to 1000
                // context: Object?|Function
                //              The context in which to run execute callback, or a callback if not using context
                // callback: Function?
                //              The function to execute.
                //
                // example:
                //      Simple DOM and Modules ready syntax
                //      |       require(["dojo/ready"], function(ready){
                //      |               ready(function(){ alert("Dom ready!"); });
                //      |       });
                //
                // example:
                //      Using a priority
                //      |       require(["dojo/ready"], function(ready){
                //      |               ready(2, function(){ alert("low priority ready!"); })
                //      |       });
                //
                // example:
                //      Using context
                //      |       require(["dojo/ready"], function(ready){
                //      |               ready(foo, function(){
                //      |                       // in here, this == foo
                //      |               });
                //      |       });
                //
                // example:
                //      Using dojo/hitch style args:
                //      |       require(["dojo/ready"], function(ready){
                //      |               var foo = { dojoReady: function(){ console.warn(this, "dojo dom and modules ready."); } };
                //      |               ready(foo, "dojoReady");
                //      |       });

                var hitchArgs = lang._toArray(arguments);
                if(typeof priority != "number"){
                        callback = context;
                        context = priority;
                        priority = 1000;
                }else{
                        hitchArgs.shift();
                }
                callback = callback ?
                        lang.hitch.apply(dojo, hitchArgs) :
                        function(){
                                context();
                        };
                callback.priority = priority;
                for(var i = 0; i < loadQ.length && priority >= loadQ[i].priority; i++){}
                loadQ.splice(i, 0, callback);
                onEvent();
        };

        has.add("dojo-config-addOnLoad", 1);
        if(has("dojo-config-addOnLoad")){
                var dca = dojo.config.addOnLoad;
                if(dca){
                        ready[(lang.isArray(dca) ? "apply" : "call")](dojo, dca);
                }
        }

        if(has("dojo-sync-loader") && dojo.config.parseOnLoad && !dojo.isAsync){
                ready(99, function(){
                        if(!dojo.parser){
                                dojo.deprecated("Add explicit require(['dojo/parser']);", "", "2.0");
                                require(["dojo/parser"]);
                        }
                });
        }

        if(domReady){
                domReady(handleDomReady);
        }else{
                handleDomReady();
        }

        return ready;
});