Visual Mobile Designer Custom Components Creating Wait Screens

Java ME applications often require connections to a network to work properly. Unfortunately, wireless networks are still relatively slow. A background task waiting for a network connection or for data to transfer can pause your application and leave users wondering if the frozen screen means they should stare at an unmoving screen for an indefinite period of time or just hang up and try again later (or never at all). So how do you, as a developer, spare users from this unpleasant, but all too common, experience?

The answer is to add a "Wait Screen." Wait Screens allow users to execute a blocking background task (for example, connecting to a network), and show the progress of the task or display a message on the screen to inform the user that the application is still working as intended.

As you'll see in this tutorial, the Visual Mobile Designer (VMD), a graphical interface within the NetBeans Mobility Pack, simplifies the creation of wait screens by including a WaitScreen custom component you can design and then drag and drop into your application flow.

How the WaitScreen Component Works

There are two ways to create background tasks for the Wait Screen component. You can write a class which implements the CancellableTask interface or just use the SimpleCancellableTask resource. You assign background tasks to the Wait Screen using the setTask() method.

The WaitScreen component automatically switches to a different Displayable object when the background task is finished. If the task finishes successfully, the Wait Screen switches to a display supplied by setNextDisplayable() methods. If the task fails, the Wait Screen switches to a display supplied by setFailureDisplayable() methods. If there is no set failure displayable default, the Wait Screen will switch to a display specified by the setNextDisplayable() method. If there is no next displayable screen specified, the Wait Screen will switch back to the screen that was previously displayed.

Note that this component is available for applications that support the MIDP 2.0 device profile only.

Requirements

Before you begin, you need to install the following software on your computer:

• NetBeans IDE 5.0 or later (download)
• NetBeans Mobility Pack 5.0 or later (download)
• Java Standard Development Kit (JDK) version 1.4.2 or 5.0 (download)

If you are new to the NetBeans Mobility Pack 5.0, you should start with NetBeans Mobility Pack 5.0 Quick Start Guide before continuing.

Take the following steps to install the waitscreenexample sample application:

1. Download waitscreen.zip.
2. Unzip the file.
3. In the IDE, choose File > Open Project and browse to the folder that contains the unzipped file.
4. Open the Project and Inspector windows. It should look like the following:



5. In the Projects window, right-click the project node and choose Run Project (or press F6 key). As the application runs, an emulator window opens and displays the application running in the default device emulator.
6. In the Emulator window, click the button underneath "Launch."
   The emulator displays the URL address of the NetBeans Web site: http://netbeans.org.
7. Click the button underneath "Ok."
   The screen will ask if it is okay to use airtime.
8. Click the button underneath "Yes" to continue.
   As the emulator tries to connect to the Web site, it displays the Wait Screen.
   
   
   
9. After the emulator connects, close the application.

Now that you have seen the WaitScreen component in action, let's go back to the beginning and create this application. To create the application, you will do the following:

1. Create the WaitScreenExample project
2. Add packages and a visual MIDlet to the MyWaitScreen project
3. Add components to MyWaitScreenMIDlet
4. Add Image Resources
5. Add Ok, Back and Exit commands to the TextBox and WaitScreen components
6. Create the Application Flow
7. Create a Background Task for the Wait Screen
8. Run the Project

NOTE: Before you create this project, be sure to close or delete the sample WaitScreenExample project you ran in the steps above. The NetBeans IDE does not allow to identically-named projects to be opened at the same time.

Creating the WaitScreenExample Project

1. Choose File > New Project (Ctrl-Shift-N). Under Categories, select Mobile. Under Projects, select Mobile Application and click Next.
2. Enter WaitScreenExample in the Project Name field. Change the Project Location to a directory on your system. From now on, we will refer to this directory as $PROJECTHOME.
3. Uncheck the Create Hello MIDlet checkbox. Click Next.
4. Leave the J2ME Wireless Toolkit as the selected Target Platform. Click Next.
5. Click Finish.
   The project folder contains all of your sources and project metadata, such as the project Ant script. The application itself is displayed in the Flow Design window of the Visual Mobile Designer.

Adding Packages and a Visual MIDlet to the WaitScreenExample Project

1. Choose the WaitScreenExample project in the Project Window, then choose File > New File (Ctrl-N).
   Under Categories, select Java Classes. Under File Types, select Java Package. Click Next.
2. Enter waitscreenexample in the Package Name field. Click Finish.
3. Choose the waitscreenexample package in the Project window, then choose File > New File (Ctrl-N) . Under Categories, select MIDP. Under File Types, select Visual MIDlet. Click Next.
4. Enter MyWaitScreenMidlet into MIDlet Name and MIDP Class Name fields. Click Finish.

Adding Components to MyWaitScreenMidlet

