Research In Motion

How to use the new

navigation mode in your
BlackBerry Widget – For
trackpad/trackball devices
For BlackBerry Smartphones
Prosanta Bhattacherjee

10
2|Page

Contents

Introduction ............................................................................................................................................ 3
Configuration .......................................................................................................................................... 4
Usage....................................................................................................................................................... 4
Setting focusable elements................................................................................................................. 4
Navigation Map ................................................................................................................................... 5
JavaScript Extensions .......................................................................................................................... 5
Initial Focus ......................................................................................................................................... 5
Focus Effect ......................................................................................................................................... 5
DOM Events in Navigation Mode............................................................................................................ 6
Example ................................................................................................................................................... 6
Links ........................................................................................................................................................ 7
3|Page

Introduction

System Requirements:

JDK 1.6 installed

Operating System: Windows® XP or Windows Vista™ (32-bit)

BlackBerry® Widget SDK

* Note:

This tutorial is only applicable for trackpad/trackball devices. The new navigation mode will not
change the user experience on any touch screen devices.

This tutorial will cover how to configure the new navigation mode for BlackBerry Widgets. The
navigation mode allows BlackBerry Widgets to create a user experience that is closely comparable to
the experience that a user would get while using a Java® Application. By default, the navigation
mode displays the pointer to the user for navigation, however with the new navigation mode
enabled, the user will be able to highlight sections of the application for navigation.

New navigation mode Default navigation mode

The new navigation mode can go a long way in making your user interface a lot easier to navigate
through. If you have specific areas of the page you’d like to have control navigation, you can add
them to the navigation mode and allow the cursor to go directly to those areas.
4|Page

Configuration
There are two ways to enable the new navigation mode.

1. Add it directly to the config.xml file

a. Open the config.xml file in a text editor

b. Add the element <rim:navigation mode="focus" /> as a child to the ‘Widget’ element:

<widget xmlns:rim="http://www.blackberry.com/ns/widgets" version="1.0.0" rim:header="RIM-Widget:rim/widget"

xmlns="http://www.w3.org/ns/widgets">
…
<rim:navigation mode="focus" />
…
</widget>

2. Use the BlackBerry® Web Plug-in for Microsoft® Visual Studio® or Eclipse®

a. Open the config.xml file in the graphical interface

b. Select the checkbox next to “Enable Trackpad/Trackball Navigation Mode”

Microsoft Visual Studio

Eclipse

Usage
Running a BlackBerry Widget with the new navigation mode under a non-trackball device (such as
BlackBerry® Storm™ smartphone or the BlackBerry® Storm2™ smartphone) will result in the same
behaviour as running the BlackBerry Widget without specifying a navigation mode.

Setting focusable elements

By default all <textarea>, <a>, <input>, <select> and <button> elements are focusable. If you would
like to make other HTML elements focusable, you will need to add the attribute x-blackberry-
focusable with the value to “true” to these elements:

<img id="image1" src="pacman.png" x-blackberry-focusable="true" />

<td id="Td1" x-blackberry-focusable="true" > 1 </td>

If you would like to use any of the default elements without being focusable from the navigation
map, which will prevent the element from getting focus, add the attribute x-blackberry-focusable
with the value set to “false”:

<input value="Fixed" x-blackberry-focusable="false" />

5|Page

Navigation Map
By default the focus of the HTML elements will scroll accordingly to the direction of the
trackball/trackwheel, however this behaviour can be overridden and customized by using the "x-
blackberry-onUp", "x-blackberry-onDown", "x-blackberry-onLeft", and “x-blackberry-onRight"
attributes.

For example, given this snippet of HTML:

<input id="input1" value="OverriddenNavigationBehavior" x-blackberry-onUp="SomeJsFunction()" />

If “input1” is currently focused and the user scrolls up on the trackball/trackpad, “SomeJsFunction”
will be executed instead of the default focus behaviour of moving the focus up, and unless
SomeJsFunction programmatically changes the focus, the current focus won’t change.

JavaScript® Extensions
To assist developers in changing focus easily, we have added the “blackberry.focus” JavaScript
extension to the existing JavaScript Engine for the needs of the nagivation mode:

blackberry.focus.setFocus (id: String)

o It will set the focus on the HTML element with specified id value
e.g. blackberry.focus.setFocus(“input1”);
blackberry.focus.getFocus()
o It returns the id of the current focused HTML element
blackberry.focus.getOldFocus()
o It returns the id of the prior focused HTML element to current focused element
blackberry.focus.getDirection ()
o It returns the current direction of the scroll wheel

