Implementing the UI elements

Screen class

Screen is an abstract class that encapsulates the basic functionality required to display something on the screens. Implementers will use it, for example, to create forms so that CapitalMIDlet can easily display them.

To create this class:

Create the class Screen.

Assign the class to the example.capitals package and import the required classes.

package example.capitals.ui;

import javax.microedition.lcdui.CommandListener;
import javax.microedition.lcdui.Displayable;
import javax.microedition.lcdui.Display;

import example.capitals.CapitalMIDlet;

Implement the functionality of the screen.

/**
 * Abstract Screen class. It provides a common interface
 * for all the classes making up the user interface
 */
public abstract class Screen implements CommandListener {

   protected CapitalMIDlet midlet;   
   protected Displayable displayable;

   public Screen(CapitalMIDlet _midlet) {
      midlet = _midlet;
   }
   
   /**
    * Makes the current screen active
    */
   public void makeActive() {
      try {
         Display d = Display.getDisplay(midlet);
         
         // this prevents bringing application to foreground
         // in case application is in background and the current 
         // displayable is the same as the one made active
         if(d.getCurrent() != displayable) {      
            d.setCurrent(displayable);
         }         
      } catch (NullPointerException e) {
         throw new RuntimeException("Screen.midlet == null");
      }
   }
}

WelcomeScreen class

This is the first screen displayed by the application. It simply shows the name and version of the application and then it goes to MainScreen.

To create this class:

Create the class WelcomeScreen.

Assign the class to the example.capitals package and import the required classes.

package example.capitals.ui;

import javax.microedition.lcdui.Command;
import javax.microedition.lcdui.Displayable;
import javax.microedition.lcdui.Form;

import example.capitals.CapitalMIDlet;

Implement the functionality of the screen.

/**
 * Initial screen. It gives some basic information
 * about the application
 */
public class WelcomeScreen extends Screen {

   private Command okCommand;
   private Command exitCommand;
   
   public WelcomeScreen(CapitalMIDlet _midlet) {
      super(_midlet);
   
      String name = midlet.getAppProperty("MIDlet-Name");      
      String version = midlet.getAppProperty("MIDlet-Version");
        Form f = new Form("Capital Service");
      f.append(name);
      f.append(version);
        displayable = f;

      // create command buttons
      okCommand = new Command("OK", Command.OK, 0);
      exitCommand = new Command("Exit", Command.EXIT, 0);

      // add commands to the text box
      displayable.addCommand(okCommand);
      displayable.addCommand(exitCommand);

      // set command listener
      displayable.setCommandListener(this);
   }

   public void commandAction(Command c, Displayable d) {
      if (c == okCommand) {
         // change to Main Screen
         midlet.showMainScreen();
      } else if (c == exitCommand) {
         // initiate exit
         midlet.quit();
      }
   }
}

MainScreen class

This is a very simple screen that contains a field so that the user can enter the name of the country. This name will be further used to call the remote Web Service.

To create this class:

Create the class MainScreen.

Assign the class to the example.capitals package and import the required classes.

package example.capitals.ui;

import javax.microedition.lcdui.Command;
import javax.microedition.lcdui.Displayable;
import javax.microedition.lcdui.Form;
import javax.microedition.lcdui.TextField;
import example.capitals.CapitalMIDlet;

Implement the functionality of the screen.

/**
 * Main Screen. From this you can select the country and request
 * the WebService to be called using the country as input
 */
public class MainScreen extends Screen {
   private Command exitCommand, callCommand;
   private TextField textField;

   public MainScreen(CapitalMIDlet _midlet) {
      super(_midlet);

      // create form
      textField = new TextField("Country", "", 20, TextField.ANY);
      Form f = new Form("Capital Service");
      f.append(textField);
      displayable = f;
   
      // create command buttons
      exitCommand = new Command("Exit", Command.EXIT, 0);
      displayable.addCommand(exitCommand);
      callCommand = new Command("Retrieve Capital", Command.OK, 0);

      displayable.addCommand(callCommand);      

      // set command listener
      displayable.setCommandListener(this);
      System.out.println("Done");
   
   }

   public void commandAction(Command c, Displayable d) {
      if (c == exitCommand) {
         midlet.quit();
      } else if (c == callCommand) {
         if (textField.getString().length() > 0) {
            // request the midlet to retrieve the capital
            midlet.requestCapital(textField.getString());
         }
      }
   }
}

WaintingScreen class

This screen is displayed while Poster is contacting the remote service. Since this operation may take a while, some feedback needs to be provided to the user. WaitingScreen contains a Gauge widget whose value is increased continually until a response is received from the remote service.

