Discover application building for Palm Pre - Part 1

This is part 1 in a multipart series on coding an application for the Palm Pre. I'll start with an application that is fairly simple - a map application then expand it with a graphics overlay to display a compass heading using the canvas element. Finally, I'll add some details to flesh it out. If you are just starting out, you might want to review Palm Pre - First Pass in Debugging.

This is a pretty basic app but we'll dig deeper as the series continues. I'll probably tie in some backend work so we can store data on the device and on the web but for now I'll keep it simple. Not everything went smoothly. The Pre is being improved just like any other brand new product so expect a bit of frustration when things aren't working they way you think. I certainly spun my wheels a bit with some fairly simple problems such as my canvas not rotating without smudging. I'll get to that in a bit.

I could have used Google maps as the API but Yahoo has few restrictions and I can use it with a general application. So the first thing to do is get your Yahoo MAP API key. This is pretty easy and you can do 50,000 queries per day with it. You can get your key here.

Next, we generate an application. At this point, you ahould have already installed all the Palm development tools such as the SDK and Eclipse. To generate an application, go to File->New->Project. Select 'Mojo Application'. You should get a screen like this:

Fill out the information, nothing is all that important. I used TestApp for the name but you can use anything. The rest of the information you can just leave or change as you see fit.

Once the project has been created, we need the first scene. In Palm-speak, this is simply a single screen. The project creates a directory structure as follows:

workspace/TestApp/app/assistants
workspace/TestApp/app/views
workspace/TestApp/app/stylesheets
workspace/TestApp/app/images


Most of the directories are self-explanatory but assistants and views warrant some comments. A view is a scene's html structure. It uses the CSS in stylesheets. If you look at the 'stylematters' sample application, you'll see how CSS can be loaded within the application. Otherwise, just store what you need in a single .css template under stylesheets and include it in the index.html. As anything, if the application is complex with lots of screens then having small, fast .css files to load instead of one big one might be an advantage but generally this won't be required.

Assistants contain the javascript to implement a scene. The first scene for the application is called by the stage_controller. This is also stored in the assistants directory. Usually each scene is in its own subdirectory. I hate the number of directories and how everything spread out but Eclipse does make it easier to get to it. Unfortunately, I pretty much stay in dos and use vi with some batch files that use the command line operations and only use Eclipse occasionally.. In case someone is interested, there are a number of links at the bottom of this blog to download them.

Scenes are created through Eclipse or by using the command line tool, palm-generate. The tool sets up the basic structure and adds appropriate info in the sources.json file. For Eclipse, simply click on the phone-looking icon and select New Mojo Scene or use the menu File->Open other->Mojo scene. The command line would look like 'palm-generate -t new_scene -p "name=compass" compass. Now go ahead and launch the Palm Emulator. Sometimes there are problems if Eclipse is already running so close it and run the Emulator first if you do have problems. Run the application and if all went well, you should see this. In this example, I used the name compass so the .js file will be named compass-assistant.js and the view will be named compass-scene.html.

Now we can integrate the application code. The stage controller sets up the first scene so simply adding a call to pushScene('compass') will kick off the program. The rest of the program will be stored in compass-assistant.js. The html code under app/view/testapp/compass-scene.html is pretty simple.

<div id="main">
<canvas id="canvas" class="CompassPtr" height=100> </canvas>
</div>
<div id="map" width=320 height=450></div>

Basically, there is just one view with a canvas used for the future compass pointer. The .css file should have one entry for the compass pointer.

.CompassPtr {
   position:fixed;
   background:transparent;
   left:225px ;
   top:25px;
   width:50px;
   height:50px;
   z-index:5;
}

A map wouldn't be very interesting if we didn't leverage some of the services that the Pre provides. An obvious one is the GPS service. So here I'll setup the service, put a marker where we are, and pan as we move.

// Setup listener for gps events
this.trackingHandle = this.controller.serviceRequest("palm://com.palm.location",
{ method: "startTracking",
  parameters: {subscribe: true},
  onSuccess: this.trackingSuccess.bind(this),
  onFailure: this.trackingFailure.bind(this)
});

This is basically requesting that every second the trackingSuccess should be called with our current location information. When the first location is generated, that's when the marker is setup.

if (this.firstTrack) {
   this.myloc = new YMarker(pt);
   this.mapCtrl.drawZoomAndCenter(pt, 3);
   this.mapCtrl.addOverlay(this.myloc);
   this.firstTrack = false;
}
First, the marker is created, then take our first location point and display it, and finally add the marker to the map. This is almost done. Each time our location updates, we need to update the map. Redrawing the map is expensive so there is another good function to allow panning.

this.myloc.setYGeoPoint(pt);
this.mapCtrl.panToLatLon(pt);

This changes the marker position then scrolls the map. The map won't pan unless it moves significantly. You can get the project files here. Good luck! Up next will be adding the compass information and more.

Project Files: TestApp.zip
dbg.bat - stick in app/assistants to use command line.

The Software Rogue - http://thesoftwarerogue.blogspot.com