Initial Focus
By default, the “highest” or “first” focusable element will be initially focused when the document is
loaded. You can override this behavior using the x-blackberry-initialFocus attribute:

<a class="list" x-blackberry-initialFocus="true" >First Link</a>

Focus Effect
By default, when an element is focused, we will draw a light blue rectangle around the dimension of
the element. This effect can be customized using the CSS “:hover” pseudo-classes.

.list
{
width: 100%;
display: block;
text-decoration: none;
}
.list:hover
{
background-color: red;
color: white;

}
6|Page

<a class="list" href="http://www.rim.com" >Link to RIM</a>

<a class="list" href="http://www.blackberry.com" >Link to BlackBerry</a>

The above code will provide the following styling:

As well you can also disable the default hover effect, which is the light blue round rectangle box, by
adding a meta tag to your HTML page:

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

DOM Events in Navigation Mode

When an element is set focus, it will fire the “onmouseover” event

When an element loses focus, it will fire the “onmouseout” event

An element can gain focus when the user moves the scroll wheel under the default
navigation behaviour or the JavaScript Extension API navigation.setRimFocus is called to
programmatically set the focus to an element

When the user presses the scroll wheel, the current focused element will receive
“mousedown”, “mouseup” and “click” in sequence if it doesn’t consume these actions
as UI events in advance.

Example
The following is a quick example to help you get up and running with the new navigation mode. All
of the tools, tips and techniques above can be applied to this example to extend on it for you to
discover the new navigation mode and how it can benefit your BlackBerry Widget.

Config.xml:

<?xml version="1.0" encoding="utf-8"?>

<widget xmlns:rim="http://www.blackberry.com/ns/widgets" version="1.0.0" rim:header="RIM-Widget:rim/widget"
xmlns="http://www.w3.org/ns/widgets">
<rim:navigation mode="focus" />
<name>My Widget</name>
<description />
<author href="" rim:copyright="" email="">Me</author>
<content src="index.htm" />
<license href="" />
</widget>
7|Page

Index.html:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN">
<html>
<head>
<meta name="viewport" id="viewport" content="initial-scale=1.0,user-scalable=no" />
<title>Untitled Page</title>
<style type="text/css">
.myCell
{
background-color:Green;
}
.myCell:hover
{
background-color: blue;
}
</style>
</head>
<body>
<table>
<tr>
<td class="myCell" x-blackberry-focusable="true">Cell 1</td>
<td class="myCell" x-blackberry-focusable="true">Cell 2</td>
<td class="myCell" x-blackberry-focusable="true">Cell 3</td>
</tr>
<tr>
<td class="myCell" x-blackberry-focusable="true">Cell 4</td>
<td class="myCell" x-blackberry-focusable="true">Cell 5</td>
<td class="myCell" x-blackberry-focusable="true">Cell 6</td>
</tr>
<tr>
<td class="myCell" x-blackberry-focusable="true">Cell 7</td>
<td class="myCell" x-blackberry-focusable="true">Cell 8</td>
<td class="myCell" x-blackberry-focusable="true">Cell 9</td>
</tr>
</table>
</body>
</html>

Links
BlackBerry Widgets Web Site:
http://www.blackberry/developers/widget

BlackBerry Developers Web Site:

http://na.blackberry.com/eng/developers/

BlackBerry App World™:

http://na.blackberry.com/eng/developers/appworld.jsp

BlackBerry® Enterprise Server:

http://na.blackberry.com/eng/services/server/
8|Page

BlackBerry Web Loader:

http://www.blackberry.com/developers/downloads/webloader/

Developer Video Library:

http://na.blackberry.com/eng/developers/resources/videolibrary.jsp

Documentation:
http://na.blackberry.com/eng/support/docs/developers/?userType=21

Knowledge Base Articles:

http://www.blackberry.com/knowledgecenterpublic/livelink.exe/fetch/2000/348583/custo
mview.html?func=ll&objId=348583

Forums:
http://supportforums.blackberry.com/rim/?category.id=BlackBerryDevelopment

©2010 Research In Motion Limited. All rights reserved. BlackBerry®, RIM®, Research In Motion®,
SureType®, SurePress™ and related trademarks, names and logos are the property of Research In
Motion Limited and are registered and/or used in the U.S. and countries around the world.