Coding for Multiple Blackberry Devices - Using Preprocessor Directives in Eclipse

In order to maximize sales of your application you'll want to ensure that your code will run across all the Blackberry JDE component versions, or at minimum you'll want to write code that is portable across the most popular Blackberry phones on the market: the Pearl, Curve, Bold and Storm and the various iterations of models within each line.

The main issue outside of the complexity of managing memory and laying out the screen components is that you want to have a single manageable code base that runs across Blackberry phones so you don't have to contend with several branches of code specific for each phone. You might think that you'd simply import the appropriate Storm touch classes, code the touch interface aspects of your app, compile and run to make your existing code work for 4.7.0. The problem is that shortly after you're done you'll see that your code will run on the Storm simulator but fail miserably for anything below 4.7.0 - the 4.6.x components and below don't recognize imports of classes built for 4.7.0.

Preprocessor Directives and Definitions

So how do we take our existing code, add the touch aspects, and have it compile in 4.6.x and below? This is where preprocessor directives come into play. In standard C and Java programming, preprocessor directives are invoked by the compiler as the first part of translation. For example, #include and #define in C and import in Java. In the context of Blackberry programming, the preprocessor directives will tell the compiler to import class definitions and perform statements within our code dependent on preprocessor definitions that we set up within the Eclipse programming environment.

For our example, we will use the preprocessor directives to tell the compiler to load the TouchEvent and VirtualKeyboard classes from 4.7.x. In order to do this within the Eclipse environment we have to do a bit of a hack by using the #ifndef (otherwise known as 'if not defined') directive as if it is a #ifdef(otherwise known as 'if defined'). We'll also configure the Eclipse IDE to provide the preprocessor definition which will write the appropriate config to the .jdp RIM project file without us having to manually edit it.

Eclipse Configuration

The current iteration of the Eclipse Blackberry plugin has the capability for preprocessor definitions built in, under the project properties. The settings can be found by clicking in the Eclipse menu on Project->Properties->Blackberry Project Properties and selecting the "Compile" tab. It will look like the image below:



If your Eclipse doesn't have the 'Preprocessor Defines' box then you'll have to update your plugin version to take advantage of this feature. Click the Edit button and add the following lines:

• JDE_4_7_0


• PREPROCESSOR

Click the Apply button and Eclipse will clean the project and rewrite the Preprocessor defines you just added to the .jdp RIM project file. Just as a sanity check, open this file and check the 'Options' line that is near the end. It should now look like this if the changes were appropriately made:

• Options=-define=JDE_4_7_0;PREPROCESSOR

Adding Preprocessor Directives to Your Code

Now that you've configured Eclipse with the proper Preprocessor definitions you need to add the directives to your code so the preprocessor knows what to add and when. For our example we are going to add the code necessary to perform touch events and import the appropriate 4.7.x classes. First you want to import the classes to your program file, then surround the import statement with the directives,refer to the example below:

//#preprocess
import java.util.Enumeration;
import java.util.Hashtable;
import java.util.Vector;

//#ifndef JDE_4_7_0
/*
//#endif
 import net.rim.device.api.ui.TouchEvent;
 import net.rim.device.api.ui.VirtualKeyboard;
 
//#ifndef JDE_4_7_0
*/
//#endif

import net.rim.device.api.ui.Graphics;
import net.rim.device.api.ui.Keypad;
import net.rim.device.api.ui.MenuItem;
....

We're using #ifndef statements and multi-line comments to trick Eclipse into allowing the import statements without showing errors when you don't have the 4.7 components installed. As a result these statements will appear as comments in Eclipse but will load appropriately when the JDE_4_7_0 preprocessor definition is loaded. Note that you must have the #preprocess statement at the top of any file where you're using preprocessor directives.

Within your code blocks you'll also have to use this commenting approach around any statements dependent on the 4.7 components. Refer below to the VirtualKeyboard calls within the constructor call:

public SearchScreen(Search s){
  
  
  super(DEFAULT_MENU);
  //Necessary because by default keyUp events are disabled
  UiApplication.getUiApplication().enableKeyUpEvents(true);
  search = s;
  myCallback = new ListCallback();
  myCallback.erase();
  myList = new ListField(0,Field.FIELD_HCENTER);
  ingredients = search.getIngredientList();
       
  //#ifndef JDE_4_7_0
  /*
  //#endif
        
     vk = this.getVirtualKeyboard();
     vk.setVisibility(VirtualKeyboard.HIDE_FORCE);
  
  //#ifndef JDE_4_7_0
  */
  //#endif
}
 

Now when you want to run the code using 4.6 or lower components just delete the JDE_4_7_0 preprocessor definition from the project properties and change the installed components to 4.6 or lower. You'll find that Eclipse won't generate any errors and the code will run as intended across devices.

Epilogue

Obviously there are other issues that plague Blackberry developers when it comes to cross phone portability. One issue is that of available phone memory which determines the number of persistent/normal object handles available to your program. For a great guide on managing memory, check out the Blackberry Memory Best Practice Guide.

Secondarily, you'll have to ensure that your application layout is portable across phones since the resolution is different between models. You'll find yourself having to check the resolution of the device within your code in order to position buttons, align text boxes, etc. for each device. In other words, there will be a lot of code that checks the screen width and height to layout the screen for each device similar to the code below that sets the font size for different devices:

width = Display.getWidth();
height = Display.getHeight();

if(width == 480 || width == 360)
  fSize = 21;
else if(width == 320)
  fSize = 18;
else
  fSize = 16;