Visual Mobile Designer Custom Components: PIM Browser

Contributed by Karol Harezlak

The Visual Mobile Designer (VMD) is a graphical interface within NetBeans Mobility that enables you to design mobile applications using drag and drop components. The VMD allows you to define the application flow and design your GUI using the components supplied by the IDE or components you design yourself. The VMD contains many standard User Interface (UI) components that you can use to create applications such as Lists, Alerts, Forms and Images. It also includes custom components that simplify the creation of more complex features, such as Wait Screens, Splash Screens, Table Items and more.

The PIM Browser is a custom component that provides easy access to standard mobile devices functions like calendar, address book or task list. You can use the PIM Browser component to enable mobile Java applications to access locally stored personal information databases. This component utilizes The PIM (Personal Information Management) API which is a part of the JSR-75 specification's PDA Optional Packages for the Java ME Platform. Because JSR-75 is not a part of the MIDP 2.0 specification, it is by definition a custom component and can only be used with JSR-75 enabled devices.

Application Overview

This example shows you how to use the PIM Browser component in a mobile application for JSR-75 capable devices. It demonstrates the basic features of the the component such as browsing the content of a device's contact database, Calendar or To Do List. In addition to the PIM Browser, we also need to use three other components: Splash Screen, TextBox and Alert.

Software Requirements

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

• NetBeans IDE 6.0 or 6.1 Mobility edition (download)
• Java Standard Development Kit (JDK) version 5.0 or 6.0 (download)

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

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 PIMBrowserExample application:

1. Download pimbrowserexample.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 Navigator 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 a Splash Screen component then PIM Browser, as shown:
   
7. Contact's details
   
   

• Move the cursor up and down to navigate through available positions.
• Click the button underneath "Back" to come back to the contact's list.
• Click the button underneath "Exit" to close the application.

Creating an application with the PIM Browser Custom Component

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

1. Create the PIMBrowserExample project
2. Add packages and a visual MIDlet to the PIMBrowserExample project
3. Add components to the PIMBrowserExample
4. Add Commands to the PIM Browser Components
5. Connect the Components to create an application flow
6. Adding contacts to the Wireless Toolkit Contact Database
7. Run the Project

Creating the PIMBrowserExample Project

1. Choose File > New Project (Ctrl-Shift-N). Under Categories, select Mobile. Under Projects, select MIDP Application and click Next.
2. Enter PIMBrowserExample in the Project Name field. Change the Project Location to a directory on your system. From now on let's refer to this directory as $PROJECTHOME.
3. Uncheck the Create Hello MIDlet checkbox. Click Next.
4. Leave the Java ME 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 PIMBrowserExample Project

1. Choose the PIMBrowserExample 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 pimbrowserexample in the Package Name field. Click Finish.
3. Choose the pimbrowserexample 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 PIMBrowserExample into MIDlet Name and MIDP Class Name fields. Click Finish.

Adding Components to the PIMBrowserExample

1. Switch your Visual MIDlet to the Flow Designer window. Drag the following components from the Component Palette and drop them in the Flow Designer:
• Splash Screen
• Alert
• IM Browser
2. Click on splashScreen and, in the Properties Window, change value of property Text from "null" to the "PIM Browser Example"
3. Click on alert component and, in the Properties Window, change value of property String to the "Contact selected"

Adding Commands to the PIMBrowserExample

1. Open the Flow Designer Window.
2. Choose Exit Command from the Commands section of the Component Palette. Drag and drop it into Flow Designer Window (pimBrowser component).

Connecting Components

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

Adding contacts to the Wireless Toolkit Contact Database

 

Copy the sample contact to the WTK folder $WTKHOME/appdb/DefaultColorPhone/pim/contacts/Contacts/. This folder is empty on "default", so it's necessary to copy at least one file(contact) to test PIM Browser example.

More information about WTK Persistent Storage is available at Sun Java Wireless Toolkit for CLDC User's Guide (section: 4.3.2.1 Persistent Storage) Using the Emulator

Running the Project

1. Press <F6> to Run the main project or select Run > Run Main Project.

To Learn More about the PIM Browser Component

The NetBeans IDE provides API Javadocs for the PIM Browser component, as well as other components you can use in the VMD. To read the Javadocs for the PIM Browser component do the following:

1. Choose Help > Javadoc References > org.netbeans.microediton.lcdui.pda The file is opened in a web browser.
2. Click org.netbeans.microedition.lcdui.pda to see links for the component information.

Related Tutorials

• Visual Mobile Designer Custom Components: SMS Composer
• Visual Mobile Designer Custom Components: File Browser
• Visual Mobile Designer Custom Components: Login Screen