Each Android project includes a manifest file, AndroidManifest.xml, stored in the root of the project hierarchy. The manifest lets you define the structure and metadata of your application, its components, and its requirements.
It includes nodes for each of the components (Activities, Services, Content Providers, and Broadcast Receivers) that make up your application and, using Intent Filters and Permissions, determines how they interact with each other and with other applications.
The manifest also offers attributes to specify application metadata (like its icon or theme), and additional top level nodes can be used for security settings, unit tests, and defining hardware and platform support requirements, as described below.
The manifest is made up of a root <manifest> tag with a package attribute set to the project’s package. It usually includes an xmlns:android attribute that supplies several system attributes used within the file.
Use the versionCode attribute to define the current application version as an integer. This value is used internally to compare application versions. Use the versionName attribute to specify a public version number that is displayed to users.
A typical manifest node is shown in the following XML snippet:
[ … manifest nodes … ]
The <manifest> tag includes nodes that define the application components, security settings, test classes,
and requirements that make up your application. The following list gives a summary of the available
<manifest> node tags, and an XML snippet demonstrating how each one is used:
➤ uses-sdk This node lets you define a minimum, maximum, and target SDK version that must beavailable on a device in order for your application to function properly. Using a combination of minSDKVersion, maxSDKVersion, and targetSDKVersion attributes you can restrict which devices your application can run on, based on the SDK version supported by the installed platform.
The minimum SDK version specifies the lowest version of the SDK that includes the APIs you have used in your application. If you fail to specify a minimum version one will be assumed and your application will crash if it attempts to access APIs that aren’t available on the host device.
The maximum SDK version lets you define an upper limit you are willing to support. Your application will not be visible on the Market for devices running a higher platform release. It’s good practice not to set the maximum SDK value unless you know your application will definitely not work on newer platform releases.
The target SDK version attribute lets you specify the platform against which you did your development and testing. Setting a target SDK version tells the system that there is no need to apply any forward- or backward- compatibility changes to support that particular version.
The supported SDK version is not equivalent to the platform version and cannot be derived from it. For example, Android platform release 2.0 supports the SDK version 5. To find the correct SDK version for each platform use the table at
➤ uses-configuration Use uses-configuration nodes to specify each combination of input mechanisms supported by your application. You can specify any combination of input devices that include:
➤ reqFiveWayNav Specify true for this attribute if you require an input device capable of navigating up, down, left, and right and of clicking the current selection. This includes both trackballs and D-pads.
➤ reqHardKeyboard If your application requires a hardware keyboard specify true.
➤ reqKeyboardType Lets you specify the keyboard type as one of nokeys, qwerty, twelvekey, or undefined.
➤ reqNavigation Specify the attribute value as one of nonav, dpad, trackball, wheel, or undefined as a required navigation device.
Introducing the Application Manifest ❘ 53
➤ reqTouchScreen Select one of notouch, stylus, finger, or undefined to specify the required touchscreen input.
You can specify multiple supported configurations, for example a device with a finger touchscreen, a trackball, and either a QUERTY or twelve-key hardware keyboard, as shown here:
When specifying required configurations be aware that your application won’t be installed on any device that does not have one of the combinations specified. In the above example a device with a QWERTY keyboard and a D-pad (but no touchscreen or trackball) would not be supported. Ideally you should develop your application to ensure it works with any input configuration, in which case no uses-configuration node is required.
➤ uses-feature One of the advantages of Android is the wide variety of hardware platforms it runs on. Use multiple uses-feature nodes to specify each of the hardware features your application requires. This will prevent your application from being installed on a device that does not include a required hardware feature. You can require support for any hardware that is optional on a compatible device. Currently optional hardware features include
➤ android.hardware.camera For applications that require camera hardware.
➤ android.hardware.camera.autofocus If you require an autofocus camera.
As the variety of platforms on which Android is available increases, so too will the optional hardware. A full list of uses-feature hardware can be found here. You can also use the uses-feature node to specify the minimum version of OpenGL required by your application. Use the glEsVersion attribute, specifying the OpenGL ES version as an integer. The higher 16 bits represent the major number and the lower 16 bits represent the minor number.
<uses-feature android:glEsVersion=” 0x00010001″
➤ supports-screens After the initial round of HVGA hardware, 2009 saw the introduction of WVGA and QVGA screens to the Android device menagerie. With future Android devices likely to feature devices with larger screens, the supports-screen node lets you specify the screen sizes your application can, and can’t, support.
Exact dimensions will vary depending on hardware, but in general the supported screen sizes match resolutions as follows:
➤ smallScreens Screens with a resolution smaller than traditional HVGA—typically QVGA screens.
➤ normalScreens Used to specify typical mobile phone screens of at least HVGA, including WVGA andWQVGA.
➤ largeScreens Screens larger than normal. In this instance a large screen is considered to be significantly larger than a mobile phone display.
➤ anyDensity Set to true if your application can be scaled to accommodate any screen resolution.
As of SDK 1.6 (API level 4), the default value for each attribute is true. Use this node to specify screen sizes you do not support.
Where possible you should optimize your application for different screen resolutions and densities using the resources folder, as shown later in this chapter. If you specify a supports-screen node that excludes certain screen sizes, your application will not be available to be installed on devices with unsupported screens.
➤ application A manifest can contain only one application node. It uses attributes to specify the metadata for your application (including its title, icon, and theme). During development you should include a debuggable attribute set to true to enable debugging—though you may wish to disable this on your release builds.
The <application> node also acts as a container that includes the Activity, Service, Content Provider, and Broadcast Receiver tags used to specify the application components. You can also define your own implementation of the Application class. Later in this chapter you’ll learn how to create and use your own
Application class extension to manage application state.
[ … application nodes … ]
➤ activity An <activity> tag is required for every Activity displayed by your application. Using the android:name attribute to specify the Activity class name.
You must include the main launch Activity and any other screen or dialog that can be displayed. Trying to start an Activity that’s not defined in the manifest will throw a runtime exception. Each Activity node supports <intent-filter> child tags that specify which Intents launch the Activity.
<activity android:name=”.MyActivity” android:label=”@string/app_name”>
<action android:name=”android.intent.action.MAIN” />
<category android:name=”android.intent.category.LAUNCHER” />
➤ service As with the activity tag, create a new service tag for each Service class used in your application. Service tags also support <intent-filter> child tags to allow late runtime binding.
<service android:enabled=”true” android:name=”.MyService”></service>
➤ provider Provider tags specify each of your application’s Content Providers. Content Providers are used to manage database access and sharing within and between applications.
➤ receiver By adding a receiver tag, you can register a Broadcast Receiver without having to launch your application first. Broadcast Receivers are like global event listeners that, once registered, will execute whenever a matching Intent is broadcast by the system or an application. By registering a Broadcast Receiver in the manifest you can make this process entirely autonomous. If a matching Intent is
broadcast, your application will be started automatically and the registered Broadcast Receiver will be run.
android:label=”My Intent Receiver”
➤ uses-permission As part of the security model, uses-permission tags declare the permissions you’ve determined your application needs to operate properly. The permissions you include will be presented to the user before installation commences. Permissions are required for many of the native Android services, particularly those with a cost or security implication (such as dialing, receiving SMS, or using the location-based services).
➤ permission Third-party applications can also specify permissions before providing access to shared application components. Before you can restrict access to an application component, you need to define a permission in the manifest. Use the permission tag to create a permission definition.
Application components can then require permissions by adding the android:permission attribute. Other applications will then need to include a uses-permission tag in their manifests to use these protected components.
Within the permission tag, you can specify the level of access the permission will permit (normal, dangerous, signature, signatureOrSystem), a label, and an external resource containing the description that explains the risks of granting the specified permission.
➤ instrumentation Instrumentation classes provide a test framework for your application components at run time. They provide hooks to monitor your application and its interaction with the system resources.
Create a new node for each of the test classes you’ve created for your application.
<instrumentation android:label=”My Test”
The ADT New Project Wizard automatically creates a new manifest file when it creates a new project.
USING THE MANIFEST EDITOR
The ADT plug-in includes a visual Manifest Editor so you don’t have to manipulate the underlying XML directly.
To use the Manifest Editor in Eclipse, right-click the AndroidManifest.xml file in your project folder and
select Open With . . . ➪ Android Manifest Editor. This presents the Android Manifest Overview
screen, as shown in Figure 3-1. This screen gives you a high-level view of your application structure, enabling you to set your application version information and root level manifest nodes, including <uses-sdk> and <uses-features>, as described previously in this chapter. It also provides shortcut links to the Application, Permissions, Instrumentation, and raw XML screens. Each of the next three tabs
contains a visual interface for managing the application, security, and instrumentation (testing) settings, while the last tag (using the manifest’s file name) gives access to the raw XML. Of particular interest is the Application tab, shown in Figure 3-2. Use it to manage the
application node and the application component hierarchy, where you specify the application components. You can specify an application’s attributes — including its icon, label, and theme — in the Application Attributes panel. The Application Nodes tree beneath it lets you manage the application components, including their attributes and any associated Intent Filter subnodes.
THE ANDROID APPLICATION LIFE CYCLE
Unlike most traditional environments, Android applications have limited control over their own life cycles. Instead, application components must listen for changes in the application state and react accordingly, taking particular care to be prepared for untimely termination.
By default, each Android application runs in its own process, each of which is running a separate instance of Dalvik. Memory and process management is handled exclusively by the run time. While it’s uncommon, it’s possible to force application components within the same application to run in different processes or to have multiple applications share the same process using the android:process attribute on the affected component nodes within the manifest.
Android aggressively manages its resources, doing whatever it takes to ensure that the device remains responsive. This means that processes (and their hosted applications) will be killed, without warning in some cases, to free resources for higher-priority applications — generally those interacting directly with the user at the time. The prioritization process is discussed in the next section.