Blackberry Threads- Dynamically Update UI Components using the Observer Design Pattern

Using threads for basic tasks on the Blackberry is not necessarily as difficult as it may first appear. You can leverage RIM's net.rim.device.api.system.Application class to synchronize with the EventLock and perform whatever tasks your threading model requires. Of course when programming games or intricate UI component interaction using threads can be complex and downright challenging. Thankfully, for most apps you're likely to do simple threading tasks that don't require such interaction. In order to modify UI components you must perform all the work within the UI thread and there are two general rules that you'll have to follow:
1) Modify UI components using the invokeLater() method, 2)Never call an HTTP request within the UI thread.

The invokeLater() method is used when changes are made to the UI outside of the main UI thread. It places your runnable object into your application's main event queue and is processed after all events pending in the main queue are complete. In other words, it's similar to regular Java threads where you use the join() method so your code waits for other threads to complete before grabbing the eventlock. Making HTTP requests within the UI thread will most assuredly make your application slow down and could make it crash. Instead of using invokeLater() or other methods to grab the UI thread you'll want to do something like the following:

new Thread(){

  public void run(){

    HttpConnection http_con = (HttpConnection)Connector.open("http://berrytutorials.blogspot.com");

  }

}.start();

Here we're creating a new thread that opens the HTTP connection but it will run as a background process and not tie up system resources on the main UI thread. For more details on opening HTTP check out the HTTPDemo included in the RIM samples that are part of your component pack download for Eclipse.

Background

For the example we'll be using the code from a previous tutorial on Listfields and will modify it to make updates to the list from a thread. Take a few minutes to read through that code, copy it and place it into a new Blackberry project in Eclipse - otherwise you can get the sample code in it's entirety here.

Thread.sleep() will be used to simulate your code performing data processing or making an HTTP connection that will occur in the background of the app. Once that's complete the listfield will be updated with a simple string that will include the thread name and an element number that is incremented for each update so you can see the thread working. It wouldn't take much modification to modify the code below and, for example, make a connection to Twitter via their API to grab updates to the people you follow, then update the list with that content.

You might ask, "How does the ListField know when to update itself?" - what I'm doing in the code is leveraging the Observer design pattern to attach the ListField as a "observer" to the Thread we create. It will "listen" to the Thread until it's notified of an update and then will add the new message to the list and redraw itself. Here's an image that will serve to give you an overview of what the Observer pattern is doing, courtesy of javaworld.com:




For the sample code, the Subject shown in the image above will be the Thread we create and the Observer is the ListField itself - once the Thread has slept (simulating the HTTP connection or data processing task) it will notify the Listfield of the change. To do this appropriately we'll create an interface for the ListField to implement containing the update() method and will create the addObserver(), removeObserver() and notifyObservers() methods in the Thread class. The reason we use the interface here is that many different Classes might need to observe the Thread's progress and could be attached as Observers. The Thread loops through the attached Observers and informs them of the changes via the the update() method. The end result will be a ListField that auto updates elements every 10 seconds as in the screenshot below:



In this sample we don't necessarily have to use the interface since we're only attaching one Observer but it's good practice to see how it works. If you're not familiar with the Observer pattern take a few minutes and read through the following links: Background on Design Patterns GangofFour - Observer Pattern, PDF on Observer Pattern

Subject Code - Create the Thread

First we need to add a private class that is used to implement the Thread itself. Following the Observer pattern we'll add the methods 'addObserver(MyListField mlf)' and 'removeObserver(MyListField mlf)' that permit the thread to add/remove Observers to itself and a 'notifyObservers()' function that will inform observers that are attached to the Thread that a change has occurred. Here's the code:

//Runnable class 

 private class CheckForUpdates implements Runnable{

	  

	 private String updatedMessage;

	 private Vector observers;

	 

	 public CheckForUpdates(){

		 observers = new Vector();

	 }

	 

	 //Attach the observer to the class

	 public void addObserver(MyListField mlf){

		 observers.addElement(mlf);

	 }

	 

	 //Not used for this example - remove an observer

	 public void removeObserver(MyListField mlf){

		 observers.removeElement(mlf);

	 }

	 

	 //Go through vector of observers and call update on them

	 //Sending the updatedMessage String.

	 public void notifyObservers(){

		 for(int i=0;i			 ((MyListField)observers.elementAt(i)).update(updatedMessage);

		 }

	 }

	 

	 //Overridden runnable method.  Simulates checking external resource(such as HTTP call to remote server)

	 //using the sleep() method then changes the message and notifies the attached observers.

	  public void run(){

		  int counter = 0;

		  try{

		  	while(true){

		  		//Simulate an HTTP connection OR data processing

		  		Thread.sleep(10000);

		  		counter++;

		  		updatedMessage = Thread.currentThread().getName() + "- Element " + Integer.toString(counter);

		  		notifyObservers();

		  	}

		  }

		  

		  //Simply return if interrupted.

		  catch (InterruptedException e){

			  return;

		  }

	  }

	  

	 

 }

 