To create this class:

Create the class WaitingScreen.

Assign the class to the example.capitals package and import the required classes.

package example.capitals.ui;

import javax.microedition.lcdui.Command;
import javax.microedition.lcdui.Displayable;
import javax.microedition.lcdui.Form;
import javax.microedition.lcdui.Gauge;
import java.util.Timer;
import java.util.TimerTask;

import example.capitals.CapitalMIDlet;

Implement the functionality of the screen.

/**
 * Simple screen showing the progress of the connection
 * to the remote WebService
 */
public class WaitingScreen extends Screen {
   private Gauge progressGauge;
   private Command exitCommand;

   public WaitingScreen(CapitalMIDlet _midlet) {
      super(_midlet);

      // create displayable
      Form f = new Form("Calling Web Service");
      progressGauge = new Gauge("", false, 10, 0);
      f.append(progressGauge);
      displayable = f;

      // create the timer
      Timer timer = new Timer();
      timer.schedule(new TimerTask() {
         public void run() {
            if (progressGauge.getValue() == progressGauge.getMaxValue()) {
               progressGauge.setValue(0);
            } else {
               progressGauge.setValue(progressGauge.getValue()+1);
            }
         }
        }, 0, 1000);

      // add commands to the text box
      exitCommand = new Command("Exit", Command.EXIT, 0);
      displayable.addCommand(exitCommand);

      // set command listener
      displayable.setCommandListener(this);
   }

   public void commandAction(Command arg0, Displayable arg1) {
      midlet.quit();
   }   
}

ResultsScreen class

When the remote procedure call is successful, CapitalMIDlet will create a ResultsScreen to show the returned value. The screen is a simple form containing fields for the nation and its capital.

To create this class:

Create the class ResultsScreen.

Assign the class to the example.capitals package and import the required classes.

package example.capitals.ui;

import javax.microedition.lcdui.Command;
import javax.microedition.lcdui.Displayable;
import javax.microedition.lcdui.Form;
import javax.microedition.lcdui.StringItem;
import example.capitals.CapitalMIDlet;

Implement the functionality of the screen.

/**
 * This class presents the results of the remote call to the user
*/
public class ResultScreen extends Screen {
   private Command exitCommand, backCommand;

   public ResultScreen(CapitalMIDlet _midlet, String nation,
      String capital) {
      super(_midlet);

      // create the results form
      Form f = new Form("Result");
      f.append(new StringItem("Nation", nation));
      f.append(new StringItem("Capital", capital));
      displayable = f;

      // add commands
      exitCommand = new Command("Exit", Command.EXIT, 0);
      backCommand = new Command("Back", Command.BACK, 0);
      displayable.addCommand(exitCommand);
      displayable.addCommand(backCommand);

      displayable.setCommandListener(this);
   }

   public void commandAction(Command c, Displayable d) {
      if (c == exitCommand) {
         midlet.quit();
      } else if (c == backCommand) {
           // Go back
           midlet.showMainScreen();
      }
   }
}

ErrorScreen class

Finally ErrorScreen is displayed when the remote call fails. This failure can be caused by a multitude of reasons, such as problems in the remote end, communications problems caused by proxies and firewalls, changes in the service definition, and so on. JAX-RPC uses RemoteException to encapsulate all the errors in a unique Java exception.

To create this class:

Create the class ErrorScreen.

Assign the class to the example.capitals package and import the required classes.

package example.capitals.ui;

import javax.microedition.lcdui.Command;
import javax.microedition.lcdui.Displayable;
import javax.microedition.lcdui.Form;
import javax.microedition.lcdui.StringItem;
import example.capitals.CapitalMIDlet;

Implement the functionality of the screen.

/**
 * Simple class to display an error screen
 */
public class ErrorScreen extends Screen {
   private Command exitCommand, backCommand;

   public ErrorScreen(CapitalMIDlet _midlet, String errorString) {
      super(_midlet);

      // create displayable
      Form f = new Form("Error");
      f.append(new StringItem("Value", errorString));
      displayable = f;

      // add commands
      exitCommand = new Command("Exit", Command.EXIT, 0);
      backCommand = new Command("Back", Command.BACK, 0);
      displayable.addCommand(exitCommand);
      displayable.addCommand(backCommand);

      // set command listener      
      displayable.setCommandListener(this);
   }

   public void commandAction(Command c, Displayable d) {
      if (c == exitCommand) {
         midlet.quit();
      } else if (c == backCommand) {
         // Go back
         midlet.showMainScreen();
      }
   }
}