source: Dev/branches/rest-dojo-ui/client/dojo/dom.js @ 256

define(["./_base/sniff", "./_base/lang", "./_base/window"],
                function(has, lang, win){
        // module:
        //              dojo/dom
        // summary:
        //              This module defines the core dojo DOM API.

        // FIXME: need to add unit tests for all the semi-public methods

        //>>excludeStart("webkitMobile", kwArgs.webkitMobile);
        try{
                document.execCommand("BackgroundImageCache", false, true);
        }catch(e){
                // sane browsers don't have cache "issues"
        }
        //>>excludeEnd("webkitMobile");

        // =============================
        // DOM Functions
        // =============================

        /*=====
        dojo.byId = function(id, doc){
                // summary:
                //              Returns DOM node with matching `id` attribute or `null`
                //              if not found. If `id` is a DomNode, this function is a no-op.
                //
                // id: String|DOMNode
                //              A string to match an HTML id attribute or a reference to a DOM Node
                //
                // doc: Document?
                //              Document to work in. Defaults to the current value of
                //              dojo.doc.  Can be used to retrieve
                //              node references from other documents.
                //
                // example:
                //              Look up a node by ID:
                //      |       var n = dojo.byId("foo");
                //
                // example:
                //              Check if a node exists, and use it.
                //      |       var n = dojo.byId("bar");
                //      |       if(n){ doStuff() ... }
                //
                // example:
                //              Allow string or DomNode references to be passed to a custom function:
                //      |       var foo = function(nodeOrId){
                //      |               nodeOrId = dojo.byId(nodeOrId);
                //      |               // ... more stuff
                //      |       }
        =====*/

        /*=====
        dojo.isDescendant = function(node, ancestor){
                // summary:
                //              Returns true if node is a descendant of ancestor
                // node: DOMNode|String
                //              string id or node reference to test
                // ancestor: DOMNode|String
                //              string id or node reference of potential parent to test against
                //
                // example:
                //              Test is node id="bar" is a descendant of node id="foo"
                //      |       if(dojo.isDescendant("bar", "foo")){ ... }
        };
        =====*/

        // TODO: do we need this function in the base?

        /*=====
        dojo.setSelectable = function(node, selectable){
                // summary:
                //              Enable or disable selection on a node
                // node: DOMNode|String
                //              id or reference to node
                // selectable: Boolean
                //              state to put the node in. false indicates unselectable, true
                //              allows selection.
                // example:
                //              Make the node id="bar" unselectable
                //      |       dojo.setSelectable("bar");
                // example:
                //              Make the node id="bar" selectable
                //      |       dojo.setSelectable("bar", true);
        };
        =====*/

        var dom = {};   // the result object

        //>>excludeStart("webkitMobile", kwArgs.webkitMobile);
        if(has("ie")){
                dom.byId = function(id, doc){
                        if(typeof id != "string"){
                                return id;
                        }
                        var _d = doc || win.doc, te = id && _d.getElementById(id);
                        // attributes.id.value is better than just id in case the
                        // user has a name=id inside a form
                        if(te && (te.attributes.id.value == id || te.id == id)){
                                return te;
                        }else{
                                var eles = _d.all[id];
                                if(!eles || eles.nodeName){
                                        eles = [eles];
                                }
                                // if more than 1, choose first with the correct id
                                var i = 0;
                                while((te = eles[i++])){
                                        if((te.attributes && te.attributes.id && te.attributes.id.value == id) || te.id == id){
                                                return te;
                                        }
                                }
                        }
                };
        }else{
        //>>excludeEnd("webkitMobile");
                dom.byId = function(id, doc){
                        // inline'd type check.
                        // be sure to return null per documentation, to match IE branch.
                        return ((typeof id == "string") ? (doc || win.doc).getElementById(id) : id) || null; // DOMNode
                };
        //>>excludeStart("webkitMobile", kwArgs.webkitMobile);
        }
        //>>excludeEnd("webkitMobile");
        /*=====
        };
        =====*/

        dom.isDescendant = function(/*DOMNode|String*/node, /*DOMNode|String*/ancestor){
                try{
                        node = dom.byId(node);
                        ancestor = dom.byId(ancestor);
                        while(node){
                                if(node == ancestor){
                                        return true; // Boolean
                                }
                                node = node.parentNode;
                        }
                }catch(e){ /* squelch, return false */ }
                return false; // Boolean
        };

        // TODO: do we need this function in the base?

        dom.setSelectable = function(/*DOMNode|String*/node, /*Boolean*/selectable){
                node = dom.byId(node);
                //>>excludeStart("webkitMobile", kwArgs.webkitMobile);
                if(has("mozilla")){
                        node.style.MozUserSelect = selectable ? "" : "none";
                }else if(has("khtml") || has("webkit")){
                //>>excludeEnd("webkitMobile");
                        node.style.KhtmlUserSelect = selectable ? "auto" : "none";
                //>>excludeStart("webkitMobile", kwArgs.webkitMobile);
                }else if(has("ie")){
                        var v = (node.unselectable = selectable ? "" : "on"),
                                cs = node.getElementsByTagName("*"), i = 0, l = cs.length;
                        for(; i < l; ++i){
                                cs.item(i).unselectable = v;
                        }
                }
                //>>excludeEnd("webkitMobile");
                //FIXME: else?  Opera?
        };

        return dom;
});