Note that we're creating a private Vector to hold the observers that are attached to the instance of the thread although there will be only one observer for the example. Additionally, if you take a look at the run() method, you'll see that we loop indefinitely, calling Thread.sleep(10000) and when the Thread wakes it increments the counter, updates the message to pass to the observers, and calls the 'notifyObservers()' method. If this were production you'd want to add some code that can stop the Thread based on a keystroke, menu option, or some other method, otherwise it will eventually consume all the resources available.

Observer Code - Create the Interface and Update Method

The next step is to create the Observer interface and the update() method, in this case contained in the MyListField class. Here's the code:

public interface ObserverInterface{

	 

	 public void update(String message);

 }



....

private class MyListField extends ListField implements ObserverInterface{

.....

.....

.....

 //Update function takes in a message to add to the list, 

	   //inserts it into the list, and calls invalidate to repaint the list

	    public void update(final String message){

	    	final int i = this.getSize();

	    	final ListCallback mlc = (ListCallback)this.getCallback();

	    	final MyListField mlf = this;

	    	UiApplication.getUiApplication().invokeLater(new Runnable(){

	    		  public void run(){

	    			  mlf.insert(i);

	    	          mlc.insert(message,i);

	    	         

	    		  }

	    		});

	    	  

	          

	    }

The update() method grabs the UiApplication event lock by calling 'invokeLater()' with a new Runnable() where we insert the String into the List. Thus, the main UI thread will complete whatever functions it's performing and pass the lock to our thread which updates the List and redraws it to the screen.

Constructor code

Finally, add the following to the constructor of the ListFieldTest class:

//Declare the Runnable Thread

	        CheckForUpdates cfu = new CheckForUpdates();

	        

	        //Attach the Observer - in this case myList is the observer

	        cfu.addObserver(myList);

	        

	        //Declare a new thread with our Runnable as input and start thread

	        Thread t = new Thread(cfu);

	        t.start();

	        

That's all there is to it. We create an instance of our Thread, attach the List as an Observer so the thread can call the List's update() function when there's a change, and simply start the thread. Side Note: Java has Observer/Observable as part of the language specification however RIM does not and as a result you can't leverage the code that's already out there. Nonetheless, implementing the pattern wasn't too difficult, at least for this simple example, and understanding how design patterns work will really make life easier.

Create a Custom Listfield - Change Highlight Color when Scrolling

When you're programming for Blackberry you will likely find yourself in need of displaying a list of items that are selectable to the end user. The ListField class in the Blackberry API is extremely versatile and should be your first choice when considering how to display a list of options.

Key to coding the ListField is to register a ListFieldCallback - a class that implements the ListFieldCallback interface and can be thought of as a data structure that holds the contents of the List and permits you to modify, update, delete, and read these contents. In other words, the ListField handles the painting of the list and the Callback handles the storage of the list contents.

For this article I'll show you how to get a ListField up and running on the Blackberry and how to customize the highlighting of each row when the user scrolls across the list. For demonstration purposes we'll create the ListField as a private class within the main class that extends UiApplication and simply add our field managers that will hold the ListField to the MainScreen. Note that the code samples do not include the required code for capturing the user selection and performing an action on it - I may write another tutorial around that if people request it however that's pretty straightforward. In the end, our main goal is to have a list that looks like the one below, where the user selection is highlighted in a different color as they scroll across the list:

Write the Constructor

Please note that all the code below is continuous and should be contained in one file. I'll put a link to download the entire code in one file if the demand is there. However, I think it's a good learning experience to see each piece, understand how it works and put it together at the end into a cohesive working program. First, we'll import the necessary classes and create the main function for our example. I'm going to do all the heavy lifting in the constructor of the class - please note that the VerticalFieldManager and the HorizontalFieldManager in the next sections are also part of the constructor. Also, we're declaring instances of the ListField and ListFieldCallback early in the constructor and will flesh out those classes a bit later. Here's the first part of the code:

import net.rim.device.api.system.Bitmap;
import net.rim.device.api.system.Display;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;

import java.util.Vector;

public class ListFieldTest extends UiApplication {
 