Selecting the Visual MIDlet in the Inspector window opens the Visual Mobile Designer (VMD). Clicking on the Flow design window at the top of the VMD window opens the Flow Designer, where you design the application flow.

1. Switch your Visual MIDlet to the Flow Designer window. Drag the following Screen components from the Component Palette and drop them in the Flow Designer:
   
• TextBox
• WaitScreen
• List
• Alert
  
2. Choose textBox1. In the Properties window (underneath the Component Palette), change the Title property to Text Box.
3. Use the same process to change the titles of the following components:
   
   • Change waitScreen1 to Wait Screen
   • Change List1 to List
   • Change Alert1 to Alert
4. Use the String property for each of the following components to change the values:
   
   • Change the textBox1 string to http://netbeans.org
   • Change the alert1 string to Connection Failed
5. Change the WaitScreen1 text property to Please Wait...

The Flow Designer window should look like the following graphic:

Notice that each component has at least one orange square next to it, which we will use later to connect the components to each other in the order of the application flow. Notice also that waitScreen1 has two squares on its right.

Adding Image Resources

In this section, you add images that will be used by the Wait Screen and the Alert Screen.

1. Download and copy the alert.png and sandglass.png files to $PROJECTHOME/src/waitscreenexample folder.
2. Right-click the Resources folder in the Inspector Window and choose Add > Image.
3. Select image1 in the Inspector Window. In the Properties Window choose the Resource Path property and click on the ellipsis (...) button. In the dialog, choose alert.png.
4. Select the alert1 component.
5. In the Properties Window of alert1 find the Image property and choose image1 from the list.
   This action binds the alert.png image to the alert1 component.
6. Repeating Steps 2 to 5, add an image2, set its Resource Path to sandglass.png, and bind it to the waitScreen1 component.

Adding Ok, Back and Exit commands to the TextBox and WaitScreen components

1. Choose the Ok Command from Commands section in the Component Palette. Drag it and drop it into textBox1.
2. Choose the Back Command from Commands section in the Component Palette. Drag it and drop it into list1.
3. Choose the Exit Command from Commands section in the Component Palette. Drag it and drop it into list1.

Create the Application Flow

Now you're ready to create the flow of the application.

1. In the Flow design window, click on the Start Point on the Mobile Device and drag it to the textBox1 component.
2. In the same manner, connect the components together as shown in the following graphic.
   
   

Creating a Background Task for the Wait Screen

1. Right-click Resources in the Inspector Window and choose Add > SimpleCancellableTask.
2. Select waitScreen1 component in the Flow Design Window.
3. Click on the Task property in the waitScreen1 Properties Window and choose simpleCancellableTask1 from the drop-down menu.
   Now simpleCancellableTask1 is a background task of the waitScreen1 component.
4. Click the Source button at the top of the VMD window.
   This displays the source code for the application.
5. Add a method for the background task by pasting the the following code into the MyWaitScreenMIDlet source code after
public void destroyapp(boolean unconditional) {
}:

      private void getServerInfo() throws IOException {
      String url = textBox1.getString();
      list1.deleteAll();
      /**
      * Open an HttpConnection
      */
      HttpConnection hc = (HttpConnection) Connector.open(url);

      /**
      * Gets a header field key and header field by index and
      * insert it into list1.
      */
      list1.setTitle(hc.getURL());
      for (int i=0;hc.getHeaderFieldKey(i)!=null; i++){
      list1.insert(0,hc.getHeaderFieldKey(0)+" :"+hc.getHeaderField(0),null);
      }
      /**
      * Closing time ...
      */
      hc.close();
      }

6. In the Properties Window of SimpleCancellableTask1 choose Execute property.
7. In the Insert Code Window type: getServerInfo();

Running the Project

1. Press <F6> to Run the main project.

   Alternatively you could select Run > Run Main Project.

To Learn More about the WaitScreen Component and SimpleCancellableTask Resource

The NetBeans IDE provides API documentation—javadocs—for the WaitScreen component and SimplecancellableTask resource, as well as other components you can use in the VMD. To read the javadocs:

1. Choose View > Documentation Indices > NetBeans MIDP Components.
   This action displays a file in the browser.

Next Steps

• Read our other Custom Component tutorials:
  • Creating Mobile Splash Screens
  • Creating Table Items
• Read Lukas Hasik's Blog entries on the WaitScreen and SimpleCancellableTask
  • Change in API of SimpleCancellableTask (1 Nov 2005)
  • Simple Example of a WaitScreen Component (7 Mar 2006)
• See another example of a WaitScreen in action in this NetBeans Day Mobility Demo
• Read the NetBeans Mobility Pack Quick Start Guide to learn about other features of the NetBeans Mobility Pack