BlackBerry Widget Navigation Mode: Everything you Need to Know


Have you heard of BlackBerry® Widget navigation mode yet?  It is a configuration option that allows Widget developers to set their own focus-based navigation scheme.  Instead of using the default mode, choosing this type of navigation mode allows you to provide your users with more granular control over how they interact with page elements in their Widget applications.

What is the default navigation mode for BlackBerry Widget applications?

When a BlackBerry Widget application is created, its default navigation mode is pointer mode.  This means that a cursor, similar to a mouse pointer, moves around the screen when you scroll the trackpad or trackball.  It is very similar to how the native BlackBerry® Browser application is used where different regions of the page can be interacted with, such as hyperlinks and input fields.  The reason for this similarity is because of a browser field object that is embedded within a compiled BlackBerry Widget – one that is used to render embedded (and remote) web content.

However, the BlackBerry Browser input mechanism isn’t always the best fit for BlackBerry Widget applications.

Figure 1: Default navigation.  Pointer moves around page when you scroll trackpad/trackball.

Ideal for some applications, but not all.

Wouldn’t it be great if there was a different type of navigation scheme?

Yes, it would be great, and guess what – there is!

We call it “navigation mode,” and it’s a focus-based navigation scheme that is used in the other native BlackBerry applications.  Developers define interactive regions of page content as being “focusable” (e.g. tab headers, input fields, buttons, etc.) that automatically gain focus when the user scrolls the trackpad/trackball towards them.  This provides a similar user experience to how native BlackBerry applications are used, such as the Messages or Contacts application.  When scrolling up and down within these applications, focus moves between each email or contact.

Another example is the home screen on your BlackBerry® smartphone.  You scroll from icon to icon, rather than moving a pointer around the screen.  Depending on the design/layout of your Widget application, “navigation mode” may be more intuitive, and help make it easier and quicker to navigate between interactive application elements.

Figure 2: Focus based navigation.  Scrolling Up/Down changes focus between
page elements that have been marked as focusable.  Ideal for an application like this,
where the screen is composed entirely of buttons.

That’s awesome. How do I use it?

1. Using either the BlackBerry® Web Plug-in for Microsoft® Visual Studio® or the BlackBerry® Web Plug-in for Eclipse®, open the configuration document (Config.xml), within your BlackBerry Widget project, and select the “Enable trackball/trackpad navigation” checkbox.

2. Add the property “x-blackberry-focusable=”true”” to whichever HTML elements within your web content you wish to mark as focusable.  When navigation scrolls towards these items, they will automatically gain focus.  For example:

<style type="text/css">
td { background-color: White; color: Black; }
td:hover { background-color: Gray; color: Red; }
.focusable { background-color: Blue; color: White; }
<table border="0" cellspacing="0" cellpadding="0">
<td> </td>
<td x-blackberry-focusable="true"> </td>
<td> </td>
<td x-blackberry-focusable="true"> </td>
<td x-blackberry-focusable="true"> </td>
<td x-blackberry-focusable="true"> </td>
<td> </td>
<td x-blackberry-focusable="true"> </td>
<td> </td>

3. Customize the default behavior of navigation mode by using JavaScript® and HTML.  You can use the blackberry.focus JavaScript object and x-blackberry HTML properties to produce a more granular user experience:

blackberry.focus.setFocus(id) – sets focus to an element having the given ID.

x-blackberry-initialFocus=”true” – declares element to attain focus when page is loaded.

x-blackberry-onDown=”callbackFunction()” – calls JavaScript function when focus moves down from the current element.  There are also corresponding properties that allow you to capture onUp, onLeft and onRight events.


Implementing focus-based Widget navigation mode is only relevant on BlackBerry smartphones that have trackball/trackpad input.  On a touch screen device, users interact with elements on the screen simply by touching the screen, and do not have a cursor/pointer that they can navigate among elements within an application.  As a result, BlackBerry Widget developers should be aware that only touch input events are recognized on a touch screen device; regardless of whether a BlackBerry Widget application is configured to use focus-based navigation, users can only interact with elements in their Widget using touch events.

You can find more information, such as sample code and a tutorial about using navigation mode in your Blackberry Widget applications, on the BlackBerry Widget SDK page. Check it out, then come back to the BlackBerry Developer’s Blog and let us know how it worked for you.

Eclipse is a trademark of Eclipse Foundation, Inc. Microsoft and Visual Studio are trademarks of Microsoft Corporation.  JavaScript is a trademark of Sun Microsystems, Inc. All other trademarks are the property of their respective owners.

Join the conversation

Show comments Hide comments
+ -
  • astanley

    Hey folks,

    As a follow up to this article, I wanted to share that the source code for the sample application shown above can be found in the BlackBerry Developer Resource Center:

    Another example (Grocery list):


  • Sujay Krishna

    This would be much more developer friendly n user friendly if only it was a setting that can be changed by the user, default-value being specified by the developer.

  • David Shannon

    great… so, can you go about making the divs scroll properly? Or how about just making the simulator work the same as the phone?

blog comments powered by Disqus