 public static void main(String[] args){
  
  //main entry point 
  ListFieldTest theApp = new ListFieldTest();
  theApp.enterEventDispatcher();
 
 }


 public ListFieldTest(){

   HorizontalFieldManager _hfm;
                
   //The _vfm will hold the ListField and we'll add it to the _hfm
   VerticalFieldManager _vfm;

  //Create the vars for ListField creation
  ListField myList;
  ListCallback myCallback;

  //Get the device width and height
  final int width = Display.getWidth();
  final int height = Display.getHeight();
        
  //Create the mainScreen - this holds the _hfm and _vfm managers
  MainScreen mainScreen;
  mainScreen = new MainScreen();
                
  //Private class that we will create in a minute
  myCallback = new ListCallback();
  myCallback.erase();

  myList = new MyListField();
  myList.setCallback(myCallback);
                
  //Populate the list with sample elements
  for(int i=0;i<20;i++){
        myList.insert(i);
        myCallback.insert("Element #" + Integer.toString(i), i);
        
  }

Create the HorizontalFieldManager

Now we need to create the HorizontalFieldManager that will hold the ListField and VerticalFieldManager. The HFM will act as the "parent" container and will hold the VFM child and we will also use it to draw the gradient. Refer to the code below for the HorizontalFieldManager:

//Draw background gradient on this manager and add VerticalFieldManager for scrolling.
   _hfm = new HorizontalFieldManager() {
   
    public void paint(Graphics g)
    {
     
    
     //Variables for drawing the gradient
     int[] X_PTS_MAIN = { 0, width, width, 0}; 
     int[] Y_PTS_MAIN = { 0, 0, height, height }; 
     int[] drawColors_MAIN = { Color.BLACK, Color.BLACK, Color.DARKBLUE, Color.DARKBLUE};
 
     
     try {
      //Draw the gradients   
         g.drawShadedFilledPath(X_PTS_MAIN, Y_PTS_MAIN, null, drawColors_MAIN, null);
         
     } catch (IllegalArgumentException iae) {
         System.out.println("Bad arguments."); 
     }
     
     
     
     //Call super to paint the graphics on the inherited window 
     super.paint(g);
     
      
      }
   
   //Sublayout is passed the width and height of the parent window and will tell the window manager
   //how to layout the buttons, images, etc.
   protected void sublayout(int w, int h) {  
    
    //GetFieldCount returns the number of fields attached to the instance of this manager.
    //and lays out the position
              if (getFieldCount() >0) {                 
                            
                   Field searchRes = getField(0);
                   layoutChild(searchRes, width, height);
                   setPositionChild(searchRes,0,0);
                
              }
              
              
             
              setExtent(width,height);
             
          }
   
   
  };

Create the VerticalFieldManager

In the VerticalFieldManager declaration we will pass in the VERTICAL_SCROLL option so the lists scroll properly within the container once we add the ListField. Additionally, make sure to override the navigationMovement() function calling this.invalidate() otherwise when you scroll the ListField won't redraw as the user scrolls over the options. Try it without the invalidate() call to see what happens. Here's the final code for the VFM in the constructor:

   _vfm = new VerticalFieldManager(Manager.VERTICAL_SCROLL|Manager.USE_ALL_HEIGHT|Manager.USE_ALL_WIDTH) {
    
    public void paint(Graphics g)
       {
            g.setColor(Color.GRAY);  
           super.paint(g);
     
       }
    
    protected boolean navigationMovement(int dx, int dy, int status, int time){
           this.invalidate();
           return super.navigationMovement(dx,dy,status,time);
          }
          
    
   };
        //Add the list to the verticalFieldManager
         _vfm.add(myList);
         
        //Add the verticalFieldManager to the HorizontalFieldManager
        _hfm.add(_vfm);
       //Finally, add the HorizontalFieldManager to the MainScreen and push it to the stack 
        mainScreen.add(_hfm);
        pushScreen(mainScreen);
 
 
 }//End Ctor
 

Create the ListField Class

Now we'll create a private ListField class and we'll override the paint() method to draw the highlight color on the selected row. The tricky part is forcing the redraw of the highlight color - you must first determine the selected row by calling getSelectedIndex() then mathematically calculate the size of the row to paint the highlight color. Here's the code (the comments are pretty detailed explaining what is going on there):

private class MyListField extends ListField{
  
  
  //0,ListField.MULTI_SELECT
    private boolean hasFocus = false;
    
