add extjs 6.0.1 sources

[extjs.git] / extjs / packages / core / src / dom / Fly.js

/**\r
 * A flyweight Ext.dom.Element that can be dynamically attached to a DOM node.\r
 * In general this class should not be instantiated directly.  Use {@link Ext#fly}\r
 * to create and retrieve Fly instances.\r
 */\r
Ext.define('Ext.dom.Fly', {\r
    extend: 'Ext.dom.Element',\r
    alternateClassName: 'Ext.dom.Element.Fly',\r
\r
    // This adds the ability to wrap DOCUMENT_FRAGMENT_NODE\r
    // Document Fragments cannot have event listeners and therefore do not\r
    // need  the caching mechanism provided by Ext.get.\r
    // However the many Element APIs are useful such as Traversal, child appending/removing.\r
    validNodeTypes: {\r
        1: 1, // ELEMENT_NODE\r
        9: 1, // DOCUMENT_NODE\r
        11: 1 // DOCUMENT_FRAGMENT_NODE\r
    },\r
\r
    /**\r
     * @property {Boolean} isFly\r
     * This is `true` to identify Element flyweights\r
     */\r
    isFly: true,\r
\r
    constructor: function(dom) {\r
        this.dom = dom;\r
\r
        // set an "el" property that references "this".  This allows\r
        // Ext.util.Positionable methods to operate on this.el.dom since it\r
        // gets mixed into both Element and Component\r
        this.el = this;\r
    },\r
\r
    attach: function (dom) {\r
        var me = this;\r
\r
        if (!dom) {\r
            return me.detach();\r
        }\r
        me.dom = dom;\r
\r
        // If the element is not being managed by an Ext.Element instance,\r
        // we have to assume that the classList/classMap in the data object are out of sync with reality.\r
        if (!Ext.cache[dom.id]) {\r
            me.getData().isSynchronized = false;\r
        }\r
\r
        return me;\r
    },\r
\r
    detach: function() {\r
        this.dom = null;\r
    },\r
\r
    addListener:\r
        //<debug>\r
        function() {\r
            Ext.raise(\r
                "Cannot use addListener() on Ext.dom.Fly instances. " +\r
                "Please use Ext.get() to retrieve an Ext.dom.Element instance instead."\r
            );\r
        } ||\r
        //</debug>\r
        null,\r
\r
    removeListener: \r
        //<debug>\r
        function() {\r
            Ext.raise(\r
                "Cannot use removeListener() on Ext.dom.Fly instances. " +\r
                "Please use Ext.get() to retrieve an Ext.dom.Element instance instead."\r
            );\r
        } ||\r
        //</debug>\r
        null\r
}, function(Fly) {\r
    var flyweights = {};\r
\r
    /**\r
     * @member Ext\r
     * @property {Object} cache\r
     * Stores `Fly` instances keyed by their assigned or generated name.\r
     * @readonly\r
     * @private\r
     * @since 5.0.0\r
     */\r
    Fly.cache = flyweights;\r
\r
    /**\r
     * @member Ext\r
     * @method fly\r
     * Gets the globally shared flyweight Element, with the passed node as the active\r
     * element. Do not store a reference to this element - the dom node can be overwritten\r
     * by other code. {@link Ext#fly} is alias for {@link Ext.dom.Element#fly}.\r
     *\r
     * Use this to make one-time references to DOM elements which are not going to be\r
     * accessed again either by application code, or by Ext's classes. If accessing an\r
     * element which will be processed regularly, then {@link Ext#get Ext.get} will be\r
     * more appropriate to take advantage of the caching provided by the\r
     * {@link Ext.dom.Element} class.\r
     * \r
     * If this method is called with and id or element that has already been cached by\r
     * a previous call to Ext.get() it will return the cached Element instead of the\r
     * flyweight instance.\r
     *\r
     * @param {String/HTMLElement} dom The DOM node or `id`.\r
     * @param {String} [named] Allows for creation of named reusable flyweights to prevent \r
     * conflicts (e.g. internally Ext uses "_global").\r
     * @return {Ext.dom.Element} The shared Element object (or `null` if no matching\r
     * element was found).\r
     */\r
    Ext.fly = function(dom, named) {\r
        var fly = null,\r
            fn = Ext.fly,\r
            nodeType, data;\r
\r
        // name the flyweight after the calling method name if possible.\r
        named = named || (fn.caller && fn.caller.$name) || '_global';\r
\r
        dom = Ext.getDom(dom);\r
\r
        if (dom) {\r
            nodeType = dom.nodeType;\r
            // check if we have a valid node type or if the el is a window object before\r
            // proceeding. This allows elements, document fragments, and document/window\r
            // objects (even those inside iframes) to be wrapped.\r
            // Note: a window object can be detected by comparing it's window property to\r
            // itself, but we must use == for the comparison because === will return false\r
            // in IE8 even though the 2 window objects are the same\r
            if (Fly.prototype.validNodeTypes[nodeType] || (!nodeType && (dom.window == dom))) {\r
                fly = Ext.cache[dom.id];\r
\r
                // If there's no Element cached, or the element cached is for another DOM node, return a Fly\r
                if (!fly || fly.dom !== dom) {\r
                    fly = flyweights[named] || (flyweights[named] = new Fly());\r
                    fly.dom = dom;\r
                    data = fly.getData(true);\r
                    if (data) {\r
                        data.isSynchronized = false;\r
                    }\r
                }\r
            }\r
        }\r
        return fly;\r
    };\r
});\r