New Resources for Developers

We're back in action after a Thanksgiving break filled with turkey, stuffing, and pumpkin pie. Now it's the holiday season (at least, here in the U.S.) and we're filled with good will toward developers. Today I wanted to talk about a couple things we just finished polishing up.

First, the Android 1.0 SDK, release 2 is now available. Like the previous 1.0_r1 release, this new 1.0_r2 build creates applications that are compatible with Android 1.0 devices, such as the T-Mobile G1. This new release fixes a few bugs. In 1.0_r1, it was possible for developers to write technically-illegal code by using the Java Reflection APIs to access private or protected fields and methods. 1.0_r2 fixes that problem by enforcing private/protected visibility of items accessed via Reflection. Meanwhile, the class android.R.styleable was included in 1.0_r1 primarily for documentation purposes as a way for developers to look up the style attributes available to them to use. However, actually referring to that class via source code would result in applications that might break when run on future versions of the Android platform, so 1.0_r2 corrects the oversight and removes access to the class from the android.jar file. (The class remains in the documentation for reference purposes, though.)

Both of these problems are obscure "future-proofing" issues, and I'd be quite surprised if they actually caused problems for anyone, but now they're fixed. 1.0_r2 also includes a few other smaller changes; check out the release notes for all the details.

Second, many of you have asked if developer devices will be available. We've worked with our partners to create a program for developers to purchase devices that enable them to test and debug applications more easily.

I think these new tools will be quite helpful to developers, and I'm looking forward to seeing what people do with Android, next.

Touch Mode

Designing and developing user interfaces for Android is very different from doing so in a regular desktop environment. Because Android runs applications on mobile devices, application designers and developers must deal with numerous constraints that are not always obvious. To help you design and develop better applications, we are publishing a new series of posts focusing on Android user interfaces. In this series, we will give you design guides and tools, development tips, and explain the fundamental principles of the Android UI toolkit. The goal here is simple: we want to help you design and develop a great user experience. To start off this series, I'd like to introduce touch mode, one of the most important principles of the UI toolkit.

The touch mode is a state of the view hierarchy that depends solely on the user interaction with the phone. By itself, the touch mode is something very easy to understand as it simply indicates whether the last user interaction was performed with the touch screen. For example, if you are using a G1 phone, selecting a widget with the trackball will take you out of touch mode; however, if you touch a button on the screen with your finger, you will enter touch mode. When the user is not in touch mode, we talk about the trackball mode, navigation mode or keyboard navigation, so do not be surprised if you encounter these terms. Finally, there is only one API directly related to touch mode, View.isInTouchMode().

Sounds easy enough right? Oddly enough, touch mode is deceivingly simple and the consequences of entering touch mode are far greater than you might think. Let's look at some of the reasons why.

Touch Mode, Selection, and Focus

Designing a UI toolkit for mobile devices is difficult because of the various interaction mechanisms they provide. Some devices offer only 12 keys, some have a touch screen, some require a stylus, some have both a touch screen and a keyboard. In that regard, it is a great benefit for the Android development community that the first commercially available device, the G1, offers multiple forms of input using a touch screen, a trackball, and a keyboard. Because the user can interact with applications using three different mechanisms, we had to think very hard about all the possible issues that could arise. One issue led us to create the touch mode.

Imagine a simple application, ApiDemos for example, that shows a list of text items. The user can freely navigate through the list using the trackball and they can also scroll and fling the list using their finger. The issue in this scenario is the selection. If I select an item at the top of the list and then fling the list towards the bottom, what should happen to the selection? Should it remain on the item and scroll off the screen? In this case, what would happen if I then decide to move the selection with the trackball? Or worse, if I press the trackball to act upon the currently selected item, which is not shown on screen anymore. After careful considerations, we decided to remove the selection altogether.

In touch mode, there is no focus and no selection. Any selected item in a list of in a grid becomes unselected as soon as the user enters touch mode. Similarly, any focused widgets become unfocused when the user enters touch mode. The image below illustrates what happens when the user touches a list after selecting an item with the trackball.

