All applications written for Android 1.5 or earlier, by default, support only the baseline HVGA screen used on the T-Mobile G1 and similar devices, which is normal screen size and medium density (mdpi). Android 1.6 introduced support for different screen configurations and added APIs that allow applications to control how they operate on different screens, using alternative resources for different screen configurations.
If your manifest file includes the
<uses-sdk> element, with the
android:minSdkVersion attribute set to
"3" or lower, and does not include the
android:targetSdkVersion set to
"4" or higher, then this document is for you. By default, an application written for Android 1.5 or below that does not set the
android:targetSdkVersion set to
"4" or higher runs in compatibility mode when on a device with a screen larger than the normal screen size (basically, the system displays the application in a small window that is roughly the size of the normal screen size).
This document describes how to get your application out of compatibility mode and instead support multiple screens, but also maintain compatibility with Android 1.5 and below.
Note: Before you begin, you should first decide whether it's even necessary to support Android 1.5. To see the relative number of devices that are still running Android 1.5, see the Platform Versions Dashboard.
If you have already developed and published an Android application based on Android 1.5 or earlier platform version, and want to maintain compatibility with Android 1.5, you need to make some changes to your application in order for it to properly run on newer devices with different screen configurations. You should be able to make these changes to your application such that you can distribute a single
.apk to all devices.
The recommended strategy is to develop your application against Android 1.6 (because it's the lowest version that includes support for multiple screens) and test your application on each platform version your application supports (especially the minimum platform, such as Android 1.5). Here's how to do that:
android:minSdkVersionattribute as it is. You do not need to increment the value of the attribute to support new devices and multiple screens.
<uses-sdk>element. Set the value of
"4". This allows your application to "inherit" the platform's multiple screens support, even though it is technically using an earlier version of the API.
Adding this attribute will cause an error in the compiler, because the attribute is unknown to Android 1.5. You'll fix this next.
Your application is now prepared to run on multiple screens, while maintaining support for Android 1.5 or lower.
Here's how you should begin testing your application:
android:minSdkVersion. You need AVDs running the older platforms you are targeting, so that you can ensure there are no functional regressions.
android:minSdkVersion. If you are in doubt, refer to SDK reference documentation and look for the API Level specifier for the API you want to use. Using newer APIs not supported by your minimum version will mean that your application will no longer be compatible with devices running on that version.
In particular, remember to test your application on an AVD that emulates a small-screen device. Users of devices with QVGA resolution at low density may want to download your application, so you should understand how your application will look and function on a small-screen device. In some cases, the reduced screen area and density mean that you need to make tradeoffs in design on those devices.
Also give extra attention to testing your application on an AVD that emulates an xlarge screen. Devices with extra large screens are tablet-sized or larger, so you should pay close attention to how usable your application is on such screens. You might want to design new layouts specifically for extra large screens, to address usability aspects such as the location and size of buttons in your UI. To test your application on an extra large screen, create an AVD targeted to Android 3.0 and use the WXGA emulator skin.
Once you've completed the procedures above, you should follow the recommendations in Supporting Multiple Screens to add complete support for different screen configurations.
To allow applications to run on larger screens without stretching the UI, Android provides a compatibility mode that draws an application's UI in a "postage stamp" window when on larger screens. That is, the system displays the application at the baseline size (normal) and density (mdpi), with a black border that fills the rest of the screen.
Compatibility mode exists primarily to support application's developed for Android 1.5 (or lower) when running on larger screens, because multiple screen support was not added until Android 1.6, older applications were not designed to support different screen configurations.
As such, if you've set your
"3" or lower and have not set the
"4" or higher, then compatibility mode is enabled and the system will not scale your application, because your application implicitly declares that it only supports the baseline screen configuration (normal screen size and medium density).
You can also affect whether compatibility mode is enabled by using the
<supports-screens> element (you can enable it by setting
android:resizeable or specific screen sizes to
"false"). However, you should not explicitly enable compatibility mode for your application, but should instead apply the necessary techniques to supporting multiple screens and allow your application to properly fit the screen on all screen sizes.