Customizing BlackBerry Applications

BlackBerry — alive and kicking

Before iPhone and Android came along to wage the Smartphone wars, the powerful BlackBerry platform from Research in Motion (RIM) paved the way and made mobile email a household term.

In addition to defining what mobile email should look like, the other thing BlackBerry made look easy was calendar and contact collaboration. I say collaboration because the BlackBerry does more than just “sync”.

Syncing is great when you are a single user, but when you can “sync” in real time to a shared database, you’re now collaborating. If you doubt the value of that, just try to make an appointment while you’re out at lunch with a colleague and then come back to the office and find out that your assistant put another client meeting at the same spot on your non-synced calendar. Ouch!

Today other platforms also offer synchronization with calendar and contacts, both corporate and Internet based, so if you’re just tuning in you might think this is no big deal. However, BlackBerry offered this functionality years before the iPhone was a twinkle in Mr. Jobs’ imaginative eyes.

I personally still tote around a BlackBerry as my everyday device — though I have a gaggle of other devices in my backpack for testing applications for clients and for proto-typing new ideas.

One of the reasons I still like the BlackBerry is because it is a “one-hand” device. Fortunately, I do have use of both of my hands, however I am often busy doing something — like driving or holding my young son as I walk around the house trying to find out where he put one of my devices. If I want to dial someone, it is awkward to hold the device and “slide my finger to unlock it” — and then dial — all with one hand. I can unlock the BlackBerry with one hand and then press and hold a button to speed-dial someone, like my wife, who may have seen where the boy put the iPhone when it went missing.

In the same vein of a one-handed, quick speed-dial button, there is another feature about BlackBerry that is very powerful — to me anyway. It is the context menu, or the ApplicationMenuItem, as it is officially known.

Menu Mania

BlackBerry’s Java programming environment allows application developers to modify the built-in menus, providing context sensitive functionality. This is a powerful technique. Imagine adding your own menu to the email application and being able to manipulate the currently selected message. Or how about being able to take action on the currently selected entry in the Address Book?

We can even add a menu item to the system-wide menu. I have done this for clients to add a menu for searching back-end systems. No matter what application the users are running, they can easily get to the one menu item of most importance to them. Have a look at an application written for this article below where we display our own, customized menu item within the system menu, available in every application.

When this menu is selected, it launches the linuxdlsazine website to an index of the Upwardly Mobile articles, as shown below.

This link may or may not be the top of your reading list — you can easily replace it with the link of your choice as we build the code together. Let’s build this application.

Building the application

Before we jump in, let me just say that there are a couple of different development environments available to you as a BlackBerry developer. The tried and true method is with RIM’s BlackBerry Java Development Environment, or JDE. Of late, RIM has supported building applications within Eclipse. As it appears that more and more development is taking place within Eclipse, we are going to use Eclipse for building this sample application. If there is sufficient interest in building BlackBerry applications, we’ll do another article on setting this environment up. Please let me know if this is of interest to you.

To start, we create a new project in Eclipse, as shown below.

We need to create two class files for our application. The first is the main application class, which extends the UiApplication class provided by RIM in the SDK. The image below depicts this process using the Eclipse “File -> New -> Class” dialog box.

Here is the source code for this class.

/**
 *
 */
package com.msi.linuxmagazine;

import net.rim.device.api.ui.UiApplication;
import net.rim.blackberry.api.menuitem.*; // ApplicationMenuItemRepository

/**
 * @author @fableson
 *
 */
public class MenuDemo extends UiApplication {

    // one and only instance of our application
    static MenuDemo theApp = null;

	// constructor
    public MenuDemo()
    {
    	// setup menu(s)
        LMMenu lmm = new LMMenu(0);
        ApplicationMenuItemRepository.getInstance(). \
addMenuItem(ApplicationMenuItemRepository.MENUITEM_SYSTEM ,lmm);
   }
	/**
	 * @param args
	 */
	public static void main(String[] args) {
        theApp = new MenuDemo();
        if (theApp != null)
        {
            theApp.enterEventDispatcher();
        }
	}
}

This file contains a single class, MenuDemo, which extends UiApplication.

Like all Java applications, the entry point is the main method. This method creates a new instance of the MenuDemo class.

In the MenuDemo constructor we create an instance of the LMMenu class.

The LMMenu class extends ApplicationMenuItem, which is the BlackBerry menu item class.

Next, we add our newly created menu to the System Menu. There are many choices for where our menu should be assigned. Here is a quick list of the various places where we can place our menu within the BlackBerry environment.

Let’s look at the LMMenu.java file.

package com.msi.linuxmagazine;

import net.rim.blackberry.api.menuitem.*;
import net.rim.blackberry.api.browser.*;

class LMMenu extends ApplicationMenuItem {

	LMMenu(int order)
	{
		super(order);
	}
	public Object run(Object arg0) {
		// handle the action of our menu
		try {
		System.out.println("Our menu was hit!");
		Browser.getDefaultSession().displayPage("http://www.linuxdls.com/blogs/fableson");
		} catch (Exception e) {
			System.err.println(e.getMessage());
		}
		return null;
	}

	public String toString() {
		// this is the label for our menu
		return "linuxdlsazine";
	}
}

This class is very simple, with only three methods.

• LMMenu is a simple constructor that calls its super() method to initialize the menu item. Note that you could also override this constructor to pass in things like menu title and preferred link.
• run is the method which is invoked when the user selects your method. In our application, we put a quick line to the log (usefully really only when debugging on the simulator) and then we launch the BlackBerry browser pointing to our favorite online column.
• The toString method provides the textual label for the menu item. Go ahead, change this to something else and watch the application display your string.

With this code in place, we are almost ready to test the application.

Project Properties

Our application has no user interface beyond the menu item — and for that, we are actually riding a top the system menu. Without a GUI of our own, how does our application get started? Well, we ask the OS to start our application at start-up time as a system module. To specify these settings, we must go into the project properties as shown here.

With our application built and set to start at boot-time, we are ready to test the application. The easiest way to do this within Eclipse is to use the “Run As” menu, as shown here.

With any luck, you will now have a new menu item in your application as shown earlier in this article. Selecting the menu item causes the BlackBerry browser to launch, just as hoped.

In order for our application to run on a real device, we need to have it signed because it uses some protected APIs. Assuming you’ve already got a set of developer keys from RIM installed, simply Request Signatures via the submenu under BlackBerry in Eclipse, as shown here. Once the application is signed, it is capable of being installed and run on a real device.

iPhone and Android are very cool and certainly the new kids on the block — but don’t forget about the millions of BlackBerry users who are not going to switch any time soon. They needs “Apps for that” also. Perhaps you can add your own magic to BlackBerry’s AppWorld.

You can download the source code for this application from our hosting site.