DEVELOPERS BLOG

Handling BlackBerry Input Methods : Part 2

This post was written by Naveenan Murugesu

naveenan_classicblog jan2015

Happy New Year Everyone! Just before the 2014 festive season, we published a blog post, Handling BlackBerry Input Methods, which talked about the various new input methods to support in your apps:

    • Touch Sensitive Keyboard ( BlackBerry Passport)
    • Navigation Keys ( BlackBerry Classic)
    • Trackpad Input ( BlackBerry Classic)

In this post, we will look at the Trackpad Input in detail and we will see how you can customize the behavior of the trackpad using the new plugins and APIs available in WebWorks SDK 2.2.  By customizing the trackpad, you will enhance the user experience and the usability of your application.

Trackpad Input

The BlackBerry Classic re-introduces the optical trackpad.  The trackpad uses an infrared sensor to detect displacement of a finger moving over top of it and translates that input into directional movements on the screen.  WebWorks allows you to customize the behavior of the trackpad in a number of ways.  By default, your Webworks application will present a cursor for the user navigation, which is called cursor navigation mode. As a developer, you cannot customize the navigation path in the cursor navigation mode.  However, with spatial navigation, the trackpad allows the user to skip from one focusable element to the next and as a developer, you can choose which element to receive the initial focus and you can define your own navigation path.

Navigation mode is defined as part of your app’s configuration.  To use spatial navigation in your application, you must enable it in your app configuration.

Config.xml

 <platform name=”blackberry10″>

     <preference name=”SpatialNavigation” value=”enable” />

</platform

Once the Spatial Navigation is enabled in the config.xml, as a developer, you can skip from one focusable element to the next.  By default, WebWorks automatically gives focus to the following HTML elements:

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

Defining the initial focus

You can define which element initially receives the focus when a new screen is displayed in your application.  We can use HTML 5 tabindex attribute to achieve that.  The element with the lowest tabindex value gets initial focus as shown in the example below:

<a class=”l1″ href=”www.my-company2.com tabindex=”2″>Link 1</a>

<a class=”l2″ href=”www.my-company3.com tabindex=”3″>Link 2</a>

<a class=”l3″ href=”www.my-company1.com tabindex=”1″>Link 3</a>

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

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, as described above.

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

Property Description
nav-down Defines the element that gains focus when the user uses the touchpad to navigate down.
nav-left Defines the element that gains focus when the user uses the touchpad to navigate to the left.
nav-right Defines the element that gains focus when the user uses the touchpad to navigate to the right.
nav-up Defines the element that gains focus when the user uses the touchpad to navigate up

For example, consider the following HTML:

<a class=”l1″ href=”www.my-company2.com tabindex=”2″>Link 1</a>

<a class=”l2″ href=”www.my-company3.com tabindex=”3″>Link 2</a>

<a class=”l3″ href=”www.my-company1.com tabindex=”1″>Link 3</a>

And if we apply the following CSS rule:

a#l2 {

        nav-right: #l1;

        nav-left: #l3;

        nav-down: #l3;

        nav-up: #l1;

        }

In this example, the nav-right CSS property define which element receive focus based on the direction the user swipes the trackpad.  When <a id=”l2”> has focus, and the user swipes up or to the right, <a id=”l1”> gains focus.  A swipe down or to the left gives <a id=”l3”> focus.

That is it for now.  You can start adding the trackpad support to your application by performing the following simple steps:

Download and Install the WebWorks SDK 2.2

Re-package your application with the new SDK

Add the required plugins.

Make the necessary changes in the config.xml.

Follow steps outlined in this blog post.

That’s all.  Stay tuned for our next blog!  The next series of blog posts will go in depth and talk about the new input methods in greater detail.

 

Come join us for a live demo – Meet the new BlackBerry Classic January 22nd http://www.communitech.ca/community-event/come-meet-the-new-blackberry-classic/

Lee Van Cromvoirt

About Lee Van Cromvoirt

As part of the BlackBerry Developer Programs Team, I enjoy working to enable Enterprise Application Developers to reach their mobile goals.