    public  void onFocus(int direction){
      hasFocus = true;  
    }
    
     public void onUnfocus() 
        {
               hasFocus = false;
               super.onUnfocus();
               invalidate();
        }
     
    public void paint(Graphics graphics) 
          {   int width = Display.getWidth();
              //Get the current clipping region 
              XYRect redrawRect = graphics.getClippingRect();
              if(redrawRect.y < 0)
              {
                  throw new IllegalStateException("Error with clipping rect.");
              }

              //Determine the start location of the clipping region and end.
              int rowHeight = getRowHeight();

              int curSelected;
              
              //If the ListeField has focus determine the selected row.
              if (hasFocus) 
              {
                   curSelected = getSelectedIndex();
                   
              } 
              else 
              {
                  curSelected = -1;
              }
              
              int startLine = redrawRect.y / rowHeight;
              int endLine = (redrawRect.y + redrawRect.height - 1) / rowHeight;
              endLine = Math.min(endLine, getSize() - 1);
              int y = startLine * rowHeight;

              //Setup the data used for drawing.
              int[] yInds = new int[]{y, y, y + rowHeight, y + rowHeight};
              int[] xInds = new int[]{0, width, width, 0};

              //Set the callback - assuming String values.
              ListFieldCallback callBack = this.getCallback();

              //Draw each row
              for(; startLine <= endLine; ++startLine) 
              {               
             //If the line we're drawing is the currentlySelected line then draw the fill path in LIGHTYELLOW and the 
               //font text in Black.  
             if(startLine == curSelected){
              
                     graphics.setColor(Color.LIGHTYELLOW);
                     graphics.drawFilledPath(xInds, yInds, null, null);
                     graphics.setColor(Color.BLACK);
                     graphics.drawText((String)callBack.get(this, startLine), 0, yInds[0]);
                   
             }
             else{
                     //Draw the odd or selected rows.
                    graphics.setColor(Color.LIGHTGREY);
                    graphics.drawText((String)callBack.get(this, startLine), 0, yInds[0]);
             }
             
              //Assign new values to the y axis moving one row down.
                y += rowHeight;
                yInds[0] = y;
                yInds[1] = yInds[0];
                yInds[2] = y + rowHeight;
                yInds[3] = yInds[2];
              }
              
              //super.paint(graphics);
          }
 }

Create the ListfieldCallback Class

The final step is to create the private ListFieldCallback class that's attached to our ListField. Since we're not embedding images or doing other fancy things, only writing Strings to the Callback, the code is relatively straightforward, as shown below:

//Private class to populate the ListField private variable
 private class ListCallback implements ListFieldCallback{

  
  private Vector listElements = new Vector();
        
     public void drawListRow(ListField list, Graphics g, 
                         int index, int y, int w) {  

        String text = (String)listElements.elementAt(index);
        g.setColor(Color.LIGHTGREY);
        g.drawText(text, 0, y, 0, w);  
     }
        
     public Object get(ListField list, int index) {  
        return listElements.elementAt(index); 
     }     

     public int indexOfList(ListField list, String p, int s) {  
        //return listElements.getSelectedIndex();
        return listElements.indexOf(p, s);  
     }
        
        
     public void insert(String toInsert, int index) {  
        listElements.insertElementAt(toInsert, index);  
     }
     
     public void add(String toInsert){
      listElements.addElement(toInsert);
     }
        
     public void erase() {  
        listElements.removeAllElements();  
     }

  public int getPreferredWidth(ListField listField) {
   // TODO Auto-generated method stub
   return 0;
  }

  
  
  }
 }

The final result will be a scrollable list that highlights the user selected option in a Light Yellow color, as shown in the screenshot at the top of this post. Once you understand how this works you can see how modifications to the overridden paint() method in ListField could permit you to have highly modifiable rows in the list - for example, in a Flikr client app you might have a scrollable list of your friends with a thumbnail on each row showing a sample picture from that friend's account. When the user scrolls to a new friend in the list (startLine == curSelected), you might initiate a function that updates the thumbnail with a changing feed of images from that user's account. The possibilities are almost infinite when customizing ListFields. I'll be on the lookout for questions in the comments section.