Adding A Splash Screen to Your PhoneGap App

First, I have to say that the reason I think it’s worth writing about this is because it took quite a bit of research to finally find information on how to do this.  So, if you happen to stumble upon this blog, hopefully this will help you.

Overview

To add a splash screen to your app, you need to do a few things:

• The image: obviously, you have to have an image to use for a splash screen and to place it in the /res folder of your project.
• The Java: Modify your main java file to specify loading a splash screen for x number of milliseconds
• The Unload: Optionally, modify your index.html file to unload the splash screen once the device is ready.

Details

The Image

My splash image is at “res/drawable-hdpi/splash.png” and apparently it must be all lowercase.  I haven’t tried the other resolutions or other image formats than PNG.   To test, I created mine as a PNG with dimensions of 320 x 480 pixels and it seems to work for phone displays.  I’ll update this once I test the other resolutions/formats.  Or, you can update me if you figure it out sooner.

The Java Modification

This goes in the main “.java” file of the application located in the “src” folder (e.g. “src/your/application/domain/splashscreentest.java“.  The function to modify is the onCreate().  Mine looks like this (lines 2 and 3 inside the function is where the changes take place):

@Override
public void onCreate(Bundle savedInstanceState) {
     super.onCreate(savedInstanceState);
     super.setIntegerProperty(“splashscreen”, R.drawable.splash);
     super.loadUrl(“file:///android_asset/www/index.html”, 30000);
}

Code dissection

• Line 2: This is setting a property specified in the first parameter (i.e. “splashscreen”).  The second parameter tells it where to pull the image from  (i.e. R.drawable.splash = res/drawable-anydpi/splash.png … anydpi refers to the different folders used to store the splash screen).
• Line 3: Loads the index.html file as it normally would, but only after the number of milliseconds specified in the second parameter.       In my example above, I’ve set to 30 seconds.  Yes, it’s overkill, but I wanted to avoid the issues with the emulator being so slow that the splash screen would not be up long enough to load the app.

Keep in mind that unless specified otherwise, the splash screen will remain loaded until the entire time period has elapsed.  See next section for solution.

The Unload of the Splash Screen

In newer versions of PhoneGap (I believe 1.8.0 and up), index.html loads on a separate thread, so there’s the possibility that the app is ready to go, but is prevented by the splash screen to do so.  To fix this, add a line to the top of the onDeviceReady() function in index.html to unload the splash screen and show index.html:

function onDeviceReady() {
     // alert(“Application Loaded”);
     navigator.splashscreen.hide();

     …
     …
     …
}

And that’s all.  At this point, your app should be displaying a splash screen!

Hello World!

After spending a couple of days setting up my development environment with Eclipse, PhoneGap (Cordova 2.0), and jQuery Mobile, I tackled my first application: “Hello World!”

Granted, I can only work on this for 1 or 2 hours at a time since this is my after-work self-improvement studies.  Still, I thought, a simple “Hello World!” shouldn’t take more than 1 hour, right? Wrong! I think one of the biggest contributors to the learning curve for me was learning a whole new world of terminology, including esoteric acronyms like:

AVD

It took me quite a while to even get to the point where I could deploy my app to AVD.  In fact, it even took me a while to figure out what AVD meant! What the heck is the AVD? Oh, yes, it’s the Android Virtual Device, in other words, this is the emulator in which you can run your applications for testing purposes … as long as you’re willing to wait and wait and wait for the AVD to launch.

JAR

If you’ve never played around with Java, the JAR is simply a thing you use to store things in, such as cookies, pickles, candy, etc.  Well, in Java it’s a bit similar, JAR (Java ARchive) files contain things like classes or executables that can be used by the Java run-time and so on http://en.wikipedia.org/wiki/JAR_(file_format)

ADT

ADT Plugin.  This is the Android Development Tools plugin for eclipse.  It makes your life easier … supposedly.

I’ll add more acronyms as they pop into my head.

Traveling through the Gap

The title is in reference to mobile application development using the PhoneGap framework (Cordova 2.0 is my starting point).  I started this learning experience about a week ago.  Sometimes the gap narrows to painful widths, sometimes it opens up and I see the light.  It’s been quite a ride, especially since I haven’t really been able to find comprehensive documentation.  I attribute that to two things: the framework is moving forward at breakneck speed and the project is very community driven and apparently not very organized in terms of disseminating the information.  All in all, it appears to be very promising and to have great potential, even if things are a bit of a mystery to me still.

I’ll try to keep this blog updated with issues I find and how I resolve them.