Focus

Guidelines

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.

In summary, running a widget with focus-based navigation mode markup on a BlackBerry device without a trackball is the same as running the widget without specifying any focus-based navigation and the entire navigation related HTML mark-up, JavaScript and CSS extensions are ignored.

Currently, focus based navigation will not function in a "child" document that is contained by a <frameset> <frame> or <iframe> or any other HTML element that contains a document element. Focus based navigation only works in the "root" document.

Configuration

Navigation mode can be enabled for BlackBerry devices with trackball by adding a element in config.xml document that looks like the following: <rim:navigation mode="focus" />

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=&quot;SomeJsFunction()" />

If the input1 element is currently focused, and the user scrolls up using the trackpad or trackball, SomeJsFunction() will be executed instead of the default focus moving behavior. The content of the x-blackberry-onUp value will be executed as JavaScript and the default focus movement will not occur.

In the above case, if SomeJsFunction() doesn't programmatically move the focus to another element, the current focused element will not change. If you want to trap scrolling and do not want any navigation action to occur, or JavaScript to execute, you can override one of the navigation attributes with an empty value like the following: x-blackberry-onUp="".

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

By default, when an element is focused, a light-blue round rectangle appears around the dimension of the element. When an element gains focus, the CSS hover will be triggered, allowing you to customize the focused element. You can also turn off the default focus highlight by using the following meta tag:

<meta name="x-blackberry-defaultHoverEffect" content="false" />

Limitations

Currently focus navigation doesn't support the <select> element with the "multiple" attribute. Therefore the <select< element with the "multiple" attribute is not focusable and cannot be added to navigation map. The workaround is to either add some navigation JavaScript outside the <select> element or simply using other HTML elements to mimic the multiple selection function.

API Summary

getDirection

Supported Platform(s)

Description

Returns the current direction of the scroll action. This is an integer value that is represented in the direction constants RIGHT, LEFT, UP, DOWN

getFocus

Supported Platform(s)

Description

Returns the id of the current focused HTML element

getPriorFocus

Supported Platform(s)

Description

Returns the id of the prior focused HTML element to current focused element

setFocus

Supported Platform(s)

Description

This function will set the focus on the HTML element with specified id value

Constants:

Code Example(s)

<html>
  <head>
    <meta name="viewport" id="viewport" content="initial-scale=1.0,user-scalable=no" />
    <script type="text/javascript">
      function moveDown(id)
      {
        blackberry.focus.setFocus(id);
      }
    </script>
  </head>
  <body>
    <table>
      <tr>
          <td></td>
          <td x-blackberry-focusable="true" x-blackberry-onDown="moveDown('bottom');" ></td>
          <td ></td>
      </tr>
      <tr>
          <td x-blackberry-focusable="true"></td>
          <td x-blackberry-focusable="true" onclick="alert('clicked me')" ></td>
          <td x-blackberry-focusable="true" x-blackberry-onDown=""></td>
      </tr>
      <tr>
          <td></td>
          <td x-blackberry-focusable="true" id="bottom"></td>
          <td></td>
      </tr>
    </table>
  </body>
</html>