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

To see style changes (for example, highlighting) when moving from one element to another in Navigation mode, you must define your own event handlers. The following example shows how to do this using JavaScript and HTML.

<html>
<head>

   <title>Color Input Type</title>
   <script type="text/javascript">
      function highlight(e) {
         e.setAttribute("style","background-color: red; outline: cyan solid thick;");
      }
    
      function unhighlight(e) {
         e.setAttribute("style","");
      }
   </script>
</head>

<body>    
   <h2>Test input type - text/password/email/search/tel/number</h2>
      <div>
         <label>Text: </label>
         <input type="text" 
                x-blackberry-focusable="true" 
                onmouseover="highlight(this);" 
                onmouseout="unhighlight(this);" />
      </div>
      <div>
         <label>Number: </label>
         <input type="number" 
                x-blackberry-focusable="true" 
                onmouseover="highlight(this);" 
                onmouseout="unhighlight(this);" />
      </div>
</body>
</html>

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.

You can change the navigation map by using the x-blackberry-onUp, x-blackberry-onDown, x-blackberry-onLeft, and x-blackberry-onRight attributes. These attributes specify an action to take for each direction that the user moves the trackball or trackpad. You can define these actions with a JavaScript function that you specify in the code for your application.

Changing an action for a focusable element

In the following code sample, when a specific element has focus and the user moves the trackball or trackpad, the JavaScript function JSAltFunction runs and focus does not move to the next focusable element in the navigation map.
<input id="finput" value="AltAction" x-blackberry-onUp="JSAltFunction()" />

Using JavaScript extensions to change focus

You can use JavaScript extensions to specify the HTML id attribute of the focusable element to change the focus to, or to indicate the direction to move the focus.

BlackBerry extension Description
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.

DOM events

When an element gains focus, a mouseover event occurs. When the user moves the trackball or trackpad, elements gain or lose focus by using the default navigation behavior or the JavaScript blackberry.Focus API.

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