To make things more natural for the user, the framework knows how to resurrect the selection/focus whenever the user leaves touch mode. For instance, in the example above, if the user were to use the trackball again, the selection would reappear on the previously-selected item. This is why some developers are confused when they create a custom view and start receiving key events only after moving the trackball once: their application is in touch mode, and they need to use the trackball to exit touch mode and resurrect the focus.

The relationship between touch mode, selection, and focus means you must not rely on selection and/or focus to exist in your application. A very common problem with new Android developers is to rely on ListView.getSelectedItemPosition(). In touch mode, this method will return INVALID_POSITION. You should instead use click listeners or the choice mode.

Focusable in Touch Mode

Now that you know focus doesn't exist in touch mode, I must explain that it's not entirely true. Focus can exist in touch mode but in a very special way we call focusable in touch mode. This special mode was created for widgets that receive text input, like EditText or, when filtering is enabled, ListView. This is why the user can type text inside a text field without first selecting it with the trackball or their finger. When a user touches the screen, the application will enter touch mode if it wasn't in touch mode already.  What happens during the transition to touch mode depends on what the user touched, and what currently has focus.  If the user touches a widget that is focusable in touch mode, that widget will receive focus.  Otherwise, any currently focused widget will not retain focus unless it is focusable in touch mode. For instance, in the picture below, when the user touches the screen, the input text field receives the focus.

Focusable in touch mode is a property that you can set yourself either from code or XML. However, it should be used sparingly and only in very specific situations as it breaks consistency with Android normal behavior. A game is a good example of an application that can make good use of the focusable in touch mode property. MapView, if used in fullscreen as in Google Maps, is another good example of where you can use focusable in touch mode correctly.

Below is another example of a focusable in touch mode widget. When the user taps an AutoCompleteTextView's suggestion with his finger, the focus remains on the input text field:

New Android developers often think that focusable in touch mode is the solution they need to "fix" the problem of disappearing selection/focus. We really encourage you to think very hard before using it. If used incorrectly, it can make your application behave differently from the rest of the system and simply throw off the user's habits. The Android framework contains all the tools you need to handle user interactions without using "focusable in touch mode". For example, instead of trying to make ListView always keep its selection, simply use the appropriate choice mode. And if you feel that the framework does not suit all your need, feel free to let us know or contribute a patch.

Touch Mode Cheat Sheet

Do:

