add extjs 6.0.1 sources

[extjs.git] / extjs / classic / classic / src / Img.js

/**\r
 * Simple helper class for easily creating image components. This renders an image tag to\r
 * the DOM with the configured src.\r
 *\r
 * {@img Ext.Img/Ext.Img.png Ext.Img component}\r
 *\r
 * ## Example usage:\r
 *\r
 *     var changingImage = Ext.create('Ext.Img', {\r
 *         src: 'http://www.sencha.com/img/20110215-feat-html5.png',\r
 *         width: 184,\r
 *         height: 90,\r
 *         renderTo: Ext.getBody()\r
 *     });\r
 *\r
 *     // change the src of the image programmatically\r
 *     changingImage.setSrc('http://www.sencha.com/img/20110215-feat-perf.png');\r
 *\r
 * By default, only an img element is rendered and that is this component's primary\r
 * {@link Ext.Component#getEl element}. If the {@link Ext.Component#autoEl} property\r
 * is other than 'img' (the default), the a child img element will be added to the primary\r
 * element. This can be used to create a wrapper element around the img.\r
 *\r
 * ## Wrapping the img in a div:\r
 *\r
 *     var wrappedImage = Ext.create('Ext.Img', {\r
 *         src: 'http://www.sencha.com/img/20110215-feat-html5.png',\r
 *         autoEl: 'div', // wrap in a div\r
 *         renderTo: Ext.getBody()\r
 *     });\r
 *\r
 * ## Image Dimensions\r
 *\r
 * You should include height and width dimensions for any image owned by a parent \r
 * container.  By omitting dimensions, an owning container will not know how to \r
 * size and position the image in the initial layout.\r
 */\r
