WinJS.UI.XYFocus.moveFocus function

This function moves focus to the next element that should receive focus.

Syntax

var htmlElement = WinJS.UI.XYFocus.moveFocus(direction, options);

Parameters

• direction
  Type: String

  The direction in which to move focus: "up", "left", "down", or "right".

• options [optional]
  Type: Object

  An 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

See also

WinJS.UI.XYFocus

focusRoot

tabindex attribute | tabindex property