node-focusmanager.js revision b6a72da8ecd1c725f5c9432172ae02d72e09162b
/**
* <p>The FocusManager Node Plugin makes it easy to manage focus among
* a Node's descendants. Primarily intended to help with widget development,
* use of the FocusManager Node Plugin improves the keyboard accessibility
* of widgets by reducing the number of Nodes in the browser's default tab flow
* to one per widget. With one tab stop per widget, users can quickly
* navigate between widgets by pressing the tab key. Additionally, the
* FocusManager provides an easy means of defining the key(s) used to move
* focus between a Node's descendants. Finally, as the CSS
* <a href="http://www.w3.org/TR/CSS21/selector.html#x38"><code>:focus</code></a>
* pseudo class is not supported on all elements in all
* <a href="http://developer.yahoo.com/yui/articles/gbs/">A-Grade browsers</a>,
* the FocusManager Node Plugin provides an easy, cross-browser means of
* styling focus.
* </p>
*
* @module focusmanager
*/
// Frequently used strings
var ACTIVE_DESCENDANT = "activeDescendant",
ID = "id",
DISABLED = "disabled",
TAB_INDEX = "tabIndex",
HAS_FOCUS = "hasFocus",
FOCUS_CLASS = "focusClass",
CIRCULAR = "circular",
UI = "UI",
KEY = "key",
FOCUS_MANAGER = "focusManager",
HOST = "host",
// Collection of keys that, when pressed, cause the browser viewport
// to scroll.
scrollKeys = {
37: true,
38: true,
39: true,
40: true
},
// Library shortcuts
/**
* The FocusManager class is a plugin for a Node instance. The class is used
* via the <a href="Node.html#method_plug"><code>plug</code></a> method of Node
* and should not be instantiated directly.
* @namespace plugin
* @class FocusManager
*/
var FocusManager = function () {
};
FocusManager.ATTRS = {
/**
* Boolean indicating that one of the descendants is focused.
*
* @attribute hasFocus
* @readOnly
* @default false
* @type boolean
*/
hasFocus: {
value: false,
readOnly: true
},
/**
* String representing the CSS selector used to define the descendant Nodes.
*
* @attribute descendants
* @type string
*/
descendants: {
}
},
/**
* Node, or index of the Node, representing the descendant that is either
* focused or is focusable (<code>tabIndex</code> attribute is set to 0).
* The value cannot represent a disabled descendant Node. Use a value of -1
* to remove all descendant Nodes from the default tab flow.
* If no value is specified, the active descendant will be inferred using
* the following criteria:
* <ol>
* <li>Examining the <code>tabIndex</code> attribute of each descendant and
* using the first descendant whose <code>tabIndex</code> attribute is set
* to 0</li>
* <li>If no default can be inferred then the value is set to either 0 or
* the index of the first enabled descendant.</li>
* </ol>
*
* @attribute activeDescendant
* @type Number
*/
descendantsMap = this._descendantsMap,
descendants = this._descendants,
}
}
else {
// The user passed a reference to a Node that wasn't one
// of the descendants.
}
}
else {
}
if (descendants) {
// Setting the "activeDescendant" attribute to the index
// of a disabled descendant is invalid.
}
}
return returnValue;
}
},
/**
* Object literal representing the keys to be used to navigate between the
* <code>{ next: "down:40", previous: "down:38" }</code>. The value for the
* "next" and "previous" properties are used to attach "key" event listeners.
* See the <a href="event/#keylistener">Using the key Event</a> section of
* the Event documentation for more information on "key" event listeners.
*
* @attribute keys
* @type Object
*/
keys: {
value: {
next: null,
previous: null
}
},
/**
* String representing the CSS class name used to indicate the Node instance
* that currently has DOM focus.
*
* @attribute focusClass
* @type String
*/
focusClass: { },
/**
* when the end or beginning of the descendants has been reached.
*
* @attribute circular
* @type Boolean
*/
circular: {
value: true
}
};
// Protected properties
// Boolean indicating if the FocusManager is active.
_stopped: true,
// NodeList representing the descendants selected via the
// "descendants" attribute.
_descendants: null,
// Object literal mapping the IDs of each descendant to its index in the
// "_descendants" NodeList.
_descendantsMap: null,
// Reference to the Node instance to which the focused CSS class (defined
// by the "focusClass" attribute) is currently applied.
_focusedNode: null,
// Number representing the index of the last descendant Node.
_lastNodeIndex: 0,
// Array of handles for event handlers used for a FocusManager instance.
_eventHandlers: null,
// Protected methods
/**
* @method _initDescendants
* @description Sets the <code>tabIndex</code> attribute of all of the
* descendants to -1, except the active descendant, whose
* <code>tabIndex</code> attribute is set to 0.
* @protected
*/
_initDescendants: function () {
descendantsMap = {},
nFirstEnabled = -1,
sID,
i = 0;
nActiveDescendant = -1;
}
if (descendants) {
if (nDescendants > 1) {
for (i = 0; i < nDescendants; i++) {
nFirstEnabled = i;
}
// If the user didn't specify a value for the
// "activeDescendant" attribute try to infer it from
// the markup.
if (nActiveDescendant < 0 &&
nActiveDescendant = i;
}
if (!sID) {
}
descendantsMap[sID] = i;
}
// If the user didn't specify a value for the
// "activeDescendant" attribute and no default value could be
// determined from the markup, then default to 0.
if (nActiveDescendant < 0) {
nActiveDescendant = 0;
}
// Check to make sure the active descendant isn't disabled,
// and fall back to the first enabled descendant if it is.
}
this._descendants = descendants;
this._descendantsMap = descendantsMap;
// Need to set the "tabIndex" attribute here, since the
// "activeDescendantChange" event handler used to manage
// the setting of the "tabIndex" attribute isn't wired up yet.
}
}
},
/**
* @method _isDescendant
* @description Determines if the specified Node instance is a descendant
* managed by the FocusManager.
* @param node {Node} Node instance to be checked.
* @return {Boolean} Boolean indicating if the specified Node instance is a
* descendant managed by the FocusManager.
*/
_isDescendant: function (node) {
},
/**
* @method _removeFocusClass
* @description Removes the CSS class representing focus (as specified by
* the "focusClass" attribute) from the Node instance to which it is
* currently applied.
* @protected
*/
_removeFocusClass: function () {
var oFocusedNode = this._focusedNode,
if (oFocusedNode && sClassName) {
}
},
/**
* @method _detachKeyHandler
* @description Detaches the "key" event handlers used to support the "keys"
* attribute.
* @protected
*/
_detachKeyHandler: function () {
var prevKeyHandler = this._prevKeyHandler,
nextKeyHandler = this._nextKeyHandler,
keyPressHandler = this._keyPressHandler;
if (prevKeyHandler) {
}
if (nextKeyHandler) {
}
if (keyPressHandler) {
}
},
/**
* @method _preventScroll
* @description Prevents the viewport from scolling when the user presses
* the up, down, left, or right key.
* @protected
*/
_preventScroll: function (event) {
}
},
/**
* @method _attachKeyHandler
* @description Attaches the "key" event handlers used to support the "keys"
* attribute.
* @protected
*/
_attachKeyHandler: function () {
this._detachKeyHandler();
if (sPreviousKey) {
this._prevKeyHandler =
}
if (sNextKey) {
this._nextKeyHandler =
}
// For Opera and Firefox 2: In these browsers it is necessary to
// call the "preventDefault" method on a "keypress" event in order
// to prevent the viewport from scrolling.
this._keyPressHandler =
}
},
/**
* @method _detachEventHandlers
* @description Detaches all event handlers used by the FocusManager.
* @protected
*/
_detachEventHandlers: function () {
this._detachKeyHandler();
var aHandlers = this._eventHandlers;
if (aHandlers) {
});
this._eventHandlers = null;
}
},
/**
* @method _detachEventHandlers
* @description Attaches all event handlers used by the FocusManager.
* @protected
*/
_attachEventHandlers: function () {
var descendants = this._descendants,
aHandlers = this._eventHandlers || [];
// For performance: defer attaching all event handlers until the
// first time one of the specified descendants receives focus
Y.on("mousedown",
this._afterActiveDescendantChange));
}
else {
this._attachKeyHandler();
}
this._eventHandlers = aHandlers;
}
},
// Protected event handlers
/**
* @method _onDocMouseDown
* @description "mousedown" event handler for the owner document of the
* FocusManager's Node.
* @protected
* @param event {Object} Object representing the DOM event.
*/
_onDocMouseDown: function (event) {
// Fix general problem in Webkit: mousing down on a button or an
// anchor element doesn't focus it.
// For all browsers: makes sure that the descendant that
// was the target of the mousedown event is now considered the
// active descendant.
}
// Fix for Webkit:
// Document doesn't receive focus in Webkit when the user mouses
// down on it, so the "hasFocus" attribute won't get set to the
// correct value.
this._onDocFocus(event);
}
},
/**
* @method _onDocFocus
* @description "focus" event handler for the owner document of the
* FocusManager's Node.
* @protected
* @param event {Object} Object representing the DOM event.
*/
_onDocFocus: function (event) {
oFocusedNode = this._focusedNode,
if (this._focusTarget) {
this._focusTarget = null;
}
// The target is a descendant of the root Node.
if (!bHasFocus && bInCollection) {
// The user has focused a focusable descendant.
bHasFocus = true;
}
else if (bHasFocus && !bInCollection) {
// The user has focused a child of the root Node that is
// not one of the descendants managed by this FocusManager
// so clear the currently focused descendant.
bHasFocus = false;
}
}
else {
// The target is some other node in the document.
bHasFocus = false;
}
if (sClassName) {
this._removeFocusClass();
}
if (bInCollection && bHasFocus) {
this._focusedNode = oTarget;
}
}
this._attachEventHandlers();
}
},
/**
* @method _focusNext
* @description Keydown event handler that moves focus to the next
* enabled descendant.
* @protected
* @param event {Object} Object representing the DOM event.
* @param activeDescendant {Number} Number representing the index of the
* next descendant to be focused
*/
(nActiveDescendant <= this._lastNodeIndex)) {
nActiveDescendant = 0;
}
}
else {
this.focus(nActiveDescendant);
}
}
this._preventScroll(event);
},
/**
* @method _focusPrevious
* @description Keydown event handler that moves focus to the previous
* enabled descendant.
* @protected
* @param event {Object} Object representing the DOM event.
* @param activeDescendant {Number} Number representing the index of the
* next descendant to be focused.
*/
nActiveDescendant = this._lastNodeIndex;
}
}
else {
this.focus(nActiveDescendant);
}
}
this._preventScroll(event);
},
/**
* @method _afterActiveDescendantChange
* @description afterChange event handler for the
* "activeDescendant" attribute.
* @protected
* @param event {Object} Object representing the change event.
*/
_afterActiveDescendantChange: function (event) {
if (oNode) {
}
if (oNode) {
}
},
// Public methods
initializer: function (config) {
this.start();
},
destructor: function () {
this.stop();
},
/**
* @method focus
* @description Focuses the active descendant and sets the "hasFocus"
* attribute to true.
* @param index {Number} Optional. Number representing the index of the
* descendant to be set as the active descendant.
* @param index {Node} Optional. Node instance representing the
* descendant to be set as the active descendant.
*/
}
if (oNode) {
// In Opera focusing a <BUTTON> element programmatically
// will result in the document object getting focus first,
// immediately followed by the <BUTTON> element.
// This results in the "_onDocFocus" handler incorrectly
// setting the "hasFocus" Attribute to false. To fix this,
// set a flag ("_focusTarget") that the "_onDocFocus" method
// can look for to properly handle this edge case.
this._focusTarget = oNode;
}
}
},
/**
* @method blur
* @description Blurs the current active descendant and sets the hasFocus
* attribute to false.
*/
blur: function () {
var oNode;
if (oNode) {
// For Opera and Webkit: Blurring an element in either browser
// doesn't result in another element (such as the document)
// being focused. Therefore, the "_onDocFocus" method
// responsible for managing the application and removal of the
// focus indicator CSS class name is never called.
this._removeFocusClass();
}
}
},
/**
* @method start
* @description Enables the FocusManager.
*/
start: function () {
if (this._stopped) {
this._initDescendants();
this._attachEventHandlers();
this._stopped = false;
}
},
/**
* @method stop
* @description Disables the FocusManager by detaching all event handlers.
*/
stop: function () {
if (!this._stopped) {
this._detachEventHandlers();
this._descendants = null;
this._focusedNode = null;
this._lastNodeIndex = 0;
this._stopped = true;
}
},
/**
* @method refresh
* @description Refreshes the FocusManager's descendants by re-executing the
* CSS selector query specified by the "descendants" attribute.
*/
refresh: function () {
this._initDescendants();
}
});
Y.namespace("Plugin");