Ext.define('Ext.Img', {\r
    extend: 'Ext.Component',\r
    alias: ['widget.image', 'widget.imagecomponent'],\r
\r
    autoEl: 'img',\r
\r
    baseCls: Ext.baseCSSPrefix + 'img',\r
\r
    config: {\r
        /**\r
         * @cfg {String} src The source of this image. See {@link Ext#resolveResource} for\r
         * details on locating application resources.\r
         * @accessor\r
         */\r
        src: null\r
    },\r
\r
    /**\r
     * @cfg {String} alt\r
     * The descriptive text for non-visual UI description.\r
     */\r
    alt: '',\r
\r
    /**\r
     * @cfg {String} title\r
     * Specifies addtional information about the image.\r
     */\r
    title: '',\r
\r
    /**\r
     * @cfg {String} imgCls\r
     * Optional CSS classes to add to the img element.\r
     */\r
    imgCls: '',\r
\r
    /**\r
     * @cfg {Number/String} glyph\r
     * A numeric unicode character code to serve as the image.  If this option is used\r
     * The image will be rendered using a div with innerHTML set to the html entity\r
     * for the given character code.  The default font-family for glyphs can be set\r
     * globally using {@link Ext#setGlyphFontFamily Ext.setGlyphFontFamily()}. Alternatively,\r
     * this config option accepts a string with the charCode and font-family separated by\r
     * the `@` symbol. For example '65@My Font Family'.\r
     */\r
    \r
    maskOnDisable: false,\r
\r
    initComponent: function() {\r
        if (this.glyph) {\r
            this.autoEl = 'div';\r
        }\r
\r
        this.callParent();\r
    },\r
\r
    applySrc: function (src) {\r
        return src && Ext.resolveResource(src);\r
    },\r
\r
    getElConfig: function() {\r
        var me = this,\r
            autoEl = me.autoEl,\r
            config = me.callParent(),\r
            glyphFontFamily = Ext._glyphFontFamily,\r
            glyph = me.glyph,\r
            img, glyphParts;\r
\r
        // It is sometimes helpful (like in a panel header icon) to have the img wrapped\r
        // by a div. If our autoEl is not 'img' then we just add an img child to the el.\r
        if (autoEl === 'img' || (Ext.isObject(autoEl) && autoEl.tag === 'img')) {\r
            img = config;\r
        }\r
        else if (me.glyph) {\r
            if (typeof glyph === 'string') {\r
                glyphParts = glyph.split('@');\r
                glyph = glyphParts[0];\r
                glyphFontFamily = glyphParts[1] || glyphFontFamily;\r
            }\r
            \r
            config.html = '&#' + glyph + ';';\r
            \r
            if (glyphFontFamily) {\r
                config.style = config.style || {};\r
                config.style.fontFamily = glyphFontFamily;\r
            }\r
            \r
            // A glyph is a graphic which is not an <img> tag so it should have\r
            // the corresponding role for Accessibility interface to recognize\r
            config.role = 'img';\r
        }\r
        else {\r
            config.cn = [img = {\r
                tag: 'img',\r
                id: me.id + '-img'\r
            }];\r
        }\r
\r
        if (img) {\r
            if (me.imgCls) {\r
                img.cls = (img.cls ? img.cls + ' ' : '') + me.imgCls;\r
            }\r
\r
            img.src = me.src || Ext.BLANK_IMAGE_URL;\r
        }\r
\r
        if (me.alt) {\r
            (img || config).alt = me.alt;\r
        }\r
        else {\r
            // Images that do not have alt attribute can't be properly announced\r
            // by screen readers. In best case they will be silently skipped;\r
            // in worst case screen reader will announce data url. Yes, that very long\r
            // base-64 encoded string. :/\r
            // That will make the application totally unusable for blind people.\r
            (img || config).alt = '';\r
            \r
            //<debug>\r
            Ext.log.warn('For WAI-ARIA compliance, IMG elements SHOULD have an alt attribute.');\r
            //</debug>\r
        }\r
\r
        if (me.title) {\r
            (img || config).title = me.title;\r
        }\r
\r
        return config;\r
    },\r
\r
    onRender: function () {\r
        var me = this,\r
            autoEl = me.autoEl,\r
            el;\r
\r
        me.callParent(arguments);\r
\r
        el = me.el;\r
        \r
        if (autoEl === 'img' || (Ext.isObject(autoEl) && autoEl.tag === 'img')) {\r
            me.imgEl = el;\r
        } else {\r
            me.imgEl = el.getById(me.id + '-img');\r
        }\r
    },\r
\r
    onDestroy: function () {\r
        var me = this,\r
            imgEl = me.imgEl;\r
\r
        // Only clean up when the img is a child, otherwise it will get handled\r
        // by the element destruction in the parent\r
        if (imgEl && me.el !== imgEl) {\r
            imgEl.destroy();\r
        }\r
        this.imgEl = null;\r
        this.callParent();\r
    },\r
\r
    getTitle: function () {\r
        return this.title;\r
    },\r
\r
    /**\r
     * Updates the {@link #title} of the image.\r
     * @param {String} title\r
     */\r
    setTitle: function (title) {\r
        var me = this,\r
            imgEl = me.imgEl;\r
\r
        me.title = title || '';\r
\r
        if (imgEl) {\r
            imgEl.dom.title = title || '';\r
        }\r
    },\r
\r
    getAlt: function () {\r
        return this.alt;\r
    },\r
\r
    /**\r
     * Updates the {@link #alt} of the image.\r
     * @param {String} alt\r
     */\r
    setAlt: function (alt) {\r
        var me = this,\r
            imgEl = me.imgEl;\r
\r
        me.alt = alt || '';\r
\r
        if (imgEl) {\r
            imgEl.dom.alt = alt || '';\r
        }\r
    },\r
\r
    updateSrc: function (src) {\r
        var imgEl = this.imgEl;\r
\r
        if (imgEl) {\r
            imgEl.dom.src = src || Ext.BLANK_IMAGE_URL;\r
        }\r
    },\r
\r
    /**\r
     * Updates the {@link #glyph} of the image.\r
     * @param {Number/String} glyph\r
     */\r
    setGlyph: function (glyph) {\r
        var me = this,\r
            glyphFontFamily = Ext._glyphFontFamily,\r
            old = me.glyph,\r
            el = me.el,\r
            glyphParts;\r
\r
        me.glyph = glyph;\r
        if (me.rendered && glyph !== old) {\r
            if (typeof glyph === 'string') {\r
                glyphParts = glyph.split('@');\r
                glyph = glyphParts[0];\r
                glyphFontFamily = glyphParts[1] || glyphFontFamily;\r
            }\r
\r
            el.dom.innerHTML = '&#' + glyph + ';';\r
            if (glyphFontFamily) {\r
                el.setStyle('font-family', glyphFontFamily);\r
            }\r
        }\r
    }\r
});