DirectionalNavigation Reference

Provides automatic focus handling.

Methods

findNextFocusElement(direction, options)
Programmatically determines the next element that should receive input focus without moving focus.

direction
Type string
Specifies the direction to move focus. The value can be one of the following strings:

• "left"
• "right"
• "up"
• "down"

options Type Object
An object with the following properties:

• focusRoot - An HTMLElement to use as the focus root so that only elements under the focus root are considered by the algorithm.
• historyRect - An object of the form:
  {
  top: ,
  left: ,
  bottom: ,
  right: ,
  width: ,
  height:
  }
  This object represents the previous focus history and is used to give weight to certain elements over others.
• referenceElement - An HTMLElement that the algorithm will use as the currently focused element.
• referenceRect - An object of the form:
  {
  top: ,
  left: ,
  bottom: ,
  right: ,
  width: ,
  height:
  }
  This object represents a fake element currently focused element.

Use findNextFocusElement to determine the next element that the automatic focus algorithm would set focus the focus to, based on the current focus and the navigation direction specified in keyCode.

If focusHintRectangle is null, focus is calculated from the currently focused element, moving in the direction specified by keyCode.

If focusHintRectangle is not null, it must specify the left, top, width, and height of a rectangle that is used as the source location of the focus navigation. Focus is calculated from the specified rectangle, moving in the direction specified by keyCode.

findNextFocusElement ignores manual focus overrides set in a data-win-focus property. It returns the next element that would be selected heuristically, regardless of manual focus overrides.

Normally, focus navigation is handled automatically for you. Use findNextFocusElement only if you are doing manual focus handling. See Using Automatic Focus for more information.

Example

The following examples uses findNextFocusElement to determine the best candidate for next focus, and then sets focus to the returned element.

JavaScript

var nextElement = TVJS.DirectionalNavigation.findNextFocusElement("left", null);
if (nextElement) {
    nextElement.focus();
}

The following example demonstrates navigating to a page as if focus was coming in from the left of the page. It specifies an off-screen rectangle for focusHintRectangle, and then sets focus to the returned element.

JavaScript

var nextElement = TVJS.DirectionalNavigation.findNextFocusElement("right", {left: -1, top: -1, width: 1, height: 1});
if (nextElement) {
    nextElement.focus();
}

moveFocus(direction, options)
The same as findNextFocusElement except it also sets focus.

direction
See findNextFocusElement

options
See findNextFocusElement

Properties

focusRoot
Type HTMLElement
Root element for automatic focus handling. Descendants of the focus root are the only elements considered for directional navigation.

The focus root determines the elements that are considered as targets for automatic focus navigation. Only descendants of the focus root are considered for automatic focus navigation. Setting the focus root restricts the automatic focus algorithm to only look at descendants of the root element when deciding which elements can receive focus in response to navigation events.

Setting focusRoot to null disables automatic focus handling. To re-enable automatic focus, set focusRoot to an element on the page.

Example

The following example sets the focus root to a container element. Only descendants of the container will be considered for focus navigation.

var newFocusRoot = document.getElementById("subContainer");
TVJS.DirectionalNavigation.focusRoot = newFocusRoot;

keyCodeMap Type Object An object containing 4 arrays, one for each direction: left, right, up, down. Each array has a set of keyCodes that will trigger a focus navigation.

Example:

TVJS.DirectionalNavigation.keyCodeMap.left.push(65) // a  
TVJS.DirectionalNavigation.keyCodeMap.right.push(68) // d 
TVJS.DirectionalNavigation.keyCodeMap.up.push(87) // w 
TVJS.DirectionalNavigation.keyCodeMap.down.push(83) // s 

Events

focuschanging
Occurs when the automatic focus algorithm is about to set focus. You can call preventDefault() on the event object to stop the algorithm from settings focus. Or you can hook this event to execute custom code before focus gets set.

Event args Detail An object containing the following properties:

• nextFocusElement - An HTMLElement representing the element that is about to receive focus
• keyCode - The keyCode that initiated the focus movement

`function onfocuschanging(eventArgs) { /* Your code */ }`  

// addEventListener syntax

TVJS.DirectionalNavigation.addEventListener("focuschanging", onfocuschanging);
TVJS.DirectionalNavigation.removeEventListener("focuschanging", onfocuschanging);

Remarks

This event is sent immediately before the focus changes. Cancel the event to prevent focus change. To cancel the event, call eventArgs.preventDefault() in your event handler.

The eventArgs.detail.nextFocusElement property of the event data specifies the next element that will receive the focus.

Important
Because the focuschanging event is synchronous, avoid extensive processing in the event handler. Otherwise, the UI may appear unresponsive. If you do need to perform lengthy or extensive processing in response to this event, call setImmediate and pass a function that performs the processing, or use an asynchronous action.