This is the fifth part of my end-to-end BlackBerry application walk-through. In this article I will go over the following subjects:
- Using resource files for localizing text strings without coding changes
- Setting an application icon on the Ribbon
- Home Screen’s command list icons
- Trimming the cached articles list
- Encoding HTTP request data
- Application “About” dialog
- Alerting the user when a long-running operation is taking place
Using Resource Files for Localizing Text Strings
Although an in-depth discussion about resource files is beyond the scope of this post (a good place to see more information on this subject is the BlackBerry Java Development Environment Fundamentals Guide, which you can obtain from the BlackBerry developers site), I will tell you that each application needs a resource header file, a resource contents file for the root (global) locale and a resource content file for each specific locale it will support.
The resource header file defines descriptive keys for each localized string. Resource content files map descriptive keys to values for the global and specific locales.
Resources for a given locale end up being stored in a ResourceBundle object. A ResourceBundleFamily object groups the resources for an application as a collection of ResourceBundle objects. This is the mechanism an application uses to switch languages depending on the user's locale.
For our application, I created the resource header file (KnowledgeBase.rrh) and a resource contents file for the root locale (KnowledgeBase.rrc). Based on these files, the BlackBerry IDE will create at compile time a resource interface, KnowledgeBaseResource, that we can use to gain access to the localized strings. The resource interface has the same name as the resource header file with the word Resource appended.
To access our localized resources through the application’s resource bundle, we first need to obtain a reference to our resource bundle:
private ResourceBundle resources = ResourceBundle.getBundle(KnowledgeBaseResource.BUNDLE_ID,
KnowledgeBaseResource.BUNDLE_NAME);
Now we’re ready to retrieve a localized string like so
String screenTitle = resources.getString(KnowledgeBaseResource.TTL_HOME_SCRN);
Like I said at the beginning of this section, there’s much more to resources than what I’ve covered here. You should plan on learning more and I would suggest you start by checking out the BlackBerry Java Development Environment Fundamentals Guide, available on the BlackBerry developers site.
Setting an Application Icon
It’s time now to replace the default application icon with something nicer. To set the application icon through the BlackBerry JDE, add the image that will serve as the application icon to the Project and bring up its properties:
In the File Properties applet, select “Use as application icon”:
And when we run the application, we see the new application icon:
Note that although this procedure allows you to set the application icon, it does not allow you to change the image when the application is selected or unselected within the Ribbon. I will describe how to achieve this behavior in a future article.
Home Screen’s Command List Icons
Originally, the three commands on the Home Screen were preceded by the same icon, a green star:
I’ve made some changes to the HomeScreen so that now, each command is preceded by an icon that reflects the command’s function:
I achieved this by modifying the code in the MyObjectListField Class within the Home Screen. In a nutshell, MyObjectListField now has three private bitmaps, one per command, and when it’s time to draw the list row, the appropriate bitmap is drawn before the command. This is how the code looks:
private class MyObjectListField extends ObjectListField {
private Bitmap searchIcon = Bitmap.getBitmapResource(resources.getString(KnowledgeBaseResource.IMG_SEARCH));
private Bitmap tagsIcon = Bitmap.getBitmapResource(resources.getString(KnowledgeBaseResource.IMG_TAGS_LIST));
private Bitmap recentIcon = Bitmap.getBitmapResource(resources.getString(KnowledgeBaseResource.IMG_VIEW_RECENT));
private Bitmap icon;
// We are going to take care of drawing the item.
public void drawListRow(ListField listField, Graphics graphics,
int index, int y, int width) {
if ( mainMenuItems[index] == mnuSearchTitles) {
icon = searchIcon;
}
if ( mainMenuItems[index] == mnuBrowseTags) {
icon = tagsIcon;
}
if ( mainMenuItems[index] == mnuViewRecent) {
icon = recentIcon;
}
if (null != icon) {
int offsetY = (this.getRowHeight() - icon.getHeight())/2;
graphics.drawBitmap(1,y + offsetY, icon.getWidth(),
icon.getHeight(),icon,0,0);
graphics.drawText(mainMenuItems[index],
icon.getWidth() + 2, y, DrawStyle.ELLIPSIS, width - icon.getWidth() + 2);
} else {
graphics.drawText("- " + mainMenuItems[index], 0,
y, DrawStyle.ELLIPSIS, width - graphics.getFont().getAdvance("- "));
}
}
}
Trimming the Cached Articles List
Based on the requirements I set, our application should maintain an in-memory cache with the most recently viewed articles.
The application’s DataStore Class is already capable of handling the storage and retrieval of the cached articles via the setCachedArticles() and getCachedArticles() methods. We also have a way for the user to set the maximum number of cached articles there can be.
What we’re missing is the mechanism to, once a user opens an article, add such article to the cache and prune the cache so the number of articles does not exceed the maximum the user defined. A good place to implement such mechanism is the Article Screen. Let’s add some code that will take care of the possible scenarios:
- The cache is empty
- The cache has some articles, but it still has room
- The cache is full
- The article we’re viewing is already cached
When the cache is empty, we only need to add the currently viewed article:
// Handle the case when there's nothing cached.
if (null == cachedItems || cachedItems.length == 0) {
cachedItems = new Article[]{article};
DataStore.setCachedArticles(cachedItems);
return;
}
When the cache is not empty but still has room, we only need to insert the current article at the top of the list:
// Handle the case when we need to add one more article to the list.
Article[] newList = new Article[cachedItems.length + 1];
// Insert the old items in the new list.
for (int i = 1; i <= cachedItems.length; i++) {
// We're shifting the articles too, to leave room at the top of the list
// for the article we're currently viewing.
newList[i] = cachedItems[i - 1];
}
// Now, put the article we're viewing at the top of the list.
newList[0] = article;
DataStore.setCachedArticles(newList);
When the cache is full, we have to make room for the for the current article:
// Handle the case when the cached need to be trimmed.
Article[] newList = new Article[maxAllowed];
// Insert all the items, except the oldest, in the new list.
for (int i = 1; i < maxAllowed; i++) {
// We're shifting the articles too, to leave room at the top of the list
// for the article we're currently viewing.
newList[i] = cachedItems[i - 1];
}
// Now, put the article we're viewing at the top of the list.
newList[0] = article;
DataStore.setCachedArticles(newList);
When the article we’re viewing is already cached we just bail out:
// Bail if the article we're viewing is already cached.
for (int i = 0; i < cachedItems.length; i++) {
if (article.id.equalsIgnoreCase(cachedItems[i].id)) {
return;
}
}
Looks like we took care of all the scenarios, doesn’t it? Well, not quite yet. What happens if the cache has N number of articles and the user, through the Options Screen, changes the maximum number of articles the cache can store to something less than N? To handle this situation we need to add some code to the Options Screen:
private void trimCachedArticlesList() {
Article[] cached = DataStore.getCachedArticles();
if (null == cached || cached.length == 0) {
return;
}
int maxAllowed = DataStore.getMaxCachedArticles();
if (cached.length <= maxAllowed) {
return;
}
Article[] newList = new Article[maxAllowed];
for (int i = 0; i < maxAllowed; i++) {
newList[i] = cached[i];
}
DataStore.setCachedArticles(newList);
}
And now I think we’re in good shape. If I forgot some detail I’m sure you will let me know. :)
Encoding HTTP Request Data
On the subject of forgetting details, back when I added the HTTP handling code, the routine that took care of creating the HTTP request data looked like this:
public static String createRequestString(final String[] keys, final String[] values) {
StringBuffer requestContents = new StringBuffer("");
if (keys != null) {
for (int i = 0; i < keys.length; i++) {
requestContents.append(keys[i] + "=" + values[i] + "&");
}
}
// Terminate the request with a valid sequence.
requestContents.append("0=0\r\n";);
return requestContents.toString();
}
Everything seems fine with this code until you start wondering what would happen if any actual values (any of the values[i]) in the request data contained reserved characters like ";", "/", "?", ":", "=", "&". And it can become as serious as it became for me last week when a production application started “randomly” failing because of this encoding issue.
What we need here is to make sure that our request data is correctly encoded so our server-side application can make sense of the request.
Working to fix my last week’s emergency, I stumbled upon net.rim.blackberry.api.browser.URLEncodedPostData. URLEncodedPostData is precisely a class that encodes form data using URL-encoding. Let’s use it to take care of our encoding issues:
public static byte[] createPostData(final String[] keys, final String[] values) {
URLEncodedPostData postData = new URLEncodedPostData(URLEncodedPostData.DEFAULT_CHARSET, true);
if (keys != null) {
for (int i = 0; i < keys.length; i++) {
postData.append( keys[i], values[i]);
}
}
return postData.getBytes();
}
Application “About” Dialog
I thought of the “About” dialog as a nice touch for our application. It is triggered by the “About” menu that I just added to the Home Screen.
Of interest here is the use of ApplicationDescriptor to obtain the application name and the version number: