NetBeans Mobility Pack 5.0 Quick Start Guide

Creating a MIDP Application

1. Choose File > New Project (Ctrl-Shift-N). Under Categories, select Mobile. Under Projects, select Mobile Application and click Next.
2. Enter MyHello in the Project Name field. Change the Project Location to any directory on your system. From now on, we will refer to this directory as $PROJECTHOME.
3. Check the Set as Main Project and Create Hello MIDlet checkboxes (both are checked by default). Click Next.
4. Leave the J2ME Wireless Toolkit as the selected Target Platform.
5. Click Finish. The IDE creates the $PROJECTHOME/MyHello project folder. 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.

Editing the Java Source Code

Now let's edit the text displayed by the MIDlet.

1. Click on Screen Design.
   This opens the Screen Designer window, and displays the helloForm[Form] screen, which is the only screen available in the application.
2. Double-click on the "Hello world!" text and type in some new text.

Compiling and Running the Project

1. Choose Run > Run Main Project (F6) from the Run menu. Double-click the Output window to maximize it so you can see all the output. Note that the HelloMIDlet.java file is built before it is executed. A device emulator opens to display the results of the executed MIDlet. The default device emulator is DefaultColorPhone.
2. In the device emulator window, click on the button below the Launch command. The device emulator launches the MIDlet and displays the text you entered in the source code.
3. Click on the button below Exit to close the MIDlet. Then click on the button in the upper right corner of the device to close the emulator window.

Creating a New Java ME MIDP project

