Focus

The focus object provides functions and properties for retrieving and setting focus to focusable areas of the HTML

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 <frame>. Focus based navigation only works in the "root" document and first-level <iframe> elements.

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 dimensions of the element. If you wish to customize the behaviour and styling of a control when it gains or loses focus, you can use the onmouseover/onmouseout events to invoke custom JavaScript; CSS hover will NOT be triggered.

Please see our documentation for a code sample on using onmouseout/onmouseover to customize styling of focused elements.


Code Example:
<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>


Supported Platform(s)

- BlackBerry OS 5.0+
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
blackberry.focus.getDirection Y Y Y       
blackberry.focus.getFocus Y Y Y       
blackberry.focus.getPriorFocus Y Y Y       
blackberry.focus.setFocus Y Y Y       
RIGHT Y Y Y       
LEFT Y Y Y       
UP Y Y Y       
DOWN Y Y Y       

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.


Constants

Number RIGHT
Number LEFT
Number UP
Number DOWN

Functions

static Number blackberry.focus.getDirection ()


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


Supported Platforms
 - BlackBerry OS 5.0+

static String blackberry.focus.getFocus ()


Returns the id of the current focused HTML element


Supported Platforms
 - BlackBerry OS 5.0+

static String blackberry.focus.getPriorFocus ()


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


Supported Platforms
 - BlackBerry OS 5.0+

static void blackberry.focus.setFocus (id : String)


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


Supported Platforms
 - BlackBerry OS 5.0+


Parameters
id The element 'id' in which you want to set focus

Constants

static Number RIGHT


User scrolled Right


Supported Platforms
 - BlackBerry OS 5.0+

static Number LEFT


User scrolled Left


Supported Platforms
 - BlackBerry OS 5.0+

static Number UP


User scrolled Up


Supported Platforms
 - BlackBerry OS 5.0+

static Number DOWN


User scrolled Down


Supported Platforms
 - BlackBerry OS 5.0+

Documentation generated by JsDoc Toolkit 2.4.0 on Mon Feb 11 2013 14:51:07 GMT-0500 (EST)