Focus-based navigation on non-touch devices
Focus-based navigation in BlackBerry WebWorks applications permits BlackBerry 7 and earlier smartphone users to focus on particular screen elements by using the trackball or trackpad. If you do not enable focus-based navigation in your application, users navigate and select screen elements by using the cursor pointer.
You can use focus-based navigation in applications that run on a smartphone with a trackball or trackpad. If you specify the navigation mode for a smartphone that does not have a trackball or trackpad, it has no effect on navigation through your application screens.
You specify the navigation mode in the config.xml file. For navigation mode, you must also allow permission to blackberry.ui.dialog using the feature element in the config.xml file. Permission for the blackberry.ui.dialog is required for use of standard system dialog boxes. For more information on the functions this API provides, see blackberry.ui.dialog in the API Reference.
Specifying the navigation mode
<widget> <rim:navigation mode="focus"/> <feature id="blackberry.ui.dialog"/> </widget>
Defining focusable screen elements
By default, the <textarea>, <a>, <input>, <select>, <button>, and <iframe> HTML elements can receive focus when a user navigates a screen in your application.
You can define other HTML elements as focusable elements in the navigation map by setting the x-blackberry-focusable attribute to true for the HTML element.
For elements that can receive focus by default, you can define them as not focusable elements by setting the x-blackberry-focusable attribute to false for the HTML element.
Defining screen elements as focusable elements
<img id="image" src="imageb.png" x-blackberry-focusable="true" /> <td id="tabledef" x-blackberry-focusable="true">Table</td>
Defining screen elements as not focusable elements
<input value="name" x-blackberry-focusable="false" />
Defining initial focus
By default, when a web page displays, the BlackBerry smartphone gives focus to the element with the highest tabindex value.
You can change the initial focus by using the x-blackberry-initialFocus attribute.
<a class="list" x-blackberry-initialFocus="true">First element</a>
Changing the focus highlight
Focusable elements that are outside the viewable area
Navigation mode supports scrolling if the content of the HTML page extends beyond the screen size.
When no focusable element appears within the viewable screen area, no elements have focus. If the user clicks the trackball or trackpad, no events occur. When the user scrolls the screen, the first focusable element that appears on the screen gains focus. When multiple focusable elements appear on the screen, the first element that appears on the screen gains focus.
Changing the navigation map
By default, the navigation map includes all the focusable HTML elements. The focus moves from one focusable element to the next according to the direction that the user moves the trackball or trackpad.
Changing an action for a focusable element
<input id="finput" value="AltAction" x-blackberry-onUp="JSAltFunction()" />
|blackberry.focus.setFocus(id: String)||This function changes the focus to the HTML element with the id attribute that you specify. For example, to set the focus on an element with the id attribute input1, specify blackberry.focus.setFocus("input1");.|
|blackberry.focus.getFocus()||This function returns the id of the currently focused HTML element.|
|blackberry.focus.getOldFocus()||This function returns the id of the previously focused HTML element.|
|blackberry.focus.getDirection()||This function returns the direction that the user moves the trackball or trackpad.|
When an element loses focus, a mouseout event occurs. When the user clicks the trackball or trackpad, the element that has focus receives the mousedown, mouseup, and click events in sequence.
Last modified: 2013-08-14