Adjust your Android app

Handling update notifications

The BlackBerry World storefront prompts the app user when there are updates available for your app.

You must remove any intents, update checks, or prompts for Google Play ™ that may exist in your app code, as they may not work as expected in an app that has been ported to BlackBerry 10, which could lead to a negative user experience.

Resizing your app icons

The sizes of the app icons on BlackBerry 10 devices are different from the size of the app icons on Android devices.

For more information on app icon sizes in relation to various device screen resolutions, see Application icons.

For best results, you should create an appropriately sized icon for your app before you repackage it. The BlackBerry Runtime for Android apps allows you to support more than one BlackBerry device in a single release build (.bar file). This flexibility allows you to provide an ideally sized icon for each device supported by your app.

Trackball input

The BlackBerry Classic smartphone comes with a trackpad (also known as a trackball or Optical Navigation Module) that provides a new method of input for your Android apps. The trackpad uses an infrared sensor to detect finger movements, which are then translated into directional input.

In the Android OS, a trackpad is known as a trackball. In this documentation, the terms trackpad and trackball both refer to the same Optical Navigation Module that is found on the BlackBerry Classic smartphone.

The BlackBerry Classic device.

Modes of user interaction

Android supports two distinct modes of user interaction. The first mode, known as Touch mode, relies on the user having direct interaction with UI controls that respond to touch events. Touch mode is the typical way that users interact with all-touch devices that do not have a physical keyboard.

Touch mode is automatically deactivated when the device receives input from any one of the following input devices:

  • Trackball (or trackpad)
  • Directional pad (D-pad) keys
  • Keyboard arrow keys

There's no official term for the second mode, so we refer to it in this documentation as Non-Touch mode. When a device is in Non-Touch mode, its UI depends on focus. When a UI component can be configured to receive focus, and is therefore focusable, then its View can be set up to accept and handle input events.

In Non-Touch mode, input focus is given to one View at a time. A View can change its appearance to show the user that it has focus. Android widgets use a highlight, which serves as visual feedback, to show when they gain focus. When a UI component and its View have focus, they can receive input events. However, the View may or may not handle the events it receives. The OS processes any events that the View does not consume. These unconsumed events may cause the focus to move to another View. This approach is how the OS handles the routine movement of focus in response to input.

Some Views are focusable by default. For example, Android components such as the Button, ListView, and EditText are all focusable by default. For more information, see the Android View API reference.

You can use the android.focusable attribute to make a UI component focusable.

To support accessibility, you can use the AccessibilityNodeInfo class, which can also be used to set focus to UI components.

Trackball events

A Trackball event is a type of MotionEvent, which is an event that describes movements in terms of an action code and a set of axis values. The source class for these events is the SOURCE_CLASS_TRACKBALL, which is made up of related X and Y axes that can be retrieved using the getAxisValue() method and axis constants. For example, to get the value of the x axis:

// Use the constant AXIS_X as a parameter to get the
// value of the x-axis of a motion event

For more information on these constants, see AXIS_X and AXIS_Y.

The ACTION_MOVE constants represent all trackball movement values, which occur when users swipe their fingers across the trackball. The constants that represent the press gesture are the ACTION_DOWN and ACTION_UP constants. The OS processes any trackball events that are not consumed, and converts them into their equivalent D-pad key events. These newly generated D-pad key events are sent back to the View that currently has focus. The View interprets these D-pad key events as arrow key presses from an external keyboard. The events are delivered to the View as the KeyEvent parameter for the onKeyUp() and onKeyDown() event handlers.

In a repackaged Android app, the BlackBerry 10 OS converts trackball events into D-pad key events that produce movements that match user expectations.

When an existing Android UI control that supports D-pad key events is extended into a custom control, this custom control inherits support for trackball events. However, when you completely customize a UI control, you must add support for navigation events where it makes sense.

For more information about Android user interface components, see View.

Trackball in Android apps

The guidelines for Android development suggest that support for keyboard navigation should be included in all apps. Keyboard navigation support makes the app useable with arrow keys when an external keyboard is available. Keyboard navigation is also a requirement for accessibility.

For more information, see Implementing Accessibility.

The default behavior of a View for the onTrackballEvent() is to ignore it, which means that implementing keyboard navigation makes trackball navigation available as unconsumed trackball events. These unconsumed trackball events are reinjected into the View as D-pad key events. Most Views implement keyboard navigation and use it to provide trackball support.

Alternatively, you can choose to override the onTrackballEvent() and use it in your app. This approach exposes the raw trackball events with finer granularity than is available when using D-pad key events. This approach makes it possible to implement trackball-specific behaviors. For example, game control and scrolling are a couple of instances where this approach can be useful.

The trackpad on BlackBerry Classic smartphones conforms to the Android input event architecture and behaves like an Android device with a trackball. Any Android app that supports the trackball works on BlackBerry Classic.

As a minimum, an Android app that supports keyboard navigation automatically gains trackball support. Keyboard navigation does not harness the full potential of raw trackball events, but it does provide a functional trackball experience.

Supporting keyboard navigation

To support keyboard navigation:

  1. Identify the Views in your app hierarchy that accept user interaction, and configure them to be focusable.

    For more information, see using android.focusable or setFocusable().

  2. Implement a visual highlight when focus is gained.

    For more information, see onFocusChanged().

  3. Handle D-pad key events for the View that has focus. Focus should stay with the current View.

When D-pad key events are not handled, focus eventually moves to the next focusable View.

Using the Trackball with a MapView control

You can pan and scroll a map in an Android MapView control by using the trackball on the BlackBerry Classic smartphone.

The MapView control:

  • Acquires focus when the user clicks on it with the trackball
  • Controls the map position so that the user can pan or scroll the map (the user must use the touch screen for zooming or interacting with map markers)
  • Displays a highlight when it's selected
  • Releases its focus when the user clicks the Back button

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

comments powered by Disqus