Research In Motion

How to use the new navigation mode in your BlackBerry Widget – For trackpad/trackball devices
For BlackBerry Smartphones
Prosanta Bhattacherjee

10

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

If you have specific areas of the page you’d like to have control navigation.6 installed Operating System: Windows® XP or Windows Vista™ (32-bit) BlackBerry® Widget SDK * Note: This tutorial is only applicable for trackpad/trackball devices. however with the new navigation mode enabled. you can add them to the navigation mode and allow the cursor to go directly to those areas. By default. .3|Page Introduction System Requirements: JDK 1. 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. This tutorial will cover how to configure the new navigation mode for BlackBerry Widgets. the user will be able to highlight sections of the application for navigation. 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. the navigation mode displays the pointer to the user for navigation. The new navigation mode will not change the user experience on any touch screen devices.

Open the config. Add the element <rim:navigation mode="focus" /> as a child to the ‘Widget’ element: <widget xmlns:rim="http://www.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.org/ns/widgets"> … <rim:navigation mode="focus" /> … </widget> 2. add the attribute x-blackberry-focusable with the value set to “false”: <input value="Fixed" x-blackberry-focusable="false" /> . Add it directly to the config. If you would like to make other HTML elements focusable.4|Page Configuration There are two ways to enable the new navigation mode.0.w3. Use the BlackBerry® Web Plug-in for Microsoft® Visual Studio® or Eclipse® a. <select> and <button> elements are focusable.xml file a. Setting focusable elements By default all <textarea>. 1.xml file in the graphical interface b.0" rim:header="RIM-Widget:rim/widget" xmlns="http://www.xml file in a text editor b. <a>. Open the config.blackberry. 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. you will need to add the attribute x-blackberryfocusable with the value to “true” to these elements: <img id="image1" src="pacman.com/ns/widgets" version="1. which will prevent the element from getting focus. <input>.

g. the “highest” or “first” focusable element will be initially focused when the document is loaded.setFocus(“input1”). "x-blackberry-onLeft". we will draw a light blue rectangle around the dimension of the element. } . and “x-blackberry-onRight" attributes. "x-blackberry-onDown". color: white.list:hover { background-color: red.focus” JavaScript extension to the existing JavaScript Engine for the needs of the nagivation mode: blackberry. the current focus won’t change.focus.focus.focus. JavaScript® Extensions To assist developers in changing focus easily. however this behaviour can be overridden and customized by using the "xblackberry-onUp".getOldFocus() It returns the id of the prior focused HTML element to current focused element blackberry. we have added the “blackberry. 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.5|Page Navigation Map By default the focus of the HTML elements will scroll accordingly to the direction of the trackball/trackwheel.list { width: 100%.getDirection () It returns the current direction of the scroll wheel Initial Focus By default. blackberry. This effect can be customized using the CSS “:hover” pseudo-classes. text-decoration: none. “SomeJsFunction” will be executed instead of the default focus behaviour of moving the focus up. and unless SomeJsFunction programmatically changes the focus.setFocus (id: String) o It will set the focus on the HTML element with specified id value e. display: block.focus. blackberry. 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.focus. .getFocus() o o o It returns the id of the current focused HTML element blackberry. } . when an element is focused.

0" rim:header="RIM-Widget:rim/widget" xmlns="http://www.com" >Link to RIM</a> <a class="list" href="http://www. 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.com" >Link to BlackBerry</a> The above code will provide the following styling: As well you can also disable the default hover effect.blackberry. Example The following is a quick example to help you get up and running with the new navigation mode. All of the tools. the current focused element will receive “mousedown”.blackberry. 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.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> .rim.setRimFocus is called to programmatically set the focus to an element When the user presses the scroll wheel.0.xml: <?xml version="1.6|Page <a class="list" href="http://www. which is the light blue round rectangle box. “mouseup” and “click” in sequence if it doesn’t consume these actions as UI events in advance.w3. Config.0" encoding="utf-8"?> <widget xmlns:rim="http://www.com/ns/widgets" version="1. 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.

7|Page Index.com/eng/developers/ BlackBerry App World™: http://na.0 Transitional//EN"> <html> <head> <meta name="viewport" id="viewport" content="initial-scale=1.html: <!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.myCell:hover { background-color: blue.user-scalable=no" /> <title>Untitled Page</title> <style type="text/css"> .com/eng/developers/appworld.jsp BlackBerry® Enterprise Server: http://na. } .0.blackberry. } </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.blackberry.com/eng/services/server/ .myCell { background-color:Green.blackberry/developers/widget BlackBerry Developers Web Site: http://na.

and countries around the world.blackberry.blackberry.com/eng/developers/resources/videolibrary.com/developers/downloads/webloader/ Developer Video Library: http://na.blackberry.com/knowledgecenterpublic/livelink.com/eng/support/docs/developers/?userType=21 Knowledge Base Articles: http://www. All rights reserved.com/rim/?category. RIM®. names and logos are the property of Research In Motion Limited and are registered and/or used in the U. SureType®.blackberry.S. Research In Motion®.id=BlackBerryDevelopment ©2010 Research In Motion Limited.8|Page BlackBerry Web Loader: http://www.exe/fetch/2000/348583/custo mview.html?func=ll&objId=348583 Forums: http://supportforums. BlackBerry®. SurePress™ and related trademarks. .blackberry.jsp Documentation: http://na.

Sign up to vote on this title
UsefulNot useful