Visual Mobile Designer Custom Components: Creating Wait Screens for Mobile Applications

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 leaves users wondering if the screen is frozen indefinitely or if it is better for them to hang up and try again later (or not at all). So how do developers spare users 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. In this tutorial we show how the Visual Mobile Designer (VMD) simplifies the creation of wait screens by including a Wait Screen custom component you can customize and add into your application flow.

If you are new to mobile application development in NetBeans, you should start with the NetBeans Java ME MIDP Quick Start Guide before continuing.

Contents

Content on this page applies to NetBeans IDE 6.9 or later

To complete this tutorial, you need the following software and resources:

Software or Resource Version Required
NetBeans IDE with Java ME Version 6.9 or later
Java Development Kit (JDK) Version 6 or version 7

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 switches to a display specified by the setNextDisplayable() method. If there is no next displayable screen specified, the Wait Screen switches 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.

top

Installing and Running the Sample Application

Before we begin, you might want to see final result of the tutorial.

Take the following steps to install the waitscreenexample sample application:

  1. Download WaitScreenExample.zip.
  2. Unzip the file.
  3. In the IDE, choose File > Open Project and browse to the folder that contains the unzipped file.
  4. Click Open Project.
    The Project view should look like the following:

    Project Window with WaitScreenExample Files

  5. In the Projects window, right-click the project node and choose Run (or press F6). 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 asks 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.

    DefaultColorPhone emulator displaying the sample wait screen application

  9. After the emulator connects, close the application.

top

Creating a Mobile Application with the WaitScreen Custom Component

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 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 Java ME. 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. We refer to this directory as $PROJECTHOME.
  3. Uncheck the Create Hello MIDlet checkbox. Click Next.
  4. Leave the Sun Java Wireless Toolkit 2.5.2 as the selected Emulator Platform. Click Finish.

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. 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 opens the Visual Mobile Designer (VMD). Clicking on the Flow view 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 view. Drag the following Screen components from the Component Palette and drop them in the Flow Designer:
    • TextBox
    • WaitScreen
    • List
    • Alert
  2. Choose textBox. 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 waitScreen to Wait Screen
    • Change list to List
    • Change alert to Alert
  4. Use the values of the properties for each of the following components:
    • Change the textBox Text property to http://netbeans.org
    • Change the alert String property to Connection Failed
    • Change the WaitScreen Text property to Please Wait...

The Flow view should look like the following image:

Flow view with component icons

Adding Image Resources

In this section, you add images that are 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 alert component and choose Properties in the popup menu.
  3. In the Properties dialog box, click the ellipsis button (Ellipsis button) against the Image property.
  4. In the Image dialog box, click Add.
    The image1 component is added.
  5. Click Browse and in the Open dialog box specify the path to the copied alert.png file.
  6. Click Open.
    The image is added.
  7. Click OK to close the Image dialog box.
  8. Click Close to close the Properties dialog box.
    The alert.png image is bound to the alert component.
  9. Repeat Steps 2 to 8 for the waitScreen component, add sandglass.png as an image2, and bind it to the component.

Adding Ok, Back and Exit Commands to the TextBox and WaitScreen Components

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

Creating the Application Flow

Now you are ready to create the flow of the application.

  1. In the Flow view, click on Started on the Mobile Device and drag it to the textBox component.
  2. In the same manner, connect the components together as shown in the following graphic.

    Flow Designer Screen connected in the following manner: Mobile Device to textBox1 to waitScreen1 to list to MobileDevice. A connection from the Failure command to alert, which then connects to list

Creating a Background Task for the Wait Screen

  1. In the Flow view, right-click the waitScreen component and choose Properties from the popup menu.
  2. In the Properties dialog box, choose <NewCancellableTask> from the Task drop-down menu and click Close.
    simpleCancellableTask is now a background task of the waitScreen component.
  3. Click the Source button at the top of the Visual Mobile Designer to switch to the source code for the application.
  4. 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 = textBox.getString();
          list.deleteAll();
          /**
          * Open an HttpConnection
          */ 
          HttpConnection hc = (HttpConnection) Connector.open(url);
    
          /**
          * Gets a header field key and header field by index and
          * insert it into list.
          */
          list.setTitle(hc.getURL());   
          for (int i=0;hc.getHeaderFieldKey(i)!=null; i++){
          list.insert(i,hc.getHeaderFieldKey(i)+" :"+hc.getHeaderField(i),null);       
          }     
          /**
          * Closing time ...
          */
          hc.close();
          } 
    
  5. Right-click in the source code and choose Fix Imports in the popup menu (alternatively, press Ctrl+Shift+I).
  6. Find the public class MyWaitScreenMidlet extends MIDlet implements CommandListener { string (line 18) and insert final so that it reads:
     public final class MyWaitScreenMidlet extends MIDlet implements CommandListener {
  7. Find the public MyWaitScreenMidlet() method in the source code (line 38) and insert the following code after public MyWaitScreenMidlet() {:
     List list1 = getList();
  8. Click Screen to switch to the Screen view and select SimpleCancellableTask.
  9. In the Properties window, click the ellipsis button (Ellipsis button) against the Executable Code property.
  10. Click Go To source in the Executable code dialog box.
  11. Find the getSimpleCancellableTask() method in the source code (line 328) and insert the following code after public void execute() throws Exception { where it reads // write task-execution user code here:
     getServerInfo();

Running the Project

Press F6 to Run the main project.

Alternatively you could select Run > Run Main Project.

top

Javadoc for the WaitScreen and SimpleCancellableTask Components

The NetBeans IDE provides API Javadocs for the WaitScreen and SimpleCancellableTask components, as well as other components you can use in the VMD. To read the Javadocs for the WaitScreen and SimpleCancellableTask components, complete the steps below:

  1. Place the cursor on the WaitScreen or SimpleCancellableTask component in the source code and press Ctr-Shift-Space (or choose Source > Show Documentation).
    The Javadoc for this element displays in a popup window.
  2. Click the Show documentation in external web browser icon (Show documentation in external web browser) in the popup window to view the detailed information about the WaitScreen or SimpleCancellableTask component in your browser.

top



See Also

top

get support for the NetBeans

Support


By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2013, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo