add extjs 6.0.1 sources

[extjs.git] / extjs / packages / core / src / mixin / Accessible.js

/**\r
 * This mixin defines certain config options, properties, and APIs to be used\r
 * by Components that implement accessible traits according to WAI-ARIA 1.0 specification.\r
 *\r
 * @private\r
 */\r
Ext.define('Ext.mixin.Accessible', {\r
    extend: 'Ext.Mixin',\r
    \r
    mixinConfig: {\r
        id: 'accessible'\r
    },\r
    \r
    /**\r
     * @cfg {String} [ariaLabel] ARIA label for this Component. It is best to use\r
     * {@link #ariaLabelledBy} option instead, because screen readers prefer\r
     * `aria-labelledby` attribute to `aria-label`. {@link #ariaLabel} and\r
     * {@link #ariaLabelledBy} config options are mutually exclusive.\r
     */\r
    \r
    /**\r
     * @cfg {String} [ariaLabelledBy] DOM selector for a child element that is to be used\r
     * as label for this Component, set in `aria-labelledby` attribute.\r
     * If the selector is by `#id`, the label element can be any existing element,\r
     * not necessarily a child of the main Component element.\r
     *\r
     * {@link #ariaLabelledBy} and {@link #ariaLabel} config options are\r
     * mutually exclusive, and `ariaLabelledBy` has the higher precedence.\r
     */\r
    \r
    /**\r
     * @cfg {String} [ariaDescribedBy] DOM selector for a child element that is to be used\r
     * as description for this Component, set in `aria-describedby` attribute.\r
     * The selector works the same way as {@link #ariaLabelledBy}.\r
     */\r
    \r
    config: {\r
        /**\r
         * @cfg {Object} ariaAttributes An object containing ARIA attributes to be set\r
         * on this Component's ARIA element. Use this to set the attributes that cannot be\r
         * determined by the Component's state, such as `aria-live`, `aria-flowto`, etc.\r
         *\r
         * **Note** that this config is only meaningful at the Component rendering time,\r
         * and setting it after that will do nothing.\r
         */\r
        ariaAttributes: {\r
            $value: null,\r
            lazy: true\r
        }\r
    },\r
    \r
    /**\r
     * @property {String} [ariaRole] ARIA role for this Component, defaults to no role.\r
     * With no role, no other ARIA attributes are set.\r
     *\r
     * @readonly\r
     */\r
    \r
    /**\r
     * @property {Object} [ariaRenderAttributes] **Instance specific** ARIA attributes\r
     * to render into Component's ariaEl. This object is only used during rendering,\r
     * and is discarded afterwards.\r
     *\r
     * @private\r
     */\r
    \r
    privates: {\r
        /**\r
         * Find component(s) that label or describe this component,\r
         * and return the id(s) of their ariaEl elements.\r
         *\r
         * @param {Function/String/String[]} [reference] Component reference,\r
         * or array of component references, or a function that should return\r
         * the proper attribute string. The function will be called in the\r
         * context of the labelled component.\r
         *\r
         * @return {Ext.Element} Element id string, or null\r
         * @private\r
         */\r
        getAriaLabelEl: function(selector) {\r
            var ids = [],\r
                refHolder, i, len, cmp, result;\r
            \r
            if (selector) {\r
                if (Ext.isFunction(selector)) {\r
                    return selector.call(this);\r
                }\r
                else {\r
                    if (!Ext.isArray(selector)) {\r
                        selector = [selector];\r
                    }\r
                    \r
                    refHolder = this.lookupReferenceHolder();\r
                    \r
                    if (refHolder) {\r
                        for (i = 0, len = selector.length; i < len; i++) {\r
                            cmp = refHolder.lookupReference(selector[i]);\r
                            \r
                            if (cmp) {\r
                                ids.push(cmp.ariaEl.id);\r
                            }\r
                        }\r
                    }\r
                }\r
            }\r
        \r
            return ids.length ? ids.join(' ') : null;\r
        }\r
    }\r
});\r