The focus object provides functions and properties for retrieving and setting focus to focusable areas of the HTML
If the BlackBerry device doesn't have a trackball or trackpad, the focus-based navigation mode will not be enabled even if the widget configuration document specifies that focus-based navigation is used. If the widget is configured for focus-based navigation and it runs on a BlackBerry device that uses a trackpad or trackball, focus-based navigation will be enabled.
Currently, focus based navigation will not function in a "child" document that is contained by a <frame>. Focus based navigation only works in the "root" document and first-level <iframe> elements.
Navigation mode can be enabled for BlackBerry devices with trackball by adding a
HTML Mark-up Details
By default, all <textarea>, <a>, <input>, <select> and <button> elements are focusable. If you wish to have other HTML elements to become focusable, which will make them a part of the navigation map, you can add the attribute x-blackberry-focusable with the value of "true" to these elements, e.g.
<td id="Td1" x-blackberry-focusable="true" > 1 </td>
In addition, if you want to remove some of the default focusable elements from the navigation map, which prevent them from gaining focus, add the attribute x-blackberry-focusable with the value of "false" to these elements. For example:
<input value="Fixed" x-blackberry-focusable="false" />
By default, the "highest" focusable element will be initially focused after the document is completely loaded. You can set a specific focusable element to be initially focused after the document is loaded by adding the "x-blackberry-initialFocus" attribute to it. For example:
<a class="list" x-blackberry-initialFocus="true" >First Link</a>
Events and Overrides
By default, all focusable HTML elements compose the navigation map and the focus will move from one focusable element to another focusable element according to the direction of the scroll wheel and the 2-D dimension of the focusable elements. This default navigation behavior can be overridden and customized, by using the x-blackberry-onUp, x-blackberry-onDown, x-blackberry-onLeft, and x-blackberry-onRight event attributes. For example, here is a snippet of HTML:
<input id="input1" value="OverrideNavigationBehavior" x-blackberry-onUp="SomeJsFunction()" />
When an element gains focus, it will receive a mouseover event. An element can gain focus when the user moves the trackpad or trackball under the default navigation behavior or if blackberry.focus.setFocus() is called programmatically to set the focus to an element. When an element loses focus, it will receive a mouseout event. An element loses focus when the focus is set to another element.
When the user presses the trackpad or trackball in a selection action, the current focused element will receive a mousedown, mouseup, and click in sequence if it doesn't consume these actions as UI events in advance. For example, when the current focused element is a text box, the element won't receive a mousedown, mouseup, and click when the user presses the trackpad or trackball, because the text box consumed these actions as UI events before these actions were popped up to the DOM level.
When there is no focusable element visible in the current viewable part of the screen, no element will be considered focused. In this case, the mousedown, mouseup, and click event is not directed to any element if you press the scroll wheel.
Focus Visual Effect
Please see our documentation for a code sample on using onmouseout/onmouseover to customize styling of focused elements.
Configuration Document Settings
To use all of the API described for this object, you must ensure the following settings are in your configuration document:
|This API does not require a <feature> element to be declared in the configuration document of your BlackBerry WebWorks Application.|
|Permission Elements (PlayBook and BlackBerry 10+)|
|This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application.|
Returns the current direction of the scroll action. This is an integer value that is represented in the direction constants RIGHT, LEFT, UP, DOWN
|- BlackBerry OS 5.0+|
Returns the id of the current focused HTML element
|- BlackBerry OS 5.0+|
Returns the id of the prior focused HTML element to current focused element
|- BlackBerry OS 5.0+|