Building Android Apps : Installing KiloGap in the Emulator

Now it’s time to test our shiny new native Android app in the emulator.

1. If your emulator is not running, launch it by entering the following command in the Terminal application (this way, you can let it “warm up” while you’re building the Kilo package):

   emulator -avd mySim

   
   

   You should see the Android emulator window appear after a few seconds. Notice that the command prompt doesn’t return in the terminal window—it will sort of just sit there and hang until you close the emulator. We won’t be interacting with this window, so you can minimize it to get it out of the way.

2. Open a new terminal window and navigate into the KiloGap directory. In my case, the command to do so is:

   cd ~/Desktop/KiloGap

   
   

3. Enter the following command to compile your app with debugging enabled:

   ant debug

   
   

   If all goes well, you’ll see a stream of output with BUILD SUCCESSFUL at the end (Figure 1). A binary executable named Kilo-debug.apk will now be sitting in the ~/Desktop/KiloGap/bin directory (Figure 2).

   Figure 1. If the ant debug command finishes without errors, you’ll see BUILD SUCCESSFUL at the end of the output

   

   Figure 2. The ant debug command will create the Kilo-debug.apk binary in the KiloGap’s bin directory

   

4. Now that we have a binary, we can install it on the emulator. To do so, enter the following command:

   adb -e install -r ~/Desktop/KiloGap/bin/Kilo-debug.apk

   
   

   “adb” is short for Android Debug Bridge, which is a tool that is included in the Android SDK . The -e flag tells adb to install our binary package (i.e., ~/Desktop/KiloGap/bin/Kilo-debug.apk) on the first running emulator that it finds. The -r flag tells adb to replace the binary on the emulator if it has been installed previously. If you get a “device offline” error, go into the emulator and unlock it if it’s locked (for example, on Android 2.2, slide the green lock icon to the right), then try again.

Your app is now available on the emulator just like any other application (Figure 3). To play around with it, locate Kilo in the application launcher and tap it to launch the app. You’ll notice right away that there is a bit of cleanup to do. For example, there is an approximately 40px gap at the bottom of the window (Figure 4).

Figure 3. Your app is now available on the emulator, just like any other application

Figure 4. Your web app is now running as a native app on the Android Emulator

1. Using the Screen’s Full Height

This gap occurs because jQTouch does not realize we are running it outside of a normal web browser, so it’s allowing room for the browser’s toolbar. Fortunately, the fix is easy. Just open ~/Desktop/KiloGap/assets/www/kilo.js and add the following to the document ready function:

if (typeof(PhoneGap) != 'undefined') {
    $('body > *').css({minHeight: window.innerHeight + 'px !important'});
}

This code uses the typeof operator to make sure the PhoneGap object has been defined. If the code is running inside PhoneGap, this conditional will evaluate to true. If the code is launched as a web app, the PhoneGap object will be undefined and the conditional will evaluate to false.

When the app is launched with PhoneGap, the immediate children of the HTML body element will be given a minimum height that matches the height of the window’s content area (455px on emulator, 508px on the Nexus One). To make sure the declaration takes effect, add the !important directive to override any conflicting instructions elsewhere in the stylesheets. Now the app will completely fill the window when launched (Figure 5).

Figure 5. The body height has changed from 420px to 455px, so now the app takes up the whole screen

2. Customizing the App Icon

So far, our app is represented in the emulator using the default PhoneGap icon (a blue square with a ladder on it). To customize the look of the icon, we need to place our own image in a particular spot in the KiloGap project directory; actually, in three spots.

Navigate to ~/Desktop/KiloGap/res in the Finder and you’ll see three folders that begin with the prefix drawable: drawable-hdpi, drawable-ldpi, and drawable-mdpi. Because Android supports a wide range of devices with varying screen characteristics, these three folders were created to hold different resolution versions of your icon graphics. ldpi is for 100 to 140 dpi screens, mdpi is for 140 to 180 dpi screens, and hdpi is 190 to 250 dpi screens.

Perfecting the display of your home screen icon across all Android devices is a graphic design issue that falls outside the scope of this book. But don’t worry—for now just replace the default PhoneGap icon.png files with a 56-pixel square .png, and Android will do a really good job of rendering it appropriately on various devices. For the examples here, I’ll be using a chocolate frosted donut with jimmies on a pink background.

Once you have replaced the default icons, enter the following commands in the Terminal application to recompile and install the app:

cd ~/Desktop/KiloGap
ant debug
adb -d install -r bin/Kilo-debug.apk

When the process completes, you should see your new icon displayed in the launcher on the phone (Figure 6).

Figure 6. You can customize your app’s launcher icon by putting a .png file in each of the three drawable directories in your Android project