add extjs 6.0.1 sources

[extjs.git] / extjs / classic / classic / src / util / FocusableContainer.js

/**\r
 * A mixin for groups of Focusable things (Components, Widgets, etc) that\r
 * should respond to arrow keys to navigate among the peers, but keep only\r
 * one of the peers tabbable by default (tabIndex=0)\r
 *\r
 * Some examples: Toolbars, Radio groups, Tab bars, Panel headers, Menus\r
 */\r
\r
Ext.define('Ext.util.FocusableContainer', {\r
    extend: 'Ext.Mixin',\r
    \r
    requires: [\r
        'Ext.util.KeyNav'\r
    ],\r
    \r
    mixinConfig: {\r
        id: 'focusablecontainer',\r
        \r
        before: {\r
            onAdd: 'onFocusableChildAdd',\r
            onRemove: 'onFocusableChildRemove',\r
            destroy: 'destroyFocusableContainer',\r
            onFocusEnter: 'onFocusEnter'\r
        },\r
        \r
        after: {\r
            afterRender: 'initFocusableContainer',\r
            onFocusLeave: 'onFocusLeave',\r
            afterShow: 'activateFocusableContainerEl'\r
        }\r
    },\r
    \r
    isFocusableContainer: true,\r
    \r
    /**\r
     * @cfg {Boolean} [enableFocusableContainer=true] Enable or disable\r
     * navigation with arrow keys for this FocusableContainer. This option may\r
     * be useful with nested FocusableContainers such as Grid column headers,\r
     * when only the root container should handle keyboard events.\r
     */\r
    enableFocusableContainer: true,\r
    \r
    /**\r
     * @cfg {Number} [activeChildTabIndex=0] DOM tabIndex attribute to set on the\r
     * active Focusable child of this container when using the "Roaming tabindex"\r
     * technique. Set this value to > 0 to precisely control the tabbing order\r
     * of the components/containers on the page.\r
     */\r
    activeChildTabIndex: 0,\r
    \r
    /**\r
     * @cfg {Number} [inactiveChildTabIndex=-1] DOM tabIndex attribute to set on\r
     * inactive Focusable children of this container when using the "Roaming tabindex"\r
     * technique. This value rarely needs to be changed from its default.\r
     */\r
    inactiveChildTabIndex: -1,\r
    \r
    privates: {\r
        initFocusableContainer: function(clearChildren) {\r
            var items, i, len;\r
            \r
            // Allow nested containers to optionally disable\r
            // children containers' behavior\r
            if (this.enableFocusableContainer) {\r
                clearChildren = clearChildren != null ? clearChildren : true;\r
                this.doInitFocusableContainer(clearChildren);\r
            }\r
            \r
            // A FocusableContainer instance such as a toolbar could have decided\r
            // to opt out of FC behavior for some reason; it could have happened\r
            // after all or almost all child items have been initialized with\r
            // focusableContainer reference. We need to clean this up if we're not\r
            // going to behave like a FocusableContainer after all.\r
            else {\r
                items = this.getFocusables();\r
                \r
                for (i = 0, len = items.length; i < len; i++) {\r
                    items[i].focusableContainer = null;\r
                }\r
            }\r
        },\r
        \r
        doInitFocusableContainer: function(clearChildren) {\r
            var me = this,\r
                el, child;\r
            \r
            el = me.getFocusableContainerEl();\r
            \r
            // This flag allows post factum initialization of the focusable container,\r
            // i.e. when container was empty initially and then some tabbable children\r
            // were added and we need to clear their tabIndices after priming our own\r
            // element's tabIndex.\r
            // This is useful for Panel and Window headers that might have tools\r
            // added dynamically.\r
            if (clearChildren) {\r
                me.clearFocusables();\r
            }\r
            \r
            // If we have no potentially focusable children, or all potentially focusable\r
            // children are presently disabled, don't init the container el tabIndex.\r
            // There is no point in tabbing into container when it can't shift focus\r
            // to a child.\r
            child = me.findNextFocusableChild({ step: 1, beforeRender: true });\r
            \r
            if (child) {\r
                // We set tabIndex on the focusable container el so that the user\r
                // could tab into it; we catch its focus event and focus a child instead\r
                me.activateFocusableContainerEl(el);\r
            }\r
            \r
            // Unsightly long names help to avoid possible clashing with class\r
            // or instance properties. We have to be extra careful in a mixin!\r
            me.focusableContainerMouseListener = me.mon(\r
                el, 'mousedown', me.onFocusableContainerMousedown, me\r
            );\r
            \r
            // Having keyNav doesn't hurt when container el is not focusable\r
            me.focusableKeyNav = me.createFocusableContainerKeyNav(el);\r
        },\r
        \r
        createFocusableContainerKeyNav: function(el) {\r
            var me = this;\r
            \r
            return new Ext.util.KeyNav(el, {\r
                eventName: 'keydown',\r
                ignoreInputFields: true,\r
                scope: me,\r
\r
                tab: me.onFocusableContainerTabKey,\r
                enter: me.onFocusableContainerEnterKey,\r
                space: me.onFocusableContainerSpaceKey,\r
                up: me.onFocusableContainerUpKey,\r
                down: me.onFocusableContainerDownKey,\r
                left: me.onFocusableContainerLeftKey,\r
                right: me.onFocusableContainerRightKey\r
            });\r
        },\r
        \r
        destroyFocusableContainer: function() {\r
            if (this.enableFocusableContainer) {\r
                this.doDestroyFocusableContainer();\r
            }\r
        },\r
    \r
        doDestroyFocusableContainer: function() {\r
            var me = this;\r
        \r
            if (me.keyNav) {\r
                me.keyNav.destroy();\r
            }\r
            \r
            if (me.focusableContainerMouseListener) {\r
                me.focusableContainerMouseListener.destroy();\r
            }\r
            \r
            me.focusableKeyNav = me.focusableContainerMouseListener = null;\r
        },\r
        \r
        // Default FocusableContainer implies a flat list of focusable children\r
        getFocusables: function() {\r
            return this.items.items;\r
        },\r
\r
        initDefaultFocusable: function(beforeRender) {\r
            var me = this,\r
                activeIndex = me.activeChildTabIndex,\r
                haveFocusable = false,\r
                items, item, i, len, tabIdx;\r
\r
            items = me.getFocusables();\r
            len   = items.length;\r
\r
            if (!len) {\r
                return;\r
            }\r
\r
            // Check if any child Focusable is already active.\r
            // Note that we're not determining *which* focusable child\r
            // to focus here, only that we have some focusables.\r
            for (i = 0; i < len; i++) {\r
                item = items[i];\r
\r
                if (item.focusable && !item.disabled) {\r
                    haveFocusable = true;\r
                    tabIdx = item.getTabIndex();\r
\r
                    if (tabIdx != null && tabIdx >= activeIndex) {\r
                        return item;\r
                    }\r
                }\r
            }\r
\r
            // No interactive children found, no point in going further\r
            if (!haveFocusable) {\r
                return;\r
            }\r
\r
            // No child is focusable by default, so the first *interactive*\r
            // one gets initial childTabIndex. We are not looking for a focusable\r
            // child here because it may not be focusable yet if this happens\r
            // before rendering; we assume that an interactive child will become\r
            // focusable later and now activateFocusable() will just assign it\r
            // the respective tabIndex.\r
            item = me.findNextFocusableChild({\r
                beforeRender: beforeRender,\r
                items: items,\r
                step: true\r
            });\r
\r
            if (item) {\r
                me.activateFocusable(item);\r
            }\r
\r
            return item;\r
        },\r
\r
        clearFocusables: function() {\r
            var me = this,\r
                items = me.getFocusables(),\r
                len = items.length,\r
                item, i;\r
\r
            for (i = 0; i < len; i++) {\r
                item = items[i];\r
\r
                if (item.focusable && !item.disabled) {\r
                    me.deactivateFocusable(item);\r
                }\r
            }\r
        },\r
\r
        activateFocusable: function(child, /* optional */ newTabIndex) {\r
            var activeIndex = newTabIndex != null ? newTabIndex : this.activeChildTabIndex;\r
\r
            child.setTabIndex(activeIndex);\r
        },\r
\r
        deactivateFocusable: function(child, /* optional */ newTabIndex) {\r
            var inactiveIndex = newTabIndex != null ? newTabIndex : this.inactiveChildTabIndex;\r
\r
            child.setTabIndex(inactiveIndex);\r
        },\r
\r
        onFocusableContainerTabKey: function() {\r
            return true;\r
        },\r
\r
        onFocusableContainerEnterKey: function() {\r
            return true;\r
        },\r
\r
        onFocusableContainerSpaceKey: function() {\r
            return true;\r
        },\r
\r
        onFocusableContainerUpKey: function(e) {\r
            // Default action is to scroll the nearest vertically scrollable container\r
            e.preventDefault();\r
            \r
            return this.moveChildFocus(e, false);\r
        },\r
        \r
        onFocusableContainerDownKey: function(e) {\r
            // Ditto\r
            e.preventDefault();\r
            \r
            return this.moveChildFocus(e, true);\r
        },\r
        \r
        onFocusableContainerLeftKey: function(e) {\r
            // Default action is to scroll the nearest horizontally scrollable container\r
            e.preventDefault();\r
            \r
            return this.moveChildFocus(e, false);\r
        },\r
        \r
        onFocusableContainerRightKey: function(e) {\r
            // Ditto\r
            e.preventDefault();\r
            \r
            return this.moveChildFocus(e, true);\r
        },\r
        \r
        getFocusableFromEvent: function(e) {\r
            var child = Ext.Component.fromElement(e.getTarget());\r
        \r
            //<debug>\r
            if (!child) {\r
                Ext.raise("No focusable child found for keyboard event!");\r
            }\r
            //</debug>\r
            \r
            return child;\r
        },\r
        \r
        moveChildFocus: function(e, forward) {\r
            var child = this.getFocusableFromEvent(e);\r
            \r
            return this.focusChild(child, forward, e);\r
        },\r
    \r
        focusChild: function(child, forward) {\r
            var nextChild = this.findNextFocusableChild({\r
                child: child,\r
                step: forward\r
            });\r
        \r
            if (nextChild) {\r
                nextChild.focus();\r
            }\r
        \r
            return nextChild;\r
        },\r
        \r
        findNextFocusableChild: function(options) {\r
            // This method is private, so options should always be provided\r
            var beforeRender = options.beforeRender,\r
                items, item, child, step, idx, i, len;\r
        \r
            items = options.items || this.getFocusables();\r
            step  = options.step != null ? options.step : 1;\r
            child = options.child;\r
            \r
            // If the child is null or undefined, idx will be -1.\r
            // The loop below will account for that, trying to find\r
            // the first focusable child from either end (depending on step)\r
            idx = Ext.Array.indexOf(items, child);\r
            \r
            // It's often easier to pass a boolean for 1/-1\r
            step = step === true ? 1 : step === false ? -1 : step;\r
        \r
            len = items.length;\r
            i   = step > 0 ? (idx < len ? idx + step : 0) : (idx > 0 ? idx + step : len - 1);\r
        \r
            for (;; i += step) {\r
                // We're looking for the first or last focusable child\r
                // and we've reached the end of the items, so punt\r
                if (idx < 0 && (i >= len || i < 0)) {\r
                    return null;\r
                }\r
                \r
                // Loop over forward\r
                else if (i >= len) {\r
                    i = -1; // Iterator will increase it once more\r
                    continue;\r
                }\r
                \r
                // Loop over backward\r
                else if (i < 0) {\r
                    i = len;\r
                    continue;\r
                }\r
                \r
                // Looped to the same item, give up\r
                else if (i === idx) {\r
                    return null;\r
                }\r
                \r
                item = items[i];\r
                \r
                if (!item || !item.focusable || item.disabled) {\r
                    continue;\r
                }\r
                \r
                // This loop can be run either at FocusableContainer init time,\r
                // or later when we need to navigate upon pressing an arrow key.\r
                // When we're navigating, we have to know exactly if the child is\r
                // focusable or not, hence only rendered children will make the cut.\r
                // At the init time item.isFocusable() may return false incorrectly\r
                // just because the item has not been rendered yet and its focusEl\r
                // is not defined, so we don't bother to call isFocusable and return\r
                // the first potentially focusable child.\r
                if (beforeRender || (item.isFocusable && item.isFocusable())) {\r
                    return item;\r
                }\r
            }\r
        \r
            return null;\r
        },\r
    \r
        getFocusableContainerEl: function() {\r
            return this.el;\r
        },\r
        \r
        onFocusableChildAdd: function(child) {\r
            if (this.enableFocusableContainer) {\r
                return this.doFocusableChildAdd(child);\r
            }\r
        },\r
        \r
        activateFocusableContainerEl: function(el) {\r
            el = el || this.getFocusableContainerEl();\r
            \r
            // Might not yet be rendered\r
            if (el) {\r
                el.set({ tabIndex: this.activeChildTabIndex });\r
            }\r
        },\r
        \r
        deactivateFocusableContainerEl: function(el) {\r
            el = el || this.getFocusableContainerEl();\r
            \r
            if (el) {\r
                el.set({ tabIndex: undefined });\r
            }\r
        },\r
        \r
        isFocusableContainerActive: function() {\r
            var me = this,\r
                isActive = false,\r
                el, child, focusEl;\r
            \r
            el = me.getFocusableContainerEl();\r
            \r
            if (el && el.isTabbable && el.isTabbable()) {\r
                isActive = true;\r
            }\r
            else {\r
                child = me.lastFocusedChild;\r
                focusEl = child && child.getFocusEl && child.getFocusEl();\r
                \r
                if (focusEl && focusEl.isTabbable && focusEl.isTabbable()) {\r
                    isActive = true;\r
                }\r
            }\r
            \r
            return isActive;\r
        },\r
        \r
        doFocusableChildAdd: function(child) {\r
            if (child.focusable) {\r
                child.focusableContainer = this;\r
            }\r
        },\r
        \r
        onFocusableChildRemove: function(child) {\r
            if (this.enableFocusableContainer) {\r
                return this.doFocusableChildRemove(child);\r
            }\r
            \r
            child.focusableContainer = null;\r
        },\r
    \r
        doFocusableChildRemove: function(child) {\r
            // If the focused child is being removed, we deactivate the FocusableContainer\r
            // So that it returns to the tabbing order.\r
            // For example, locking a grid column must return the owning HeaderContainer\r
            // to tabbability\r
            if (child === this.lastFocusedChild) {\r
                this.lastFocusedChild = null;\r
                this.activateFocusableContainerEl();\r
            }\r
        },\r
        \r
        onFocusableContainerMousedown: function(e, target) {\r
            var targetCmp = Ext.Component.fromElement(target);\r
            \r
            // Capture the timestamp for the mousedown. If we're navigating\r
            // into the container itself via the mouse we don't want to\r
            // default focus the first child like we would when using the keyboard.\r
            // By the time we get to the focusenter handling, we don't know what has caused\r
            // the focus to be triggered, so if the timestamp falls within some small epsilon,\r
            // the focus enter has been caused via the mouse and we can react accordingly.\r
            this.mousedownTimestamp = targetCmp === this ? Ext.Date.now() : 0;\r
            \r
            // Prevent focusing the container itself. DO NOT remove this clause, it is\r
            // untestable by our unit tests: injecting mousedown events will not cause\r
            // default action in the browser, the element never gets focus and tests\r
            // never fail. See http://www.w3.org/TR/DOM-Level-3-Events/#trusted-events\r
            if (targetCmp === this) {\r
                e.preventDefault();\r
            }\r
        },\r
\r
        onFocusEnter: function(e) {\r
            var me = this,\r
                target = e.toComponent,\r
                mousedownTimestamp = me.mousedownTimestamp,\r
                epsilon = 50,\r
                child;\r
            \r
            if (!me.enableFocusableContainer) {\r
                return null;\r
            }\r
            \r
            me.mousedownTimestamp = 0;\r
            \r
            if (target === me) {\r
                if (!mousedownTimestamp || Ext.Date.now() - mousedownTimestamp > epsilon) {\r
                    child = me.initDefaultFocusable();\r
\r
                    if (child) {\r
                        me.deactivateFocusableContainerEl();\r
                        child.focus();\r
                    }\r
                }\r
            }\r
            else {\r
                me.deactivateFocusableContainerEl();\r
            }\r
            \r
            return target;\r
        },\r
\r
        onFocusLeave: function(e) {\r
            var me = this,\r
                lastFocused = me.lastFocusedChild;\r
            \r
            if (!me.enableFocusableContainer) {\r
                return;\r
            }\r
\r
            if (!me.destroyed && !me.destroying) {\r
                me.clearFocusables();\r
\r
                if (lastFocused && !lastFocused.disabled) {\r
                    me.activateFocusable(lastFocused);\r
                }\r
                else {\r
                    me.activateFocusableContainerEl();\r
                }\r
            }\r
        },\r
        \r
        beforeFocusableChildBlur: Ext.privateFn,\r
        afterFocusableChildBlur: Ext.privateFn,\r
    \r
        beforeFocusableChildFocus: function(child) {\r
            var me = this;\r
            \r
            if (!me.enableFocusableContainer) {\r
                return;\r
            }\r
            \r
            me.clearFocusables();\r
            me.activateFocusable(child);\r
            \r
            if (child.needArrowKeys) {\r
                me.guardFocusableChild(child);\r
            }\r
        },\r
        \r
        guardFocusableChild: function(child) {\r
            var me = this,\r
                index = me.activeChildTabIndex,\r
                guard;\r
            \r
            guard = me.findNextFocusableChild({ child: child, step: -1 });\r
            \r
            if (guard) {\r
                guard.setTabIndex(index);\r
            }\r
            \r
            guard = me.findNextFocusableChild({ child: child, step: 1 });\r
            \r
            if (guard) {\r
                guard.setTabIndex(index);\r
            }\r
        },\r
    \r
        afterFocusableChildFocus: function(child) {\r
            if (!this.enableFocusableContainer) {\r
                return;\r
            }\r
            \r
            this.lastFocusedChild = child;\r
        },\r
        \r
        beforeFocusableChildEnable: Ext.privateFn,\r
        \r
        onFocusableChildEnable: function(child) {\r
            var me = this;\r
            \r
            if (!me.enableFocusableContainer) {\r
                return;\r
            }\r
            \r
            // Some Components like Buttons do not render tabIndex attribute\r
            // when they start their lifecycle disabled, or remove tabIndex\r
            // if they get disabled later. Subsequently, such Components will\r
            // reset their tabIndex to default configured value upon enabling.\r
            // We don't want these children to be tabbable so we reset their\r
            // tabIndex yet again, unless this child is the last focused one.\r
            if (child !== me.lastFocusedChild) {\r
                me.deactivateFocusable(child);\r
                \r
                if (!me.isFocusableContainerActive()) {\r
                    me.activateFocusableContainerEl();\r
                }\r
            }\r
        },\r
        \r
        beforeFocusableChildDisable: function(child) {\r
            var me = this,\r
                nextTarget;\r
            \r
            if (!me.enableFocusableContainer || me.destroying || me.destroyed) {\r
                return;\r
            }\r
            \r
            // When currently focused child is about to be disabled,\r
            // it may lose the focus as well. For example, Buttons\r
            // will remove tabIndex attribute upon disabling, which\r
            // in turn will throw focus to the document body and cause\r
            // onFocusLeave to fire on the FocusableContainer.\r
            // We're focusing the next sibling to prevent that.\r
            if (child.hasFocus) {\r
                nextTarget = me.findNextFocusableChild({ child: child }) ||\r
                             child.findFocusTarget();\r
                \r
                // Note that it is entirely possible not to find the nextTarget,\r
                // e.g. when we're disabling the last button in a toolbar rendered\r
                // directly into document body. We don't have a good way to handle\r
                // such cases at present.\r
                if (nextTarget) {\r
                    nextTarget.focus();\r
                }\r
            }\r
        },\r
        \r
        onFocusableChildDisable: function(child) {\r
            var me = this,\r
                lastFocused = me.lastFocusedChild,\r
                firstFocusableChild;\r
            \r
            if (!me.enableFocusableContainer || me.destroying || me.destroyed) {\r
                return;\r
            }\r
            \r
            // If the disabled child was the last focused item of this\r
            // FocusableContainer, we have to reset the tabbability of\r
            // our container element.\r
            if (child === lastFocused) {\r
                me.activateFocusableContainerEl();\r
            }\r
            \r
            // It is also possible that the disabled child was the last\r
            // focusable child of this container, in which case we need\r
            // to make the container untabbable.\r
            firstFocusableChild = me.findNextFocusableChild({ step: 1 });\r
            \r
            if (!firstFocusableChild) {\r
                me.deactivateFocusableContainerEl();\r
            }\r
        },\r
        \r
        // TODO\r
        onFocusableChildShow: Ext.privateFn,\r
        onFocusableChildHide: Ext.privateFn,\r
        onFocusableChildMasked: Ext.privateFn,\r
        onFocusableChildDestroy: Ext.privateFn,\r
        onFocusableChildUpdate: Ext.privateFn\r
    }\r
});\r