Setting the navigation mode for trackpad input

The BlackBerry Classic device introduces the trackpad.

Devices with trackpads provide navigation capabilities that are not available on devices with touch-only interfaces. You can choose one of the following navigation modes for your app to use when it's running on a BlackBerry Classic device:

  • Cursor navigation mode: In cursor navigation mode, the trackpad acts as a mouse, allowing the user to move the pointer around the screen to select focusable elements. For example, to complete a form, users position the pointer over a field and then click the trackpad to enter input. They must repeat this set of steps for each field they want to complete.

  • Spatial navigation mode: In spatial navigation mode, the trackpad allows the user to move from one focusable element to the next. A focusable element is an element that the user can select. In web content, certain elements, such as links and form elements, can receive focus so that the user can interact with them (for example, to follow a link or complete a text field in a form).

    You can control how users move from element to element by defining a focus order for the elements on a page. For more information, see Defining the navigation path for spatial navigation.

Navigation mode is not user configurable. Rather, it is defined as part of your app configuration. By default, apps use cursor navigation. To use spatial navigation, you must enable it in your app configuration.

With spatial navigation, you can customize the behavior of trackpad navigation by setting the position of the initial focus for a screen and customizing the navigation path.

Enabling spatial navigation mode using the SDK web tool

  1. Open BlackBerry WebWorks <version>. A new browser window opens, displaying the BlackBerry 10 WebWorks SDK web tool.
  2. Navigate to your project and click Configuration.
  3. Select the Enable Spatial Navigation check box.

Enabling spatial navigation mode in the config.xml file

You can enable spatial navigation mode for your app by adding a <preference> element to the config.xml file. Because this preference is specific to BlackBerry 10, you must nest this <preference> element in a <platform> element.

To enable spatial navigation in the config.xml file:

  1. Open the config.xml file in a text editor.
  2. Add a <platform> element for BlackBerry 10, if one doesn't exist. For example:
    <platform name="blackberry10">
    </platform>
  3. Within the <platform> element for BlackBerry 10, add a <preference> element. For example:
    <platform name="blackberry10">
        <preference name="SpatialNavigation" value="enable" />
    </platform>

Defining the navigation path for spatial navigation

Spatial navigation allows the user to navigate from one focusable element to another. A focusable element is an element that the user can select and can interact with. For example, an input field must receive focus to allow the user to type input. When a link receives focus, the link is highlighted, and the user can follow the link by pressing the Enter key.

Spatial navigation doesn't require that you add any plugins to your project. You can use standard HTML and CSS to define which elements can receive focus, and how the user can navigate through those elements:
  • In the HTML source, you can set the tabindex attribute for an element. This attribute allows you to define a value to an element that defines the element's position in the navigation path.
  • Using the CSS navigation properties, nav-left, nav-right, nav-up, and nav-down, you can define which element receives focus based on the direction that the user swipes on the trackpad. The elements that you specify as the targets of these properties become part of the navigation path, even if you haven't set the tabindex attribute for those elements. These CSS navigation properties provide greater control over the navigation path than the tabindex attribute.

If you don't set the tabindex attribute or CSS navigation properties, WebWorks provides a default navigation path. In this case, the following elements receive focus in the order they appear:

  • <a>
  • <button>
  • <iframe>
  • <input>
  • <select>
  • <textarea>

Best practices

Define the trackpad navigation path logically. Carefully consider how the user is likely to move around your app as you define a navigation path. Make sure that the focus doesn't jump around unexpectedly.

Defining the initial focus

You can use the tabindex attribute to define which element receives focus when a new screen is displayed in your app. The element with the lowest tabindex value gets initial focus on the page. For example:
<a id="link1" href="http://www.my-company2.com" tabindex="2">Follow Link 1!</a>
<a id="link2" href="http://www.my-company3.com" tabindex="3">Follow Link 2!</a>
<a id="link3" href="http://www.my-company1.com" tabindex="1">Follow Link 3!</a>

In the example above, Link 3 actually receives initial focus, since it has the lowest tabindex value.

In HTML5, every element supports the tabindex attribute. However, making an element focusable makes sense only for those elements that a user typically needs to interact with, such as form elements or links.

Changing the navigation path

By default, the navigation path includes all the focusable HTML elements. The focus moves from one focusable element to the next, either according to the direction that the user moves the trackpad, or according to the tabindex values.

You can change the navigation path by using the following CSS properties:

Property Description
nav-down

Defines the element that receives focus when the user uses the touchpad to navigate down.

nav-left

Defines the element that receives focus when the user uses the touchpad to navigate to the left.

nav-right

Defines the element that receives focus when the user uses the touchpad to navigate to the right.

nav-up

Defines the element that receives focus when the user uses the touchpad to navigate up.

For example, consider the following HTML:
<a id="link1" href="http://www.my-company2.com" tabindex="2">Follow Link 1!</a>
<a id="link2" href="http://www.my-company3.com" >Follow Link 2!</a>
<a id="link3" href="http://www.my-company1.com" tabindex="1">Follow Link 3!</a>
Now consider the following CSS rule:
a#link2 {     
    nav-right:  #link1;  
    nav-left:  #link3;     
    nav-down:  #link3;  
    nav-up:  #link1;
}

In this example, the CSS navigation properties define which elements receive focus based on the direction the user swipes the trackpad. Let's assume Link 2 has focus. When the user swipes up or to the right, Link 3 receives focus. When the user swipes down or to the left, Link 1 receives focus.

Last modified: 2014-10-09



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus