WinJS.UI.XYFocus.moveFocus function
.png)
This function moves focus to the next element that should receive focus.
Syntax
var htmlElement = WinJS.UI.XYFocus.moveFocus(direction, options);
Parameters
direction
Type: StringThe direction in which to move focus: "up", "left", "down", or "right".
options [optional]
Type: ObjectAn object that contains one or more property/value pairs to apply to the search for the next element. The following properties are supported:
| Property | Description |
|---|---|
focusRoot |
Type: HTMLElement Specifies the root element of the search. By default, the document body is used as the search root. |
referenceElement |
Type: HTMLElement Performs the search as though the specified element were the currently focused element, instead of using the actual currently focused element. |
Return value
Type: HTMLElement
The element that received focus, or null if an element wasn't found.
Remarks
Changing focus to an element using moveFocus() executes a relative move in a two-dimensional (XY) plane based on the current element that has focus or a specified reference element. This function does not use the tabindex element attribute to determine the next element to receive focus. (Although it will use the presence of a set tabindex attribute as an indicator that the element is qualified to receive focus.)
Elements considered as focusable by default include:
- a
- button
- iframe
- input
- select
- textarea
Note In HTML5, the tabindex attribute can be used on any HTML element. However, while it is not necessarily useful for keyboard navigation, it could be used to create a reference element for XY navigation. An HTML element that has its tabindex value set to -1 is not focusable.
If the moveFocus() function returns null, there is no element in the specified direction to receive focus and the move fails; focus remains with the current element.
The moveFocus() function always changes focus relative to the direction of the HTML element that already has focus. But it is possible to change this behavior by specifying a new focusRoot or referenceElement from which to make the focus move. The focusRoot defines the focus root element within the element tree (body is used by default) and becomes the reference element from which to move. The referenceElement can be any element capable of receiving focus as the reference element from which to move.
After the moveFocus() function has been called, the focuschanging event fires. Once the new element has focus, the focuschanged event fires.
Requirements
Minimum WinJS version |
WinJS 3.0 |
Namespace |
WinJS.UI.XYFocus |