• Remain consistent with the core applications
• Use the appropriate feature if you need persistent selection (radio button, check box, ListView's choice mode, etc.)
• Use focusable in touch mode if you write a game

Don't:

• Do not try to keep the focus or selection in touch mode

Behind the apps: Amazed

This week's developer video features Jason Tomlinson of Hands-On Mobile. He wrote Amazed, an application open sourced in the apps-for-android project. Things Jason mentions in the videos include:

• Amazed was built primarily to get familiar with the accelerometer. This helped him in his work on Guitar Hero® World Tour Mobile for Android.
• Using traceview to track down which methods take the most CPU cycles.

This and other Android developer videos can be found here.

Behind the apps: Amazon and imeem

Last week we introduced a couple Android developers who shared how they built their Android apps and gave their insight into Android app development. This week, we have videos of two developers who've built music-related apps.

The first is of Allan Hsu—he wrote imeem's Android app. A couple of things he mentions in his videos:

• Using SQLite databases and regular expressions
• Completing the app, including rewriting many of their Activities and web service API calls, in just 6 weeks.

The second video features Casey Langen—he wrote the Amazon MP3 for Android app. Things he mentions in the videos include:

• Using Apache HTTPClient to download data from their servers. Also used ListView in all activities and the MediaPlayer for song previews.
• Developers new to Android should get familiar with ViewGroups and how they're implemented.

Check out other Android developer videos here: Android App Developers.

The stories behind the apps

As we mentioned yesterday, the Android Market is now open for developers to upload their applications. I'm pretty excited because Market, along with the availability of the first Android-powered phone and the Android 1.0 SDK, puts the basic pieces of the Android platform into place for developers to create and distribute their apps.

To help developers better understand what's available to them, we've collected stories from some Android application developers. In the videos, you'll hear them talk about how they built their apps, their takes on the Android platform, and also some tips they want to share with other developers. I think they have a lot of insight to share about Android application development, so I hope you'll find these videos useful.

Here are the first two developers in this series:

Jeff Sharkey is an ADC finalist—he built CompareEverywhere.

Jacob Abrams is from Glu Mobile and helped to build their first Android app, Bonsai Blast.

Keep an eye on this blog, our YouTube channel, or the playlist for this series for more of these videos in the coming weeks.

Android Market: Now available for users

Last month I outlined some details around Android Market. Today, Android Market launched for users to download applications along with the first Android-powered phone—the T-Mobile G1.

With Android Market, users can easily download apps to their Android-powered phone. Users can also rate the apps they've downloaded and leave comments. These users' ratings along with anonymous usage statistics help determine how apps are ranked and presented within Android Market.

If you're a developer, you will be able to register and upload your applications starting next Monday, 2008-10-27, when we've wrapped up a few final details. In order to make sure that each developer is authenticated and responsible for their apps, you will need to register and pay a one time $25 application fee. Once registered, your apps can be made available to users without further validation or approval.

Starting in early Q1, developers will also be able to distribute paid apps in addition to free apps. Developers will get 70% of the revenue from each purchase; the remaining amount goes to carriers and billing settlement fees—Google does not take a percentage. We believe this revenue model creates a fair and positive experience for users, developers, and carriers.

There are already over 50 apps available in Android Market today. You can view a showcase of some of these apps—which include multimedia, location-based tools, barcode scanners, travel guides and games—at http://www.android.com/market/. Now that Android Market is live and ready for contributions, we hope to see developers adding their own compelling apps starting next week.

In the coming months, we'll continue to roll out additional tools and enhancements to Android Market. We also expect to see additional Android-powered devices rolling out by different carriers around the world. Starting today, you can get a device, test your apps on it, and get them ready for upload. On Monday, to share your app with the world, simply register, upload your application and publish it. It's really that easy. I look forward to seeing what you bring to the Market.

Update: As of Monday morning (2008-10-27), http://market.android.com/publish is now available for developers to publish their apps on Android Market.

New Android Maps API Terms of Service and Key Enforcement

When we released the 0.9_r1 beta SDK, we mentioned that the Maps API included with Android would soon require an API key to function correctly and load map tiles. Part of the reason for this was that the Terms of Service (ToS) for the Maps API had not been finalized.

Today, I'm pleased to be able to tell you that the new Android Maps API ToS are now finalized and they're actually pretty exciting. Most of the restrictions present in the old ToS are now gone—for instance, it's now permissible to use the Android Maps API to build "friend finder" style applications. There are still a few limitations, but not nearly as many as before.

Now that the ToS are finalized, it's time to take the next step. Until now, developers have been able to use any value for their Maps API key—that is, the Maps API keys weren't enforced. However, starting early tomorrow morning (Oct 22nd, PDT), we are turning on Maps key enforcement, so the grace period is ending very soon. This means it's also time for developers to acquire and begin using real API keys. Here's what you'll need to do:

1. Visit http://code.google.com/android/maps-api-signup.html, fill out the required information, agree to the Terms of Service, and submit.
2. Take the key you are given in response, and place it either:
• In the XML layout where you declare your MapView, or
• In your source code, where you instantiate your MapView object

The way the keys work is that when you use a MapView, it queries the system to find the public fingerprint ID of the certificate used to
sign the currently-running application. The MapView then works with the server to verify that the certificate which signed the current application is the same certificate to which the current Maps API key belongs. If they match, then tiles are displayed; if they do not match, then no map tiles are displayed.

You will need one Maps API key for each certificate you use to sign your applications. That is, you'll need separate Maps API keys for both your debug-time signing certificate used in the emulator, and for your release-time certificate you'll use when publishing your apps. Fortunately this is free, and there is no limit to the number of keys you can acquire. Finally, note that this only applies if you're using a MapView in your
Android application. If you don't use Maps at all, or if you use an Intentto launch Google Maps, you don't need to follow these steps.

Be sure to get your Maps API key now to avoid a disruption.