1. Choose File > New Project (Ctrl-Shift-N). Under Categories, select Mobile. Under Projects, select Mobile Application and click Next.
2. Enter MyHelloMIDlet in the Project Name field. Change the Project Location to any directory on your system. From now on, we will refer to this directory as $PROJECTHOME.
3. Check the Set as Main Project checkbox and remove the check from the Create Hello MIDlet checkbox. Click Next.
4. Leave the J2ME Wireless Toolkit as the selected Target Platform.
5. Click Finish. The IDE creates the $PROJECTHOME/MyHelloMIDlet project folder. The project folder contains all of your sources and project metadata, such as the project Ant script.
6. Right-click the MyHelloMIDlet node in the Explorer window and choose New > File/Folder.
7. Under Categories, choose MIDP. Under File Types, choose MIDlet. Click Next.
8. Enter HelloMIDlet as the MIDlet name. Click Finish. The HelloMIDlet.java is created.
9. Double click the HelloMIDlet.java to display the source code in the Editor.
10. Click in the Source Editor and change
    

    public class HelloMidlet extends MIDlet

    
    to
    

    public class HelloMIDlet
                  extends MIDlet implements javax.microedition.lcdui.CommandListener
                  {

11. Add the following text before the startApp() method:
    

    public HelloMIDlet() {
    }
    private void initialize() {
      javax.microedition.lcdui.Display.getDisplay(this).setCurrent(get_helloTextBox());
    }
    
    public void commandAction(javax.microedition.lcdui.Command command, javax.microedition.lcdui.Displayable
      displayable) {
       if (displayable == helloTextBox) {
          if (command == exitCommand) {
             javax.microedition.lcdui.Display.getDisplay(this).setCurrent(null);
             destroyApp(true);
             notifyDestroyed();
          }
       }
    
    }
    
    private javax.microedition.lcdui.TextBox get_helloTextBox() {
       if (helloTextBox == null) {
           helloTextBox = new javax.microedition.lcdui.TextBox(null, "Test String",120, 0x0);
           helloTextBox.addCommand(get_exitCommand());
           helloTextBox.setCommandListener(this);
       }
       return helloTextBox;
    }
    
    private javax.microedition.lcdui.Command get_exitCommand() {
       if (exitCommand == null) {
           exitCommand = new javax.microedition.lcdui.Command("Exit", javax.microedition.lcdui.Command.EXIT,
      1);
       }
       return exitCommand;
    }
    
    javax.microedition.lcdui.TextBox helloTextBox;
    javax.microedition.lcdui.Command exitCommand;

12. Add a line initialize(); to the startApp() method, so it looks like the following:

      public void startApp() {
       initialize();
        }

Editing the Java Source Code

Now let's add some text for our MIDlet to display.

1. In the get_helloTextBox() method, replace the "test string" code with the text of your choice. For example, "Hello World."

Compiling and Running the Project

1. Choose Run > Run Main Project (F6) from the Run menu. Double-click the Output window to maximize it so you can see all the output. Note that the HelloMIDlet.java file is built before it is executed. A device emulator opens to display the results of the executed MIDlet. The default device emulator is DefaultColorPhone.
2. In the device emulator window, click on the button below the Launch command. The device emulator launches the MIDlet and displays the text you entered in the source code.
3. Click on the button below Exit to close the MIDlet. Then click on the button in the upper right corner of the device to close the emulator window.

Changing the Default Emulator Device

1. Right-click the MyHello Project node and choose Properties. In the Properties dialog, choose the Platform node. Here, you can change the device for the default configuration.
2. Click the Device drop-down list and choose QwertyDevice. Click OK.
3. Run the application again, and the application runs in the QwertyDevice emulator.

Adding a new Emulator Platform

1. Choose Tools > Java Platform Manager from the main toolbar.
2. In the Java PlatformManager dialog, click the Add Platform button.
3. In the Select Platform Type page, choose the Java Micro Edition Platform Emulator. Click Next.
   In the Platforms page, the IDE searches for all available Java ME platforms and lists them in the window. Platforms that are compliant with the Unified Emulator Interface (UEI) standard are verified and appear with a check in the checkbox next to the platform name. Platforms that are not UEI-compliant, or that you might not be able to install for other reasons, are listed in red. The wizard also identifies which platforms have already been installed.
   
   NOTE: To install platforms that are not UEI-compliant, click the Back button and choose Custom Java Micro Edition Platform Emulator.
4. In the Platforms page, put a check next to any platform emulator you want to install. Click Finish. Then click Close.
   The selected platform or platforms are installed.
5. Choose File > "MyHello" Properties.
6. Choose the Platform node, then choose the name of the new emulator (for example, J2ME Wireless Toolkit 2.2) from the Emulator Platform drop-down menu. Click OK.

Adding a Configuration

1. Right-click the MyHello Project node and choose Properties. In the Properties dialog, Choose Add Configuration from the Project Configuration drop-down list. This opens the Add Configuration dialog.
2. Enter a name for your configuration in the Configuration Name field. The name should identify the target platform on which you will deploy the JAR/JAD created for this configuration. For this example, enter BlackWhiteDisplay and click OK. You have just created a new configuration
3. Configurations can also be added by clicking the Manage Configurations button in the Properties dialog. This brings up the Project Configuration Manager dialog which contains options for adding, removing, or duplicating configurations.

Customizing a Configuration

You can add as many configurations as you would like to your project. You can then modify settings in the Project Properties dialog for each configuration that you've added.

1. Right-click the MyHello Project node and choose Properties. In the Properties dialog, choose the Platform node. This opens the J2ME MIDP Configuration dialog.
2. Choose the BlackWhiteDisplay configuration from the configuration combo box at the top of the Properties dialog.
3. The components in the Platform dialog are all disabled. This is because this configuration is currently taking the values used by the Default configuration for this panel. Uncheck the Use Default Project Configuration Values option at the bottom of the panel. All components on this panel can now be edited.
4. Change the Device option to DefaultGrayPhone.
5. Toggle the Project Configuration dialog at the top of the Properties dialog and observe that the Device option changes based on which configuration is currently selected. This method of configuration customization works for each panel (other than the general panel) in the dialog. Click OK to save your configuration changes and exit the Properties dialog.

Creating an Ability

When you create an ability, you associate it with one or more project configurations that support a specific attribute or set of attributes. You can then associate the ability with one or more code blocks that support the attribute. If you later need to add or remove configurations, you won't have to go through all your code and associate the configuration with each code block. Instead, you need only to associate the configuration with an ability. The configuration is then automatically associated with any code block that is associated with the ability.

1. Right-click on the MyHello project node and choose Properties.
2. Choose the Abilities page from the Category menu tree.
3. Choose a configuration from the Project Configuration dropdown menu. This is the configuration with which the ability will be associated.
4. If necessary, uncheck the Use Values from "DefaultConfiguration" checkbox.
5. Click the Add button.
   This opens the Add Ability dialog.
6. In the New Ability dialog, enter a name for the ability, or choose an ability from the drop-down menu. Optionally, enter a value for the ability.
   Click Ok to close the New Ability dialog. The ability is now associated with the selected project configuration.

You can associate the ability with other configurations by choosing a different configuration from the Project Configuration menu and clicking the Add button.

Adding Configuration-Specific Code (Preprocessor code)

Preprocessor blocks enable you to create, manage and track code that is specific to one or more project configurations or abilities. The code is enabled (or disabled) only for the configurations or abilities you identify.

1. In the HelloMIDlet.java Editor window, right-click on the source code line where TextBox is instantiated ( helloTextBox = new javax.microedition.lcdui.TextBox(null, "Hello, World",120, 0x0);).
2. Right-click on the line and choose Preprocessor Blocks > Create If/Else Block. In the first, pink section, append the word "Color" to the "Hello World" string. In the second, gray section, add "Gray" to the "Hello World" string.
3. The code marked by the //#if preprocessor directive will be in effect whenever the active configuration matches the directive value (in this case, DefaultConfiguration.) The code encased by the //#else preprocessor directive will be used whenever the active configuration does not match the value of the preprocessor.
   
   In other words, the emulator displays "Hello World Color" whenever the active platform is "DefaultConfiguration," and displays "Hello World Gray" if the active platform is any other emulator platform. The //#endif preprocessor directive completes the preprocessor block.

You can test the preprocessor code by running the MIDlet using different emulator devices, as described in Changing the Emulator Platform.

Running Configurations

Configurations can be built and run individually or simultaneously.

1. Right-click the MyHelloMIDlet Project node and choose Run.
2. Activate a different configuration by right-clicking the MyHelloMIDlet Project node and choosing Set Active Project Configuration and then a choose a different configuration. This can also be done with the configuration combo box in each text editor. Run the project again.
3. Two emulators appear, one color and one gray. The gray emulator displays "Hello World Gray" and the color emulator displays "Hello World Color"

Creating a Java ME Web Services
(JSR-172) Client

1. Right-click on a project node and choose New > File/Folder.
   
2. In the New File wizard, choose MIDP under Categories. Under File Types, choose J2ME Web Services Client.
   
3. Identify the WSDL file location for the Web service to be added to the project.
• If the WSDL service is on the Web:
  1. Choose Running Web Service and enter a URL for the WSDL file and enter a local filename for the retrieved WSDL.
  2. If you are behind a firewall, click Proxy Settings to designate the appropriate HTTP host and port.
  3. Click Retrieve WSDL to get a local copy of the WDSL file. The IDE downloads the WSDL file.
• If you have a WSDL file in your environment, select Existing WSDL file and enter a filename.
  
4. The WSDL file is retrieved and the rest of the fields on the page are filled with default names derived from the WSDL file name.
   
5. Press Finish.
   The IDE creates an opened settings file and generates client stubs.

• In some rare situations, you might need to convert CLDC 1.1 types to CLDC 1.0 types, which means Float and Double types are converted to String variables. To make the conversion, select the checkbox “Convert floating point to String” on the settings file and click the Generate Stubs button.
  
• If you are behind a firewall, there is no public setting available for the HTTPS proxy within NetBeans. To work around this, run the IDE from the command line with the command -J-DhttpsProxy.host and -J-DhttpsProxy.port, or add the proxy settings into the /etc/netbeans.conf file.
• The generated files should not be edited. Any changes made to the files are lost when you regenerate them.

Localizing Your Application

Localization is the process of designing software so that it can be adapted (localized) to various languages and regions without engineering changes to the software. When you localize an application, you provide alternate language values for each element in your application, such as screen text, menus, and icons.

Adding Localization Support

1. Create the java classes that initialize the localization support and message property files.
   1. Right-click the MyHelloMIDlet Project node and choose New > File/Folder.
   2. Under Categories, select MIDP. Under File Types, select Localization Support Class. Click Next.
   3. Accept the default values by clicking Finish. This creates the files LocalizationSupport.java and messages.properties.
2. Change the Internationalization String and Search formats.
   1. Choose Tools > Options and click the Advanced Options button.
   2. Select the Internationalization node in the Options menu tree.
   3. In the properties window:
      • Change the value of the II8N String Format property to LocalizationSupport.getMessage("{key}")
      • Change the value of the II8N Search Format property to (getString|getBundle|getMessage)[:space:]*\([:space:]*{hardString}|//NOI18N
3. Add localization keys and their values.
   1. Choose Tools > Internationalization > Internationalization Wizard. This opens the Internationalization wizard.
   2. Select the HelloMIDlet MIDlet as the source file to internationalize. Click Next.
   3. Select the messages.properties resource file as the file in which to store the values for the internationalized strings. Click Next.
   4. Modify the Value fields for each key identified for the HelloMIDlet MIDlet.
   5. After all the strings have been added to the messages.properties file, do the following to add values for each new locale:
      1. Right-click on the file node in the Projects view and choose Add Locale.
      2. Choose a locale you want to support from the Predefined Locales list box, or use the combo boxes at the top of the form to define a new locale.
      3. Expand the message.properties node in the Projects view, and double-click on the newly-added locale.
      4. Translate all properties into the appropriate language.
4. Add code to initialize localization.
   1. Enter the following string in your MIDlet wherever you want a key localized:
      LocalizationSupport.getMessage("Key");
      For example, LocalizationSupport.getMessage("LAB_NextButton");

The mobile application will use the microedition.locale attribute to determine which version of the messages.properties file should be used.