Docstoc

android

Document Sample
android Powered By Docstoc
					What is Android? | Android Developers                                                                          29.04.09 0:33




What is Android?

Android is a software stack for mobile devices that includes an operating system, middleware and key applications.
The Android SDK provides the tools and APIs necessary to begin developing applications on the Android platform
using the Java programming language.



Features
     Application framework enabling reuse and replacement of components
     Dalvik virtual machine optimized for mobile devices
     Integrated browser based on the open source WebKit engine
     Optimized graphics powered by a custom 2D graphics library; 3D graphics based on the OpenGL ES 1.0
     specification (hardware acceleration optional)
     SQLite for structured data storage
     Media support for common audio, video, and still image formats (MPEG4, H.264, MP3, AAC, AMR, JPG, PNG,
     GIF)
     GSM Telephony (hardware dependent)
     Bluetooth, EDGE, 3G, and WiFi (hardware dependent)
     Camera, GPS, compass, and accelerometer (hardware dependent)
     Rich development environment including a device emulator, tools for debugging, memory and performance
     profiling, and a plugin for the Eclipse IDE




Android Architecture
The following diagram shows the major components of the Android operating system. Each section is described in
more detail below.




http://developer.android.com/guide/basics/what-is-android.html                                                       Page 1 of 3
What is Android? | Android Developers                                                                                   29.04.09 0:33




Applications
Android will ship with a set of core applications including an email client, SMS program, calendar, maps, browser,
contacts, and others. All applications are written using the Java programming language.



Application Framework
Developers have full access to the same framework APIs used by the core applications. The application architecture is
designed to simplify the reuse of components; any application can publish its capabilities and any other application
may then make use of those capabilities (subject to security constraints enforced by the framework). This same
mechanism allows components to be replaced by the user.

Underlying all applications is a set of services and systems, including:

     A rich and extensible set of Views that can be used to build an application, including lists, grids, text boxes,
     buttons, and even an embeddable web browser
     Content Providers that enable applications to access data from other applications (such as Contacts), or to share
     their own data
     A Resource Manager, providing access to non-code resources such as localized strings, graphics, and layout files
     A Notification Manager that enables all applications to display custom alerts in the status bar


http://developer.android.com/guide/basics/what-is-android.html                                                            Page 2 of 3
What is Android? | Android Developers                                                                                     29.04.09 0:33


     An Activity Manager that manages the lifecycle of applications and provides a common navigation backstack

For more details and a walkthrough of an application, see the Notepad Tutorial.



Libraries
Android includes a set of C/C++ libraries used by various components of the Android system. These capabilities are
exposed to developers through the Android application framework. Some of the core libraries are listed below:

     System C library - a BSD-derived implementation of the standard C system library (libc), tuned for embedded
     Linux-based devices
     Media Libraries - based on PacketVideo's OpenCORE; the libraries support playback and recording of many
     popular audio and video formats, as well as static image files, including MPEG4, H.264, MP3, AAC, AMR, JPG,
     and PNG
     Surface Manager - manages access to the display subsystem and seamlessly composites 2D and 3D graphic
     layers from multiple applications
     LibWebCore - a modern web browser engine which powers both the Android browser and an embeddable web
     view
     SGL - the underlying 2D graphics engine
     3D libraries - an implementation based on OpenGL ES 1.0 APIs; the libraries use either hardware 3D
     acceleration (where available) or the included, highly optimized 3D software rasterizer
     FreeType - bitmap and vector font rendering
     SQLite - a powerful and lightweight relational database engine available to all applications




Android Runtime
Android includes a set of core libraries that provides most of the functionality available in the core libraries of the Java
programming language.

Every Android application runs in its own process, with its own instance of the Dalvik virtual machine. Dalvik has been
written so that a device can run multiple VMs efficiently. The Dalvik VM executes files in the Dalvik Executable (.dex)
format which is optimized for minimal memory footprint. The VM is register-based, and runs classes compiled by a
Java language compiler that have been transformed into the .dex format by the included "dx" tool.

The Dalvik VM relies on the Linux kernel for underlying functionality such as threading and low-level memory
management.



Linux Kernel
Android relies on Linux version 2.6 for core system services such as security, memory management, process
management, network stack, and driver model. The kernel also acts as an abstraction layer between the hardware and
the rest of the software stack.

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/basics/what-is-android.html                                                              Page 3 of 3
Application Fundamentals | Android Developers                                                                      29.04.09 0:33




Application Fundamentals

Android applications are written in the Java programming language. The compiled Java code — along with any data
and resource files required by the application — is bundled by the aapt tool into an Android package, an archive file
marked by an .apk suffix. This file is the vehicle for distributing the application and installing it on mobile devices; it's
the file users download to their devices. All the code in a single .apk file is considered to be one application.

In many ways, each Android application lives in its own world:

     By default, every application runs in its own Linux process. Android starts the process when any of the
     application's code needs to be executed, and shuts down the process when it's no longer needed and system
     resources are required by other applications.
     Each process has its own Java virtual machine (VM), so application code runs in isolation from the code of all
     other applications.
     By default, each application is assigned a unique Linux user ID. Permissions are set so that the application's files
     are visible only that user, only to the application itself — although there are ways to export them to other
     applications as well.

It's possible to arrange for two applications to share the same user ID, in which case they will be able to see each
other's files. To conserve system resources, applications with the same ID can also arrange to run in the same Linux
process, sharing the same VM.



Application Components
A central feature of Android is that one application can make use of elements of other applications (provided those
applications permit it). For example, if your application needs to display a scrolling list of images and another
application has developed a suitable scroller and made it available to others, you can call upon that scroller to do the
work, rather than develop your own. Your application doesn't incorporate the code of the other application or link to it.
Rather, it simply starts up that piece of the other application when the need arises.

For this to work, the system must be able to start an application process when any part of it is needed, and instantiate
the Java objects for that part. Therefore, unlike applications on most other systems, Android applications don't have a
single entry point for everything in the application (no main() function, for example). Rather, they have essential
components that the system can instantiate and run as needed. There are four types of components:

Activities
    An activity presents a visual user interface for one focused endeavor the user can undertake. For example, an
    activity might present a list of menu items users can choose from or it might display photographs along with their
    captions. A text messaging application might have one activity that shows a list of contacts to send messages to,
    a second activity to write the message to the chosen contact, and other activities to review old messages or
    change settings. Though they work together to form a cohesive user interface, each activity is independent of the
    others. Each one is implemented as a subclass of the Activity base class.

     An application might consist of just one activity or, like the text messaging application just mentioned, it may
     contain several. What the activities are, and how many there are depends, of course, on the application and its
     design. Typically, one of the activities is marked as the first one that should be presented to the user when the
     application is launched. Moving from one activity to another is accomplished by having the current activity start the
     next one.

http://developer.android.com/guide/topics/fundamentals.html                                                          Page 1 of 19
Application Fundamentals | Android Developers                                                                    29.04.09 0:33



     Each activity is given a default window to draw in. Typically, the window fills the screen, but it might be smaller
     than the screen and float on top of other windows. An activity can also make use of additional windows — for
     example, a pop-up dialog that calls for a user response in the midst of the activity, or a window that presents
     users with vital information when they select a particular item on-screen.

     The visual content of the window is provided by a hierarchy of views — objects derived from the base View class.
     Each view controls a particular rectangular space within the window. Parent views contain and organize the layout
     of their children. Leaf views (those at the bottom of the hierarchy) draw in the rectangles they control and respond
     to user actions directed at that space. Thus, views are where the activity's interaction with the user takes place.
     For example, a view might display a small image and initiate an action when the user taps that image. Android
     has a number of ready-made views that you can use — including buttons, text fields, scroll bars, menu items,
     check boxes, and more.

     A view hierarchy is placed within an activity's window by the Activity.setContentView() method. The
     content view is the View object at the root of the hierarchy. (See the separate User Interface document for more
     information on views and the hierarchy.)

Services
    A service doesn't have a visual user interface, but rather runs in the background for an indefinite period of time.
    For example, a service might play background music as the user attends to other matters, or it might fetch data
    over the network or calculate something and provide the result to activities that need it. Each service extends the
    Service base class.

     A prime example is a media player playing songs from a play list. The player application would probably have one
     or more activities that allow the user to choose songs and start playing them. However, the music playback itself
     would not be handled by an activity because users will expect the music to keep playing even after they leave the
     player and begin something different. To keep the music going, the media player activity could start a service to
     run in the background. The system would then keep the music playback service running even after the activity
     that started it leaves the screen.

     It's possible to connect to (bind to) an ongoing service (and start the service if it's not already running). While
     connected, you can communicate with the service through an interface that the service exposes. For the music
     service, this interface might allow users to pause, rewind, stop, and restart the playback.

     Like activities and the other components, services run in the main thread of the application process. So that they
     won't block other components or the user interface, they often spawn another thread for time-consuming tasks
     (like music playback). See Processes and Threads, later.

Broadcast receivers
    A broadcast receiver is a component that does nothing but receive and react to broadcast announcements. Many
    broadcasts originate in system code — for example, announcements that the timezone has changed, that the
    battery is low, that a picture has been taken, or that the user changed a language preference. Applications can
    also initiate broadcasts — for example, to let other applications know that some data has been downloaded to the
    device and is available for them to use.

     An application can have any number of broadcast receivers to respond to any announcements it considers
     important. All receivers extend the BroadcastReceiver base class.

     Broadcast receivers do not display a user interface. However, they may start an activity in response to the
     information they receive, or they may use the NotificationManager to alert the user. Notifications can get the user's
     attention in various ways — flashing the backlight, vibrating the device, playing a sound, and so on. They typically
     place a persistent icon in the status bar, which users can open to get the message.

Content providers
   A content provider makes a specific set of the application's data available to other applications. The data can be
   stored in the file system, in an SQLite database, or in any other manner that makes sense. The content provider
   extends the ContentProvider base class to implement a standard set of methods that enable other applications to
   retrieve and store data of the type it controls. However, applications do not call these methods directly. Rather
   they use a ContentResolver object and call its methods instead. A ContentResolver can talk to any content
   provider; it cooperates with the provider to manage any interprocess communication that's involved.
http://developer.android.com/guide/topics/fundamentals.html                                                       Page 2 of 19
Application Fundamentals | Android Developers                                                                   29.04.09 0:33


     provider; it cooperates with the provider to manage any interprocess communication that's involved.

     See the separate Content Providers document for more information on using content providers.

Whenever there's a request that should be handled by a particular component, Android makes sure that the
application process of the component is running, starting it if necessary, and that an appropriate instance of the
component is available, creating the instance if necessary.


Activating components: intents
Content providers are activated when they're targeted by a request from a ContentResolver. The other three
components — activities, services, and broadcast receivers — are activated by asynchronous messages called intents.
An intent is an Intent object that holds the content of the message. For activities and services, it names the action
being requested and specifies the URI of the data to act on, among other things. For example, it might convey a
request for an activity to present an image to the user or let the user edit some text. For broadcast receivers, the
Intent object names the action being announced. For example, it might announce to interested parties that the camera
button has been pressed.

There are separate methods for activiating each type of component:

     An activity is launched (or given something new to do) by passing an Intent object to
     Context.startActivity() or Activity.startActivityForResult(). The responding activity can look
     at the initial intent that caused it to be launched by calling its getIntent() method. Android calls the activity's
     onNewIntent() method to pass it any subsequent intents.
     One activity often starts the next one. If it expects a result back from the activity it's starting, it calls
     startActivityForResult() instead of startActivity(). For example, if it starts an activity that lets the
     user pick a photo, it might expect to be returned the chosen photo. The result is returned in an Intent object that's
     passed to the calling activity's onActivityResult() method.

     A service is started (or new instructions are given to an ongoing service) by passing an Intent object to
     Context.startService(). Android calls the service's onStart() method and passes it the Intent object.
     Similarly, an intent can be passed to Context.bindService() to establish an ongoing connection between the
     calling component and a target service. The service receives the Intent object in an onBind() call. (If the service
     is not already running, bindService() can optionally start it.) For example, an activity might establish a
     connection with the music playback service mentioned earlier so that it can provide the user with the means (a
     user interface) for controlling the playback. The activity would call bindService() to set up that connection, and
     then call methods defined by the service to affect the playback.
     A later section, Remote procedure calls, has more details about binding to a service.

     An application can initiate a broadcast by passing an Intent object to methods like Context.sendBroadcast(),
     Context.sendOrderedBroadcast(), and Context.sendStickyBroadcast() in any of their variations.
     Android delivers the intent to all interested broadcast receivers by calling their onReceive() methods.

For more on intent messages, see the separate article, Intents and Intent Filters.


Shutting down components
A content provider is active only while it's responding to a request from a ContentResolver. And a broadcast receiver is
active only while it's responding to a broadcast message. So there's no need to explicitly shut down these components.

Activities, on the other hand, provide the user interface. They're in a long-running conversation with the user and may
remain active, even when idle, as long as the conversation continues. Similarly, services may also remain running for a
long time. So Android has methods to shut down activities and services in an orderly way:

     An activity can be shut down by calling its finish() method. One activity can shut down another activity (one it
     started with startActivityForResult()) by calling finishActivity().
     A service can be stopped by calling its stopSelf() method, or by calling Context.stopService().

http://developer.android.com/guide/topics/fundamentals.html                                                      Page 3 of 19
Application Fundamentals | Android Developers                                                                    29.04.09 0:33




Components might also be shut down by the system when they are no longer being used or when Android must
reclaim memory for more active components. A later section, Component Lifecycles, discusses this possibility and its
ramifications in more detail.


The manifest file
Before Android can start an application component, it must learn that the component exists. Therefore, applications
declare their components in a manifest file that's bundled into the Android package, the .apk file that also holds the
application's code, files, and resources.

The manifest is a structured XML file and is always named AndroidManifest.xml for all applications. It does a number
of things in addition to declaring the application's components, such as naming any libraries the application needs to
be linked against (besides the default Android library) and identifying any permissions the application expects to be
granted.

But the principal task of the manifest is to inform Android about the application's components. For example, an activity
might be declared as follows:

     <?xml version="1.0" encoding="utf-8"?>
     <manifest . . . >
         <application . . . >
             <activity android:name="com.example.project.FreneticActivity"
                        android:icon="@drawable/small_pic.png"
                        android:label="@string/freneticLabel"
                        . . . >
             </activity>
             . . .
         </application>
     </manifest>

The name attribute of the <activity> element names the Activity subclass that implements the activity. The icon
and label attributes point to resource files containing an icon and label that can be displayed to users to represent
the activity.

The other components are declared in a similar way — <service> elements for services, <receiver> elements for
broadcast receivers, and <provider> elements for content providers. Activities, services, and content providers that
are not declared in the manifest are not visible to the system and are consequently never run. However, broadcast
receivers can either be declared in the manifest, or they can be created dynamically in code (as BroadcastReceiver
objects) and registered with the system by calling Context.registerReceiver().

For more on how to structure a manifest file for your application, see The AndroidManifest.xml File.


Intent filters
An Intent object can explicitly name a target component. If it does, Android finds that component (based on the
declarations in the manifest file) and activates it. But if a target is not explicitly named, Android must locate the best
component to respond to the intent. It does so by comparing the Intent object to the intent filters of potential targets. A
component's intent filters inform Android of the kinds of intents the component is able to handle. Like other essential
information about the component, they're declared in the manifest file. Here's an extension of the previous example
that adds two intent filters to the activity:

     <?xml version="1.0" encoding="utf-8"?>
     <manifest . . . >
         <application . . . >
             <activity android:name="com.example.project.FreneticActivity"
                       android:icon="@drawable/small_pic.png"
                       android:label="@string/freneticLabel"
                       . . . >


http://developer.android.com/guide/topics/fundamentals.html                                                       Page 4 of 19
Application Fundamentals | Android Developers                                                                       29.04.09 0:33

                        . . . >
                 <intent-filter . . . >
                     <action android:name="android.intent.action.MAIN" />
                     <category android:name="android.intent.category.LAUNCHER" />
                 </intent-filter>
                 <intent-filter . . . >
                     <action android:name="com.example.project.BOUNCE" />
                     <data android:type="image/jpeg" />
                     <category android:name="android.intent.category.DEFAULT" />
                 </intent-filter>
             </activity>
             . . .
         </application>
     </manifest>

The first filter in the example — the combination of the action "android.intent.action.MAIN" and the category
"android.intent.category.LAUNCHER" — is a common one. It marks the activity as one that should be
represented in the application launcher, the screen listing applications users can launch on the device. In other words,
the activity is the entry point for the application, the initial one users would see when they choose the application in
the launcher.

The second filter declares an action that the activity can perform on a particular type of data.

A component can have any number of intent filters, each one declaring a different set of capabilities. If it doesn't have
any filters, it can be activated only by intents that explicitly name the component as the target.

For a broadcast receiver that's created and registered in code, the intent filter is instantiated directly as an IntentFilter
object. All other filters are set up in the manifest.

For more on intent filters, see a separate document, Intents and Intent Filters.



Activities and Tasks
As noted earlier, one activity can start another, including one defined in a different application. Suppose, for example,
that you'd like to let users display a street map of some location. There's already an activity that can do that, so all
your activity needs to do is put together an Intent object with the required information and pass it to
startActivity(). The map viewer will display the map. When the user hits the BACK key, your activity will
reappear on screen.

To the user, it will seem as if the map viewer is part of the same application as your activity, even though it's defined
in another application and runs in that application's process. Android maintains this user experience by keeping both
activities in the same task. Simply put, a task is what the user experiences as an "application." It's a group of related
activities, arranged in a stack. The root activity in the stack is the one that began the task — typically, it's an activity
the user selected in the application launcher. The activity at the top of the stack is one that's currently running — the
one that is the focus for user actions. When one activity starts another, the new activity is pushed on the stack; it
becomes the running activity. The previous activity remains in the stack. When the user presses the BACK key, the
current activity is popped from the stack, and the previous one resumes as the running activity.

The stack contains objects, so if a task has more than one instance of the same Activity subclass open — multiple
map viewers, for example — the stack has a separate entry for each instance. Activities in the stack are never
rearranged, only pushed and popped.

A task is a stack of activities, not a class or an element in the manifest file. So there's no way to set values for a task
independently of its activities. Values for the task as a whole are set in the root activity. For example, the next section
will talk about the "affinity of a task"; that value is read from the affinity set for the task's root activity.

All the activities in a task move together as a unit. The entire task (the entire activity stack) can be brought to the
foreground or sent to the background. Suppose, for instance, that the current task has four activities in its stack —
three under the current activity. The user presses the HOME key, goes to the application launcher, and selects a new
application (actually, a new task). The current task goes into the background and the root activity for the new task is

http://developer.android.com/guide/topics/fundamentals.html                                                          Page 5 of 19
Application Fundamentals | Android Developers                                                                      29.04.09 0:33



displayed. Then, after a short period, the user goes back to the home screen and again selects the previous
application (the previous task). That task, with all four activities in the stack, comes forward. When the user presses
the BACK key, the screen does not display the activity the user just left (the root activity of the previous task). Rather,
the activity on the top of the stack is removed and the previous activity in the same task is displayed.

The behavior just described is the default behavior for activities and tasks. But there are ways to modify almost all
aspects of it. The association of activities with tasks, and the behavior of an activity within a task, is controlled by the
interaction between flags set in the Intent object that started the activity and attributes set in the activity's
<activity> element in the manifest. Both requester and respondent have a say in what happens.

In this regard, the principal Intent flags are:

     FLAG_ACTIVITY_NEW_TASK
     FLAG_ACTIVITY_CLEAR_TOP
     FLAG_ACTIVITY_RESET_TASK_IF_NEEDED
     FLAG_ACTIVITY_SINGLE_TOP

The principal <activity> attributes are:

     taskAffinity
     launchMode
     allowTaskReparenting
     clearTaskOnLaunch
     alwaysRetainTaskState
     finishOnTaskLaunch

The following sections describe what some of these flags and attributes do, how they interact, and what considerations
should govern their use.


Affinities and new tasks
By default, all the activities in an application have an affinity for each other — that is, there's a preference for them all
to belong to the same task. However, an individual affinity can be set for each activity with the taskAffinity
attribute of the <activity> element. Activities defined in different applications can share an affinity, or activities
defined in the same application can be assigned different affinities. The affinity comes into play in two circumstances:
When the Intent object that launches an activity contains the FLAG_ACTIVITY_NEW_TASK flag, and when an activity
has its allowTaskReparenting attribute set to "true".

The FLAG_ACTIVITY_NEW_TASK flag
    As described earlier, a new activity is, by default, launched into the task of the activity that called
    startActivity(). It's pushed onto the same stack as the caller. However, if the Intent object passed to
    startActivity() contains the FLAG_ACTIVITY_NEW_TASK flag, the system looks for a different task to
    house the new activity. Often, as the name of the flag implies, it's a new task. However, it doesn't have to be. If
    there's already an existing task with the same affinity as the new activity, the activity is launched into that task. If
    not, it begins a new task.

The allowTaskReparenting attribute
    If an activity has its allowTaskReparenting attribute set to "true", it can move from the task it starts in to the
    task it has an affinity for when that task comes to the fore. For example, suppose that an activity that reports
    weather conditions in selected cities is defined as part of a travel application. It has the same affinity as other
    activities in the same application (the default affinity) and it allows reparenting. One of your activities starts the
    weather reporter, so it initially belongs to the same task as your activity. However, when the travel application next
    comes forward, the weather reporter will be reassigned to and displayed with that task.

If an .apk file contains more than one "application" from the user's point of view, you will probably want to assign
different affinities to the activities associated with each of them.


Launch modes

http://developer.android.com/guide/topics/fundamentals.html                                                          Page 6 of 19
Application Fundamentals | Android Developers                                                                             29.04.09 0:33



There are four different launch modes that can be assigned to an <activity> element's launchMode attribute:

     "standard" (the default mode)
     "singleTop"
     "singleTask"
     "singleInstance"

The modes differ from each other on these four points:

     Which task will hold the activity that responds to the intent. For the "standard" and "singleTop" modes,
     it's the task that originated the intent (and called startActivity()) — unless the Intent object contains the
     FLAG_ACTIVITY_NEW_TASK flag. In that case, a different task is chosen as described in the previous section,
     Affinities and new tasks.
     In contrast, the "singleTask" and "singleInstance" modes mark activities that are always at the root of a
     task. They define a task; they're never launched into another task.

     Whether there can be multiple instances of the activity. A "standard" or "singleTop" activity can be
     instantiated many times. They can belong to multiple tasks, and a given task can have multiple instances of the
     same activity.
     In contrast, "singleTask" and "singleInstance" activities are limited to just one instance. Since these
     activities are at the root of a task, this limitation means that there is never more than a single instance of the task
     on the device at one time.

     Whether the instance can have other activities in its task. A "singleInstance" activity stands alone as the
     only activity in its task. If it starts another activity, that activity will be launched into a different task regardless of its
     launch mode — as if FLAG_ACTIVITY_NEW_TASK was in the intent. In all other respects, the
     "singleInstance" mode is identical to "singleTask".
     The other three modes permit multiple activities to belong to the task. A "singleTask" activity will always be the
     root activity of the task, but it can start other activities that will be assigned to its task. Instances of "standard"
     and "singleTop" activities can appear anywhere in a stack.
     Whether a new instance of the class will be launched to handle a new intent. For the default "standard"
     mode, a new instance is created to respond to every new intent. Each instance handles just one intent. For the
     "singleTop" mode, an existing instance of the class is re-used to handle a new intent if it resides at the top of
     the activity stack of the target task. If it does not reside at the top, it is not re-used. Instead, a new instance is
     created for the new intent and pushed on the stack.
     For example, suppose a task's activity stack consists of root activity A with activities B, C, and D on top in that
     order, so the stack is A-B-C-D. An intent arrives for an activity of type D. If D has the default "standard" launch
     mode, a new instance of the class is launched and the stack becomes A-B-C-D-D. However, if D's launch mode
     is "singleTop", the existing instance is expected to handle the new intent (since it's at the top of the stack) and
     the stack remains A-B-C-D.
     If, on the other hand, the arriving intent is for an activity of type B, a new instance of B would be launched no
     matter whether B's mode is "standard" or "singleTop" (since B is not at the top of the stack), so the resulting
     stack would be A-B-C-D-B.
     As noted above, there's never more than one instance of a "singleTask" or "singleInstance" activity, so
     that instance is expected to handle all new intents. A "singleInstance" activity is always at the top of the stack
     (since it is the only activity in the task), so it is always in position to handle the intent. However, a "singleTask"
     activity may or may not have other activities above it in the stack. If it does, it is not in position to handle the
     intent, and the intent is dropped. (Even though the intent is dropped, its arrival would have caused the task to
     come to the foreground, where it would remain.)

When an existing activity is asked to handle a new intent, the Intent object is passed to the activity in an
onNewIntent() call. (The intent object that originally started the activity can be retrieved by calling getIntent().)

Note that when a new instance of an Activity is created to handle a new intent, the user can always press the BACK
key to return to the previous state (to the previous activity). But when an existing instance of an Activity handles a new
intent, the user cannot press the BACK key to return to what that instance was doing before the new intent arrived.

http://developer.android.com/guide/topics/fundamentals.html                                                                Page 7 of 19
Application Fundamentals | Android Developers                                                                          29.04.09 0:33


intent, the user cannot press the BACK key to return to what that instance was doing before the new intent arrived.

For more on launch modes, see the description of the <activity> element.


Clearing the stack
If the user leaves a task for a long time, the system clears the task of all activities except the root activity. When the
user returns to the task again, it's as the user left it, except that only the initial activity is present. The idea is that, after
a time, users will likely have abandoned what they were doing before and are returning to the task to begin something
new.

That's the default. There are some activity attributes that can be used to control this behavior and modify it:

The alwaysRetainTaskState attribute
    If this attribute is set to "true" in the root activity of a task, the default behavior just described does not happen.
    The task retains all activities in its stack even after a long period.

The clearTaskOnLaunch attribute
    If this attribute is set to "true" in the root activity of a task, the stack is cleared down to the root activity
    whenever the user leaves the task and returns to it. In other words, it's the polar opposite of
    alwaysRetainTaskState. The user always returns to the task in its initial state, even after a momentary
    absence.

The finishOnTaskLaunch attribute
    This attribute is like clearTaskOnLaunch, but it operates on a single activity, not an entire task. And it can
    cause any activity to go away, including the root activity. When it's set to "true", the activity remains part of the
    task only for the current session. If the user leaves and then returns to the task, it no longer is present.

There's another way to force activities to be removed from the stack. If an Intent object includes the
FLAG_ACTIVITY_CLEAR_TOP flag, and the target task already has an instance of the type of activity that should
handle the intent in its stack, all activities above that instance are cleared away so that it stands at the top of the stack
and can respond to the intent. If the launch mode of the designated activity is "standard", it too will be removed from
the stack, and a new instance will be launched to handle the incoming intent. That's because a new instance is always
created for a new intent when the launch mode is "standard".

FLAG_ACTIVITY_CLEAR_TOP is most often used in conjunction with FLAG_ACTIVITY_NEW_TASK. When used
together, these flags are a way of locating an existing activity in another task and putting it in a position where it can
respond to the intent.


Starting tasks
An activity is set up as the entry point for a task by giving it an intent filter with "android.intent.action.MAIN"
as the specified action and "android.intent.category.LAUNCHER" as the specified category. (There's an
example of this type of filter in the earlier Intent Filters section.) A filter of this kind causes an icon and label for the
activity to be displayed in the application launcher, giving users a way both to launch the task and to return to it at any
time after it has been launched.

This second ability is important: Users must be able to leave a task and then come back to it later. For this reason, the
two launch modes that mark activities as always initiating a task, "singleTask" and "singleInstance", should be
used only when the activity has a MAIN and LAUNCHER filter. Imagine, for example, what could happen if the filter is
missing: An intent launches a "singleTask" activity, initiating a new task, and the user spends some time working in
that task. The user then presses the HOME key. The task is now ordered behind and obscured by the home screen.
And, because it is not represented in the application launcher, the user has no way to return to it.

A similar difficulty attends the FLAG_ACTIVITY_NEW_TASK flag. If this flag causes an activity to begin a new task and
the user presses the HOME key to leave it, there must be some way for the user to navigate back to it again. Some
entities (such as the notification manager) always start activities in an external task, never as part of their own, so they
always put FLAG_ACTIVITY_NEW_TASK in the intents they pass to startActivity(). If you have an activity that
can be invoked by an external entity that might use this flag, take care that the user has a independent way to get
http://developer.android.com/guide/topics/fundamentals.html                                                              Page 8 of 19
Application Fundamentals | Android Developers                                                                 29.04.09 0:33


can be invoked by an external entity that might use this flag, take care that the user has a independent way to get
back to the task that's started.

For those cases where you don't want the user to be able to return to an activity, set the <activity> element's
finishOnTaskLaunch to "true". See Clearing the stack, earlier.



Processes and Threads
When the first of an application's components needs to be run, Android starts a Linux process for it with a single
thread of execution. By default, all components of the application run in that process and thread.

However, you can arrange for components to run in other processes, and you can spawn additional threads for any
process.


Processes
The process where a component runs is controlled by the manifest file. The component elements — <activity>,
<service>, <receiver>, and <provider> — each have a process attribute that can specify a process where
that component should run. These attributes can be set so that each component runs in its own process, or so that
some components share a process while others do not. They can also be set so that components of different
applications run in the same process — provided that the applications share the same Linux user ID and are signed by
the same authorities. The <application> element also has a process attribute, for setting a default value that
applies to all components.

All components are instantiated in the main thread of the specified process, and system calls to the component are
dispatched from that thread. Separate threads are not created for each instance. Consequently, methods that respond
to those calls — methods like View.onKeyDown() that report user actions and the lifecycle notifications discussed
later in the Component Lifecycles section — always run in the main thread of the process. This means that no
component should perform long or blocking operations (such as networking operations or computation loops) when
called by the system, since this will block any other components also in the process. You can spawn separate threads
for long operations, as discussed under Threads, next.

Android may decide to shut down a process at some point, when memory is low and required by other processes that
are more immediately serving the user. Application components running in the process are consequently destroyed. A
process is restarted for those components when there's again work for them to do.

When deciding which processes to terminate, Android weighs their relative importance to the user. For example, it
more readily shuts down a process with activities that are no longer visible on screen than a process with visible
activities. The decision whether to terminate a process, therefore, depends on the state of the components running in
that process. Those states are the subject of a later section, Component Lifecycles.


Threads
Even though you may confine your application to a single process, there will likely be times when you will need to
spawn a thread to do some background work. Since the user interface must always be quick to respond to user
actions, the thread that hosts an activity should not also host time-consuming operations like network downloads.
Anything that may not be completed quickly should be assigned to a different thread.

Threads are created in code using standard Java Thread objects. Android provides a number of convenience classes
for managing threads — Looper for running a message loop within a thread, Handler for processing messages, and
HandlerThread for setting up a thread with a message loop.


Remote procedure calls
Android has a lightweight mechanism for remote procedure calls (RPCs) — where a method is called locally, but
executed remotely (in another process), with any result returned back to the caller. This entails decomposing the

http://developer.android.com/guide/topics/fundamentals.html                                                    Page 9 of 19
Application Fundamentals | Android Developers                                                                 29.04.09 0:33



method call and all its attendant data to a level the operating system can understand, transmitting it from the local
process and address space to the remote process and address space, and reassembling and reenacting the call there.
Return values have to be transmitted in the opposite direction. Android provides all the code to do that work, so that
you can concentrate on defining and implementing the RPC interface itself.

An RPC interface can include only methods. All methods are executed synchronously (the local method blocks until the
remote method finishes), even if there is no return value.

In brief, the mechanism works as follows: You'd begin by declaring the RPC interface you want to implement using a
simple IDL (interface definition language). From that declaration, the aidl tool generates a Java interface definition
that must be made available to both the local and the remote process. It contains two inner class, as shown in the
following diagram:




The inner classes have all the code needed to administer remote procedure calls for the interface you declared with
the IDL. Both inner classes implement the IBinder interface. One of them is used locally and internally by the system;
the code you write can ignore it. The other, called Stub, extends the Binder class. In addition to internal code for
effectuating the IPC calls, it contains declarations for the methods in the RPC interface you declared. You would
subclass Stub to implement those methods, as indicated in the diagram.

Typically, the remote process would be managed by a service (because a service can inform the system about the
process and its connections to other processes). It would have both the interface file generated by the aidl tool and
the Stub subclass implementing the RPC methods. Clients of the service would have only the interface file generated
by the aidl tool.

Here's how a connection between a service and its clients is set up:

     Clients of the service (on the local side) would implement onServiceConnected() and
     onServiceDisconnected() methods so they can be notified when a successful connection to the remote
     service is established, and when it goes away. They would then call bindService() to set up the connection.
     The service's onBind() method would be implemented to either accept or reject the connection, depending on
     the intent it receives (the intent passed to bindService()). If the connection is accepted, it returns an instance
     of the Stub subclass.
     If the service accepts the connection, Android calls the client's onServiceConnected() method and passes it
     an IBinder object, a proxy for the Stub subclass managed by the service. Through the proxy, the client can make
http://developer.android.com/guide/topics/fundamentals.html                                                   Page 10 of 19
Application Fundamentals | Android Developers                                                                       29.04.09 0:33


     an IBinder object, a proxy for the Stub subclass managed by the service. Through the proxy, the client can make
     calls on the remote service.

This brief description omits some details of the RPC mechanism. For more information, see Designing a Remote
Interface Using AIDL and the IBinder class description.


Thread-safe methods
In a few contexts, the methods you implement may be called from more than one thread, and therefore must be
written to be thread-safe.

This is primarily true for methods that can be called remotely — as in the RPC mechanism discussed in the previous
section. When a call on a method implemented in an IBinder object originates in the same process as the IBinder, the
method is executed in the caller's thread. However, when the call originates in another process, the method is
executed in a thread chosen from a pool of threads that Android maintains in the same process as the IBinder; it's not
executed in the main thread of the process. For example, whereas a service's onBind() method would be called
from the main thread of the service's process, methods implemented in the object that onBind() returns (for
example, a Stub subclass that implements RPC methods) would be called from threads in the pool. Since services can
have more than one client, more than one pool thread can engage the same IBinder method at the same time. IBinder
methods must, therefore, be implemented to be thread-safe.

Similarly, a content provider can receive data requests that originate in other processes. Although the ContentResolver
and ContentProvider classes hide the details of how the interprocess communication is managed, ContentProvider
methods that respond to those requests — the methods query(), insert(), delete(), update(), and
getType() — are called from a pool of threads in the content provider's process, not the main thread of the process.
Since these methods may be called from any number of threads at the same time, they too must be implemented to
be thread-safe.



Component Lifecycles
Application components have a lifecycle — a beginning when Android instantiates them to respond to intents through
to an end when the instances are destroyed. In between, they may sometimes be active or inactive,or, in the case of
activities, visible to the user or invisible. This section discusses the lifecycles of activities, services, and broadcast
receivers — including the states that they can be in during their lifetimes, the methods that notify you of transitions
between states, and the effect of those states on the possibility that the process hosting them might be terminated and
the instances destroyed.


Activity lifecycle
An activity has essentially three states:

     It is active or running when it is in the foreground of the screen (at the top of the activity stack for the current
     task). This is the activity that is the focus for the user's actions.

     It is paused if it has lost focus but is still visible to the user. That is, another activity lies on top of it and that
     activity either is transparent or doesn't cover the full screen, so some of the paused activity can show through. A
     paused activity is completely alive (it maintains all state and member information and remains attached to the
     window manager), but can be killed by the system in extreme low memory situations.

     It is stopped if it is completely obscured by another activity. It still retains all state and member information.
     However, it is no longer visible to the user so its window is hidden and it will often be killed by the system when
     memory is needed elsewhere.

If an activity is paused or stopped, the system can drop it from memory either by asking it to finish (calling its finish()
method), or simply killing its process. When it is displayed again to the user, it must be completely restarted and
restored to its previous state.

http://developer.android.com/guide/topics/fundamentals.html                                                          Page 11 of 19
Application Fundamentals | Android Developers                                                                      29.04.09 0:33




As an activity transitions from state to state, it is notified of the change by calls to the following protected methods:

     void     onCreate(Bundle savedInstanceState)
     void     onStart()
     void     onRestart()
     void     onResume()
     void     onPause()
     void     onStop()
     void     onDestroy()

All of these methods are hooks that you can override to do appropriate work when the state changes. All activities
must implement onCreate() to do the initial setup when the object is first instantiated. Many will also implement
onPause() to commit data changes and otherwise prepare to stop interacting with the user.

Taken together, these seven methods define the entire lifecycle of
an activity. There are three nested loops that you can monitor by
implementing them:                                                           Calling into the superclass
                                                                             An implementation of any activity lifecycle
     The entire lifetime of an activity happens between the first call       method should always first call the superclass
     to onCreate() through to a single final call to onDestroy().            version. For example:
     An activity does all its initial setup of "global" state in
     onCreate(), and releases all remaining resources in                         protected void onPause() {
                                                                                     super.onPause();
     onDestroy(). For example, if it has a thread running in the                     . . .
     background to download data from the network, it may create                 }
     that thread in onCreate() and then stop the thread in
     onDestroy().

     The visible lifetime of an activity happens between a call to onStart() until a corresponding call to onStop().
     During this time, the user can see the activity on-screen, though it may not be in the foreground and interacting
     with the user. Between these two methods, you can maintain resources that are needed to show the activity to the
     user. For example, you can register a BroadcastReceiver in onStart() to monitor for changes that impact your
     UI, and unregister it in onStop() when the user can no longer see what you are displaying. The onStart() and
     onStop() methods can be called multiple times, as the activity alternates between being visible and hidden to
     the user.

     The foreground lifetime of an activity happens between a call to onResume() until a corresponding call to
     onPause(). During this time, the activity is in front of all other activities on screen and is interacting with the
     user. An activity can frequently transition between the resumed and paused states — for example, onPause() is
     called when the device goes to sleep or when a new activity is started, onResume() is called when an activity
     result or a new intent is delivered. Therefore, the code in these two methods should be fairly lightweight.

The following diagram illustrates these loops and the paths an activity may take between states. The colored ovals are
major states the activity can be in. The square rectangles represent the callback methods you can implement to
perform operations when the activity transitions between states.




http://developer.android.com/guide/topics/fundamentals.html                                                         Page 12 of 19
Application Fundamentals | Android Developers                                                                    29.04.09 0:33




The following table describes each of these methods in more detail and locates it within the activity's overall lifecycle:

  Method                                   Description                         Killable?   Next

  onCreate()                               Called when the activity is first   No          onStart()
                                           created. This is where you
                                           should do all of your normal
                                           static set up — create views,
                                           bind data to lists, and so on.
                                           This method is passed a Bundle
                                           object containing the activity's


http://developer.android.com/guide/topics/fundamentals.html                                                      Page 13 of 19
Application Fundamentals | Android Developers                                                         29.04.09 0:33


                                           previous state, if that state was
                                           captured (see Saving Activity
                                           State, later).
                                           Always followed by
                                           onStart().


           onRestart()                     Called after the activity has          No    onStart()
                                           been stopped, just prior to it
                                           being started again.
                                           Always followed by onStart()


           onStart()                       Called just before the activity        No    onResume()
                                           becomes visible to the user.                 or
                                           Followed by onResume() if the                onStop()
                                           activity comes to the
                                           foreground, or onStop() if it
                                           becomes hidden.


                    onResume()             Called just before the activity        No    onPause()
                                           starts interacting with the user.
                                           At this point the activity is at the
                                           top of the activity stack, with
                                           user input going to it.
                                           Always followed by
                                           onPause().


                    onPause()              Called when the system is              Yes   onResume()
                                           about to start resuming another              or
                                           activity. This method is typically           onStop()
                                           used to commit unsaved
                                           changes to persistent data, stop
                                           animations and other things that
                                           may be consuming CPU, and
                                           so on. It should do whatever it
                                           does very quickly, because the
                                           next activity will not be resumed
                                           until it returns.
                                           Followed either by
                                           onResume() if the activity
                                           returns back to the front, or by
                                           onStop() if it becomes
                                           invisible to the user.


           onStop()                        Called when the activity is no         Yes   onRestart()
                                           longer visible to the user. This             or
                                           may happen because it is being               onDestroy()
                                           destroyed, or because another
                                           activity (either an existing one
                                           or a new one) has been
                                           resumed and is covering it.
                                           Followed either by
                                           onRestart() if the activity is
                                           coming back to interact with the
                                           user, or by onDestroy() if
                                           this activity is going away.


http://developer.android.com/guide/topics/fundamentals.html                                           Page 14 of 19
Application Fundamentals | Android Developers                                                                       29.04.09 0:33



  onDestroy()                              Called before the activity is        Yes      nothing
                                           destroyed. This is the final call
                                           that the activity will receive. It
                                           could be called either because
                                           the activity is finishing
                                           (someone called finish() on
                                           it), or because the system is
                                           temporarily destroying this
                                           instance of the activity to save
                                           space. You can distinguish
                                           between these two scenarios
                                           with the isFinishing()
                                           method.

Note the Killable column in the table above. It indicates whether or not the system can kill the process hosting the
activity at any time after the method returns, without executing another line of the activity's code. Three methods
(onPause(), onStop(), and onDestroy()) are marked "Yes." Because onPause() is the first of the three, it's the
only one that's guaranteed to be called before the process is killed — onStop() and onDestroy() may not be.
Therefore, you should use onPause() to write any persistent data (such as user edits) to storage.

Methods that are marked "No" in the Killable column protect the process hosting the activity from being killed from the
moment they are called. Thus an activity is in a killable state, for example, from the time onPause() returns to the
time onResume() is called. It will not again be killable until onPause() again returns.

As noted in a later section, Processes and lifecycle, an activity that's not technically "killable" by this definition might
still be killed by the system — but that would happen only in extreme and dire circumstances when there is no other
recourse.

Saving activity state
When the system, rather than the user, shuts down an activity to conserve memory, the user may expect to return to
the activity and find it in its previous state.

To capture that state before the activity is killed, you can implement an onSaveInstanceState() method for the
activity. Android calls this method before making the activity vulnerable to being destroyed — that is, before
onPause() is called. It passes the method a Bundle object where you can record the dynamic state of the activity as
name-value pairs. When the activity is again started, the Bundle is passed both to onCreate() and to a method
that's called after onStart(), onRestoreInstanceState(), so that either or both of them can recreate the
captured state.

Unlike onPause() and the other methods discussed earlier, onSaveInstanceState() and
onRestoreInstanceState() are not lifecycle methods. They are not always called. For example, Android calls
onSaveInstanceState() before the activity becomes vulnerable to being destroyed by the system, but does not
bother calling it when the instance is actually being destroyed by a user action (such as pressing the BACK key). In
that case, the user won't expect to return to the activity, so there's no reason to save its state.

Because onSaveInstanceState() is not always called, you should use it only to record the transient state of the
activity, not to store persistent data. Use onPause() for that purpose instead.

Coordinating activities
When one activity starts another, they both experience lifecycle transitions. One pauses and may stop, while the other
starts up. On occasion, you may need to coordinate these activities, one with the other.

The order of lifecycle callbacks is well defined, particularly when the two activities are in the same process:

 1. The current activity's onPause() method is called.
 2. Next, the starting activity's onCreate(), onStart(), and onResume() methods are called in sequence.
 3. Then, if the starting activity is no longer visible on screen, its onStop() method is called.


http://developer.android.com/guide/topics/fundamentals.html                                                         Page 15 of 19
Application Fundamentals | Android Developers                                                                     29.04.09 0:33




Service lifecycle
A service can be used in two ways:

     It can be started and allowed to run until someone stops it or it stops itself. In this mode, it's started by calling
     Context.startService() and stopped by calling Context.stopService(). It can stop itself by calling
     Service.stopSelf() or Service.stopSelfResult(). Only one stopService() call is needed to stop
     the service, no matter how many times startService() was called.

     It can be operated programmatically using an interface that it defines and exports. Clients establish a connection
     to the Service object and use that connection to call into the service. The connection is established by calling
     Context.bindService(), and is closed by calling Context.unbindService(). Multiple clients can bind to
     the same service. If the service has not already been launched, bindService() can optionally launch it.

The two modes are not entirely separate. You can bind to a service that was started with startService(). For
example, a background music service could be started by calling startService() with an Intent object that
identifies the music to play. Only later, possibly when the user wants to exercise some control over the player or get
information about the current song, would an activity establish a connection to the service by calling bindService().
In cases like this, stopService() will not actually stop the service until the last binding is closed.

Like an activity, a service has lifecycle methods that you can implement to monitor changes in its state. But they are
fewer than the activity methods — only three — and they are public, not protected:

     void onCreate()
     void onStart(Intent intent)
     void onDestroy()

By implementing these methods, you can monitor two nested loops of the service's lifecycle:

     The entire lifetime of a service happens between the time onCreate() is called and the time onDestroy()
     returns. Like an activity, a service does its initial setup in onCreate(), and releases all remaining resources in
     onDestroy(). For example, a music playback service could create the thread where the music will be played in
     onCreate(), and then stop the thread in onDestroy().

     The active lifetime of a service begins with a call to onStart(). This method is handed the Intent object that
     was passed to startService(). The music service would open the Intent to discover which music to play, and
     begin the playback.
     There's no equivalent callback for when the service stops — no onStop() method.

The onCreate() and onDestroy() methods are called for all services, whether they're started by
Context.startService() or Context.bindService(). However, onStart() is called only for services started
by startService().

If a service permits others to bind to it, there are additional callback methods for it to implement:

     IBinder onBind(Intent intent)
     boolean onUnbind(Intent intent)
     void onRebind(Intent intent)

The onBind() callback is passed the Intent object that was passed to bindService and onUnbind() is handed
the intent that was passed to unbindService(). If the service permits the binding, onBind() returns the
communications channel that clients use to interact with the service. The onUnbind() method can ask for
onRebind() to be called if a new client connects to the service.

The following diagram illustrates the callback methods for a service. Although, it separates services that are created via
startService from those created by bindService(), keep in mind that any service, no matter how it's started,
can potentially allow clients to bind to it, so any service may receive onBind() and onUnbind() calls.



http://developer.android.com/guide/topics/fundamentals.html                                                       Page 16 of 19
Application Fundamentals | Android Developers                                                               29.04.09 0:33




Broadcast receiver lifecycle
A broadcast receiver has single callback method:

     void onReceive(Context curContext, Intent broadcastMsg)

When a broadcast message arrives for the receiver, Android calls its onReceive() method and passes it the Intent
object containing the message. The broadcast receiver is considered to be active only while it is executing this
method. When onReceive() returns, it is inactive.

A process with an active broadcast receiver is protected from being killed. But a process with only inactive
components can be killed by the system at any time, when the memory it consumes is needed by other processes.

This presents a problem when the response to a broadcast message is time consuming and, therefore, something that
should be done in a separate thread, away from the main thread where other components of the user interface run. If
onReceive() spawns the thread and then returns, the entire process, including the new thread, is judged to be
inactive (unless other application components are active in the process), putting it in jeopardy of being killed. The
solution to this problem is for onReceive() to start a service and let the service do the job, so the system knows that
there is still active work being done in the process.

The next section has more on the vulnerability of processes to being killed.


http://developer.android.com/guide/topics/fundamentals.html                                                  Page 17 of 19
Application Fundamentals | Android Developers                                                                      29.04.09 0:33



Processes and lifecycles
The Android system tries to maintain an application process for as long as possible, but eventually it will need to
remove old processes when memory runs low. To determine which processes to keep and which to kill, Android
places each process into an "importance hierarchy" based on the components running in it and the state of those
components. Processes with the lowest importance are eliminated first, then those with the next lowest, and so on.
There are five levels in the hierarchy. The following list presents them in order of importance:

 1. A foreground process is one that is required for what the user is currently doing. A process is considered to be
    in the foreground if any of the following conditions hold:
           It is running an activity that the user is interacting with (the Activity object's onResume() method has been
           called).

           It hosts a service that's bound to the activity that the user is interacting with.

           It has a Service object that's executing one of its lifecycle callbacks (onCreate(), onStart(), or
           onDestroy()).

           It has a BroadcastReceiver object that's executing its onReceive() method.

     Only a few foreground processes will exist at any given time. They are killed only as a last resort — if memory is
     so low that they cannot all continue to run. Generally, at that point, the device has reached a memory paging
     state, so killing some foreground processes is required to keep the user interface responsive.

 2. A visible process is one that doesn't have any foreground components, but still can affect what the user sees on
    screen. A process is considered to be visible if either of the following conditions holds:
           It hosts an activity that is not in the foreground, but is still visible to the user (its onPause() method has
           been called). This may occur, for example, if the foreground activity is a dialog that allows the previous
           activity to be seen behind it.

           It hosts a service that's bound to a visible activity.

     A visible process is considered extremely important and will not be killed unless doing so is required to keep all
     foreground processes running.

 3. A service process is one that is running a service that has been started with the startService() method and
    that does not fall into either of the two higher categories. Although service processes are not directly tied to
    anything the user sees, they are generally doing things that the user cares about (such as playing an mp3 in the
    background or downloading data on the network), so the system keeps them running unless there's not enough
    memory to retain them along with all foreground and visible processes.

 4. A background process is one holding an activity that's not currently visible to the user (the Activity object's
    onStop() method has been called). These processes have no direct impact on the user experience, and can be
    killed at any time to reclaim memory for a foreground, visible, or service process. Usually there are many
    background processes running, so they are kept in an LRU (least recently used) list to ensure that the process
    with the activity that was most recently seen by the user is the last to be killed. If an activity implements its
    lifecycle methods correctly, and captures its current state, killing its process will not have a deleterious effect on
    the user experience.

 5. An empty process is one that doesn't hold any active application components. The only reason to keep such a
    process around is as a cache to improve startup time the next time a component needs to run in it. The system
    often kills these processes in order to balance overall system resources between process caches and the
    underlying kernel caches.

Android ranks a process at the highest level it can, based upon the importance of the components currently active in
the process. For example, if a process hosts a service and a visible activity, the process will be ranked as a visible
process, not a service process.

In addition, a process's ranking may be increased because other processes are dependent on it. A process that is
serving another process can never be ranked lower than the process it is serving. For example, if a content provider in
http://developer.android.com/guide/topics/fundamentals.html                                                        Page 18 of 19
Application Fundamentals | Android Developers                                                                         29.04.09 0:33


serving another process can never be ranked lower than the process it is serving. For example, if a content provider in
process A is serving a client in process B, or if a service in process A is bound to a component in process B, process
A will always be considered at least as important as process B.

Because a process running a service is ranked higher than one with background activities, an activity that initiates a
long-running operation might do well to start a service for that operation, rather than simply spawn a thread —
particularly if the operation will likely outlast the activity. Examples of this are playing music in the background and
uploading a picture taken by the camera to a web site. Using a service guarantees that the operation will have at least
"service process" priority, regardless of what happens to the activity. As noted in the Broadcast receiver lifecycle
section earlier, this is the same reason that broadcast receivers should employ services rather than simply put time-
consuming operations in a thread.

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/fundamentals.html                                                           Page 19 of 19
User Interface | Android Developers                                                                             29.04.09 0:34




User Interface

In an Android application, the user interface is built using View and ViewGroup objects. There are many types of views
and view groups, each of which is a descendant of the View class.

View objects are the basic units of user interface expression on the Android platform. The View class serves as the
base for subclasses called "widgets," which offer fully implemented UI objects, like text fields and buttons. The
ViewGroup class serves as the base for subclasses called "layouts," which offer different kinds of layout architecture,
like linear, tabular and relative.

A View object is a data structure whose properties store the layout parameters and content for a specific rectangular
area of the screen. A View object handles its own measurement, layout, drawing, focus change, scrolling, and
key/gesture interactions for the rectangular area of the screen in which it resides. As an object in the user interface, a
View is also a point of interaction for the user and the receiver of the interaction events.



View Hierarchy
On the Android platform, you define an Activity's UI using a hierarchy of View and ViewGroup nodes, as shown in the
diagram below. This hierarchy tree can be as simple or complex as you need it to be, and you can build it up using
Android's set of predefined widgets and layouts, or with custom Views that you create yourself.




In order to attach the view hierarchy tree to the screen for rendering, your Activity must call the setContentView()
method and pass a reference to the root node object. The Android system receives this reference and uses it to
invalidate, measure, and draw the tree. The root node of the hierarchy requests that its child nodes draw themselves
— in turn, each view group node is responsible for calling upon each of its own child views to draw themselves. The
children may request a size and location within the parent, but the parent object has the final decision on where how
big each child can be. Android parses the elements of your layout in-order (from the top of the hierarchy tree),
instantiating the Views and adding them to their parent(s). Because these are drawn in-order, if there are elements that
overlap positions, the last one to be drawn will lie on top of others previously drawn to that space.

For a more detailed discussion on how view hierarchies are measured and drawn, read How Android Draws Views.



Layout
http://developer.android.com/guide/topics/ui/index.html                                                           Page 1 of 4
User Interface | Android Developers                                                                          29.04.09 0:34




The most common way to define your layout and express the view hierarchy is with an XML layout file. XML offers a
human-readable structure for the layout, much like HTML. Each element in XML is either a View or ViewGroup object
(or descendent thereof). View objects are leaves in the tree, ViewGroup objects are branches in the tree (see the
View Hierarchy figure above).

The name of an XML element is respective to the Java class that it represents. So a <TextView> element creates a
TextView in your UI, and a <LinearLayout> element creates a LinearLayout view group. When you load a layout
resource, the Android system initializes these run-time objects, corresponding to the elements in your layout.

For example, a simple vertical layout with a text view and a button looks like this:


     <?xml version="1.0" encoding="utf-8"?>
     <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
                   android:layout_width="fill_parent"
                   android:layout_height="fill_parent"
                   android:orientation="vertical" >
         <TextView android:id="@+id/text"
                   android:layout_width="wrap_content"
                   android:layout_height="wrap_content"
                   android:text="Hello, I am a TextView" />
         <Button android:id="@+id/button"
                 android:layout_width="wrap_content"
                 android:layout_height="wrap_content"
                 android:text="Hello, I am a Button" />
     </LinearLayout>

Notice that the LinearLayout element contains both the TextView and the Button. You can nest another LinearLayout
(or other type of view group) inside here, to lengthen the view hierarchy and create a more complex layout.

For more on building a UI layout, read Declaring Layout.

There are a variety of ways in which you can layout your views.
Using more and different kinds of view groups, you can structure
                                                                           Tip: You can also draw View and ViewGroups
child views and view groups in an infinite number of ways. Some
                                                                           objects in Java code, using the
pre-defined view groups offered by Android (called layouts) include        addView(View) methods to dynamically
LinearLayout, RelativeLayout, AbsoluteLayout, TableLayout,                 insert new View and ViewGroup objects.
GridLayout and others. Each offers a unique set of layout
parameters that are used to define the positions of child views and
layout structure.

To learn about some of the different kinds of view groups used for a layout, read Common Layout Objects.



Widgets
A widget is a View object that serves as an interface for interaction with the user. Android provides a set of fully
implemented widgets, like buttons, checkboxes, and text-entry fields, so you can quickly build your UI. Some widgets
provided by Android are more complex, like a date picker, a clock, and zoom controls. But you're not limited to the
kinds of widgets provided by the Android platform. If you'd like to do something more customized and create your own
actionable elements, you can, by defining your own View object or by extending and combining existing widgets.

Read more in Building Custom Components.

For a list of the widgets provided by Android, see the android.widget package.



UI Events

http://developer.android.com/guide/topics/ui/index.html                                                         Page 2 of 4
User Interface | Android Developers                                                                            29.04.09 0:34



Once you've added some Views/widgets to the UI, you probably want to know about the user's interaction with them,
so you can perform actions. To be informed of UI events, you need to do one of two things:

     Define an event listener and register it with the View. More often than not, this is how you'll listen for events.
     The View class contains a collection of nested interfaces named On<something>Listener, each with a callback
     method called On<something>(). For example, View.OnClickListener (for handling "clicks" on a View),
     View.OnTouchListener (for handling touch screen events in a View), and View.OnKeyListener (for handling device
     key presses within a View). So if you want your View to be notified when it is "clicked" (such as when a button is
     selected), implement OnClickListener and define its onClick() callback method (where you perform the action
     upon click), and register it to the View with setOnClickListener().
     Override an existing callback method for the View. This is what you should do when you've implemented your
     own View class and want to listen for specific events that occur within it. Example events you can handle include
     when the screen is touched (onTouchEvent()), when the trackball is moved (onTrackballEvent()), or
     when a key on the device is pressed (onKeyDown()). This allows you to define the default behavior for each
     event inside your custom View and determine whether the event should be passed on to some other child View.
     Again, these are callbacks to the View class, so your only chance to define them is when you build a custom
     component.

Continue reading about handling user interaction with Views in the Handling UI Events document.



Menus
Application menus are another important part of an application's UI. Menus offers a reliable interface that reveals
application functions and settings. The most common application menu is revealed by pressing the MENU key on the
device. However, you can also add Context Menus, which may be revealed when the user presses and holds down on
an item.

Menus are also structured using a View hierarchy, but you don't define this structure yourself. Instead, you define the
onCreateOptionsMenu() or onCreateContextMenu() callback methods for your Activity and declare the items
that you want to include in your menu. At the appropriate time, Android will automatically create the necessary View
hierarchy for the menu and draw each of your menu items in it.

Menus also handle their own events, so there's no need to register event listeners on the items in your menu. When
an item in your menu is selected, the onOptionsItemSelected() or onContextItemSelected() method will
be called by the framework.

And just like your application layout, you have the option to declare the items for you menu in an XML file.

Read Creating Menus to learn more.



Advanced Topics
Once you've grappled the fundamentals of creating a user interface, you can explore some advanced features for
creating a more complex application interface.


Adapters
Sometimes you'll want to populate a view group with some information that can't be hard-coded, instead, you want to
bind your view to an external source of data. To do this, you use an AdapterView as your view group and each child
View is initialized and populated with data from the Adapter.

The AdapterView object is an implementation of ViewGroup that determines its child views based on a given Adapter
object. The Adapter acts like a courier between your data source (perhaps an array of external strings) and the
AdapterView, which displays it. There are several implementations of the Adapter class, for specific tasks, such as the

http://developer.android.com/guide/topics/ui/index.html                                                          Page 3 of 4
User Interface | Android Developers                                                                                   29.04.09 0:34


AdapterView, which displays it. There are several implementations of the Adapter class, for specific tasks, such as the
CursorAdapter for reading database data from a Cursor, or an ArrayAdapter for reading from an arbitrary array.

To learn more about using an Adapter to populate your views, read Binding to Data with AdapterView.


Styles and Themes
Perhaps you're not satisfied with the look of the standard widgets. To revise them, you can create some of your own
styles and themes.

     A style is a set of one or more formatting attributes that you can apply as a unit to individual elements in your
     layout. For example, you could define a style that specifies a certain text size and color, then apply it to only
     specific View elements.
     A theme is a set of one or more formatting attributes that you can apply as a unit to all activities in an application,
     or just a single activity. For example, you could define a theme that sets specific colors for the window frame and
     the panel background, and sets text sizes and colors for menus. This theme can then be applied to specific
     activities or the entire application.

Styles and themes are resources. Android provides some default style and theme resources that you can use, or you
can declare your own custom style and theme resources.

Learn more about using styles and themes in the Applying Styles and Themes document.

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/ui/index.html                                                                 Page 4 of 4
Declaring Layout | Android Developers                                                                               29.04.09 0:36




User Interface >

Declaring Layout

Your layout is the architecture for the user interface in an Activity. It defines the layout structure and holds all the
elements that appear to the user. You can declare your layout in two ways:

     Declare UI elements in XML. Android provides a straightforward XML vocabulary that corresponds to the View
     classes and subclasses, such as those for widgets and layouts.
     Instantiate layout elements at runtime. Your application can create View and ViewGroup objects (and
     manipulate their properties) programmatically.

The Android framework gives you the flexibility to use either or both of these methods for declaring and managing your
application's UI. For example, you could declare your application's default layouts in XML, including the screen
elements that will appear in them and their properties. You could then add code in your application that would modify
the state of the screen objects, including those declared in XML, at run time.

The advantage to declaring your UI in XML is that it enables you to
better separate the presentation of your application from the code           The Android Development Tools (ADT) plugin
that controls its behavior. Your UI descriptions are external to your        for Eclipse offers a layout preview of your XML
application code, which means that you can modify or adapt it                — with the XML file opened, select the Layout
without having to modify your source code and recompile. For                 tab.
example, you can create XML layouts for different screen                     You should also try the Hierarchy Viewer tool,
orientations, different device screen sizes, and different languages.        for debugging layouts — it reveals layout
Additionally, declaring the layout in XML makes it easier to visualize       property values, draws wireframes with
the structure of your UI, so it's easier to debug problems. As such,         padding/margin indicators, and full rendered
                                                                             views while you debug on the emulator or
this document focuses on teaching you how to declare your layout
                                                                             device.
in XML. If you're interested in instantiating View objects at runtime,
refer to the ViewGroup and View class references.

In general, the XML vocabulary for declaring UI elements closely follows the structure and naming of the classes and
methods, where element names correspond to class names and attribute names correspond to methods. In fact, the
correspondence is often so direct that you can guess what XML attribute corresponds to a class method, or guess what
class corresponds to a given xml element. However, note that not all vocabulary is identical. In some cases, there are
slight naming differences. For example, the EditText element has a text attribute that corresponds to
EditText.setText().

     Tip: Learn more about different layout types in Common Layout Objects. There are also a collection of tutorials
     on building various layouts in the Hello Views tutorial guide.



Write the XML
Using Android's XML vocabulary, you can quickly design UI layouts
and the screen elements they contain, in the same way you create             For your convenience, the API reference
web pages in HTML — with a series of nested elements.                        documentation for UI related classes lists the
                                                                             available XML attributes that correspond to the
Each layout file must contain exactly one root element, which must           class methods, including inherited attributes.
be a View or ViewGroup object. Once you've defined the root                  To learn more about the available XML
element, you can add additional layout objects or widgets as child           elements and attributes, as well as the format of
elements to gradually build a View hierarchy that defines your               the XML file, see Layout Resources.
layout. For example, here's an XML layout that uses a vertical

http://developer.android.com/guide/topics/ui/declaring-layout.html                                                     Page 1 of 5
Declaring Layout | Android Developers                                                                           29.04.09 0:36


layout. For example, here's an XML layout that uses a vertical
LinearLayout to hold a TextView and a Button:

     <?xml version="1.0" encoding="utf-8"?>
     <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
                   android:layout_width="fill_parent"
                   android:layout_height="fill_parent"
                   android:orientation="vertical" >
         <TextView android:id="@+id/text"
                   android:layout_width="wrap_content"
                   android:layout_height="wrap_content"
                   android:text="Hello, I am a TextView" />
         <Button android:id="@+id/button"
                 android:layout_width="wrap_content"
                 android:layout_height="wrap_content"
                 android:text="Hello, I am a Button" />
     </LinearLayout>

After you've declared your layout in XML, save the file with the .xml extension, in your Android project's
res/layout/ directory, so it will properly compile.

We'll discuss each of the attributes shown here a little later.



Load the XML Resource
When you compile your application, each XML layout file is compiled into a View resource. You should load the layout
resource from your application code, in your Activity.onCreate() callback implementation. Do so by calling
setContentView(), passing it the reference to your layout resource in the form of:
R.layout.layout_file_name For example, if your XML layout is saved as main_layout.xml, you would load it
for your Activity like so:


     public void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
         setContentView.(R.layout.main_layout);
     }

The onCreate() callback method in your Activity is called by the Android framework when your Activity is launched
(see the discussion on Lifecycles, in the Application Fundamantals, for more on this).



Attributes
Every View and ViewGroup object supports their own variety of XML attributes. Some attributes are specific to a View
object (for example, TextView supports the textSize attribute), but these attributes are also inherited by any View
objects that may extend this class. Some are common to all View objects, because they are inherited from the root
View class (like the id attribute). And, other attributes are considered "layout parameters," which are attributes that
describe certain layout orientations of the View object, as defined by that object's parent ViewGroup object.


ID
Any View object may have an integer ID associated with it, to uniquely identify the View within the tree. When the
application is compiled, this ID is referenced as an integer, but the ID is typically assigned in the layout XML file as a
string, in the id attribute. This is an XML attribute common to all View objects (defined by the View class) and you will
use it very often. The syntax for an ID, inside an XML tag is:



http://developer.android.com/guide/topics/ui/declaring-layout.html                                                Page 2 of 5
Declaring Layout | Android Developers                                                                          29.04.09 0:36


     android:id="@+id/my_button"

The at-symbol (@) at the beginning of the string indicates that the XML parser should parse and expand the rest of
the ID string and identify it as an ID resource. The plus-symbol (+) means that this is a new resource name that must
be created and added to our resources (in the R.java file). There are a number of other ID resources that are offered
by the Android framework. When referencing an Android resource ID, you do not need the plus-symbol, but must add
the android package namespace, like so:

     android:id="@android:id/empty"

With the android package namespace in place, we're now referencing an ID from the android.R resources class,
rather than the local resources class.

In order to create views and reference them from the application, a common pattern is to:

 1. Define a view/widget in the layout file and assign it a unique ID:

           <Button android:id="@+id/my_button"
                   android:layout_width="wrap_content"
                   android:layout_height="wrap_content"
                   android:text="@string/my_button_text"/>

 2. Then create an instance of the view object and capture it from the layout (typically in the onCreate() method):

           Button myButton = (Button) findViewById(R.id.my_button);


Defining IDs for view objects is important when creating a RelativeLayout. In a relative layout, sibling views can define
their layout relative to another sibling view, which is referenced by the unique ID.

An ID need not be unique throughout the entire tree, but it should be unique within the part of the tree you are
searching (which may often be the entire tree, so it's best to be completely unique when possible).


Layout Parameters
XML layout attributes named layout_something define layout parameters for the View that are appropriate for the
ViewGroup in which it resides.

Every ViewGroup class implements a nested class that extends ViewGroup.LayoutParams. This subclass contains
property types that define the size and position for each child view, as appropriate for the view group. As you can see
in the figure below, the parent view group defines layout parameters for each child view (including the child view
group).




http://developer.android.com/guide/topics/ui/declaring-layout.html                                                 Page 3 of 5
Declaring Layout | Android Developers                                                                            29.04.09 0:36




Note that every LayoutParams subclass has its own syntax for setting values. Each child element must define
LayoutParams that are appropriate for its parent, though it may also define different LayoutParams for its own children.

All view groups include a width and height (layout_width and layout_height), and each view is required to
define them. Many LayoutParams also include optional margins and borders. You can specify width and height with
exact measurements, though you probably won't want to do this often. More often, you will tell your view to size itself
either to the dimensions required by its content, or to become as big as its parent view group will allow (with the
wrap_content and fill_parent values, respectively). The accepted measurement types are defined in the Available
Resources document.



Layout Position
The geometry of a view is that of a rectangle. A view has a location, expressed as a pair of left and top coordinates,
and two dimensions, expressed as a width and a height. The unit for location and dimensions is the pixel.

It is possible to retrieve the location of a view by invoking the methods getLeft() and getTop(). The former returns the
left, or X, coordinate of the rectangle representing the view. The latter returns the top, or Y, coordinate of the rectangle
representing the view. These methods both return the location of the view relative to its parent. For instance, when
getLeft() returns 20, that means the view is located 20 pixels to the right of the left edge of its direct parent.

In addition, several convenience methods are offered to avoid unnecessary computations, namely getRight() and
getBottom(). These methods return the coordinates of the right and bottom edges of the rectangle representing the
view. For instance, calling getRight() is similar to the following computation: getLeft() + getWidth().



Size, Padding and Margins
The size of a view is expressed with a width and a height. A view actually possess two pairs of width and height
values.

The first pair is known as measured width and measured height. These dimensions define how big a view wants to be
within its parent. The measured dimensions can be obtained by calling getMeasuredWidth() and getMeasuredHeight().

The second pair is simply known as width and height, or sometimes drawing width and drawing height. These
dimensions define the actual size of the view on screen, at drawing time and after layout. These values may, but do
not have to, be different from the measured width and height. The width and height can be obtained by calling

http://developer.android.com/guide/topics/ui/declaring-layout.html                                                 Page 4 of 5
Declaring Layout | Android Developers                                                                                 29.04.09 0:36



getWidth() and getHeight().

To measure its dimensions, a view takes into account its padding. The padding is expressed in pixels for the left, top,
right and bottom parts of the view. Padding can be used to offset the content of the view by a specific amount of
pixels. For instance, a left padding of 2 will push the view's content by 2 pixels to the right of the left edge. Padding
can be set using the setPadding(int, int, int, int) method and queried by calling getPaddingLeft(), getPaddingTop(),
getPaddingRight() and getPaddingBottom().

Even though a view can define a padding, it does not provide any support for margins. However, view groups provide
such a support. Refer to ViewGroup and ViewGroup.MarginLayoutParams for further information.

For more information about dimensions, see Dimension Values.

" Back to User Interface                                                                                             ! Go to top

Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/ui/declaring-layout.html                                                      Page 5 of 5
Creating Menus | Android Developers                                                                           29.04.09 0:37




User Interface >

Creating Menus

Menus are an important part of any application. They provide familiar interfaces that reveal application functions and
settings. Android offers an easy programming interface for developers to provide standardized application menus for
various situations.

Android offers three fundamental types of application menus:

Options Menu
    This is the primary set of menu items for an Activity. It is revealed by pressing the device MENU key. Within the
    Options Menu are two groups of menu items:

     Icon Menu
         This is the collection of items initially visible at the bottom of the screen at the press of the MENU key. It
         supports a maximum of six menu items. These are the only menu items that support icons and the only menu
         items that do not support checkboxes or radio buttons.

     Expanded Menu
        This is a vertical list of items exposed by the "More" menu item from the Icon Menu. It exists only when the
        Icon Menu becomes over-loaded and is comprised of the sixth Option Menu item and the rest.

Context Menu
   This is a floating list of menu items that may appear when you perform a long-press on a View (such as a list
   item).

Submenu
   This is a floating list of menu items that is revealed by an item in the Options Menu or a Context Menu. A
   Submenu item cannot support nested Submenus.



Options Menu
The Options Menu is opened by pressing the device MENU key. When opened,
the Icon Menu is displayed, which holds the first six menu items. If more than six
items are added to the Options Menu, then those that can't fit in the Icon Menu
are revealed in the Expanded Menu, via the "More" menu item. The Expanded
Menu is automatically added when there are more than six items.

The Options Menu is where you should include basic application functions and
any necessary navigation items (e.g., to a home screen or application settings).
You can also add Submenus for organizing topics and including extra menu
functionality.

When this menu is opened for the first time, the Android system will call the
Activity onCreateOptionsMenu() callback method. Override this method in
your Activity and populate the Menu object given to you. You can populate the
menu by inflating a menu resource that was defined in XML, or by calling add()
for each item you'd like in the menu. This method adds a MenuItem, and returns
the newly created object to you. You can use the returned MenuItem to set
additional properties like an icon, a keyboard shortcut, an intent, and other settings
for the item.

http://developer.android.com/guide/topics/ui/menus.html                                                         Page 1 of 8
Creating Menus | Android Developers                                                                             29.04.09 0:37


for the item.

There are multiple add() methods. Usually, you'll want to use one that accepts an
itemId argument. This is a unique integer that allows you to identify the item during a callback.

When a menu item is selected from the Options Menu, you will recieve a callback to the
onOptionsItemSelected() method of your Activity. This callback passes you the MenuItem that has been
selected. You can identify the item by requesting the itemId, with getItemId(), which returns the integer that was
assigned with the add() method. Once you identify the menu item, you can take the appropriate action.

Here's an example of this procedure, inside an Activity, wherein we create an Options Menu and handle item
selections:

     /* Creates the menu items */
     public boolean onCreateOptionsMenu(Menu menu) {
         menu.add(0, MENU_NEW_GAME, 0, "New Game");
         menu.add(0, MENU_QUIT, 0, "Quit");
         return true;
     }
     /* Handles item selections */
     public boolean onOptionsItemSelected(MenuItem item) {
         switch (item.getItemId()) {
         case MENU_NEW_GAME:
             newGame();
             return true;
         case MENU_QUIT:
             quit();
             return true;
         }
         return false;
     }

The add() method used in this sample takes four arguments: groupId, itemId, order, and title. The groupId allows
you to associate this menu item with a group of other items (more about Menu groups, below) — in this example, we
ignore it. itemId is a unique integer that we give the MenuItem so that can identify it in the next callback. order allows
us to define the display order of the item — by default, they are displayed by the order in which we add them. title is,
of course, the name that goes on the menu item (this can also be a string resource, and we recommend you do it that
way for easier localization).

     Tip: If you have several menu items that can be grouped together with a title, consider organizing them into a
     Submenu.


Adding icons
Icons can also be added to items that appears in the Icon Menu with setIcon(). For example:


     menu.add(0, MENU_QUIT, 0, "Quit")
         .setIcon(R.drawable.menu_quit_icon);


Modifying the menu
If you want to sometimes re-write the Options Menu as it is opened, override the onPrepareOptionsMenu()
method, which is called each time the menu is opened. This will pass you the Menu object, just like the
onCreateOptionsMenu() callback. This is useful if you'd like to add or remove menu options depending on the
current state of an application or game.

     Note: When changing items in the menu, it's bad practice to do so based on the currently selected item. Keep
     in mind that, when in touch mode, there will not be a selected (or focused) item. Instead, you should use a
     Context Menu for such behaviors, when you want to provide functionality based on a particular item in the UI.
http://developer.android.com/guide/topics/ui/menus.html                                                           Page 2 of 8
Creating Menus | Android Developers                                                                             29.04.09 0:37


     Context Menu for such behaviors, when you want to provide functionality based on a particular item in the UI.



Context Menu
The Android context menu is similar, in concept, to the menu revealed with a "right-click" on a PC. When a view is
registered to a context menu, performing a "long-press" (press and hold for about two seconds) on the object will
reveal a floating menu that provides functions relating to that item. Context menus can be registered to any View
object, however, they are most often used for items in a ListView, which helpfully indicates the presence of the context
menu by transforming the background color of the ListView item when pressed. (The items in the phone's contact list
offer an example of this feature.)

     Note: Context menu items do not support icons or shortcut keys.

To create a context menu, you must override the Activity's context menu callback methods:
onCreateContextMenu() and onContextItemSelected(). Inside the onCreateContextMenu() callback
method, you can add menu items using one of the add() methods, or by inflating a menu resource that was defined
in XML. Then, register a ContextMenu for the View, with registerForContextMenu().

For example, here is some code that can be used with the Notepad application to add a context menu for each note
in the list:

     public void onCreateContextMenu(ContextMenu menu, View v,
                                     ContextMenuInfo menuInfo) {
       super.onCreateContextMenu(menu, v, menuInfo);
       menu.add(0, EDIT_ID, 0, "Edit");
       menu.add(0, DELETE_ID, 0, "Delete");
     }

     public boolean onContextItemSelected(MenuItem item) {
       AdapterContextMenuInfo info = (AdapterContextMenuInfo) item.getMenuInfo();
       switch (item.getItemId()) {
       case EDIT_ID:
         editNote(info.id);
         return true;
       case DELETE_ID:
         deleteNote(info.id);
         return true;
       default:
         return super.onContextItemSelected(item);
       }
     }

In onCreateContextMenu(), we are given not only the ContextMenu to which we will add MenuItems, but also the
View that was selected and a ContextMenuInfo object, which provides additional information about the object that was
selected. In this example, nothing special is done in onCreateContextMenu() — just a couple items are added as
usual. In the onContextItemSelected() callback, we request the AdapterContextMenuInfo from the MenuItem,
which provides information about the currently selected item. All we need from this is the list ID for the selected item,
so whether editing a note or deleting it, we find the ID with the AdapterContextMenuInfo.info field of the object.
This ID is passed to the editNote() and deleteNote() methods to perfrom the respective action.

Now, to register this context menu for all the items in a ListView, we pass the entire ListView to the
registerForContextMenu(View) method:

     registerForContextMenu(getListView());

Remember, you can pass any View object to register a context menu. Here, getListView() returns the ListView
object used in the Notepad application's ListActivity. As such, each item in the list is registered to this context menu.


http://developer.android.com/guide/topics/ui/menus.html                                                            Page 3 of 8
Creating Menus | Android Developers                                                                            29.04.09 0:37




Submenus
A sub menu can be added within any menu, except another sub menu. These are very useful when your application
has a lot of functions that may be organized in topics, like the items in a PC application's menu bar (File, Edit, View,
etc.).

A sub menu is created by adding it to an existing Menu with addSubMenu(). This returns a SubMenu object (an
extension of Menu). You can then add additional items to this menu, with the normal routine, using the add()
methods. For example:

     public boolean onCreateOptionsMenu(Menu menu) {
       boolean result = super.onCreateOptionsMenu(menu);
         SubMenu fileMenu = menu.addSubMenu("File");
         SubMenu editMenu = menu.addSubMenu("Edit");
         fileMenu.add("new");
         fileMenu.add("open");
         fileMenu.add("save");
         editMenu.add("undo");
         editMenu.add("redo");

         return result;
     }

Callbacks for items selected in a sub menu are made to the parent menu's callback method. For the example above,
selections in the sub menu will be handled by the onOptionsItemSelected() callback.

You can also add Submenus when you define the parent menu in XML.



Define Menus in XML
Just like Android UI layouts, you can define application menus in XML, then inflate them in your menu's
onCreate...() callback method. This makes your application code cleaner and separates more interface design into
XML, which is easier to visualize.

To start, create a new folder in your project res/ directory called menu. This is where you should keep all XML files
that define your application menus.

In a menu XML layout, there are three valid elements: <menu>, <group> and <item>. The item and group
elements must be children of a menu, but item elements may also be the children of a group, and another menu
element may be the child of an item (to create a Submenu). Of course, the root node of any file must be a menu
element.

As an example, we'll define the same menu created in the Options Menu section, above. We start with an XML file
named options_menu.xml inside the res/menu/ folder:

     <menu xmlns:android="http://schemas.android.com/apk/res/android">
         <item android:id="@+id/new_game"
               android:title="New Game" />
         <item android:id="@+id/quit"
               android:title="Quit" />
     </menu>

Then, in the onCreateOptionsMenu() method, we inflate this resource using MenuInflater.inflate():




http://developer.android.com/guide/topics/ui/menus.html                                                           Page 4 of 8
Creating Menus | Android Developers                                                                         29.04.09 0:37


     public boolean onCreateOptionsMenu(Menu menu) {
         MenuInflater inflater = getMenuInflater();
         inflater.inflate(R.menu.options_menu, menu);
         return true;
     }

The getMenuInflater() method returns the MenuInflater for our activity's context. We then call inflate(),
passing it a pointer to our menu resource and the Menu object given by the callback.

While this small sample may seem like more effort, compared to creating the menu items in the
onCreateOptionsMenu() method, this will save a lot of trouble when dealing with more items and it keeps your
application code clean.

You can define menu groups by wrapping item elements in a group element, and create Submenus by nesting
another menu inside an item. Each element also supports all the necessary attributes to control features like shortcut
keys, checkboxes, icons, and more. To learn about these attributes and more about the XML syntax, see the Menus
topic in the Available Resource Types document.



Menu Features
Here are some other features that can be applied to most menu items.


Menu groups
When adding new items to a menu, you can optionally include each item in a group. A menu group is a collection of
menu items that can share certain traits, like whether they are visible, enabled, or checkable.

A group is defined by an integer (or a resource id, in XML). A menu item is added to the group when it is added to the
menu, using one of the add() methods that accepts a groupId as an argument, such as add(int, int, int,
int).

You can show or hide the entire group with setGroupVisible(); enable or disable the group with
setGroupEnabled(); and set whether the items can be checkable with setGroupCheckable().


Checkable menu items
Any menu item can be used as an interface for turning options on and off. This
can be indicated with a checkbox for stand-alone options, or radio buttons for
groups of mutually exlusive options (see the screenshot, to the right).

     Note: Menu items in the Icon Menu cannot display a checkbox or radio
     button. If you choose to make items in the Icon Menu checkable, then you
     must personally indicate the state by swapping the icon and/or text each time
     the state changes between on and off.

To make a single item checkable, use the setCheckable() method, like so:


     menu.add(0, VIBRATE_SETTING_ID, 0, "Vibrate")
         .setCheckable(true);

This will display a checkbox with the menu item (unless it's in the Icon Menu).
When the item is selected, the onOptionsItemSelected() callback is called
as usual. It is here that you must set the state of the checkbox. You can query
the current state of the item with isChecked() and set the checked state with
setChecked(). Here's what this looks like inside the
onOptionsItemSelected() callback:

http://developer.android.com/guide/topics/ui/menus.html                                                       Page 5 of 8
Creating Menus | Android Developers                                                                           29.04.09 0:37


onOptionsItemSelected() callback:

     switch (item.getItemId()) {
     case VIBRATE_SETTING_ID:
       if (item.isChecked()) item.setChecked(false);
       else item.setChecked(true);
       return true;
     ...
     }

To make a group of mutually exclusive radio button items, simply assign the same group ID to each menu item and
call setGroupCheckable(). In this case, you don't need to call setCheckable() on each menu items, because
the group as a whole is set checkable. Here's an example of two mutually exclusive options in a Submenu:

     SubMenu subMenu = menu.addSubMenu("Color");
     subMenu.add(COLOR_MENU_GROUP, COLOR_RED_ID, 0, "Red");
     subMenu.add(COLOR_MENU_GROUP, COLOR_BLUE_ID, 0, "Blue");
     subMenu.setGroupCheckable(COLOR_MENU_GROUP, true, true);

In the setGroupCheckable() method, the first argument is the group ID that we want to set checkable. The second
argument is whether we want the group items to be checkable. The last one is whether we want each item to be
exclusively checkable (if we set this false, then all the items will be checkboxes instead of radio buttons). When the
group is set to be exclusive (radio buttons), each time a new item is selected, all other are automatically de-selected.

     Note: Checkable menu items are intended to be used only on a per-session basis and not saved to the device
     (e.g., the Map mode setting in the Maps application is not saved — screenshot above). If there are application
     settings that you would like to save for the user, then you should store the data using Preferences, and manage
     them with a PreferenceActivity.


Shortcut keys
Quick access shortcut keys using letters and/or numbers can be added to menu items with
setAlphabeticShortcut(char) (to set char shortcut), setNumericShortcut(int) (to set numeric shortcut),
or setShortcut(char,int) (to set both). Case is not sensitive. For example:

     menu.add(0, MENU_QUIT, 0, "Quit")
         .setAlphabeticShortcut('q');

Now, when the menu is open (or while holding the MENU key), pressing the "q" key will select this item.

This shortcut key will be displayed as a tip in the menu item, below the menu item name (except for items in the Icon
Menu).

     Note: Shortcuts cannot be added to items in a Context Menu.


Menu item intents
If you've read the Application Fundamentals, then you're at least a little familiar with Android Intents. These allow
applications to bind with each other, share information, and perform user tasks cooperatively. Just like your application
might fire an Intent to launch a web browser, an email client, or another Activity in your application, you can perform
such actions from within a menu. There are two ways to do this: define an Intent and assign it to a single menu item,
or define an Intent and allow Android to search the device for activities and dynamically add a menu item for each one
that meets the Intent criteria.

For more information on creating Intents and providing your application's services to other applications, read the
Intents and Intent Filters document.


http://developer.android.com/guide/topics/ui/menus.html                                                          Page 6 of 8
Creating Menus | Android Developers                                                                                 29.04.09 0:37



Set an intent for a single menu item
If you want to offer a specific menu item that launches a new Activity, then you can specifically define an Intent for the
menu item with the setIntent() method.

For example, inside the onCreateOptionsMenu() method, you can define a new menu item with an Intent like this:

     MenuItem menuItem = menu.add(0, PHOTO_PICKER_ID, 0, "Select Photo");
     menuItem.setIntent(new Intent(this, PhotoPicker.class));

Android will automatically launch the Activity when the item is selected.

     Note: This will not return a result to your Activity. If you wish to be returned a result, then do not use
     setIntent(). Instead, handle the selection as usual in the onOptionsMenuItemSelected() or
     onContextMenuItemSelected() callback and call startActivityForResult().

Dynamically add intents
If there are potentially multiple activities that are relevant to your current Activity or selected item, then the application
can dynamically add menu items that execute other services.

During menu creation, define an Intent with the category Intent.ALTERNATIVE_CATEGORY and/or
Intent.SELECTED_ALTERNATIVE, the MIME type currently selected (if any), and any other requirements, the same
way as you would satisfy an intent filter to open a new Activity. Then call addIntentOptions() to have Android
search for any services meeting those requirements and add them to the menu for you. If there are no applications
installed that satisfy the Intent, then no additional menu items are added.

     Note: SELECTED_ALTERNATIVE is used to handle the currently selected element on the screen. So, it should
     only be used when creating a Menu in onCreateContextMenu() or onPrepareOptionsMenu(), which is
     called every time the Options Menu is opened.

Here's an example demonstrating how an application would search for additional services to display on its menu.


     public boolean onCreateOptionsMenu(Menu menu){
         super.onCreateOptionsMenu(menu);

         // Create an Intent that describes the requirements to fulfill, to be included
         // in our menu. The offering app must include a category value of
     Intent.CATEGORY_ALTERNATIVE.
         Intent intent = new Intent(null, getIntent().getData());
         intent.addCategory(Intent.CATEGORY_ALTERNATIVE);

            // Search for, and populate the menu with, acceptable offering applications.
            menu.addIntentOptions(
                 thisClass.INTENT_OPTIONS, // Menu group
                 0,      // Unique item ID (none)
                 0,      // Order for the items (none)
                 this.getComponentName(),   // The current Activity name
                 null,   // Specific items to place first (none)
                 intent, // Intent created above that describes our requirements
                 0,      // Additional flags to control items (none)
                 null); // Array of MenuItems that corrolate to specific items (none)
            return true;
     }

For each Activity found that provides an Intent Filter matching the Intent defined, a menu item will be added, using the
android:label value of the intent filter as the text for the menu item. The addIntentOptions() method will also
return the number of menu items added.

Also be aware that, when addIntentOptions() is called, it will override any and all menu items in the menu group
specified in the first argument.

http://developer.android.com/guide/topics/ui/menus.html                                                                Page 7 of 8
Creating Menus | Android Developers                                                                                   29.04.09 0:37



If you wish to offer the services of your Activity to other application menus, then you only need to define an intent filter
as usual. Just be sure to include the ALTERNATIVE and/or SELECTED_ALTERNATIVE values in the name attribute
of a <category> element in the intent filter. For example:

     <intent-filter label="Resize Image">
         ...
         <category android:name="android.intent.category.ALTERNATIVE" />
         <category android:name="android.intent.category.SELECTED_ALTERNATIVE" />
         ...
     </intent-filter>

read more about writing intent filters in the Intents and Intent Filters document.

For a sample application using this technique, see the Note Pad sample code.

" Back to User Interface                                                                                             ! Go to top

Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/ui/menus.html                                                                 Page 8 of 8
Creating Dialogs | Android Developers                                                                              29.04.09 0:37




User Interface >

Creating Dialogs

A dialog is usually a small window that appears in front of the current Activity. The underlying Activity loses focus and
the dialog accepts all user interaction. Dialogs are normally used for notifications and short activities that directly relate
to the application in progress.

The Android API supports the following types of Dialog objects:

AlertDialog
     A dialog that can manage zero, one, two, or three buttons, and/or a list of selectable items that can include
     checkboxes or radio buttons. The AlertDialog is capable of constructing most dialog user interfaces and is the
     suggested dialog type. See Creating an AlertDialog below.

ProgressDialog
    A dialog that displays a progress wheel or progress bar. Because it's an extension of the AlertDialog, it also
    supports buttons. See Creating a ProgressDialog below.

DatePickerDialog
    A dialog that allows the user to select a date. See the Hello DatePicker tutorial.

TimePickerDialog
    A dialog that allows the user to select a time. See the Hello TimePicker tutorial.

If you would like to customize your own dialog, you can extend the base Dialog object or any of the subclasses listed
above and define a new layout. See the section on Creating a Custom Dialog below.



Showing a Dialog
A dialog is always created and displayed as a part of an Activity. You should normally create dialogs from within your
Activity's onCreateDialog(int) callback method. When you use this callback, the Android system automatically manages
the state of each dialog and hooks them to the Activity, effectively making it the "owner" of each dialog. As such, each
dialog inherits certain properties from the Activity. For example, when a dialog is open, the Menu key reveals the
options menu defined for the Activity and the volume keys modify the audio stream used by the Activity.

     Note: If you decide to create a dialog outside of the onCreateDialog() method, it will not be attached to an
     Activity. You can, however, attach it to an Activity with setOwnerActivity(Activity).

When you want to show a dialog, call showDialog(int) and pass it an integer that uniquely identifies the dialog that you
want to display.

When a dialog is requested for the first time, Android calls onCreateDialog(int) from your Activity, which is where you
should instantiate the Dialog. This callback method is passed the same ID that you passed to showDialog(int). After
you create the Dialog, return the object at the end of the method.

Before the dialog is displayed, Android also calls the optional callback method onPrepareDialog(int, Dialog). Define this
method if you want to change any properties of the dialog each time it is opened. This method is called every time a
dialog is opened, whereas onCreateDialog(int) is only called the very first time a dialog is opened. If you don't define
onPrepareDialog(), then the dialog will remain the same as it was the previous time it was opened. This method is
also passed the dialog's ID, along with the Dialog object you created in onCreateDialog().


http://developer.android.com/guide/topics/ui/dialogs.html                                                            Page 1 of 7
Creating Dialogs | Android Developers                                                                             29.04.09 0:37


The best way to define the onCreateDialog(int) and onPrepareDialog(int, Dialog) callback methods is with a switch
statement that checks the id parameter that's passed into the method. Each case should check for a unique dialog ID
and then create and define the respective Dialog. For example, imagine a game that uses two different dialogs: one to
indicate that the game has paused and another to indicate that the game is over. First, define an integer ID for each
dialog:

     static final int DIALOG_PAUSED_ID = 0;
     static final int DIALOG_GAMEOVER_ID = 1;

Then, define the onCreateDialog(int) callback with a switch case for each ID:

     protected Dialog onCreateDialog(int id) {
         Dialog dialog;
         switch(id) {
         case DIALOG_PAUSED_ID:
             // do the work to define the pause Dialog
             break;
         case DIALOG_GAMEOVER_ID:
             // do the work to define the game over Dialog
             break;
         default:
             dialog = null;
         }
         return dialog;
     }

     Note: In this example, there's no code inside the case statements because the procedure for defining your
     Dialog is outside the scope of this section. See the section below about Creating an AlertDialog, offers code
     suitable for this example.

When it's time to show one of the dialogs, call showDialog(int) with the ID of a dialog:


     showDialog(DIALOG_PAUSED_ID);




Dismissing a Dialog
When you're ready to close your dialog, you can dismiss it by calling dismiss() on the Dialog object. If necessary, you
can also call dismissDialog(int) from the Activity, which effectively calls dismiss() on the Dialog for you.

If you are using onCreateDialog(int) to manage the state of your dialogs (as discussed in the previous section), then
every time your dialog is dismissed, the state of the Dialog object is retained by the Activity. If you decide that you will
no longer need this object or it's important that the state is cleared, then you should call removeDialog(int). This will
remove any internal references to the object and if the dialog is showing, it will dismiss it.


Using dismiss listeners
If you'd like your applcation to perform some procedures the moment that a dialog is dismissed, then you should
attach an on-dismiss listener to your Dialog.

First define the DialogInterface.OnDismissListener interface. This interface has just one method,
onDismiss(DialogInterface), which will be called when the dialog is dismissed. Then simply pass your
OnDismissListener implementation to setOnDismissListener().

However, note that dialogs can also be "cancelled." This is a special case that indicates the dialog was explicitly
cancelled by the user. This will occur if the user presses the "back" button to close the dialog, or if the dialog explicitly
calls cancel() (perhaps from a "Cancel" button in the dialog). When a dialog is cancelled, the OnDismissListener will
still be notified, but if you'd like to be informed that the dialog was explicitly cancelled (and not dismissed normally),
http://developer.android.com/guide/topics/ui/dialogs.html                                                            Page 2 of 7
Creating Dialogs | Android Developers                                                                              29.04.09 0:37


still be notified, but if you'd like to be informed that the dialog was explicitly cancelled (and not dismissed normally),
then you should register an DialogInterface.OnCancelListener with setOnCancelListener().



Creating an AlertDialog
An AlertDialog is an extension of the Dialog class. It is capable of constructing most dialog user interfaces and is the
suggested dialog type. You should use it for dialogs that use any of the following features:

     A title
     A text message
     One, two, or three buttons
     A list of selectable items (with optional checkboxes or radio buttons)

To create an AlertDialog, use the AlertDialog.Builder subclass. Get a Builder with AlertDialog.Builder(Context) and then
use the class's public methods to define all of the AlertDialog properties. After you're done with the Builder, retrieve
the AlertDialog object with create().

The following topics show how to define various properties of the AlertDialog using the AlertDialog.Builder class. If you
use any of the following sample code inside your onCreateDialog() callback method, you can return the resulting Dialog
object to display the dialog.


Adding buttons
To create an AlertDialog with side-by-side buttons like the one shown in the
screenshot to the right, use the set...Button() methods:


     AlertDialog.Builder builder = new
     AlertDialog.Builder(this);
     builder.setMessage("Are you sure you want to exit?")
            .setCancelable(false)
            .setPositiveButton("Yes", new
     DialogInterface.OnClickListener() {
                public void onClick(DialogInterface dialog, int id) {
                     MyActivity.this.finish();
                }
            })
            .setNegativeButton("No", new DialogInterface.OnClickListener() {
                public void onClick(DialogInterface dialog, int id) {
                     dialog.cancel();
                }
            });
     AlertDialog alert = builder.create();

First, add a message for the dialog with setMessage(CharSequence). Then, begin method-chaining and set the dialog
to be not cancelable (so the user cannot close the dialog with the back button) with setCancelable(boolean). For each
button, use one of the set...Button() methods, such as setPositiveButton(), that accepts the name for the button
and a DialogInterface.OnClickListener that defines the action to take when the user selects the button.

     Note: You can only add one of each button type to the AlertDialog. That is, you cannot have more than one
     "positive" button. This limits the number of possible buttons to three: positive, neutral, and negative. These
     names are technically irrelevant to the actual functionality of your buttons, but should help you keep track of
     which one does what.


Adding a list
To create an AlertDialog with a list of selectable items like the one shown to the
right, use the setItems() method:
http://developer.android.com/guide/topics/ui/dialogs.html                                                            Page 3 of 7
Creating Dialogs | Android Developers                                                                           29.04.09 0:37


right, use the setItems() method:


     final CharSequence[] items = {"Red", "Green", "Blue"};
     AlertDialog.Builder builder = new
     AlertDialog.Builder(this);
     builder.setTitle("Pick a color");
     builder.setItems(items, new
     DialogInterface.OnClickListener() {
         public void onClick(DialogInterface dialog, int item)
     {
             Toast.makeText(getApplicationContext(),
     items[item], Toast.LENGTH_SHORT).show();
         }
     });
     AlertDialog alert = builder.create();

First, add a title to the dialog with setTitle(CharSequence). Then, add a list of selectable items with setItems(), which
accepts the array of items to display and a DialogInterface.OnClickListener that defines the action to take when the
user selects an item.

Adding checkboxes and radio buttons
To create a list of multiple-choice items (checkboxes) or single-choice items (radio
buttons) inside the dialog, use the setMultiChoiceItems() and
setSingleChoiceItems() methods, respectively. If you create one of these
selectable lists in the onCreateDialog() callback method, Android manages the
state of the list for you. As long as the Activity is active, the dialog remembers the
items that were previously selected, but when the user exits the Activity, the
selection is lost.

     Note: To save the selection when the user leaves or pauses the Activity, you
     must properly save and restore the setting throughout the Activity Lifecycle.
     To permanently save the selections, even when the Activity process is
     completely shutdown, you need to save the settings with one of the Data
     Storage techniques.

To create an AlertDialog with a list of single-choice items like the one shown to the right, use the same code from the
previous example, but replace the setItems() method with setSingleChoiceItems():

     final CharSequence[] items = {"Red", "Green", "Blue"};

     AlertDialog.Builder builder = new AlertDialog.Builder(this);
     builder.setTitle("Pick a color");
     builder.setSingleChoiceItems(items, -1, new DialogInterface.OnClickListener() {
         public void onClick(DialogInterface dialog, int item) {
             Toast.makeText(getApplicationContext(), items[item],
     Toast.LENGTH_SHORT).show();
         }
     });
     AlertDialog alert = builder.create();

The second parameter in the setSingleChoiceItems() method is an integer value for the checkedItem, which indicates
the zero-based list position of the default selected item. Use "-1" to indicate that no item should be selected by default.



Creating a ProgressDialog
A ProgressDialog is an extension of the AlertDialog class that can display a
progress animation in the form of a spinning wheel, for a task with progress that's
undefined, or a progress bar, for a task that has a defined progression. The dialog
http://developer.android.com/guide/topics/ui/dialogs.html                                                          Page 4 of 7
Creating Dialogs | Android Developers                                                                            29.04.09 0:37


undefined, or a progress bar, for a task that has a defined progression. The dialog
can also provide buttons, such as one to cancel a download.

Opening a progress dialog can be as simple as calling ProgressDialog.show(). For
example, the progress dialog shown to the right can be easily achieved without
managing the dialog through the onCreateDialog(int) callback, as shown here:


     ProgressDialog dialog = ProgressDialog.show(MyActivity.this, "",
                             "Loading. Please wait...", true);

The first parameter is the application Context, the second is a title for the dialog (left empty), the third is the message,
and the last parameter is whether the progress is indeterminate (this is only relevant when creating a progress bar,
which is discussed in the next section).

The default style of a progress dialog is the spinning wheel. If you want to create a progress bar that shows the
loading progress with granularity, some more code is required, as discussed in the next section.


Showing a progress bar
To show the progression with an animated progress bar:

 1. Initialize the ProgressDialog with the class constructor,
    ProgressDialog(Context).
 2. Set the progress style to "STYLE_HORIZONTAL" with setProgressStyle(int)
    and set any other properties, such as the message.
 3. When you're ready to show the dialog, call show() or return the
    ProgressDialog from the onCreateDialog(int) callback.
 4. You can increment the amount of progress displayed in the bar by calling either setProgress(int) with a value for
    the total percentage completed so far or incrementProgressBy(int) with an incremental value to add to the total
    percentage completed so far.

For example, your setup might look like this:

     ProgressDialog progressDialog;
     progressDialog = new ProgressDialog(mContext);
     progressDialog.setProgressStyle(ProgressDialog.STYLE_HORIZONTAL);
     progressDialog.setMessage("Loading...");
     progressDialog.setCancelable(false);

The setup is simple. Most of the code needed to create a progress dialog is actually involved in the process that
updates it. You might find that it's necessary to create a second thread in your application for this work and then report
the progress back to the Activity's UI thread with a Handler object. If you're not familiar with using additional threads
with a Handler, see the example Activity below that uses a second thread to increment a progress dialog managed by
the Activity.

  Example ProgressDialog with a second thread



Creating a Custom Dialog
If you want a customized design for a dialog, you can create your own layout for
the dialog window with layout and widget elements. After you've defined your
layout, pass the root View object or layout resource ID to setContentView(View).

For example, to create the dialog shown to the right:

http://developer.android.com/guide/topics/ui/dialogs.html                                                           Page 5 of 7
Creating Dialogs | Android Developers                                                                            29.04.09 0:37



 1. Create an XML layout saved as custom_dialog.xml:

           <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
                         android:id="@+id/layout_root"
                         android:orientation="horizontal"
                         android:layout_width="fill_parent"
                         android:layout_height="fill_parent"
                         android:padding="10dp"
                         >
               <ImageView android:id="@+id/image"
                           android:layout_width="wrap_content"
                           android:layout_height="fill_parent"
                           android:layout_marginRight="10dp"
                           />
               <TextView android:id="@+id/text"
                         android:layout_width="wrap_content"
                         android:layout_height="fill_parent"
                         android:textColor="#FFF"
                         />
           </LinearLayout>

     This XML defines an ImageView and a TextView inside a LinearLayout.
 2. Set the above layout as the dialog's content view and define the content for the ImageView and TextView
    elements:

           Context mContext = getApplicationContext();
           Dialog dialog = new Dialog(mContext);

           dialog.setContentView(R.layout.custom_dialog);
           dialog.setTitle("Custom Dialog");

           TextView text = (TextView) dialog.findViewById(R.id.text);
           text.setText("Hello, this is a custom dialog!");
           ImageView image = (ImageView) dialog.findViewById(R.id.image);
           image.setImageResource(R.drawable.android);

     After you instantiate the Dialog, set your custom layout as the dialog's content view with setContentView(int),
     passing it the layout resource ID. Now that the Dialog has a defined layout, you can capture View objects from the
     layout with findViewById(int) and modify their content.
 3. That's it. You can now show the dialog as described in Showing A Dialog.

A dialog made with the base Dialog class must have a title. If you don't call setTitle(), then the space used for the title
remains empty, but still visible. If you don't want a title at all, then you should create your custom dialog using the
AlertDialog class. However, because an AlertDialog is created easiest with the AlertDialog.Builder class, you do not
have access to the setContentView(int) method used above. Instead, you must use setView(View). This method
accepts a View object, so you need to inflate the layout's root View object from XML.

To inflate the XML layout, retrieve the LayoutInflater with getLayoutInflater() (or getSystemService()), and then call
inflate(int, ViewGroup), where the first parameter is the layout resource ID and the second is the ID of the root View.
At this point, you can use the inflated layout to find View objects in the layout and define the content for the
ImageView and TextView elements. Then instantiate the AlertDialog.Builder and set the inflated layout for the dialog
with setView(View).

Here's an example, creating a custom layout in an AlertDialog:


     AlertDialog.Builder builder;
     AlertDialog alertDialog;
     Context mContext = getApplicationContext();
     LayoutInflater inflater = (LayoutInflater)
     mContext.getSystemService(LAYOUT_INFLATER);
     View layout = inflater.inflate(R.layout.custom_dialog,

http://developer.android.com/guide/topics/ui/dialogs.html                                                          Page 6 of 7
Creating Dialogs | Android Developers                                                                                 29.04.09 0:37

     View layout = inflater.inflate(R.layout.custom_dialog,
                                    (ViewGroup) findViewById(R.id.layout_root));
     TextView text = (TextView) layout.findViewById(R.id.text);
     text.setText("Hello, this is a custom dialog!");
     ImageView image = (ImageView) layout.findViewById(R.id.image);
     image.setImageResource(R.drawable.android);

     builder = new AlertDialog.Builder(mContext);
     builder.setView(layout);
     alertDialog = builder.create();

Using an AlertDialog for your custom layout lets you take advantage of built-in AlertDialog features like managed
buttons, selectable lists, a title, an icon and so on.

For more information, refer to the reference documentation for the Dialog and AlertDialog.Builder classes.

" Back to User Interface                                                                                             ! Go to top

Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/ui/dialogs.html                                                               Page 7 of 7
Handling UI Events | Android Developers                                                                       29.04.09 0:37




User Interface >

Handling UI Events

On Android, there's more than one way to intercept the events from a user's interaction with your application. When
considering events within your user interface, the approach is to capture the events from the specific View object that
the user interacts with. The View class provides the means to do so.

Within the various View classes that you'll use to compose your layout, you may notice several public callback methods
that look useful for UI events. These methods are called by the Android framework when the respective action occurs
on that object. For instance, when a View (such as a Button) is touched, the onTouchEvent() method is called on
that object. However, in order to intercept this, you must extend the class and override the method. Obviously,
extending every View object you want to use (just to handle an event) would be obsurd. This is why the View class
also contains a collection of nested interfaces with callbacks that you can much more easily define. These interfaces,
called event listeners, are your ticket to capturing the user interaction with your UI.

While you will more commonly use the event listeners to listen for user interaction, there may come a time when you
do want to extend a View class, in order to build a custom component. Perhaps you want to extend the Button class to
make something more fancy. In this case, you'll be able to define the default event behaviors for your class using the
class event handlers.



Event Listeners
An event listener is an interface in the View class that contains a single callback method. These methods will be called
by the Android framework when the View to which the listener has been registered is triggered by user interaction with
the item in the UI.

Included in the event listener interfaces are the following callback methods:

onClick()
   From View.OnClickListener. This is called when the user either touches the item (when in touch mode), or focuses
   upon the item with the navigation-keys or trackball and presses the suitable "enter" key or presses down on the
   trackball.

onLongClick()
   From View.OnLongClickListener. This is called when the user either touches and holds the item (when in touch
   mode), or focuses upon the item with the navigation-keys or trackball and presses and holds the suitable "enter"
   key or presses and holds down on the trackball (for one second).

onFocusChange()
   From View.OnFocusChangeListener. This is called when the user navigates onto or away from the item, using the
   navigation-keys or trackball.

onKey()
   From View.OnKeyListener. This is called when the user is focused on the item and presses or releases a key on
   the device.

onTouch()
   From View.OnTouchListener. This is called when the user performs an action qualified as a touch event, including
   a press, a release, or any movement gesture on the screen (within the bounds of the item).

onCreateContextMenu()

http://developer.android.com/guide/topics/ui/ui-events.html                                                     Page 1 of 4
Handling UI Events | Android Developers                                                                          29.04.09 0:37



     From View.OnCreateContextMenuListener. This is called when a Context Menu is being built (as the result of a
     sustained "long click"). See the discussion on context menus in Creating Menus for more information.

These methods are the sole inhabitants of their respective interface. To define one of these methods and handle your
events, implement the nested interface in your Activity or define it as an anonymous class. Then, pass an instance of
your implementation to the respective View.set...Listener() method. (E.g., call setOnClickListener() and
pass it your implementation of the OnClickListener.)

The example below shows how to register an on-click listener for a Button.

     // Create an anonymous implementation of OnClickListener
     private OnClickListener mCorkyListener = new OnClickListener() {
         public void onClick(View v) {
           // do something when the button is clicked
         }
     };
     protected void onCreate(Bundle savedValues) {
         ...
         // Capture our button from layout
         Button button = (Button)findViewById(R.id.corky);
         // Register the onClick listener with the implementation above
         button.setOnClickListener(mCorkyListener);
         ...
     }

You may also find it more conventient to implement OnClickListener as a part of your Activity. This will avoid the extra
class load and object allocation. For example:

     public class ExampleActivity extends Activity implements OnClickListener {
         protected void onCreate(Bundle savedValues) {
             ...
             Button button = (Button)findViewById(R.id.corky);
             button.setOnClickListener(this);
         }
            // Implement the OnClickListener callback
            public void onClick(View v) {
              // do something when the button is clicked
            }
            ...
     }

Notice that the onClick() callback in the above example has no return value, but some other event listener methods
must return a boolean. The reason depends on the event. For the few that do, here's why:

     onLongClick() - This returns a boolean to indicate whether you have consumed the event and it should not be
     carried further. That is, return true to indicate that you have handled the event and it should stop here; return false
     if you have not handled it and/or the event should continue to any other on-click listeners.
     onKey() - This returns a boolean to indicate whether you have consumed the event and it should not be carried
     further. That is, return true to indicate that you have handled the event and it should stop here; return false if you
     have not handled it and/or the event should continue to any other on-key listeners.
     onTouch() - This returns a boolean to indicate whether your listener consumes this event. The important thing is
     that this event can have multiple actions that follow each other. So, if you return false when the down action event
     is received, you indicate that you have not consumed the event and are also not interested in subsequent actions
     from this event. Thus, you will not be called for any other actions within the event, such as a fingure gesture, or
     the eventual up action event.

Remember that key events are always delivered to the View currently in focus. They are dispatched starting from the
top of the View hierarchy, and then down, until they reach the appropriate destination. If your View (or a child of your
View) currently has focus, then you can see the event travel through the dispatchKeyEvent() method. As an
http://developer.android.com/guide/topics/ui/ui-events.html                                                         Page 2 of 4
Handling UI Events | Android Developers                                                                         29.04.09 0:37


View) currently has focus, then you can see the event travel through the dispatchKeyEvent() method. As an
alternative to capturing key events through your View, you can also receive all of the events inside your Activity with
onKeyDown() and onKeyUp().

     Note: Android will call event handlers first and then the appropriate default handlers from the class definition
     second. As such, returning true from these event listeners will stop the propagation of the event to other event
     listeners and will also block the callback to the default event handler in the View. So be certain that you want to
     terminate the event when you return true.



Event Handlers
If you're building a custom component from View, then you'll be able to define several callback methods used as
default event handlers. In the document on Building Custom Components, you'll learn see some of the common
callbacks used for event handling, including:

     onKeyDown(int, KeyEvent) - Called when a new key event occurs.
     onKeyUp(int, KeyEvent) - Called when a key up event occurs.
     onTrackballEvent(MotionEvent) - Called when a trackball motion event occurs.
     onTouchEvent(MotionEvent) - Called when a touch screen motion event occurs.
     onFocusChanged(boolean, int, Rect) - Called when the view gains or loses focus.

There are some other methods that you should be awere of, which are not part of the View class, but can directly
impact the way you're able to handle events. So, when managing more complex events inside a layout, consider these
other methods:

     Activity.dispatchTouchEvent(MotionEvent) - This allows your Activity to intercept all touch events
     before they are dispatched to the window.
     ViewGroup.onInterceptTouchEvent(MotionEvent) - This allows a ViewGroup to watch events as they
     are dispatched to child Views.
     ViewParent.requestDisallowInterceptTouchEvent(boolean) - Call this upon a parent View to
     indicate that it should not intercept touch events with onInterceptTouchEvent(MotionEvent).




Touch Mode
When a user is navigating a user interface with directional keys or a trackball, it is necessary to give focus to
actionable items (like buttons) so the user can see what will accept input. If the device has touch capabilities, however,
and the user begins interacting with the interface by touching it, then it is no longer necessary to highlight items, or
give focus to a particular View. Thus, there is a mode for interaction named "touch mode."

For a touch-capable device, once the user touches the screen, the device will enter touch mode. From this point
onward, only Views for which isFocusableInTouchMode() is true will be focusable, such as text editing widgets. Other
Views that are touchable, like buttons, will not take focus when touched; they will simply fire their on-click listeners
when pressed.

Any time a user hits a directional key or scrolls with a trackball, the device will exit touch mode, and find a view to
take focus. Now, the user may resume interacting with the user interface without touching the screen.

The touch mode state is maintained throughout the entire system (all windows and activities). To query the current
state, you can call isInTouchMode() to see whether the device is currently in touch mode.




http://developer.android.com/guide/topics/ui/ui-events.html                                                        Page 3 of 4
Handling UI Events | Android Developers                                                                               29.04.09 0:37



Handling Focus
The framework will handle routine focus movement in response to user input. This includes changing the focus as
Views are removed or hidden, or as new Views become available. Views indicate their willingness to take focus
through the isFocusable() method. To change whether a View can take focus, call setFocusable(). When in
touch mode, you may query whether a View allows focus with isFocusableInTouchMode(). You can change this
with setFocusableInTouchMode().

Focus movement is based on an algorithm which finds the nearest neighbor in a given direction. In rare cases, the
default algorithm may not match the intended behavior of the developer. In these situations, you can provide explicit
overrides with the following XML attributes in the layout file: nextFocusDown, nextFocusLeft, nextFocusRight, and
nextFocusUp. Add one of these attributes to the View from which the focus is leaving. Define the value of the attribute
to be the id of the View to which focus should be given. For example:

     <LinearLayout
         android:orientation="vertical"
         ... >
       <Button android:id="@+id/top"
               android:nextFocusUp="@+id/bottom"
               ... />
       <Button android:id="@+id/bottom"
               android:nextFocusDown="@+id/top"
               ... />
     </LinearLayout>

Ordinarily, in this vertical layout, navigating up from the first Button would not go anywhere, nor would navigating down
from the second Button. Now that the top Button has defined the bottom one as the nextFocusUp (and vice versa), the
navigation focus will cycle from top-to-bottom and bottom-to-top.

If you'd like to declare a View as focusable in your UI (when it is traditionally not), add the android:focusable
XML attribute to the View, in your layout declaration. Set the value true. You can also declare a View as focusable
while in Touch Mode with android:focusableInTouchMode.

To request a particular View to take focus, call requestFocus().

To listen for focus events (be notified when a View receives or looses focus), use onFocusChange(), as discussed
in the Event Listeners section, above.

" Back to User Interface                                                                                             ! Go to top

Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/ui/ui-events.html                                                             Page 4 of 4
Notifying the User | Android Developers                                                                          29.04.09 0:37




Notifying the User

Several types of situations may arise that require you to notify the user about an event that occurs in your application.
Some events require the user to respond and others do not. For example:

     When an event such as saving a file is complete, a small message should appear to confirm that the save was
     successful.
     If the application is running in the background and needs the user's attention, the application should create a
     notificaiton that allows the user to respond at his or her convenience.
     If the application is performing work that the user must wait for (such as loading a file), the application should
     show a hovering progress wheel or bar.

Each of these notification tasks can be achieved using a different technique:

     A Toast Notification, for brief messages that come from the background.
     A Status Bar Notification, for persistent reminders that come from the background and request the user's
     response.
     A Dialog Notification, for Activity-related notifications.

This document summarizes each of these techniques for notifying the user and includes links to full documentation.



Toast Notification
A toast notificaiton is a message that pops up on the surface of the window. It
only fills the amount of space required for the message and the user's current
activity remains visible and interactive. The notification automatically fades in and
out, and does not accept interaction events. Because a toast can be created from
a background Service, it appears even if the application isn't visible.

A toast is best for short text messages, such as "File saved," when you're fairly
certain the user is paying attention to the screen. A toast can not accept user
interaction events; if you'd like the user to respond and take action, consider using
a Status Bar Notification instead.

For more information, refer to Creating Toast Notifications.



Status Bar Notification
A status bar notification adds an icon to the system's status bar (with an optional
ticker-text message) and an expanded message in the "Notifications" window.
When the user selects the expanded message, Android fires an Intent that is
defined by the notification (usually to launch an Activity). You can also configure
the notification to alert the user with a sound, a vibration, and flashing lights on
the device.



http://developer.android.com/guide/topics/ui/notifiers/index.html                                                  Page 1 of 2
Notifying the User | Android Developers                                                                               29.04.09 0:37


This kind of notification is ideal when your application is working in a background
Service and needs to notify the user about an event. If you need to alert the user
about an event that occurs while your Activity is still in focus, consider using a
Dialog Notification instead.

For more information, refer to Creating Status Bar Notifications.



Dialog Notification
A dialog is usually a small window that appears in front of the current Activity. The
underlying Activity loses focus and the dialog accepts all user interaction. Dialogs
are normally used for notifications and short activities that directly relate to the
application in progress.

You should use a dialog when you need to show a progress bar or a short
message that requires confirmation from the user (such as an alert with "OK" and
"Cancel" buttons). You can use also use dialogs as integral componenents in your application's UI and for other
purposes besides notifications. For a complete discussion on all the available types of dialogs, including its uses for
notifications, refer to Creating Dialogs.

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/ui/notifiers/index.html                                                       Page 2 of 2
Applying Styles and Themes | Android Developers                                                                  29.04.09 0:37




User Interface >

Applying Styles and Themes

When designing your application, you can use styles and themes to apply uniform formatting to its various screens and
UI elements.

     A style is a set of one or more formatting attributes that you can apply as a unit to single elements in your layout
     XML file(s). For example, you could define a style that specifies a certain text size and color, then apply it to
     instances of a certain type of View element.
     A theme is a set of one or more formatting attributes that you can apply as a unit to all activities in an application
     or just a single activity. For example, you could define a theme that sets specific colors for the window frame and
     the panel foreground and background, and sets text sizes and colors for menus, then apply it to the activities of
     your application.

Styles and themes are resources. Android provides some default style and theme resources that you can use, or you
can declare your own custom style and theme resources.

To create custom styles and themes:

 1. Create a file named styles.xml in the your application's res/values directory. Add a root <resources>
    node.
 2. For each style or theme, add a <style> element with a unique name and, optionally, a parent attribute. The
    name is used for referencing these styles later, and the parent indicates what style resource to inherit from.
 3. Inside the <style> element, declare format values in one or more <item> element(s). Each <item> identifies
    its style property with a name attribute and defines its style value inside the element.
 4. You can then reference the custom resources from other XML resources, your manifest or application code.




Styles
Here's an example declaration of a style:


     <?xml version="1.0" encoding="utf-8"?>
     <resources>
         <style name="SpecialText" parent="@style/Text">
             <item name="android:textSize">18sp</item>
             <item name="android:textColor">#008</item>
         </style>
     </resources>

As shown, you can use <item> elements to set specific formatting values for the style. The name attribute in the
item can refer to a standard string, a hex color value, or a reference to any other resource type.

Notice the parent attribute in the <style> element. This attribute lets you specify a resource from which the current
style will inherit values. The style can inherit from any type of resource that contains the style(s) you want. In general,
your styles should always inherit (directly or indirectly) from a standard Android style resource. This way, you only have
to define the values that you want to change.

Here's how you would reference the custom style from an XML layout, in this case, for an EditText element:


http://developer.android.com/guide/topics/ui/themes.html                                                           Page 1 of 3
Applying Styles and Themes | Android Developers                                                               29.04.09 0:37




     <EditText id="@+id/text1"
               style="@style/SpecialText"
               android:layout_width="fill_parent"
               android:layout_height="wrap_content"
               android:text="Hello, World!" />

Now this EditText widget will be styled as defined by the XML example above.



Themes
Just like styles, themes are also declared in XML <style> elements, and are referenced in the same manner. The
difference is that you add a theme to an entire application or activity, via the <application> and <activity>
elements in the Android Manifest — themes cannot be applied to individual Views.

Here's an example declaration of a theme:

     <?xml version="1.0" encoding="utf-8"?>
     <resources>
       <style name="CustomTheme">
         <item name="android:windowNoTitle">true</item>
         <item name="windowFrame">@drawable/screen_frame</item>
         <item name="windowBackground">@drawable/screen_background_white</item>
         <item name="panelForegroundColor">#FF000000</item>
         <item name="panelBackgroundColor">#FFFFFFFF</item>
         <item name="panelTextColor">?panelForegroundColor</item>
         <item name="panelTextSize">14</item>
         <item name="menuItemTextColor">?panelTextColor</item>
         <item name="menuItemTextSize">?panelTextSize</item>
       </style>
     </resources>

Notice the use of the at-symbol (@) and the question-mark (?) to reference resources. The at-symbol indicates that
we're referencing a resource previously defined elsewhere (which may be from this project or from the Android
framework). The question-mark indicates that we're referencing a resource value in the currently loaded theme. This is
done by referring to a specific <item> by its name value. (E.g., panelTextColor uses the same color assigned to
panelForegroundColor, defined beforehand.) This technique can be used only in XML resources.


Set the theme in the manifest
To set this theme for all the activites of your application, open the AndroidManifest.xml file and edit the
<application> tag to include the android:theme attribute with the theme name:

     <application android:theme="@style/CustomTheme">

If you want the theme applied to just one Activity in your application, then add the theme attribute to the <activity>
tag, instead.

Just as Android provides other built-in resources, there are several themes that you swap in without having to write
one yourself. For example, you can use the Dialog theme to make your Activity appear like a dialog box. In the
manifest, reference an Android theme like so:


     <activity android:theme="@android:style/Theme.Dialog">

If you like a theme, but want to slightly tweak it, just add the theme as the parent of your custom theme. For
example, we'll modify the Theme.Dialog theme. To do so, create a style with Theme.Dialog as the parent:

http://developer.android.com/guide/topics/ui/themes.html                                                         Page 2 of 3
Applying Styles and Themes | Android Developers                                                                       29.04.09 0:37




     <style name="CustomDialogTheme" parent="@android:style/Theme.Dialog">

There it is. We've inherited the Android Dialog theme so we can adjust its styles as we like. So, for each item in the
Dialog theme that we want to change, we re-define the value here and use CustomDialogTheme instead of
Theme.Dialog inside the Android Manifest.


Set the theme from the application
You can also load a theme for an Activity programmatically, if needed. To do so, use the setTheme() method. Note
that, when doing so, you must be sure to set the theme before instantiating any Views in the context, for example,
before calling setContentView(View) or inflate(int, ViewGroup). This ensures that the system applies the
same theme for all of your UI screens. Here's an example:


         protected void onCreate(Bundle savedInstanceState) {
            super.onCreate(savedInstanceState);
            ...
            setTheme(android.R.style.Theme_Light);
            setContentView(R.layout.linear_layout_3);
     }

If you are considering loading a theme programmatically for the main screen of your application, note that the theme
would not be applied in any animations the system would use to start the activity, which would take place before your
application opens. In most cases, if you want to apply a theme to your main screen, doing so in XML is a better
approach.

For detailed information about custom styles and themes and referencing them from your application, see Available
Resource Types: Style and Themes.

For information about default themes and styles available, see R.style.

" Back to User Interface                                                                                             ! Go to top

Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/ui/themes.html                                                                Page 3 of 3
Building Custom Components | Android Developers                                                               29.04.09 0:37




User Interface >

Building Custom Components

Android offers a sophisticated and powerful componentized model for building your UI, based on the fundamental
layout classes: View and ViewGroup. To start with, the platform includes a variety of prebuilt View and ViewGroup
subclasses — called widgets and layouts, respectively — that you can use to construct your UI.

A partial list of available widgets includes Button, TextView, EditText, ListView, CheckBox, RadioButton, Gallery,
Spinner, and the more special-purpose AutoCompleteTextView, ImageSwitcher, and TextSwitcher.

Among the layouts available are LinearLayout, FrameLayout, AbsoluteLayout, and others. For more examples, see
Common Layout Objects.

If none of the prebuilt widgets or layouts meets your needs, you can create your own View subclass. If you only need
to make small adjustments to an existing widget or layout, you can simply subclass the widget or layout and override
its methods.

Creating your own View subclasses gives you precise control over the appearance and function of a screen element.
To give an idea of the control you get with custom views, here are some examples of what you could do with them:

     You could create a completely custom-rendered View type, for example a "volume control" knob rendered using
     2D graphics, and which resembles an analog electronic control.
     You could combine a group of View components into a new single component, perhaps to make something like a
     ComboBox (a combination of popup list and free entry text field), a dual-pane selector control (a left and right
     pane with a list in each where you can re-assign which item is in which list), and so on.
     You could override the way that an EditText component is rendered on the screen (the Notepad Tutorial uses this
     to good effect, to create a lined-notepad page).
     You could capture other events like key presses and handle them in some custom way (such as for a game).

The sections below explain how to create custom Views and use them in your application. For detailed reference
information, see the View class.



The Basic Approach
Here is a high level overview of what you need to know to get started in creating your own View components:

 1. Extend an existing View class or subclass with your own class.
 2. Override some of the methods from the superclass. The superclass methods to override start with 'on', for
    example, onDraw(), onMeasure(), and onKeyDown(). This is similar to the on... events in Activity or ListActivity
    that you override for lifecycle and other functionality hooks.
 3. Use your new extension class. Once completed, your new extension class can be used in place of the view upon
    which it was based.

    Tip: Extension classes can be defined as inner classes inside the activities that use them. This is useful because
    it controls access to them but isn't necessary (perhaps you want to create a new public View for wider use in
    your application).




http://developer.android.com/guide/topics/ui/custom-components.html                                             Page 1 of 6
Building Custom Components | Android Developers                                                                29.04.09 0:37



Fully Customized Components
Fully customized components can be used to create graphical components that appear however you wish. Perhaps a
graphical VU meter that looks like an old analog gauge, or a sing-a-long text view where a bouncing ball moves along
the words so you can sing along with a karaoke machine. Either way, you want something that the built-in components
just won't do, no matter how you combine them.

Fortunately, you can easily create components that look and behave in any way you like, limited perhaps only by your
imagination, the size of the screen, and the available processing power (remember that ultimately your application
might have to run on something with significantly less power than your desktop workstation).

To create a fully customized component:

 1. The most generic view you can extend is, unsurprisingly, View, so you will usually start by extending this to create
    your new super component.
 2. You can supply a constructor which can take attributes and parameters from the XML, and you can also consume
    your own such attributes and parameters (perhaps the color and range of the VU meter, or the width and damping
    of the needle, etc.)
 3. You will probably want to create your own event listeners, property accessors and modifiers, and possibly more
    sophisticated behavior in your component class as well.
 4. You will almost certainly want to override onMeasure() and are also likely to need to override onDraw() if you
    want the component to show something. While both have default behavior, the default onDraw() will do nothing,
    and the default onMeasure() will always set a size of 100x100 — which is probably not what you want.
 5. Other on... methods may also be overridden as required.


Extend onDraw() and onMeasure()
The onDraw() method delivers you a Canvas upon which you can implement anything you want: 2D graphics, other
standard or custom components, styled text, or anything else you can think of.

    Note: This does not apply to 3D graphics. If you want to use 3D graphics, you must extend SurfaceView instead
    of View, and draw from a seperate thread. See the GLSurfaceViewActivity sample for details.

onMeasure() is a little more involved. onMeasure() is a critical piece of the rendering contract between your
component and its container. onMeasure() should be overridden to efficiently and accurately report the
measurements of its contained parts. This is made slightly more complex by the requirements of limits from the parent
(which are passed in to the onMeasure() method) and by the requirement to call the setMeasuredDimension()
method with the measured width and height once they have been calculated. If you fail to call this method from an
overridden onMeasure() method, the result will be an exception at measurement time.

At a high level, implementing onMeasure() looks something like this:

 1. The overridden onMeasure() method is called with width and height measure specifications
    (widthMeasureSpec and heightMeasureSpec parameters, both are integer codes representing dimensions)
    which should be treated as requirements for the restrictions on the width and height measurements you should
    produce. A full reference to the kind of restrictions these specifications can require can be found in the reference
    documentation under View.onMeasure(int, int) (this reference documentation does a pretty good job of explaining
    the whole measurement operation as well).
 2. Your component's onMeasure() method should calculate a measurement width and height which will be
    required to render the component. It should try to stay within the specifications passed in, although it can choose
    to exceed them (in this case, the parent can choose what to do, including clipping, scrolling, throwing an
    exception, or asking the onMeasure() to try again, perhaps with different measurement specifications).
 3. Once the width and height are calculated, the setMeasuredDimension(int width, int height) method
    must be called with the calculated measurements. Failure to do this will result in an exception being thrown.



http://developer.android.com/guide/topics/ui/custom-components.html                                              Page 2 of 6
Building Custom Components | Android Developers                                                                29.04.09 0:37


Here's a summary of some of the other standard methods that the framework calls on views:

  Category           Methods                                          Description

  Creation           Constructors                                     There is a form of the constructor
                                                                      that are called when the view is
                                                                      created from code and a form that is
                                                                      called when the view is inflated from
                                                                      a layout file. The second form
                                                                      should parse and apply any
                                                                      attributes defined in the layout file.

                     onFinishInflate()                                Called after a view and all of its
                                                                      children has been inflated from XML.

  Layout             onMeasure(int, int)                              Called to determine the size
                                                                      requirements for this view and all of
                                                                      its children.

                     onLayout(boolean, int, int,                      Called when this view should assign
                     int, int)                                        a size and position to all of its
                                                                      children.

                     onSizeChanged(int, int, int,                     Called when the size of this view
                     int)                                             has changed.

  Drawing            onDraw(Canvas)                                   Called when the view should render
                                                                      its content.

  Event              onKeyDown(int, KeyEvent)                         Called when a new key event
  processing                                                          occurs.

                     onKeyUp(int, KeyEvent)                           Called when a key up event occurs.

                     onTrackballEvent(MotionEvent)                    Called when a trackball motion
                                                                      event occurs.

                     onTouchEvent(MotionEvent)                        Called when a touch screen motion
                                                                      event occurs.

  Focus              onFocusChanged(boolean, int,                     Called when the view gains or loses
                     Rect)                                            focus.

                     onWindowFocusChanged(boolean)                    Called when the window containing
                                                                      the view gains or loses focus.

  Attaching          onAttachedToWindow()                             Called when the view is attached to
                                                                      a window.

                     onDetachedFromWindow()                           Called when the view is detached
                                                                      from its window.

                     onWindowVisibilityChanged(int)                   Called when the visibility of the
                                                                      window containing the view has
                                                                      changed.


A Custom View Example
The CustomView sample in the API Demos provides an example of a customized View. The custom View is defined in
the LabelView class.



http://developer.android.com/guide/topics/ui/custom-components.html                                              Page 3 of 6
Building Custom Components | Android Developers                                                                  29.04.09 0:37


The LabelView sample demonstrates a number of different aspects of custom components:

     Extending the View class for a completely custom component.
     Parameterized constructor that takes the view inflation parameters (parameters defined in the XML). Some of
     these are passed through to the View superclass, but more importantly, there are some custom attributes defined
     and used for LabelView.
     Standard public methods of the type you would expect to see for a label component, for example setText(),
     setTextSize(), setTextColor() and so on.
     An overridden onMeasure method to determine and set the rendering size of the component. (Note that in
     LabelView, the real work is done by a private measureWidth() method.)
     An overridden onDraw() method to draw the label onto the provided canvas.

You can see some sample usages of the LabelView custom View in custom_view_1.xml from the samples. In
particular, you can see a mix of both android: namespace parameters and custom app: namespace parameters.
These app: parameters are the custom ones that the LabelView recognizes and works with, and are defined in a
styleable inner class inside of the samples R resources definition class.



Compound Controls
If you don't want to create a completely customized component, but instead are looking to put together a reusable
component that consists of a group of existing controls, then creating a Compound Component (or Compound Control)
might fit the bill. In a nutshell, this brings together a number of more atomic controls (or views) into a logical group of
items that can be treated as a single thing. For example, a Combo Box can be thought of as a combination of a single
line EditText field and an adjacent button with an attached PopupList. If you press the button and select something
from the list, it populates the EditText field, but the user can also type something directly into the EditText if they
prefer.

In Android, there are actually two other Views readily available to do this: Spinner and AutoCompleteTextView, but
regardless, the concept of a Combo Box makes an easy-to-understand example.

To create a compound component:

 1. The usual starting point is a Layout of some kind, so create a class that extends a Layout. Perhaps in the case of
    a Combo box we might use a LinearLayout with horizontal orientation. Remember that other layouts can be
    nested inside, so the compound component can be arbitrarily complex and structured. Note that just like with an
    Activity, you can use either the declarative (XML-based) approach to creating the contained components, or you
    can nest them programmatically from your code.
 2. In the constructor for the new class, take whatever parameters the superclass expects, and pass them through to
    the superclass constructor first. Then you can set up the other views to use within your new component; this is
    where you would create the EditText field and the PopupList. Note that you also might introduce your own
    attributes and parameters into the XML that can be pulled out and used by your constructor.
 3. You can also create listeners for events that your contained views might generate, for example, a listener method
    for the List Item Click Listener to update the contents of the EditText if a list selection is made.
 4. You might also create your own properties with accessors and modifiers, for example, allow the EditText value to
    be set initially in the component and query for its contents when needed.
 5. In the case of extending a Layout, you don't need to override the onDraw() and onMeasure() methods since
    the layout will have default behavior that will likely work just fine. However, you can still override them if you need
    to.
 6. You might override other on... methods, like onKeyDown(), to perhaps choose certain default values from the
    popup list of a combo box when a certain key is pressed.

To summarize, the use of a Layout as the basis for a Custom Control has a number of advantages, including:


http://developer.android.com/guide/topics/ui/custom-components.html                                                Page 4 of 6
Building Custom Components | Android Developers                                                                  29.04.09 0:37


     You can specify the layout using the declarative XML files just like with an activity screen, or you can create views
     programmatically and nest them into the layout from your code.
     The onDraw() and onMeasure() methods (plus most of the other on... methods) will likely have suitable
     behavior so you don't have to override them.
     In the end, you can very quickly construct arbitrarily complex compound views and re-use them as if they were a
     single component.

Examples of Compound Controls
In the API Demos project that comes with the SDK, there are two List examples — Example 4 and Example 6 under
Views/Lists demonstrate a SpeechView which extends LinearLayout to make a component for displaying Speech
quotes. The corresponding classes in the sample code are List4.java and List6.java.



Modifying an Existing View Type
There is an even easier option for creating a custom View which is useful in certain circumstances. If there is a
component that is already very similar to what you want, you can simply extend that component and just override the
behavior that you want to change. You can do all of the things you would do with a fully customized component, but by
starting with a more specialized class in the View heirarchy, you can also get a lot of behavior for free that probably
does exactly what you want.

For example, the SDK includes a NotePad application in the samples. This demonstrates many aspects of using the
Android platform, among them is extending an EditText View to make a lined notepad. This is not a perfect example,
and the APIs for doing this might change from this early preview, but it does demonstrate the principles.

If you haven't done so already, import the NotePad sample into Eclipse (or just look at the source using the link
provided). In particular look at the definition of MyEditText in the NoteEditor.java file.

Some points to note here

 1. The Definition
     The class is defined with the following line:
     public static class MyEditText extends EditText
           It is defined as an inner class within the NoteEditor activity, but it is public so that it could be accessed as
           NoteEditor.MyEditText from outside of the NoteEditor class if desired.
           It is static, meaning it does not generate the so-called "synthetic methods" that allow it to access data from
           the parent class, which in turn means that it really behaves as a separate class rather than something
           strongly related to NoteEditor. This is a cleaner way to create inner classes if they do not need access to
           state from the outer class, keeps the generated class small, and allows it to be used easily from other
           classes.
           It extends EditText, which is the View we have chosen to customize in this case. When we are finished,
           the new class will be able to substitute for a normal EditText view.

 2. Class Initialization
     As always, the super is called first. Furthermore, this is not a default constructor, but a parameterized one. The
     EditText is created with these parameters when it is inflated from an XML layout file, thus, our constructor needs
     to both take them and pass them to the superclass constructor as well.
 3. Overridden Methods
     In this example, there is only one method to be overridden: onDraw() — but there could easily be others needed
     when you create your own custom components.
     For the NotePad sample, overriding the onDraw() method allows us to paint the blue lines on the EditText
     view canvas (the canvas is passed into the overridden onDraw() method). The super.onDraw() method is called
     before the method ends. The superclass method should be invoked, but in this case, we do it at the end after we
     have painted the lines we want to include.
http://developer.android.com/guide/topics/ui/custom-components.html                                                 Page 5 of 6
Building Custom Components | Android Developers                                                                       29.04.09 0:37


     have painted the lines we want to include.
 4. Use the Custom Component
     We now have our custom component, but how can we use it? In the NotePad example, the custom component is
     used directly from the declarative layout, so take a look at note_editor.xml in the res/layout folder.

          <view
            class="com.android.notepad.NoteEditor$MyEditText"
            id="@+id/note"
            android:layout_width="fill_parent"
            android:layout_height="fill_parent"
            android:background="@android:drawable/empty"
            android:padding="10dip"
            android:scrollbars="vertical"
            android:fadingEdge="vertical" />

           The custom component is created as a generic view in the XML, and the class is specified using the full
           package. Note also that the inner class we defined is referenced using the NoteEditor$MyEditText
           notation which is a standard way to refer to inner classes in the Java programming language.
           If your custom View component is not defined as an inner class, then you can, alternatively, declare the View
           component with the XML element name, and exclude the class attribute. For example:

                <com.android.notepad.MyEditText
                  id="@+id/note"
                  ... />

           Notice that the MyEditText class is now a separate class file. When the class is nested in the NoteEditor
           class, this technique will not work.
           The other attributes and parameters in the definition are the ones passed into the custom component
           constructor, and then passed through to the EditText constructor, so they are the same parameters that you
           would use for an EditText view. Note that it is possible to add your own parameters as well, and we will touch
           on this again below.

And that's all there is to it. Admittedly this is a simple case, but that's the point — creating custom components is only
as complicated as you need it to be.

A more sophisticated component may override even more on... methods and introduce some of its own helper
methods, substantially customizing its properties and behavior. The only limit is your imagination and what you need
the component to do.

" Back to User Interface                                                                                             ! Go to top

Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/ui/custom-components.html                                                     Page 6 of 6
Binding to Data with AdapterView | Android Developers                                                         29.04.09 0:38




User Interface >

Binding to Data with AdapterView

The AdapterView is a ViewGroup subclass whose child Views are determined by an Adapter that binds to data of
some type. AdapterView is useful whenever you need to display stored data (as opposed to resource strings or
drawables) in your layout.

Gallery, ListView, and Spinner are examples of AdapterView subclasses that you can use to bind to a specific type of
data and display it in a certain way.

AdapterView objects have two main responsibilities:

     Filling the layout with data
     Handling user selections




Filling the Layout with Data
Inserting data into the layout is typically done by binding the AdapterView class to an Adapter, which retireves data
from an external source (perhaps a list that the code supplies or query results from the device's database).

The following code sample does the following:

 1. Creates a Spinner with an existing View and binds it to a new ArrayAdapter that reads an array of colors from the
    local resources.
 2. Creates another Spinner object from a View and binds it to a new SimpleCursorAdapter that will read people's
    names from the device contacts (see Contacts.People).


     // Get a Spinner and bind it to an ArrayAdapter that
     // references a String array.
     Spinner s1 = (Spinner) findViewById(R.id.spinner1);
     ArrayAdapter adapter = ArrayAdapter.createFromResource(
         this, R.array.colors, android.R.layout.simple_spinner_item);
     adapter.setDropDownViewResource(android.R.layout.simple_spinner_dropdown_item);
     s1.setAdapter(adapter);
     // Load a Spinner and bind it to a data query.
     private static String[] PROJECTION = new String[] {
             People._ID, People.NAME
         };

     Spinner s2 = (Spinner) findViewById(R.id.spinner2);
     Cursor cur = managedQuery(People.CONTENT_URI, PROJECTION, null, null);

     SimpleCursorAdapter adapter2 = new SimpleCursorAdapter(this,
         android.R.layout.simple_spinner_item, // Use a template
                                               // that displays a
                                               // text view
         cur, // Give the cursor to the list adatper
         new String[] {People.NAME}, // Map the NAME column in the
                                              // people database to...
         new int[] {android.R.id.text1}); // The "text1" view defined in
                                          // the XML template


http://developer.android.com/guide/topics/ui/binding.html                                                        Page 1 of 2
Binding to Data with AdapterView | Android Developers                                                                 29.04.09 0:38


     adapter2.setDropDownViewResource(android.R.layout.simple_spinner_dropdown_item);
     s2.setAdapter(adapter2);

Note that it is necessary to have the People._ID column in projection used with CursorAdapter or else you will get an
exception.

If, during the course of your application's life, you change the underlying data that is read by your Adapter, you should
call notifyDataSetChanged(). This will notify the attached View that the data has been changed and it should refresh
itself.



Handling User Selections
You handle the user's selecction by setting the class's AdapterView.OnItemClickListener member to a listener and
catching the selection changes.

     // Create a message handling object as an anonymous class.
     private OnItemClickListener mMessageClickedHandler = new OnItemClickListener() {
         public void onItemClick(AdapterView parent, View v, int position, long id)
         {
             // Display a messagebox.
             Toast.makeText(mContext,"You've got an event",Toast.LENGTH_SHORT).show();
         }
     };

     // Now hook into our object and set its onItemClickListener member
     // to our class handler object.
     mHistoryView = (ListView)findViewById(R.id.history);
     mHistoryView.setOnItemClickListener(mMessageClickedHandler);


  For more discussion on how to create different AdapterViews, read the following tutorials: Hello Spinner, Hello
  ListView, and Hello GridView.


" Back to User Interface                                                                                             ! Go to top

Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/ui/binding.html                                                               Page 2 of 2
Common Layout Objects | Android Developers                                                                                      29.04.09 0:38




User Interface >

Common Layout Objects

This section describes some of the more common types of layout objects to use in your applications. Like all layouts,
they are subclasses of ViewGroup.

Also see the Hello Views tutorials for some guidance on using more Android View layouts.



FrameLayout
FrameLayout is the simplest type of layout object. It's basically a blank space on your screen that you can later fill with
a single object — for example, a picture that you'll swap in and out. All child elements of the FrameLayout are pinned
to the top left corner of the screen; you cannot specify a different location for a child view. Subsequent child views will
simply be drawn over previous ones, partially or totally obscuring them (unless the newer object is transparent).



LinearLayout
LinearLayout aligns all children in a single direction — vertically or horizontally, depending on how you define the
orientation attribute. All children are stacked one after the other, so a vertical list will only have one child per row,
no matter how wide they are, and a horizontal list will only be one row high (the height of the tallest child, plus
padding). A LinearLayout respects margins between children and the gravity (right, center, or left alignment) of each
child.

LinearLayout also supports assigning a weight to individual children. This attribute assigns an "importance" value to a
view, and allows it to expand to fill any remaining space in the parent view. Child views can specify an integer weight
value, and then any remaining space in the view group is assigned to children in the proportion of their declared
weight. Default weight is zero. For example, if there are three text boxes and two of them declare a weight of 1, while
the other is given no weight (0), the third text box without weight will not grow and will only occupy the area required
by its content. The other two will expand equally to fill the space remaining after all three boxes are measured. If the
third box is then given a weight of 2 (instead of 0), then it is now declared "more important" than both the others, so it
gets half the total remaining space, while the first two share the rest equally.

The following two forms represent a LinearLayout with a set of
elements: a button, some labels and text boxes. The text boxes              Tip: To create a proportionate size layout on the
have their width set to fill_parent; other elements are set to              screen, create a container view group object
wrap_content. The gravity, by default, is left. The difference between      with the layout_width and
the two versions of the form is that the form on the left has weight        layout_height attributes set to fill_parent;
values unset (0 by default), while the form on the right has the            assign the children height or width to 0
comments text box weight set to 1. If the Name textbox had also             (zero); then assign relative weight values to
                                                                            each child, depending on what proportion of the
been set to 1, the Name and Comments text boxes would be the
                                                                            screen each should have.
same height.




http://developer.android.com/guide/topics/ui/layout-objects.html                                                                  Page 1 of 4
Common Layout Objects | Android Developers                                                                                      29.04.09 0:38




Within a horizontal LinearLayout, items are aligned by the position of their text base line (the first line of the first list
element — topmost or leftmost — is considered the reference line). This is so that people scanning elements in a form
shouldn't have to jump up and down to read element text in neighboring elements. This can be turned off by setting
android:baselineAligned="false" in the layout XML.

To view other sample code, see the Hello LinearLayout tutorial.



TableLayout
TableLayout positions its children into rows and columns. TableLayout containers do not display border lines for their
rows, columns, or cells. The table will have as many columns as the row with the most cells. A table can leave cells
empty, but cells cannot span columns, as they can in HTML.

TableRow objects are the child views of a TableLayout (each TableRow defines a single row in the table). Each row
has zero or more cells, each of which is defined by any kind of other View. So, the cells of a row may be composed of
a variety of View objects, like ImageView or TextView objects. A cell may also be a ViewGroup object (for example,
you can nest another TableLayout as a cell).

The following sample layout has two rows and two cells in each. The accompanying screenshot shows the result, with
cell borders displayed as dotted lines (added for visual effect).


     <?xml version="1.0" encoding="utf-8"?>
     <TableLayout
     xmlns:android="http://schemas.android.com/apk/res/android"
         android:layout_width="fill_parent"
         android:layout_height="fill_parent"
         android:stretchColumns="1">
         <TableRow>
             <TextView
                  android:text="@string/table_layout_4_open"
                  android:padding="3dip" />
             <TextView
     android:text="@string/table_layout_4_open_shortcut"
                 android:gravity="right"
                 android:padding="3dip" />
         </TableRow>
           <TableRow>
               <TextView
                   android:text="@string/table_layout_4_save"
                   android:padding="3dip" />
               <TextView

     android:text="@string/table_layout_4_save_shortcut"
                 android:gravity="right"
                 android:padding="3dip" />
         </TableRow>
     </TableLayout>


Columns can be hidden, marked to stretch and fill the available screen space, or can be marked as shrinkable to force
the column to shrink until the table fits the screen. See the TableLayout reference documentation for more details.
http://developer.android.com/guide/topics/ui/layout-objects.html                                                                  Page 2 of 4
Common Layout Objects | Android Developers                                                                                  29.04.09 0:38


the column to shrink until the table fits the screen. See the TableLayout reference documentation for more details.

To view sample code, see the Hello TableLayout tutorial.



AbsoluteLayout
AbsoluteLayout enables child views to specify their own exact x/y coordinates on the screen. Coordinates (0,0) is the
upper left corner, and values increase as you move down and to the right. Margins are not supported, and overlapping
elements are allowed (although not recommended). We generally recommend against using AbsoluteLayout unless
you have good reasons to use it, because it is fairly rigid and does not adjust to different types of displays.



RelativeLayout
RelativeLayout lets child views specify their position relative to the parent view or to each other (specified by ID). So
you can align two elements by right border, or make one below another, centered in the screen, centered left, and so
on. Elements are rendered in the order given, so if the first element is centered in the screen, other elements aligning
themselves to that element will be aligned relative to screen center. Also, because of this ordering, if using XML to
specify this layout, the element that you will reference (in order to position other view objects) must be listed in the
XML file before you refer to it from the other views via its reference ID.

The example below shows an XML file and the resulting screen in the UI. Note that the attributes that refer to relative
elements (e.g., layout_toLeft) refer to the ID using the syntax of a relative resource (@id/id).

     <?xml version="1.0" encoding="utf-8"?>
     <RelativeLayout
     xmlns:android="http://schemas.android.com/apk/res/android
                     android:layout_width="fill_parent"
                     android:layout_height="wrap_content"
                     android:background="@drawable/blue"
                     android:padding="10px" >

           <TextView android:id="@+id/label"
                     android:layout_width="fill_parent"
                     android:layout_height="wrap_content"
                     android:text="Type here:" />

           <EditText android:id="@+id/entry"
                     android:layout_width="fill_parent"
                     android:layout_height="wrap_content"
     android:background="@android:drawable/editbox_background"
                   android:layout_below="@id/label" />
           <Button android:id="@+id/ok"
                   android:layout_width="wrap_content"
                   android:layout_height="wrap_content"
                   android:layout_below="@id/entry"
                   android:layout_alignParentRight="true"
                   android:layout_marginLeft="10px"
                   android:text="OK" />
         <Button android:layout_width="wrap_content"
                 android:layout_height="wrap_content"
                 android:layout_toLeftOf="@id/ok"
                 android:layout_alignTop="@id/ok"
                 android:text="Cancel" />
     </RelativeLayout>


Some of these properties are supported directly by the element, and some are supported by its LayoutParams member
(subclass RelativeLayout for all the elements in this screen, because all elements are children of a RelativeLayout
parent object). The defined RelativeLayout parameters are: width, height, below, alignTop, toLeft,
padding[Bottom|Left|Right|Top], and margin[Bottom|Left|Right|Top]. Note that some of these
parameters specifically support relative layout positions — their values must be the ID of the element to which you'd
like this view laid relative. For example, assigning the parameter toLeft="my_button" to a TextView would place
the TextView to the left of the View with the ID my_button (which must be written in the XML before the TextView).

To view this sample code, see the Hello RelativeLayout tutorial.




http://developer.android.com/guide/topics/ui/layout-objects.html                                                              Page 3 of 4
Common Layout Objects | Android Developers                                                                                          29.04.09 0:38



Summary of Important View Groups
These objects all hold child UI elements. Some provide their own form of a visible UI, while others are invisible
structures that only manage the layout of their child views.

  Class                   Description

  AbsoluteLayout          Enables you to specify the location of child objects relative to the parent in exact
                          measurements (for example, pixels).

  FrameLayout             Layout that acts as a view frame to display a single object.

  Gallery                 A horizontal scrolling display of images, from a bound list.

  GridView                Displays a scrolling grid of m columns and n rows.

  LinearLayout            A layout that organizes its children into a single horizontal or vertical row. It creates a scrollbar
                          if the length of the window exceeds the length of the screen.

  ListView                Displays a scrolling single column list.

  RelativeLayout          Enables you to specify the location of child objects relative to each other (child A to the left of
                          child B) or to the parent (aligned to the top of the parent).

  ScrollView              A vertically scrolling column of elements.

  Spinner                 Displays a single item at a time from a bound list, inside a one-row textbox. Rather like a one-
                          row listbox that can scroll either horizontally or vertically.

  SurfaceView             Provides direct access to a dedicated drawing surface. It can hold child views layered on top
                          of the surface, but is intended for applications that need to draw pixels, rather than using
                          widgets.

  TabHost                 Provides a tab selection list that monitors clicks and enables the application to change the
                          screen whenever a tab is clicked.

  TableLayout             A tabular layout with an arbitrary number of rows and columns, each cell holding the widget of
                          your choice. The rows resize to fit the largest column. The cell borders are not visible.

  ViewFlipper             A list that displays one item at a time, inside a one-row textbox. It can be set to swap items at
                          timed intervals, like a slide show.

  ViewSwitcher            Same as ViewFlipper.

" Back to User Interface                                                                                              ! Go to top

Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/ui/layout-objects.html                                                                      Page 4 of 4
How Android Draws Views | Android Developers                                                                      29.04.09 0:38




User Interface >

How Android Draws Views

When an Activity receives focus, it will be requested to draw its layout. The Android framework will handle the
procedure for drawing, but the Activity must provide the root node of its layout hierarchy.

Drawing begins with the root node of the layout. It is requested to measure and draw the layout tree. Drawing is
handled by walking the tree and rendering each View that intersects the invalid region. In turn, each View group is
responsible for requesting each of its children to be drawn (with the draw() method) and each View is responsible for
drawing itself. Because the tree is traversed in-order, this means that parents will be drawn before (i.e., behind) their
children, with siblings drawn in the order they appear in the tree.

Drawing the layout is a two pass process: a measure pass and a
layout pass. The measuring pass is implemented in measure(int,       The framework will not draw Views that are not
int) and is a top-down traversal of the View tree. Each View         in the invalid region, and also will take care of
pushes dimension specifications down the tree during the recursion.  drawing the Views background for you.
At the end of the measure pass, every View has stored its            You can force a View to draw, by calling
measurements. The second pass happens in layout(int, int,            invalidate().
int, int) and is also top-down. During this pass each parent is responsible for positioning all of its children using
the sizes computed in the measure pass.

When a View's measure() method returns, its getMeasuredWidth() and getMeasuredHeight() values must
be set, along with those for all of that View's descendants. A View's measured width and measured height values must
respect the constraints imposed by the View's parents. This guarantees that at the end of the measure pass, all
parents accept all of their children's measurements. A parent View may call measure() more than once on its
children. For example, the parent may measure each child once with unspecified dimensions to find out how big they
want to be, then call measure() on them again with actual numbers if the sum of all the children's unconstrained
sizes is too big or too small (i.e., if the children don't agree among themselves as to how much space they each get,
the parent will intervene and set the rules on the second pass).

The measure pass uses two classes to communicate dimensions.
The View.MeasureSpec class is used by Views to tell their parents         To intiate a layout, call requestLayout().
how they want to be measured and positioned. The base                     This method is typically called by a View on
LayoutParams class just describes how big the View wants to be for        itself when it believes that is can no longer fit
both width and height. For each dimension, it can specify one of:         within its current bounds.

     an exact number
     FILL_PARENT, which means the View wants to be as big as its parent (minus padding)
     WRAP_CONTENT, which means that the View wants to be just big enough to enclose its content (plus padding).

There are subclasses of LayoutParams for different subclasses of ViewGroup. For example, AbsoluteLayout has its
own subclass of LayoutParams which adds an X and Y value.

MeasureSpecs are used to push requirements down the tree from parent to child. A MeasureSpec can be in one of
three modes:

     UNSPECIFIED: This is used by a parent to determine the desired dimension of a child View. For example, a
     LinearLayout may call measure() on its child with the height set to UNSPECIFIED and a width of EXACTLY 240
     to find out how tall the child View wants to be given a width of 240 pixels.
     EXACTLY: This is used by the parent to impose an exact size on the child. The child must use this size, and
     guarantee that all of its descendants will fit within this size.

http://developer.android.com/guide/topics/ui/how-android-draws.html                                                  Page 1 of 2
How Android Draws Views | Android Developers                                                                          29.04.09 0:38


     AT_MOST: This is used by the parent to impose a maximum size on the child. The child must gurantee that it and
     all of its descendants will fit within this size.

" Back to User Interface                                                                                             ! Go to top

Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/ui/how-android-draws.html                                                     Page 2 of 2
Resources and Assets | Android Developers                                                                             29.04.09 0:40




Resources and Assets

Resources are an integral part of an Android application. In general, these are external elements that you want to
include and reference within your application, like images, audio, video, text strings, layouts, themes, etc. Every
Android application contains a directory for resources (res/) and a directory for assets (assets/). Assets are used
less often, because their applications are far fewer. You only need to save data as an asset when you need to read
the raw bites. The directories for resources and assets both reside at the top of your project directory, alongside your
source code directory (src/).

The difference between "resources" and "assets" isn't much on the surface, but in general, you'll use resources to
store your external content much more often than you'll use assets. The real difference is that anything placed in the
resources directory will be easily accessible from your application from the R class, which is compiled by Android.
Whereas, anything placed in the assets directory will maintain its raw file format and, in order to read it, you must use
the AssetManager to read the file as a stream of bytes. So keeping files and data in resources (res/) makes them
easily accessible.

Within the documents of this topic, you'll find information on the kinds of standard resources that are typically used in
an Android application and how to reference them from you code. Resources and Internationalization is where you
should start, to learn more about how Android utilizes project resources. Then, the Available Resource Types
document offers a summary of various resource types and a reference to their specifications.

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/resources/index.html                                                          Page 1 of 1
Resources and Internationalization | Android Developers                                                          29.04.09 0:40




Resources and Assets >

Resources and Internationalization

Resources are external files (that is, non-code files) that are used by your code and compiled into your application at
build time. Android supports a number of different kinds of resource files, including XML, PNG, and JPEG files. The
XML files have very different formats depending on what they describe. This document describes what kinds of files
are supported, and the syntax or format of each.

Resources are externalized from source code, and XML files are compiled into a binary, fast loading format for
efficiency reasons. Strings, likewise are compressed into a more efficient storage form. It is for these reasons that we
have these different resource types in the Android platform.

This is a fairly technically dense document, and together with the Available Resources document, they cover a lot of
information about resources. It is not necessary to know this document by heart to use Android, but rather to know that
the information is here when you need it.



Introduction
This topic includes a terminology list associated with resources, and a series of examples of using resources in code.
For a complete guide to the supported Android resource types, see Available Resources.

The Android resource system keeps track of all non-code assets associated with an application. You use the
Resources class to access your application's resources; the Resources instance associated with your application can
generally be found through Context.getResources().

An application's resources are compiled into the application binary at build time for you by the build system. To use a
resource, you must install it correctly in the source tree and build your application. As part of the build process,
symbols for each of the resources are generated that you can use in your source code -- this allows the compiler to
verify that your application code matches up with the resources you defined.

The rest of this section is organized as a tutorial on how to use resources in an application.



Creating Resources
Android supports string, bitmap, and many other types of resource. The syntax and format of each, and where they're
stored, depends upon the type of object. In general, though, you create resources from three types of files: XML files
(everything but bitmaps and raw), bitmap files(for images) and Raw files (anything else, for example sound files, etc.).
In fact, there are two different types of XML file as well, those that get compiled as-is into the package, and those that
are used to generate resources by aapt. Here is a list of each resource type, the format of the file, a description of the
file, and details of any XML files.

You will create and store your resource files under the appropriate subdirectory under the res/ directory in your
project. Android has a resource compiler (aapt) that compiles resources according to which subfolder they are in, and
the format of the file. Here is a list of the file types for each resource. See the Available Resources for descriptions of
each type of object, the syntax, and the format or syntax of the containing file.

  Directory                     Resource Types


http://developer.android.com/guide/topics/resources/resources-i18n.html                                            Page 1 of 9
Resources and Internationalization | Android Developers                                                                  29.04.09 0:40


  res/anim/                     XML files that are compiled into frame by frame animation or tweened animation objects

  res/drawable/                 .png, .9.png, .jpg files that are compiled into the following Drawable resource subtypes:

                                To get a resource of this type, use Resource.getDrawable(id)

                                      bitmap files
                                      9-patches (resizable bitmaps)


  res/layout/                   XML files that are compiled into screen layouts (or part of a screen). See Declaring Layout

  res/values/                   XML files that can be compiled into many kinds of resource.

                                     Note: unlike the other res/ folders, this one can hold any number of files that hold
                                     descriptions of resources to create rather than the resources themselves. The XML
                                     element types control where these resources are placed under the R class.

                                While the files can be named anything, these are the typical files in this folder (the
                                convention is to name the file after the type of elements defined within):

                                      arrays.xml to define arrays
                                      colors.xml to define color drawables and color string values. Use
                                      Resources.getDrawable() and Resources.getColor(), respectively, to
                                      get these resources.
                                      dimens.xml to define dimension value. Use Resources.getDimension() to get
                                      these resources.
                                      strings.xml to define string values (use either Resources.getString or preferably
                                      Resources.getText() to get these resources. getText() will retain any rich text
                                      styling which is usually desirable for UI strings.
                                      styles.xml to define style objects.


  res/xml/                      Arbitrary XML files that are compiled and can be read at run time by calling
                                Resources.getXML().

  res/raw/                      Arbitrary files to copy directly to the device. They are added uncompiled to the compressed
                                file that your application build produces. To use these resources in your application, call
                                Resources.openRawResource() with the resource ID, which is R.raw.somefilename.

Resources are compiled into the final APK file. Android creates a wrapper class, called R, that you can use to refer to
these resources in your code. R contains subclasses named according to the path and file name of the source file


Global Resource Notes
     Several resources allow you to define colors. Android accepts color values written in various web-style formats --
     a hexadecimal constant in any of the following forms: #RGB, #ARGB, #RRGGBB, #AARRGGBB.
     All color values support setting an alpha channel value, where the first two hexadecimal numbers specify the
     transparency. Zero in the alpha channel means transparent. The default value is opaque.




Using Resources
This section describes how to use the resources you've created. It includes the following topics:



http://developer.android.com/guide/topics/resources/resources-i18n.html                                                     Page 2 of 9
Resources and Internationalization | Android Developers                                                         29.04.09 0:40


     Using resources in code - How to call resources in your code to instantiate them.
     Referring to resources from other resources - You can reference resources from other resources. This lets you
     reuse common resource values inside resources.
     Supporting Alternate Resources for Alternate Configurations - You can specify different resources to load,
     depending on the language or display configuration of the host hardware.

At compile time, Android generates a class named R that contains resource identifiers to all the resources in your
program. This class contains several subclasses, one for each type of resource supported by Android, and for which
you provided a resource file. Each class contains one or more identifiers for the compiled resources, that you use in
your code to load the resource. Here is a small resource file that contains string, layout (screens or parts of screens),
and image resources.

     Note: the R class is an auto-generated file and is not designed to be edited by hand. It will be automatically re-
     created as needed when the resources are updated.


     package com.android.samples;
     public final class R {
         public static final class string {
             public static final int greeting=0x0204000e;
             public static final int start_button_text=0x02040001;
             public static final int submit_button_text=0x02040008;
             public static final int main_screen_title=0x0204000a;
         };
         public static final class layout {
             public static final int start_screen=0x02070000;
             public static final int new_user_pane=0x02070001;
             public static final int select_user_list=0x02070002;

            };
            public static final class drawable {
                public static final int company_logo=0x02020005;
                public static final int smiling_cat=0x02020006;
                public static final int yellow_fade_background=0x02020007;
                public static final int stretch_button_1=0x02020008;

            };
     };


Using Resources in Code
Using resources in code is just a matter of knowing the full resource ID and what type of object your resource has
been compiled into. Here is the syntax for referring to a resource:

R.resource_type.resource_name

or

android.R.resource_type.resource_name

Where resource_type is the R subclass that holds a specific type of resource. resource_name is the name
attribute for resources defined in XML files, or the file name (without the extension) for resources defined by other file
types. Each type of resource will be added to a specific R subclass, depending on the type of resource it is; to learn
which R subclass hosts your compiled resource type, consult the Available Resources document. Resources compiled
by your own application can be referred to without a package name (simply as
R.resource_type.resource_name). Android contains a number of standard resources, such as screen styles and
button backgrounds. To refer to these in code, you must qualify them with android, as in
android.R.drawable.button_background.

Here are some good and bad examples of using compiled resources in code:



http://developer.android.com/guide/topics/resources/resources-i18n.html                                           Page 3 of 9
Resources and Internationalization | Android Developers                                                         29.04.09 0:40


     // Load a background for the current screen from a drawable resource.
     this.getWindow().setBackgroundDrawableResource(R.drawable.my_background_image);

     // WRONG Sending a string resource reference into a
     // method that expects a string.
     this.getWindow().setTitle(R.string.main_title);
     // RIGHT Need to get the title from the Resources wrapper.
     this.getWindow().setTitle(Resources.getText(R.string.main_title));

     // Load a custom layout for the current screen.
     setContentView(R.layout.main_screen);

     // Set a slide in animation for a ViewFlipper object.
     mFlipper.setInAnimation(AnimationUtils.loadAnimation(this,
             R.anim.hyperspace_in));

     // Set the text on a TextView object.
     TextView msgTextView = (TextView)findViewByID(R.id.msg);
     msgTextView.setText(R.string.hello_message);


References to Resources
A value supplied in an attribute (or resource) can also be a reference to a resource. This is often used in layout files to
supply strings (so they can be localized) and images (which exist in another file), though a reference can be any
resource type including colors and integers.

For example, if we have color resources, we can write a layout file that sets the text color size to be the value
contained in one of those resources:

     <?xml version="1.0" encoding="utf-8"?>
     <EditText id="text"
         xmlns:android="http://schemas.android.com/apk/res/android"
         android:layout_width="fill_parent" android:layout_height="fill_parent"
         android:textColor="@color/opaque_red"
         android:text="Hello, World!" />

Note here the use of the '@' prefix to introduce a resource reference -- the text following that is the name of a
resource in the form of @[package:]type/name. In this case we didn't need to specify the package because we are
referencing a resource in our own package. To reference a system resource, you would need to write:

     <?xml version="1.0" encoding="utf-8"?>
     <EditText id="text"
         xmlns:android="http://schemas.android.com/apk/res/android"
         android:layout_width="fill_parent" android:layout_height="fill_parent"
         android:textColor="@android:color/opaque_red"
         android:text="Hello, World!" />

As another example, you should always use resource references when supplying strings in a layout file so that they
can be localized:

     <?xml version="1.0" encoding="utf-8"?>
     <EditText id="text"
         xmlns:android="http://schemas.android.com/apk/res/android"
         android:layout_width="fill_parent" android:layout_height="fill_parent"
         android:textColor="@android:color/opaque_red"
         android:text="@string/hello_world" />

This facility can also be used to create references between resources. For example, we can create new drawable
resources that are aliases for existing images:


http://developer.android.com/guide/topics/resources/resources-i18n.html                                             Page 4 of 9
Resources and Internationalization | Android Developers                                                       29.04.09 0:40




     <?xml version="1.0" encoding="utf-8"?>
     <resources>
         <drawable id="my_background">@android:drawable/theme2_background</drawable>
     </resources>


References to Theme Attributes
Another kind of resource value allows you to reference the value of an attribute in the current theme. This attribute
reference can only be used in style resources and XML attributes; it allows you to customize the look of UI elements
by changing them to standard variations supplied by the current theme, instead of supplying more concrete values.

As an example, we can use this in our layout to set the text color to one of the standard colors defined in the base
system theme:

     <?xml version="1.0" encoding="utf-8"?>
     <EditText id="text"
         xmlns:android="http://schemas.android.com/apk/res/android"
         android:layout_width="fill_parent" android:layout_height="fill_parent"
         android:textColor="?android:textDisabledColor"
         android:text="@string/hello_world" />

Note that this is very similar to a resource reference, except we are using an '?' prefix instead of '@'. When you use
this markup, you are supplying the name of an attribute resource that will be looked up in the theme -- because the
resource tool knows that an attribute resource is expected, you do not need to explicitly state the type (which would be
?android:attr/android:textDisabledColor).

Other than using this resource identifier to find the value in the theme instead of raw resources, the name syntax is
identical to the '@' format: ?[namespace:]type/name with the type here being optional.


Using System Resources
Many resources included with the system are available to applications. All such resources are defined under the class
"android.R". For example, you can display the standard application icon in a screen with the following code:


     public class MyActivity extends Activity
     {
         public void onStart()
         {
             requestScreenFeatures(FEATURE_BADGE_IMAGE);

                    super.onStart();

                    setBadgeResource(android.R.drawable.sym_def_app_icon);
            }
     }

In a similar way, this code will apply to your screen the standard "green background" visual treatment defined by the
system:

     public class MyActivity extends Activity
     {
         public void onStart()
         {
             super.onStart();

                    setTheme(android.R.style.Theme_Black);
            }
     }


http://developer.android.com/guide/topics/resources/resources-i18n.html                                         Page 5 of 9
Resources and Internationalization | Android Developers                                                              29.04.09 0:40




Alternate Resources (for alternate languages and configurations)
You can supply different resources for your product according to the UI language or hardware configuration on the
device. Note that although you can include different string, layout, and other resources, the SDK does not expose
methods to let you specify which alternate resource set to load. Android detects the proper set for the hardware and
location, and loads them as appropriate. Users can select alternate language settings using the settings panel on the
device.

To include alternate resources, create parallel resource folders with qualifiers appended to the folder names, indicating
the configuration it applies to (language, screen orientation, and so on). For example, here is a project that holds one
string resource file for English, and another for French:


     MyApp/
         res/
                    values-en/
                        strings.xml
                    values-fr/
                        strings.xml

Android supports several types of qualifiers, with various values for each. Append these to the end of the resource
folder name, separated by dashes. You can add multiple qualifiers to each folder name, but they must appear in the
order they are listed here. For example, a folder containing drawable resources for a fully specified configuration would
look like:

     MyApp/
         res/
                    drawable-en-rUS-port-160dpi-finger-keysexposed-qwerty-dpad-480x320/

More typically, you will only specify a few specific configuration options that a resource is defined for. You may drop
any of the values from the complete list, as long as the remaining values are still in the same order:


     MyApp/
         res/
                    drawable-en-rUS-finger/
                    drawable-port/
                    drawable-port-160dpi/
                    drawable-qwerty/


  Qualifier                                     Values

  Language                                      The two letter ISO 639-1 language code in lowercase. For example: en, fr, es

  Region                                        The two letter ISO 3166-1-alpha-2 language code in uppercase preceded by a
                                                lowercase "r". For example: rUS, rFR, rES

  Screen orientation                            port, land, square

  Screen pixel density                          92dpi, 108dpi, etc.

  Touchscreen type                              notouch, stylus, finger

  Whether the keyboard is                       keysexposed, keyshidden
  available to the user

  Primary text input method                     nokeys, qwerty, 12key


http://developer.android.com/guide/topics/resources/resources-i18n.html                                                Page 6 of 9
Resources and Internationalization | Android Developers                                                                29.04.09 0:40


  Primary non-touchscreen                       nonav, dpad, trackball, wheel
  navigation method

  Screen dimensions                             320x240, 640x480, etc. The larger dimension must be specified first.

This list does not include device-specific parameters such as carrier, branding, device/hardware, or manufacturer.
Everything that an application needs to know about the device that it is running on is encoded via the resource
qualifiers in the table above.

Here are some general guidelines on qualified resource directory names:

     Values are separated by a dash (as well as a dash after the base directory name)
     Values are case-sensitive (even though they must be unique across all folder names in a case-insensitive way)
     For example,
           A portrait-specific drawable directory must be named drawable-port, not drawable-PORT.
           You may not have two directories named drawable-port and drawable-PORT, even if you had intended
           "port" and "PORT" to refer to different parameter values.

     Only one value for each qualifier type is supported (that is, you cannot specify drawable-rEN-rFR/)
     You can specify multiple parameters to define specific configurations, but they must always be in the order listed
     above. For example, drawable-en-rUS-land will apply to landscape view, US-English devices.
     Android will try to find the most specific matching directory for the current configuration, as described below
     The order of parameters listed in this table is used to break a tie in case of multiple qualified directories (see the
     example given below)
     All directories, both qualified and unqualified, live under the res/ folder. Qualified directories cannot be nested
     (you cannot have res/drawable/drawable-en)
     All resources will be referenced in code or resource reference syntax by their simple, undecorated name. So if a
     resource is named this:
          MyApp/res/drawable-port-92dp/myimage.png
     It would be referenced as this:
          R.drawable.myimage (code)
          @drawable/myimage (XML)


How Android finds the best matching directory
Android will pick which of the various underlying resource files should be used at runtime, depending on the current
configuration. The selection process is as follows:

 1. Eliminate any resources whose configuration does not match the current device configuration. For example, if the
    screen pixel density is 108dpi, this would eliminate only MyApp/res/drawable-port-92dpi/.


                    MyApp/res/drawable/myimage.png
                    MyApp/res/drawable-en/myimage.png
                    MyApp/res/drawable-port/myimage.png
                    MyApp/res/drawable-port-92dpi/myimage.png


 2. Pick the resources with the highest number of matching configurations. For example, if our locale is en-GB and
    orientation is port, then we have two candidates with one matching configuration each: MyApp/res/drawable-
    en/ and MyApp/res/drawable-port/. The directory MyApp/res/drawable/ is eliminated because it has
    zero matching configurations, while the others have one matching configuration.

                    MyApp/res/drawable/myimage.png
                    MyApp/res/drawable-en/myimage.png
                    MyApp/res/drawable-port/myimage.png

http://developer.android.com/guide/topics/resources/resources-i18n.html                                                  Page 7 of 9
Resources and Internationalization | Android Developers                                                          29.04.09 0:40




 3. Pick the final matching file based on configuration precedence, which is the order of parameters listed in the table
    above. That is, it is more important to match the language than the orientation, so we break the tie by picking the
    language-specific file, MyApp/res/drawable-en/.


                    MyApp/res/drawable-en/myimage.png
                    MyApp/res/drawable-port/myimage.png




Terminology
The resource system brings a number of different pieces together to form the final complete resource functionality. To
help understand the overall system, here are some brief definitions of the core concepts and components you will
encounter in using it:

Asset: A single blob of data associated with an application. This includes object files compiled from the Java source
code, graphics (such as PNG images), XML files, etc. These files are organized in a directory hierarchy that, during
final packaging of the application, is bundled together into a single ZIP file.

aapt: Android Asset Packaging Tool. The tool that generates the final ZIP file of application assets. In addition to
collecting raw assets together, it also parses resource definitions into binary asset data.

Resource Table: A special asset that aapt generates for you, describing all of the resources contained in an
application/package. This file is accessed for you by the Resources class; it is not touched directly by applications.

Resource: An entry in the Resource Table describing a single named value. Broadly, there are two types of resources:
primitives and bags.

Resource Identifier: In the Resource Table all resources are identified by a unique integer number. In source code
(resource descriptions, XML files, Java source code) you can use symbolic names that stand as constants for the
actual resource identifier integer.

Primitive Resource: All primitive resources can be written as a simple string, using formatting to describe a variety of
primitive types included in the resource system: integers, colors, strings, references to other resources, etc. Complex
resources, such as bitmaps and XML describes, are stored as a primitive string resource whose value is the path of
the underlying Asset holding its actual data.

Bag Resource: A special kind of resource entry that, instead of a simple string, holds an arbitrary list of name/value
pairs. Each name is itself a resource identifier, and each value can hold the same kinds of string formatted data as a
normal resource. Bags also support inheritance: a bag can inherit the values from another bag, selectively replacing or
extending them to generate its own contents.

Kind: The resource kind is a way to organize resource identifiers for various purposes. For example, drawable
resources are used to instantiate Drawable objects, so their data is a primitive resource containing either a color
constant or string path to a bitmap or XML asset. Other common resource kinds are string (localized string primitives),
color (color primitives), layout (a string path to an XML asset describing a view layout), and style (a bag resource
describing user interface attributes). There is also a standard "attr" resource kind, which defines the resource identifiers
to be used for naming bag items and XML attributes

Style: The name of the resource kind containing bags that are used to supply a set of user interface attributes. For
example, a TextView class may be given a style resource that defines its text size, color, and alignment. In a layout
XML file, you associate a style with a bag using the "style" attribute, whose value is the name of the style resource.

Style Class: Specifies a related set of attribute resources. This data is not placed in the resource table itself, but used
to generate constants in the source code that make it easier for you to retrieve values out of a style resource and/or
XML tag's attributes. For example, the Android platform defines a "View" style class that contains all of the standard
http://developer.android.com/guide/topics/resources/resources-i18n.html                                            Page 8 of 9
Resources and Internationalization | Android Developers                                                               29.04.09 0:40


XML tag's attributes. For example, the Android platform defines a "View" style class that contains all of the standard
view attributes: padding, visibility, background, etc.; when View is inflated it uses this style class to retrieve those
values from the XML file (at which point style and theme information is applied as approriate) and load them into its
instance.

Configuration: For any particular resource identifier, there may be multiple different available values depending on the
current configuration. The configuration includes the locale (language and country), screen orientation, screen density,
etc. The current configuration is used to select which resource values are in effect when the resource table is loaded.

Theme: A standard style resource that supplies global attribute values for a particular context. For example, when
writing an Activity the application developer can select a standard theme to use, such as the Theme.White or
Theme.Black styles; this style supplies information such as the screen background image/color, default text color,
button style, text editor style, text size, etc. When inflating a layout resource, most values for widgets (the text color,
selector, background) if not explicitly set will come from the current theme; style and attribute values supplied in the
layout can also assign their value from explicitly named values in the theme attributes if desired.

Overlay: A resource table that does not define a new set of resources, but instead replaces the values of resources
that are in another resource table. Like a configuration, this is applied at load time to the resource data; it can add new
configuration values (for example strings in a new locale), replace existing values (for example change the standard
white background image to a "Hello Kitty" background image), and modify resource bags (for example change the font
size of the Theme.White style to have an 18 pt font size). This is the facility that allows the user to select between
different global appearances of their device, or download files with new appearances.



Resource Reference
The Available Resources document provides a detailed list of the various types of resource and how to use them from
within the Java source code, or from other references.



Internationalization and Localization
     Coming Soon: Internationalization and Localization are critical, but are also not quite ready yet in the current
     SDK. As the SDK matures, this section will contain information on the Internationalization and Localization
     features of the Android platform. In the meantime, it is a good idea to start by externalizing all strings, and
     practicing good structure in creating and using resources.

" Back to Resources and Assets                                                                                       ! Go to top

Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/resources/resources-i18n.html                                                 Page 9 of 9
Available Resource Types | Android Developers                                                               29.04.09 0:40




Resources and Assets >

Available Resource Types

This page describes the different types of resources that you can externalize from your code and package with your
application.

For more details on how to use resources in your application, please see the Resources and Internationalization
documentation.



Simple Values
All simple resource values can be expressed as a string, using various formats to unambiguously indicate the type of
resource being created. For this reason, these values can be defined both as standard resources (under res/values/),
as well as direct values supplied for mappings in styles and themes, and attributes in XML files such as layouts.


Color Values
A color value specifies an RGB value with an alpha channel, which can be used in various places such as specifying
a solid color for a Drawable or the color to use for text. A color value always begins with a pound (#) character and
then followed by the Alpha-Red-Green-Blue information in one of the following formats:

     #RGB
     #ARGB
     #RRGGBB
     #AARRGGBB

If you want to retrieve the color represented by a resource ID, you can call the Resources.getColor() method.

Source file format: XML file requiring a <?xml version="1.0" encoding="utf-8"?> declaration, and a root
<resources> element containing one or more <color> tags.

Resource source file location: res/values/colors.xml (file name is arbitrary)

Compiled resource datatype: Resource pointer to a Java int.

Resource reference name:

     Java: R.color.some_name
     XML: @[package:]color/some_name (where some_name is the name of a specific color)

Syntax


     <color name=color_name>#color_value</color>

<color>
    Value is a color, using web-style syntax, as describe above. Has only one attribute:
           name - The name used in referring to this color.


http://developer.android.com/guide/topics/resources/available-resources.html                                    Page 1 of 14
Available Resource Types | Android Developers                                                                   29.04.09 0:40



Example XML Declaration

The following code declares two colors, the first fully opaque, and the second translucent.


     <resources>
        <color name="opaque_red">#f00</color>
        <color name="translucent_red">#80ff0000</color>
     </resources>

Example Code Use

Example Java code

     // Retrieve a color value.
     int color = getResources.getColor(R.color.opaque_red);

Example XML code

     <TextView android:layout_width="fill_parent"
               android:layout_height="wrap_content"
               android:textAlign="center"
               android:textColor="@color/translucent_red"
               android:text="Some Text"/>


Strings and Styled Text
Strings, with optional simple formatting, can be stored and retrieved as resources. You can add formatting to your
string by using three standard HTML tags: <b>, <i>, and <u>. To guarantee getting an unstyled string only (the raw
text) call the toString() method of the retrieved CharSequence object. Methods that accept string resources should
be able to process these styling tags.

If you want to retrieve the String represented by a resource ID, you can call the Context.getString() method.

Note: If you use an apostrophe or a quote in your string, you must either escape it or enclose the whole string in the
other kind of enclosing quotes:


     <string       name="good_example">"This'll work"</string>
     <string       name="good_example_2">This\'ll also work</string>
     <string       name="bad_example">This won't work!</string>
     <string       name="bad_example_2">XML encodings won&apos;t work either!</string>

Source file format: XML file requiring a <?xml version="1.0" encoding="utf-8"?> declaration, and a root
<resources> element containing one or more <string> tags.

Resource source file location: res/values/strings.xml (file name is arbitrary)

Compiled resource datatype: Resource pointer to a Java CharSequence.

Resource reference name:

     Java: R.string.some_name
     XML: @[package:]string/some_name (where some_name is the name of a specific string)

Syntax

     <string name=string_name>string_value</string>

http://developer.android.com/guide/topics/resources/available-resources.html                                     Page 2 of 14
Available Resource Types | Android Developers                                                                  29.04.09 0:40




<string>
     Value is a string, with optional styling tags. Has only one attribute:
           name - The name used in referring to this string.

Example XML Declaration

The following declares two strings: the first — simple text with no formatting (resulting in a CharSequence that is
simply a String object) — the second includes formatting information in the string (resulting in a CharSequence that is
a complex data structure). If you are using the custom editor for string files in Eclipse, the HTML formatting tags will
automatically be escaped and you will need to use Context.getString() and fromHtml(String) to retreive the resource
and then convert it to formatted text.


     <resources>
        <string name="simple_welcome_message">Welcome!</string>
        <string name="styled_welcome_message">We are <b><i>so</i></b> glad to see
     you.</string>
     </resources>

Example Code Use

Example Java code


     // Assign a styled string resource to a TextView
     // on the current screen.
     CharSequence str = getString(R.string.styled_welcome_message);
     TextView tv = (TextView)findViewByID(R.id.text);
     tv.setText(str);

Example XML code


     <TextView android:layout_width="fill_parent"
               android:layout_height="wrap_content"
               android:textAlign="center"
               android:text="@string/simple_welcome_message"/>


Using Styled Text as a Format String
Sometimes you may want to create a styled text resource that is also used as a format string. This cannot be done
directly because there is no way of passing the styled text as the format string argument of String.format() without
stripping out the style information. The workaround is to store the style tags as escaped HTML tags, and then convert
the escaped HTML string into a styled text after formatting has taken place.

To use styled text as a format string, do the following.

 1. Store your styled text resource as an escaped string, so that the HTML tags in your text resource are not
    interpreted as if they were XML tags:

           <resources>
             <string name="search_results_resultsTextFormat">%1$d results for
           &lt;b>&amp;quot;%2$s&amp;quot;&lt;/b></string>
           </resources>

     In this example the format string has two arguments: %1$d is a decimal number, %2$s is a string.
 2. Make sure any String arguments are properly escaped if they might contain '<' or '&' characters. The
    htmlEncode(String) method will do this:

           String escapedTitle = TextUtil.htmlEncode(title);

http://developer.android.com/guide/topics/resources/available-resources.html                                    Page 3 of 14
Available Resource Types | Android Developers                                                                   29.04.09 0:40




 3. Use String.format() to format the HTML text, then use fromHtml(String) to convert the HTML text into styled text:

           String resultsTextFormat =
           getContext().getResources().getString(R.string.search_results_resultsTextFormat
           );
           String resultsText = String.format(resultsTextFormat, count, escapedTitle);
           CharSequence styledResults = Html.fromHtml(resultsText);



You can create common dimensions to use for various screen elements by defining dimension values in XML. A
dimension resource is a number followed by a unit of measurement. For example: 10px, 2in, 5sp. Here are the units of
measurement supported by Android:

px
     Pixels - corresponds to actual pixels on the screen.

in
     Inches - based on the physical size of the screen.

mm
     Millimeters - based on the physical size of the screen.

pt
     Points - 1/72 of an inch based on the physical size of the screen.

dp
     Density-independent Pixels - an abstract unit that is based on the physical density of the screen. These units are
     relative to a 160 dpi screen, so one dp is one pixel on a 160 dpi screen. The ratio of dp-to-pixel will change with
     the screen density, but not necessarily in direct proportion. Note: The compiler accepts both "dip" and "dp",
     though "dp" is more consistent with "sp".

sp
     Scale-independent Pixels - this is like the dp unit, but it is also scaled by the user's font size preference. It is
     recommend you use this unit when specifying font sizes, so they will be adjusted for both the screen density and
     user's preference.

Dimension values are not normally used as raw resources, but rather as attribute values in XML files. You can,
however, create plain resources containing this data type.

Source file format: XML file requiring a <?xml version="1.0" encoding="utf-8"?> declaration, and a root
<resources> element containing one or more <dimen> tags.

Resource source file location: res/values/dimens.xml (File name is arbitrary; standard practice is to put all
dimensions in one file devoted to dimensions.)

Compiled resource datatype: Resource pointer to a dimension.

Resource reference name:

     Java: R.dimen.some_name
     XML: @[package:]dimen/some_name (where some_name is the name of a specific <dimen> element)

Syntax


     <dimen name=dimen_name>dimen_value</dimen>

<dimen>


http://developer.android.com/guide/topics/resources/available-resources.html                                     Page 4 of 14
Available Resource Types | Android Developers                                                                   29.04.09 0:40


     A valid dimension value.
           name - The name used in referring to this dimension.

Example XML Declaration

The following code declares several dimension values.

     <resources>
         <dimen name="one_pixel">1px</dimen>
         <dimen name="double_density">2dp</dimen>
         <dimen name="sixteen_sp">16sp</dimen>
     </resources>

Example Code Use

Example Java code:

     float dimen = Resources.getDimen(R.dimen.one_pixel);

Example XML code:


     <TextView android:layout_width="fill_parent"
               android:layout_height="wrap_content"
               android:textSize="@dimen/sixteen_sp"/>




Drawables
A Drawable is a type of resource that you retrieve with Resources.getDrawable() and use to draw to the screen. There
are a number of drawable resources that can be created.


Bitmap Files
Android supports bitmap resource files in a few different formats: png (preferred), jpg (acceptable), gif (discouraged).
The bitmap file itself is compiled and referenced by the file name without the extension (so
res/drawable/my_picture.png would be referenced as R.drawable.my_picture).

Source file formats: png (preferred), jpg (acceptable), gif (discouraged). One resource per file.

Resource file location: res/drawable/some_file.png or some_file.jpg or some_file.gif.

Compiled resource datatype: Resource pointer to a BitmapDrawable.

Resource reference name:

     Java: R.drawable.some_file
     XML: @[package:]drawable/some_file

For more discussion and examples using drawable resources, see the discussion in 2D Graphics.


Color Drawables
You can create a PaintDrawable object that is a rectangle of color, with optionally rounded corners. This element can
be defined in any of the files inside res/values/.


http://developer.android.com/guide/topics/resources/available-resources.html                                     Page 5 of 14
Available Resource Types | Android Developers                                                                   29.04.09 0:40


Source file format: XML file requiring a <?xml version="1.0" encoding="utf-8"?> declaration, and a root
<resources> element containing one or more <drawable> tags.

Resource source file location: res/values/colors.xml (File name is arbitrary; standard practice is to put the
PaintDrawable items in the file along with the numeric color values.)

Compiled resource datatype: Resource pointer to a PaintDrawable.

Resource reference name:

     Java: R.drawable.some_name
     XML: @[package:]drawable/some_name (where some_name is the name of a specific resource)

Syntax


     <drawable name=color_name>color_value</drawable>

<drawable>
    A valid color value.
           name - The name used in referring to this drawable.

Example XML Declaration

The following code declares several color drawables.

     <resources>
         <drawable name="solid_red">#f00</drawable>
         <drawable name="solid_blue">#0000ff</drawable>
         <drawable name="solid_green">#f0f0</drawable>
     </resources>

Example Code Use

Example Java code

     // Assign a PaintDrawable as the background to
     // a TextView on the current screen.
     Drawable redDrawable = Resources.getDrawable(R.drawable.solid_red);
     TextView tv = (TextView)findViewByID(R.id.text);
     tv.setBackground(redDrawable);

Example XML code

     <TextView android:layout_width="fill_parent"
               android:layout_height="wrap_content"
               android:textAlign="center"
               android:background="@drawable/solid_red"/>


Nine-Patch (stretchable) Images
Android supports a stretchable bitmap image, called a NinePatch graphic. This is a PNG image in which you define
stretchable sections that Android will resize to fit the object at display time to accommodate variable sized sections,
such as text strings. You typically assign this resource to the View's background. An example use of a stretchable
image is the button backgrounds that Android uses; buttons must stretch to accommodate strings of various lengths.

Source file format: PNG — one resource per file


http://developer.android.com/guide/topics/resources/available-resources.html                                     Page 6 of 14
Available Resource Types | Android Developers                                                                     29.04.09 0:40



Resource source file location: res/drawable/some_name.9.png (must end in .9.png)

Compiled resource datatype: Resource pointer to a NinePatchDrawable.

Resource reference name:

     Java: R.drawable.some_file
     XML: @[package:]drawable.some_file

For more information and examples using NinePatch drawables, see the discussion in 2D Graphics.



Animation

Tweened Animation
Android can perform simple animation on a graphic, or a series of graphics. These include rotations, fading, moving,
and stretching.

Source file format: XML file, one resource per file, one root tag with no <?xml> declaration

Resource file location: res/anim/some_file.xml

Compiled resource datatype: Resource pointer to an Animation.

Resource reference name:

     Java: R.anim.some_file
     XML: @[package:]anim/some_file

Syntax

The file must have a single root element: this will be either a single <alpha>, <scale>, <translate>, <rotate>,
interpolator element, or <set> element that holds groups of these elements (which may include another <set>). By
default, all elements are applied simultaneously. To have them occur sequentially, you must specify the startOffset
attribute.

     <set android:shareInterpolator=boolean>                                   // Only required if multiple tags are
     used.
        <alpha android:fromAlpha=float
               android:toAlpha=float >    |
        <scale android:fromXScale=float
               android:toXScale=float
               android:fromYScale=float
               android:toYScale=float
               android:pivotX=string
               android:pivotY=string >      |
        <translate android:fromX=string
                   android:toX=string
                   android:fromY=string
                   android:toY=string >     |
        <rotate android:fromDegrees=float
                android:toDegrees=float
                android:pivotX=string
                android:pivotY=string > |
        <interpolator tag>
        <set>
     </set>



http://developer.android.com/guide/topics/resources/available-resources.html                                       Page 7 of 14
Available Resource Types | Android Developers                                                                    29.04.09 0:40


Elements and Attributes

<set>
    A container that can recursively hold itself or other animations. Represents an AnimationSet. You can include as
    many child elements of the same or different types as you like. Supports the following attribute:
           shareInterpolator - Whether to share the same Interpolator among all immediate child elements.

<alpha>
    A fading animation. Represents an AlphaAnimation. Supports the following attributes:
           fromAlpha - 0.0 to 1.0, where 0.0 is transparent.
           toAlpha - 0.0 to 1.0, where 0.0 is transparent.

<scale>
    A resizing animation. Represents a ScaleAnimation. You can specify what is the center point of the image (the
    pinned center), from which it grows outward (or inward), by specifying pivotX and pivotY. So, for example, if these
    were 0, 0 (top left corner), all growth would be down and to the right. scale supports the following attributes:
           fromXScale - Starting X size, where 1.0 is no change.
           toXScale - Ending X size, where 1.0 is no change.
           fromYScale - Starting Y size, where 1.0 is no change.
           toYScale - Ending Y size, where 1.0 is no change.
           pivotX - The X coordinate of the pinned center.
           pivotY - The Y coordinate of the pinned center.

<translate>
    A vertical/horizontal motion animation. Represents a TranslateAnimation. Supports the following attributes in any
    of the following three formats: values from -100 to 100, ending with "%", indicating a percentage relative to itself;
    values from -100 to 100, ending in "%p", indicating a percentage relative to its parent; a float with no suffix,
    indicating an absolute value.
           fromXDelta - Starting X location.
           toXDelta - Ending X location.
           fromYDelta - Starting Y location.
           toYDelta - Ending Y location.

<rotate>
    A rotation animation. Represents a RotateAnimation. Supports the following attributes:
           fromDegrees - Starting rotation, in degrees.
           toDegrees - Ending rotation, in degrees.
           pivotX - The X coordinate of the center of rotation, in pixels, where (0,0) is the top left corner.
           pivotY - The Y coordinate of the center of rotation, in pixels, where (0,0) is the top left corner.

<interpolator tag>
     You can also use any of the interpolator subclass elements defined in R.styleable. Examples include
     <CycleInterpolator>, <EaseInInterpolator>, and <EaseOutInterpolator>. These objects define a velocity curve that
     describes how quickly a visual action takes place on a timeline (fast at first and slow later, slow at first and
     gradually faster, and so on).

In addition to the attributes defined for each element above, the elements <alpha>, <scale>, <translate>,
<rotate>, and <set> all support the following attributes (inherited from the Animation class):

duration
    Duration, in milliseconds, for this effect.



http://developer.android.com/guide/topics/resources/available-resources.html                                      Page 8 of 14
Available Resource Types | Android Developers                                                                  29.04.09 0:40


startOffset
     Offset start time for this effect, in milliseconds.

fillBefore
      When set true, the animation transformation is applied before the animation begins.

fillAfter
      When set true, the animation transformation is applied after the animation ends.

repeatCount
    Defines the number of times the animation should repeat.

repeatMode
    Defines the animation behavior when it reaches the end and the repeat count is greater than 0. Options are to
    either restart or reverse the animation.

zAdjustment
    Defines the z-axis ordering mode to use when running the animation (normal, top, or bottom).

interpolator
     You can optionally set an interpolator for each element to determine how quickly or slowly it performs its effect
     over time. For example, slow at the beginning and faster at the end for EaseInInterpolator, and the reverse for
     EaseOutInterpolator. A list of interpolators is given in R.anim. To specify these, use the syntax
     @android:anim/interpolatorName.

For more discussion and animation code samples, see the discussion in the 2D Graphics document.



Menus
Application menus (Options Menu, Context Menu, or Sub Menu) can be defined as XML resources and inflated by
your application using MenuInflater.

Source file format: XML file, one resource per file, one root tag, <?xml> declaration not required.

Resource file location: res/menu/some_file.xml

Compiled resource datatype: Resource pointer to a Menu (or subclass) resource.

Resource reference name:

     Java: R.menu.some_file


Syntax
The file must have a single root element: a <menu> element. In all, there are three valid elements: <menu>, <group>
and <item>. The <item> and <group> elements must be the children of a <menu>, but <item> elements can also
be the children of a <group>, and another <menu> element may be the child of an <item> (to create a Sub Menu).

     <menu xmlns:android="http://schemas.android.com/apk/res/android">

            <item android:id="@+id/example_item
                  android:title="Example Item"
                  android:icon="@drawable/example_item_icon" />

            <group android:id="@+id/example_group">
                <item android:id="@+id/example_item2
                      android:title="Example Item 2"
                      android:icon="@drawable/example_item2_icon" />


http://developer.android.com/guide/topics/resources/available-resources.html                                     Page 9 of 14
Available Resource Types | Android Developers                                                                  29.04.09 0:40

                              android:icon="@drawable/example_item2_icon" />
            </group>

            <item android:id="@+id/example_submenu
                  android:title="Example Sub Menu" >
                <menu>
                    <item android:id="@+id/example_submenu_item
                          android:title="Example Sub Menu Item" />
                </menu>
            </item>

     </menu>


Elements and Attributes
All attributes must be defined with the android namespace (e.g., android:icon="@drawable/icon").

<menu>
   The root of a menu. Contains <item> and <group> nodes. No attributes.

<group>
    A menu group. Contains <item> elements. Valid attributes:
           id - A unique integer ID for the group.
           menuCategory - Value corresponding to Menu CATEGORY_* constants — defines the priority of the group.
           Valid values: container, system, secondary, and alternative.
           orderInCategory - An integer that defines the default order of the items within the category.
           checkableBehavior - Whether the items are checkable. Valid values: none, all (exclusive / radio buttons),
           single (non-exclusive / checkboxes)
           visible - Whether the group is visible. true or false.
           enabled - Whether the group is enabled. true or false.

<item>
    A menu item. May contain a <menu> element (for a Sub Menu). Valid attributes:
           id - A unique resource ID for the item.
           menuCategory - Used to define the menu category.
           orderInCategory - Used to define the order of the item, within a group.
           title - A string for the menu title.
           titleCondensed - A condensed string title, for situations in which the normal title is too long.
           icon - A resource identifier for a drawable icon.
           alphabeticShortcut - A character for the alphabetic shortcut key.
           numericShortcut - A number for the numeric shortcut key.
           checkable - Whether the item is checkable. true or false.
           checked - Whether the item is checked by default. true or false.
           visible - Whether the item is visible by default. true or false.
           enabled - Whether the item is enabled by default. true or false.

For more discussion on how to create menus in XML and inflate them in your application, read Creating Menus.



Layout
Android lets you specify screen layouts using XML elements inside an XML file, similar to designing screen layout for a
webpage in an HTML file. Each file contains a whole screen or a part of a screen, and is compiled into a View
http://developer.android.com/guide/topics/resources/available-resources.html                                   Page 10 of 14
Available Resource Types | Android Developers                                                                   29.04.09 0:40


webpage in an HTML file. Each file contains a whole screen or a part of a screen, and is compiled into a View
resource that can be passed in to Activity.setContentView or used as a reference by other layout resource elements.
Files are saved in the res/layout/ folder of your project, and compiled by the Android resource compiler, aapt.

Every layout XML file must evaluate to a single root element. First we'll describe how to use the standard XML tags
understood by Android as it is shipped, and then we'll give a little information on how you can define your own custom
XML elements for custom View objects.

The root element must have the Android namespace "http://schemas.android.com/apk/res/android" defined in the root
element.

For a complete discussion on creating layouts, see the User Interface topic.

Source file format: XML file requiring a <?xml version="1.0" encoding="utf-8"?> declaration, and a root
element of one of the supported XML layout elements.

Resource file location: res/layout/some_file.xml.

Compiled resource datatype: Resource pointer to a View (or subclass) resource.

Resource reference name:

     Java: R.layout.some_file
     XML: @[package:]layout/some_file

Syntax


     <ViewGroupClass xmlns:android="http://schemas.android.com/apk/res/android"
                     id="@+id/string_name" (attributes)>
        <widget or other nested ViewGroupClass>+
        <requestFocus/>(0 or 1 per layout file, assigned to any element)
     </ViewGroupClass>

<ViewGroupClass>

     The file must have a single root element. This can be a ViewGroup class that contains other elements, or a widget
     (or custom item) if it's only one object. By default, you can use any (case-sensitive) Android widget or ViewGroup
     class name as an element. These elements support attributes that apply to the underlying class, but the naming is
     not as clear. How to discover what attributes are supported for what tags is discussed below. You should not
     assume that any nesting is valid (for example you cannot enclose <TextView> elements inside a
     <ListLayout>).

     If a class derives from another class, the XML element inherits all the attributes from the element that it "derives"
     from. So, for example, <EditText> is the corresponding XML element for the EditText class. It exposes its own
     unique attributes (EditText_numeric), as well as all attributes supported by <TextView> and <View>. For
     the id attribute of a tag in XML, you should use a special syntax: "@+id/somestringvalue". The "@+" syntax
     creates a resource number in the R.id class, if one doesn't exist, or uses it, if it does exist. When declaring an ID
     value for an XML tag, use this syntax. Example: <TextView id="@+id/nameTextbox"/>, and refer to it this
     way in Java: findViewById(R.id.nameTextbox). All elements support the following values:
           id - An ID value used to access this element in Java. Typically you will use the syntax @+id/string_name to
           generate an ID for you in the id.xml file if you haven't created one yourself.
           xmlns:android="http://schemas.android.com/apk/res/android" - Required for the root
           element only.

<requestFocus>
    Any element representing a View object can include this empty element, which gives it's parent tag initial focus on
    the screen. You can have only one of these elements per file.


http://developer.android.com/guide/topics/resources/available-resources.html                                     Page 11 of 14
Available Resource Types | Android Developers                                                                     29.04.09 0:40


What Attributes Are Supported for What Elements?

Android uses the LayoutInflater class at run time to load an XML layout resource and translate it into visual elements.
By default, all widget class names are supported directly as tags, but a full list of supported tags and attributes is listed
in the R.styleable reference page. However, the attribute names are somewhat obscure. If an underscore appears in
the name, this indicates that it is an attribute — typically of the element before the underscore. So, for example,
EditText_autoText means that the <EditText> tag supports an attribute autoText. When you actually use the
attribute in that element, use only the portion after the last underscore, and prefix the attribute with the prefix
"android:". So, for example, if R.styleable lists the following values:

     TextView
     TextView_lines
     TextView_maxlines

You could create an element like this:


     <TextView android:lines="10" android:maxlines="20"/>

This would create a TextView object and set its lines and maxlines properties.

Attributes come from three sources:

     Attributes exposed directly by the element. For example, TextView supports TextView_text, as discussed
     above.
     Attributes exposed by all the superclasses of that element. For example, the TextView class extends the View
     class, so the <TextView> element supports all the attributes that the <View> element exposes — a long list,
     including View_paddingBottom and View_scrollbars. These too are used without the class name:
     <TextView android:paddingBottom="20" android:scrollbars="horizontal" />.
     Attributes of the object's ViewGroup.LayoutParams subclass. All View objects support a LayoutParams
     member (see Declaring Layout). To set properties on an element's LayoutParams member, the attribute to use is
     "android:layout_layoutParamsProperty". For example: android:layout_gravity for an object wrapped by a
     <LinearLayout> element. Remember that each LayoutParams subclass also supports inherited attributes.
     Attributes exposed by each subclass are given in the format
     someLayoutParamsSubclass_Layout_layout_someproperty. This defines an attribute
     "android:layout_someproperty". Here is an example of how Android documentation lists the properties of the
     LinearLayout.LayoutParams class:

     LinearLayout_Layout // The actual object — not used.
     LinearLayout_Layout_layout_gravity // Exposes a gravity attribute
     LinearLayout_Layout_layout_height // Exposes a height attribute
     LinearLayout_Layout_layout_weight // Exposes a weight attribute
     LinearLayout_Layout_layout_width // Exposes a width attribute

Here is an example that sets some of these values on a few objects, including direct attributes, inherited attributes,
and LayoutParams attributes:


     <?xml version="1.0" encoding="utf-8"?>
     <!-- res/main_screen.xml -->
     <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
                   android:orientation="vertical"    // The object's own orientation
     property
                   android:padding="4"               // Inherited View property
                   android:gravity="center"          // The object's own property
                   android:layout_width="fill_parent" // Parent object's
     LinearLayout.LayoutParams.width

http://developer.android.com/guide/topics/resources/available-resources.html                                      Page 12 of 14
Available Resource Types | Android Developers                                                                   29.04.09 0:40

     LinearLayout.LayoutParams.width
                   android:layout_height="fill_parent"> // Parent object's
     LinearLayout.LayoutParams.height
          <TextView android:layout_width="fill_parent"   // TextView.LayoutParams.width
                    android:layout_height="wrap_content" // TextView.LayoutParams.height
                    android:layout_weight="0"            // TextView.LayoutParams.weight
                    android:paddingBottom="4"            // TextView.paddingBottom
                    android:text="@string/redirect_getter"/> // TextView.text
        <EditText id="@+id/text"
                  android:layout_width="fill_parent"                           // EditText.LayoutParams.width
                  android:layout_height="wrap_content"                         // EditText.LayoutParams.height
                  android:layout_weight="0"                                    //
     EditText.LinearLayoutParams.weight
                  android:paddingBottom="4">                                   // EditText.paddingBottom
            <requestFocus />
        </EditText>
        <Button id="@+id/apply"
                android:layout_width="wrap_content" // Button.LayoutParams.width
                android:layout_height="wrap_content" // Button.LayoutParams.height
                android:text="@string/apply" />      // TextView.text
     </LinearLayout>

Example Code Use

The most common use is to load the XML file (located at res/main_screen.xml) and use it as the current screen, as
shown here with the preceding file:


     setContentView(R.layout.main_screen);

However, layout elements can also represent repeating elements used as templates.

Also see User Interface for more information on layouts.


Custom Layout Resources
You can define custom elements to use in layout resources. These custom elements can then be used the same as
any Android layout elements: that is, you can use them and specify their attributes in other resources. The ApiDemos
sample application has an example of creating a custom layout XML tag, LabelView. To create a custom element, you
will need the following files:

     Java implementation file - The implementation file. The class must extend View or a subclass. See
     LabelView.java in ApiDemos.
     res/values/attrs.xml - Defines the XML element, and the attributes that it supports, for clients to use to instantiate
     your object in their layout XML file. Define your element in a <declare-styleable
     id=your_java_class_name>. See res/layout/attrs.xml in ApiDemos.
     res/layout/your_class.xml [optional] - An optional XML file to describe the layout of your object. This could also
     be done in Java. See custom_view_1.xml in ApiDemos.

Source file format: XML file without an <?xml> declaration, and a <resources> root element containing one or
more custom element tags.

Resource file location: res/values/attrs.xml (file name is arbitrary).

Compiled resource datatype: Resource pointer to a View (or subclass) resource.

Resource reference name: R.styleable.some_file (Java).




http://developer.android.com/guide/topics/resources/available-resources.html                                     Page 13 of 14
Available Resource Types | Android Developers                                                                         29.04.09 0:40



Styles and Themes
A style is one or more attributes applied to a single element (for example, 10 point red Arial font, applied to a
TextView). A style is applied as an attribute to an element in a layout XML file.

A theme is one or more attributes applied to a whole screen — for example, you might apply the stock Android
Theme.dialog theme to an activity designed to be a floating dialog box. A theme is assigned as an attribute to an
Activity in the manifest file.

Both styles and themes are defined in a <style> block containing one or more string or numerical values (typically
color values), or references to other resources (drawables and so on). These elements support inheritance, so you
could have MyBaseTheme, MyBaseTheme.Fancy, MyBaseTheme.Small, and so on.

For a complete discussion on styles and themes, read Applying Styles and Themes.

Source file format: XML file requiring a <?xml version="1.0" encoding="utf-8"?> declaration, and a root
<resources> element containing one or more <style> tags.

Resource source file location: res/values/styles.xml (file name is arbitrary). The file name is arbitrary, but standard
practice is to put all styles into a file named styles.xml.

Compiled resource datatype: Resource pointer to a Java CharSequence.

Resource reference name:

     Java: R.style.styleID for the whole style, R.style.styleID.itemID for an individual setting
     XML: @[package:]style/styleID for a whole style, @[package:]style/styleID/itemID for an
     individual item. Note: to refer to a value in the currently applied theme, use "?" instead of "@" as described below
     (XML).

Syntax


     <style name=string [parent=string] >
        <item name=string>Hex value | string value | reference</item>+
     </style>

<style>
     Holds one or more <item> elements, each describing one value. This style, which is a bundle of values, can be
     referred to as a theme.
           name - The name used in referring to this theme.
           parent - An optional parent theme. All values from the specified theme will be inherited into this theme. Any
           values with identical names that you specify will override inherited values. The name must be qualified by the
           package, but you don't need the /style directive (for example, android:Theme for the base Android theme,
           or MyTheme for a theme defined in your package).

<item>
    A value to use in this theme. It can be a standard string, a hex color value, or a reference to any other resource
    type.

For examples of how to declare and apply styles and themes, read Applying Styles and Themes.

" Back to Resources and Assets                                                                                       ! Go to top

Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines



http://developer.android.com/guide/topics/resources/available-resources.html                                          Page 14 of 14
Intents and Intent Filters | Android Developers                                                                    29.04.09 0:40




Intents and Intent Filters

Three of the core components of an application — activities, services, and broadcast receivers — are activated
through messages, called intents. Intent messaging is a facility for late run-time binding between components in the
same or different applications. The intent itself, an Intent object, is a passive data structure holding an abstract
description of an operation to be performed — or, in the case of broadcasts, a description of something that has
happened and is being announced. There are separate mechanisms for delivering intents to each type of component:

      An Intent object is passed to Context.startActivity() or Activity.startActivityForResult() to
      launch an activity or get an existing activity to do something new.

      An Intent object is passed to Context.startService() to initiate a service or deliver new instructions to an
      ongoing service. Similarly, an intent can be passed to Context.bindService() to establish a connection
      between the calling component and a target service. It can optionally initiate the service if it's not already running.

      Intent objects passed to any of the broadcast methods (such as Context.sendBroadcast(),
      Context.sendOrderedBroadcast(), or Context.sendStickyBroadcast()) are delivered to all
      interested broadcast receivers. Many kinds of broadcasts originate in system code.

In each case, the Android system finds the appropriate activity, service, or set of broadcast receivers to respond to the
intent, instantiating them if necessary. There is no overlap within these messaging systems: Broadcast intents are
delivered only to broadcast receivers, never to activities or services. An intent passed to startActivity() is
delivered only to an activity, never to a service or broadcast receiver, and so on.

This document begins with a description of Intent objects. It then describes the rules Android uses to map intents to
components — how it resolves which component should receive an intent message. For intents that don't explicitly
name a target component, this process involves testing the Intent object against intent filters associated with potential
targets.



Intent Objects
An Intent object is a bundle of information. It contains information of interest to the component that receives the intent
(such as the action to be taken and the data to act on) plus information of interest to the Android system (such as the
category of component that should handle the intent and instructions on how to launch a target activity). Principally, it
can contain the following:

Component name
   The name of the component that should handle the intent. This field is a ComponentName object — a
   combination of the fully qualified class name of the target component (for example
   "com.example.project.app.FreneticActivity") and the package name set in the manifest file of the
   application where the component resides (for example, "com.example.project"). The package part of the
   component name and the package name set in the manifest do not necessarily have to match.

      The component name is optional. If it is set, the Intent object is delivered to an instance of the designated class. If
      it is not set, Android uses other information in the Intent object to locate a suitable target — see Intent Resolution,
      later in this document.

      The component name is set by setComponent(), setClass(), or setClassName() and read by
      getComponent().


http://developer.android.com/guide/topics/intents/intents-filters.html                                               Page 1 of 7
Intents and Intent Filters | Android Developers                                                                              29.04.09 0:40



Action
    A string naming the action to be performed — or, in the case of broadcast intents, the action that took place and
    is being reported. The Intent class defines a number of action constants, including these:

            Constant                                       Target        Action
                                                           component

            ACTION_CALL                                    activity      Initiate a phone call.

            ACTION_EDIT                                    activity      Display data for the user to edit.

            ACTION_MAIN                                    activity      Start up as the initial activity of a task, with no data
                                                                         input and no returned output.

            ACTION_SYNC                                    activity      Synchronize data on a server with data on the mobile
                                                                         device.

            ACTION_BATTERY_LOW                             broadcast     A warning that the battery is low.
                                                           receiver

            ACTION_HEADSET_PLUG                            broadcast     A headset has been plugged into the device, or
                                                           receiver      unplugged from it.

            ACTION_SCREEN_ON                               broadcast     The screen has been turned on.
                                                           receiver

            ACTION_TIMEZONE_CHANGED                        broadcast     The setting for the time zone has changed.
                                                           receiver

      See the Intent class description for a list of pre-defined constants for generic actions. Other actions are defined
      elsewhere in the Android API. You can also define your own action strings for activating the components in your
      application. Those you invent should include the application package as a prefix — for example:
      "com.example.project.SHOW_COLOR".

      The action largely determines how the rest of the intent is structured — particularly the data and extras fields —
      much as a method name determines a set of arguments and a return value. For this reason, it's a good idea to
      use action names that are as specific as possible, and to couple them tightly to the other fields of the intent. In
      other words, instead of defining an action in isolation, define an entire protocol for the Intent objects your
      components can handle.

      The action in an Intent object is set by the setAction() method and read by getAction().

Data
    The URI of the data to be acted on and the MIME type of that data. Different actions are paired with different
    kinds of data specifications. For example, if the action field is ACTION_EDIT, the data field would contain the URI
    of the document to be displayed for editing. If the action is ACTION_CALL, the data field would be a tel: URI
    with the number to call. Similarly, if the action is ACTION_VIEW and the data field is an http: URI, the receiving
    activity would be called upon to download and display whatever data the URI refers to.

      When matching an intent to a component that is capable of handling the data, it's often important to know the type
      of data (its MIME type) in addition to its URI. For example, a component able to display image data should not be
      called upon to play an audio file.

      In many cases, the data type can be inferred from the URI — particularly content: URIs, which indicate that the
      data is located on the device and controlled by a content provider (see the separate discussion on content
      providers). But the type can also be explicitly set in the Intent object. The setData() method specifies data only
      as a URI, setType() specifies it only as a MIME type, and setDataAndType() specifies it as both a URI and
      a MIME type. The URI is read by getData() and the type by getType().



http://developer.android.com/guide/topics/intents/intents-filters.html                                                         Page 2 of 7
Intents and Intent Filters | Android Developers                                                                                 29.04.09 0:40


Category
    A string containing additional information about the kind of component that should handle the intent. Any number
    of category descriptions can be placed in an Intent object. As it does for actions, the Intent class defines several
    category constants, including these:

            Constant                                Meaning

            CATEGORY_BROWSABLE                      The target activity can be safely invoked by the browser to display data
                                                    referenced by a link — for example, an image or an e-mail message.

            CATEGORY_GADGET                         The activity can be embedded inside of another activity that hosts gadgets.

            CATEGORY_HOME                           The activity displays the home screen, the first screen the user sees when
                                                    the device is turned on or when the HOME key is pressed.

            CATEGORY_LAUNCHER                       The activity can be the initial activity of a task and is listed in the top-level
                                                    application launcher.

            CATEGORY_PREFERENCE                     The target activity is a preference panel.

      See the Intent class description for the full list of categories.

      The addCategory() method places a category in an Intent object, removeCategory() deletes a category
      previously added, and getCategories() gets the set of all categories currently in the object.

Extras
    Key-value pairs for additional information that should be delivered to the component handling the intent. Just as
    some actions are paired with particular kinds of data URIs, some are paired with particular extras. For example,
    an ACTION_TIMEZONE_CHANGED intent has a "time-zone" extra that identifies the new time zone, and
    ACTION_HEADSET_PLUG has a "state" extra indicating whether the headset is now plugged in or unplugged, as
    well as a "name" extra for the type of headset. If you were to invent a SHOW_COLOR action, the color value would
    be set in an extra key-value pair.

      The Intent object has a series of put...() methods for inserting various types of extra data and a similar set of
      get...() methods for reading the data. These methods parallel those for Bundle objects. In fact, the extras can
      be installed and read as a Bundle using the putExtras() and getExtras() methods.

Flags
    Flags of various sorts. Many instruct the Android system how to launch an activity (for example, which task the
    activity should belong to) and how to treat it after it's launched (for example, whether it belongs in the list of recent
    activities). All these flags are defined in the Intent class.

The Android system and the applications that come with the platform employ Intent objects both to send out system-
originated broadcasts and to activate system-defined components. To see how to structure an intent to activate a
system component, consult the list of intents in the reference.



Intent Resolution
Intents can be divided into two groups:

      Explicit intents designate the target component by its name (the component name field, mentioned earlier, has a
      value set). Since component names would generally not be known to developers of other applications, explicit
      intents are typically used for application-internal messages — such as an activity starting a subordinate service or
      launching a sister activity.

      Implicit intents do not name a target (the field for the component name is blank). Implicit intents are often used to
      activate components in other applications.

http://developer.android.com/guide/topics/intents/intents-filters.html                                                            Page 3 of 7
Intents and Intent Filters | Android Developers                                                                       29.04.09 0:40




Android delivers an explicit intent to an instance of the designated target class. Nothing in the Intent object other than
the component name matters for determining which component should get the intent.

A different strategy is needed for implicit intents. In the absence of a designated target, the Android system must find
the best component (or components) to handle the intent — a single activity or service to perform the requested action
or the set of broadcast receivers to respond to the broadcast announcement. It does so by comparing the contents of
the Intent object to intent filters, structures associated with components that can potentially receive intents. Filters
advertise the capabilities of a component and delimit the intents it can handle. They open the component to the
possibility of receiving implicit intents of the advertised type. If a component does not have any intent filters, it can
receive only explicit intents. A component with filters can receive both explicit and implicit intents.

Only three aspects of an Intent object are consulted when the object is tested against an intent filter:

      action
      data (both URI and data type)
      category

The extras and flags play no part in resolving which component receives an intent.


Intent filters
To inform the system which implicit intents they can handle, activities, services, and broadcast receivers can have one
or more intent filters. Each filter describes a capability of the component, a set of intents that the component is willing
to receive. It, in effect, filters in intents of a desired type, while filtering out unwanted intents — but only unwanted
implicit intents (those that don't name a target class). An explicit intent is always delivered to its target, no matter what
it contains; the filter is not consulted. But an implicit intent is delivered to a component only if it can pass through one
of the component's filters.

A component has separate filters for each job it can do, each face it can present to the user. For example, the
principal activity of the sample NotePad application has three filters — one for starting up with a blank slate, another
for starting with an assigned directory of notes that the user can view, edit, or select from, and a third for finding a
particular note without an initial specification of its directory.

An intent filter is an instance of the IntentFilter class. However, since the Android system must know about the
capabilities of a component before it can launch that component, intent filters are generally not set up in Java code,
but in the application's manifest file (AndroidManifest.xml) as <intent-filter> elements. (The one exception would
be filters for broadcast receivers that are registered dynamically by calling Context.registerReceiver(); they
are directly created as IntentFilter objects.)

A filter has fields that parallel the action, data, and category fields of
an Intent object. An implicit intent is tested against the filter in all
three areas. To be delivered to the component that owns the filter,          Filters and security
it must pass all three tests. If it fails even one of them, the Android      An intent filter cannot be relied on for security.
system won't deliver it to the component — at least not on the               While it opens a component to receiving only
basis of that filter. However, since a component can have multiple           certain kinds of implicit intents, it does nothing
intent filters, an intent that does not pass through one of a                to prevent explicit intents from targeting the
component's filters might make it through on another.                        component. Even though a filter restricts the
                                                                             intents a component will be asked to handle to
Each of the three tests is described in detail below:                        certain actions and data sources, someone
                                                                             could always put together an explicit intent with
Action test                                                                  a different action and data source, and name
    An <intent-filter> element in the manifest file lists                    the component as the target.
    actions as <action> subelements. For example:

           <intent-filter . . . >
               <action android:name="com.example.project.SHOW_CURRENT" />
               <action android:name="com.example.project.SHOW_RECENT" />
               <action android:name="com.example.project.SHOW_PENDING" />

http://developer.android.com/guide/topics/intents/intents-filters.html                                                  Page 4 of 7
Intents and Intent Filters | Android Developers                                                                            29.04.09 0:40

               <action android:name="com.example.project.SHOW_PENDING" />
               . . .
           </intent-filter>

      As the example shows, while an Intent object names just a single action, a filter may list more than one. The list
      cannot be empty; a filter must contain at least one <action> element, or it will block all intents.

      To pass this test, the action specified in the Intent object must match one of the actions listed in the filter. If the
      object or the filter does not specify an action, the results are as follows:
            If the filter fails to list any actions, there is nothing for an intent to match, so all intents fail the test. No intents
            can get through the filter.

            On the other hand, an Intent object that doesn't specify an action automatically passes the test — as long as
            the filter contains at least one action.

Category test
    An <intent-filter> element also lists categories as subelements. For example:

           <intent-filter . . . >
               <category android:name="android.intent.category.DEFAULT" />
               <category android:name="android.intent.category.BROWSABLE" />
               . . .
           </intent-filter>

      Note that the constants described earlier for actions and categories are not used in the manifest file. The full
      string values are used instead. For instance, the "android.intent.category.BROWSABLE" string in the
      example above corresponds to the CATEGORY_BROWSABLE constant mentioned earlier in this document.
      Similarly, the string "android.intent.action.EDIT" corresponds to the ACTION_EDIT constant.

      For an intent to pass the category test, every category in the Intent object must match a category in the filter. The
      filter can list additional categories, but it cannot omit any that are in the intent.

      In principle, therefore, an Intent object with no categories should always pass this test, regardless of what's in the
      filter. That's mostly true. However, with one exception, Android treats all implicit intents passed to startActivity() as
      if they contained at least one category: "android.intent.category.DEFAULT" (the CATEGORY_DEFAULT
      constant). Therefore, activities that are willing to receive implicit intents must include
      "android.intent.category.DEFAULT" in their intent filters. (Filters with "android.intent.action.MAIN"
      and "android.intent.category.LAUNCHER" settings are the exception. They mark activities that begin new
      tasks and that are represented on the launcher screen. They can include
      "android.intent.category.DEFAULT" in the list of categories, but don't need to.) See Using intent matching,
      later, for more on these filters.)

Data test
    Like the action and categories, the data specification for an intent filter is contained in a subelement. And, as in
    those cases, the subelement can appear multiple times, or not at all. For example:

           <intent-filter . . . >
               <data android:type="video/mpeg" android:scheme="http" . . . />
               <data android:type="audio/mpeg" android:scheme="http" . . . />
               . . .
           </intent-filter>

      Each <data> element can specify a URI and a data type (MIME media type). There are separate attributes —
      scheme, host, port, and path — for each part of the URI:

            scheme://host:port/path

      For example, in the following URI,


http://developer.android.com/guide/topics/intents/intents-filters.html                                                        Page 5 of 7
Intents and Intent Filters | Android Developers                                                                     29.04.09 0:40


            content://com.example.project:200/folder/subfolder/etc

      the scheme is "content", the host is "com.example.project", the port is "200", and the path is
      "folder/subfolder/etc". The host and port together constitute the URI authority; if a host is not specified,
      the port is ignored.

      Each of these attributes is optional, but they are not independent of each other: For an authority to be meaningful,
      a scheme must also be specified. For a path to be meaningful, both a scheme and an authority must be specified.

      When the URI in an Intent object is compared to a URI specification in a filter, it's compared only to the parts of
      the URI actually mentioned in the filter. For example, if a filter specifies only a scheme, all URIs with that scheme
      match the filter. If a filter specifies a scheme and an authority but no path, all URIs with the same scheme and
      authority match, regardless of their paths. If a filter specifies a scheme, an authority, and a path, only URIs with
      the same scheme, authority, and path match. However, a path specification in the filter can contain wildcards to
      require only a partial match of the path.

      The type attribute of a <data> element specifies the MIME type of the data. It's more common in filters than a
      URI. Both the Intent object and the filter can use a "*" wildcard for the subtype field — for example, "text/*" or
      "audio/*" — indicating any subtype matches.

      The data test compares both the URI and the data type in the Intent object to a URI and data type specified in
      the filter. The rules are as follows:
       a. An Intent object that contains neither a URI nor a data type passes the test only if the filter likewise does not
          specify any URIs or data types.

       b. An Intent object that contains a URI but no data type (and a type cannot be inferred from the URI) passes
          the test only if its URI matches a URI in the filter and the filter likewise does not specify a type. This will be
          the case only for URIs like mailto: and tel: that do not refer to actual data.

       c. An Intent object that contains a data type but not a URI passes the test only if the filter lists the same data
          type and similarly does not specify a URI.

       d. An Intent object that contains both a URI and a data type (or a data type can be inferred from the URI)
          passes the data type part of the test only if its type matches a type listed in the filter. It passes the URI part
          of the test either if its URI matches a URI in the filter or if it has a content: or file: URI and the filter
          does not specify a URI. In other words, a component is presumed to support content: and file: data if its
          filter lists only a data type.

If an intent can pass through the filters of more than one activity or service, the user may be asked which component
to activate. An exception is raised if no target can be found.


Common cases
The last rule shown above for the data test, rule (d), reflects the expectation that components are able to get local
data from a file or content provider. Therefore, their filters can list just a data type and do not need to explicitly name
the content: and file: schemes. This is a typical case. A <data> element like the following, for example, tells
Android that the component can get image data from a content provider and display it:

     <data android:type="image/*" />

Since most available data is dispensed by content providers, filters that specify a data type but not a URI are perhaps
the most common.

Another common configuration is filters with a scheme and a data type. For example, a <data> element like the
following tells Android that the component can get video data from the network and display it:



http://developer.android.com/guide/topics/intents/intents-filters.html                                                Page 6 of 7
Intents and Intent Filters | Android Developers                                                                       29.04.09 0:40


     <data android:scheme="http" android:type="video/*" />

Consider, for example, what the browser application does when the user follows a link on a web page. It first tries to
display the data (as it could if the link was to an HTML page). If it can't display the data, it puts together an implicit
intent with the scheme and data type and tries to start an activity that can do the job. If there are no takers, it asks the
download manager to download the data. That puts it under the control of a content provider, so a potentially larger
pool of activities (those with filters that just name a data type) can respond.

Most applications also have a way to start fresh, without a reference to any particular data. Activities that can initiate
applications have filters with "android.intent.action.MAIN" specified as the action. If they are to be
represented in the application launcher, they also specify the "android.intent.category.LAUNCHER" category:

     <intent-filter . . . >
         <action android:name="code android.intent.action.MAIN" />
         <category android:name="code android.intent.category.LAUNCHER" />
     </intent-filter>


Using intent matching
Intents are matched against intent filters not only to discover a target component to activate, but also to discover
something about the set of components on the device. For example, the Android system populates the application
launcher, the top-level screen that shows the applications that are available for the user to launch, by finding all the
activities with intent filters that specify the "android.intent.action.MAIN" action and
"android.intent.category.LAUNCHER" category (as illustrated in the previous section). It then displays the
icons and labels of those activities in the launcher. Similarly, it discovers the home screen by looking for the activity
with "android.intent.category.HOME" in its filter.

Your application can use intent matching is a similar way. The PackageManager has a set of query...() methods
that return all components that can accept a particular intent, and a similar series of resolve...() methods that
determine the best component to respond to an intent. For example, queryIntentActivities() returns a list of all activities
that can perform the intent passed as an argument, and queryIntentServices() returns a similar list of services. Neither
method activates the components; they just list the ones that can respond. There's a similar method,
queryBroadcastReceivers(), for broadcast receivers.

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/intents/intents-filters.html                                                  Page 7 of 7
Data Storage | Android Developers                                                                              29.04.09 0:41




Data Storage

A typical desktop operating system provides a common file system that any application can use to store files that can
be read by other applications (perhaps with some access control settings). Android uses a different system: On
Android, all application data (including files) are private to that application.

However, Android also provides a standard way for an application to expose its private data to other applications —
through content providers. A content provider is an optional component of an application that exposes read/write
access to the application's data, subject to whatever restrictions it might impose. Content providers implement a
standard syntax for requesting and modifying data, and a standard mechanism for reading the returned data. Android
supplies a number of content providers for standard data types, such as image, audio, and video files and personal
contact information. For more information on using content providers, see a separate document, Content Providers.

Whether or not you want to export your application's data to others, you need a way to store it. Android provides the
following four mechanisms for storing and retrieving data: Preferences, Files, Databases, and Network.



Preferences
Preferences is a lightweight mechanism to store and retrieve key-value pairs of primitive data types. It is typically used
to store application preferences, such as a default greeting or a text font to be loaded whenever the application is
started. Call Context.getSharedPreferences() to read and write values. Assign a name to your set of
preferences if you want to share them with other components in the same application, or use
Activity.getPreferences() with no name to keep them private to the calling activity. You cannot share
preferences across applications (except by using a content provider).

Here is an example of setting user preferences for silent keypress mode for a calculator:


     import android.app.Activity;
     import android.content.SharedPreferences;
     public class Calc extends Activity {
     public static final String PREFS_NAME = "MyPrefsFile";
         . . .
            @Override
            protected void onCreate(Bundle state){
               super.onCreate(state);
            . . .

                 // Restore preferences
                 SharedPreferences settings = getSharedPreferences(PREFS_NAME, 0);
                 boolean silent = settings.getBoolean("silentMode", false);
                 setSilent(silent);
            }

            @Override
            protected void onStop(){
               super.onStop();

                // Save user preferences. We need an Editor object to
                // make changes. All objects are from android.context.Context
                SharedPreferences settings = getSharedPreferences(PREFS_NAME, 0);

http://developer.android.com/guide/topics/data/data-storage.html                                                 Page 1 of 3
Data Storage | Android Developers                                                                                29.04.09 0:41

                SharedPreferences settings = getSharedPreferences(PREFS_NAME, 0);
                SharedPreferences.Editor editor = settings.edit();
                editor.putBoolean("silentMode", mSilentMode);

                // Don't forget to commit your edits!!!
                editor.commit();
            }
     }




Files
You can store files directly on the mobile device or on a removable storage medium. By default, other applications
cannot access these files.

To read data from a file, call Context.openFileInput() and pass it the local name and path of the file. It returns a
standard Java FileInputStream object. To write to a file, call Context.openFileOutput() with the name and path. It
returns a FileOutputStream object. Calling these methods with name and path strings from another application will not
work; you can only access local files.

If you have a static file to package with your application at compile time, you can save the file in your project in
res/raw/myDataFile, and then open it with Resources.openRawResource (R.raw.myDataFile). It returns an
InputStream object that you can use to read from the file.



Databases
The Android API contains support for creating and using SQLite databases. Each database is private to the application
that creates it.

The SQLiteDatabase object represents a database and has methods for interacting with it — making queries and
managing the data. To create the database, call SQLiteDatabase.create() and also subclass SQLiteOpenHelper.

As part of its support for the SQLite database system, Android exposes database management functions that let you
store complex collections of data wrapped into useful objects. For example, Android defines a data type for contact
information; it consists of many fields including a first and last name (strings), an address and phone numbers (also
strings), a photo (bitmap image), and much other information describing a person.

Android ships with the sqlite3 database tool, which enables you to browse table contents, run SQL commands, and
perform other useful functions on SQLite databases. See Examine databases (sqlite3) to learn how to run this
program.

All databases, SQLite and others, are stored on the device in /data/data/package_name/databases.

Discussion of how many tables to create, what fields they contain, and how they are linked, is beyond the scope of this
note, but Android does not impose any limitations beyond the standard SQLite concepts. We do recommend including
an autoincrement value key field that can be used as a unique ID to quickly find a record. This is not required for
private data, but if you implement a content provider, you must include such a unique ID field. See the Content
Providers document for more information on this field and the NotePadProvider class in the NotePad sample code for
an example of creating and populating a new database. Any databases you create will be accessible by name to any
other class in the application, but not outside the application.



Network
You can also use the network to store and retrieve data (when it's available). To do network operations, use the
classes in the following packages:

http://developer.android.com/guide/topics/data/data-storage.html                                                   Page 2 of 3
Data Storage | Android Developers                                                                                     29.04.09 0:41



  java.net.*
  android.net.*

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/data/data-storage.html                                                        Page 3 of 3
Content Providers | Android Developers                                                                           29.04.09 0:41




Content Providers

Content providers store and retrieve data and make it accessible to all applications. They're the only way to share data
across applications; there's no common storage area that all Android packages can access.

Android ships with a number of content providers for common data types (audio, video, images, personal contact
information, and so on). You can see some of them listed in the android.provider package. You can query these
providers for the data they contain (although, for some, you must acquire the proper permission to read the data).

If you want to make your own data public, you have two options: You can create your own content provider (a
ContentProvider subclass) or you can add the data to an existing provider — if there's one that controls the same type
of data and you have permission to write to it.

This document is an introduction to using content providers. After a brief discussion of the fundamentals, it explores
how to query a content provider, how to modify data controlled by a provider, and how to create a content provider of
your own.



Content Provider Basics
How a content provider actually stores its data under the covers is up to its designer. But all content providers
implement a common interface for querying the provider and returning results — as well as for adding, altering, and
deleting data.

It's an interface that clients use indirectly, most generally through ContentResolver objects. You get a ContentResolver
by calling getContentResolver() from within the implementation of an Activity or other application component:


     ContentResolver cr = getContentResolver();

You can then use the ContentResolver's methods to interact with whatever content providers you're interested in.

When a query is initiated, the Android system identifies the content provider that's the target of the query and makes
sure that it is up and running. The system instantiates all ContentProvider objects; you never need to do it on your
own. In fact, you never deal directly with ContentProvider objects at all. Typically, there's just a single instance of each
type of ContentProvider. But it can communicate with multiple ContentResolver objects in different applications and
processes. The interaction between processes is handled by the ContentResolver and ContentProvider classes.


The data model
Content providers expose their data as a simple table on a database model, where each row is a record and each
column is data of a particular type and meaning. For example, information about people and their phone numbers
might be exposed as follows:

  _ID        NUMBER                      NUMBER_KEY             LABEL             NAME           TYPE

  13         (425) 555 6677              425 555 6677           Kirkland office   Bully Pulpit   TYPE_WORK

  44         (212) 555-1234              212 555 1234           NY apartment      Alan Vain      TYPE_HOME



http://developer.android.com/guide/topics/providers/content-providers.html                                         Page 1 of 10
Content Providers | Android Developers                                                                            29.04.09 0:41


  45         (212) 555-6657              212 555 6657           Downtown office   Alan Vain   TYPE_MOBILE

  53         201.555.4433                201 555 4433           Love Nest         Rex Cars    TYPE_HOME

Every record includes a numeric _ID field that uniquely identifies the record within the table. IDs can be used to match
records in related tables — for example, to find a person's phone number in one table and pictures of that person in
another.

A query returns a Cursor object that can move from record to record and column to column to read the contents of
each field. It has specialized methods for reading each type of data. So, to read a field, you must know what type of
data the field contains. (There's more on query results and Cursor objects later.)


URIs
Each content provider exposes a public URI (wrapped as a Uri object) that uniquely identifies its data set. A content
provider that controls multiple data sets (multiple tables) exposes a separate URI for each one. All URIs for providers
begin with the string "content://". The content: scheme identifies the data as being controlled by a content
provider.

If you're defining a content provider, it's a good idea to also define a constant for its URI, to simplify client code and
make future updates cleaner. Android defines CONTENT_URI constants for all the providers that come with the
platform. For example, the URI for the table that matches phone numbers to people and the URI for the table that
holds pictures of people (both controlled by the Contacts content provider) are:

     android.provider.Contacts.Phones.CONTENT_URI
     android.provider.Contacts.Photos.CONTENT_URI

Similarly, the URIs for the table of recent phone calls and the table of calendar entries are:

     android.provider.CallLog.Calls.CONTENT_URI
     android.provider.Calendar.CONTENT_URI

The URI constant is used in all interactions with the content provider. Every ContentResolver method takes the URI as
its first argument. It's what identifies which provider the ContentResolver should talk to and which table of the provider
is being targeted.



Querying a Content Provider
You need three pieces of information to query a content provider:

     The URI that identifies the provider
     The names of the data fields you want to receive
     The data types for those fields

If you're querying a particular record, you also need the ID for that record.


Making the query
To query a content provider, you can use either the ContentResolver.query() method or the
Activity.managedQuery() method. Both methods take the same set of arguments, and both return a Cursor
object. However, managedQuery() causes the activity to manage the life cycle of the Cursor. A managed Cursor
handles all of the niceties, such as unloading itself when the activity pauses, and requerying itself when the activity
restarts. You can ask an Activity to begin managing an unmanaged Cursor object for you by calling
Activity.startManagingCursor().



http://developer.android.com/guide/topics/providers/content-providers.html                                          Page 2 of 10
Content Providers | Android Developers                                                                       29.04.09 0:41


The first argument to either query() or managedQuery() is the provider URI — the CONTENT_URI constant that
identifies a particular ContentProvider and data set (see URIs earlier).

To restrict a query to just one record, you can append the _ID value for that record to the URI — that is, place a
string matching the ID as the last segment of the path part of the URI. For example, if the ID is 23, the URI would be:

     content://. . . ./23

There are some helper methods, particularly ContentUris.withAppendedId() and Uri.withAppendedPath(),
that make it easy to append an ID to a URI. Both are static methods that return a Uri object with the ID added. So, for
example, if you were looking for record 23 in the database of people contacts, you might construct a query as follows:

     import       android.provider.Contacts.People;
     import       android.content.ContentUris;
     import       android.net.Uri;
     import       android.database.Cursor;

     // Use the ContentUris method to produce the base URI for the contact with _ID ==
     23.
     Uri myPerson = ContentUris.withAppendedId(People.CONTENT_URI, 23);

     // Alternatively, use the Uri method to produce the base URI.
     // It takes a string rather than an integer.
     Uri myPerson = Uri.withAppendedPath(People.CONTENT_URI, "23");
     // Then query for this specific record:
     Cursor cur = managedQuery(myPerson, null, null, null, null);

The other arguments to the query() and managedQuery() methods delimit the query in more detail. They are:

     The names of the data columns that should be returned. A null value returns all columns. Otherwise, only
     columns that are listed by name are returned. All the content providers that come with the platform define
     constants for their columns. For example, the android.provider.Contacts.Phones class defines constants for the
     names of the columns in the phone table illustrated earlier — _ID, NUMBER, NUMBER_KEY, NAME, and so on.

     A filter detailing which rows to return, formatted as an SQL WHERE clause (excluding the WHERE itself). A null
     value returns all rows (unless the URI limits the query to a single record).

     Selection arguments.

     A sorting order for the rows that are returned, formatted as an SQL ORDER BY clause (excluding the ORDER BY
     itself). A null value returns the records in the default order for the table, which may be unordered.

Let's look at an example query to retrieve a list of contact names and their primary phone numbers:


     import android.provider.Contacts.People;
     import android.database.Cursor;

     // Form an array specifying which columns to return.
     String[] projection = new String[] {
                                  People._ID,
                                  People._COUNT,
                                  People.NAME,
                                  People.NUMBER
                               };

     // Get the base URI for the People table in the Contacts content provider.
     Uri contacts = People.CONTENT_URI;
     // Make the query.
     Cursor managedCursor = managedQuery(contacts,
                              projection, // Which columns to return
                              null,       // Which rows to return (all rows)

http://developer.android.com/guide/topics/providers/content-providers.html                                     Page 3 of 10
Content Providers | Android Developers                                                                          29.04.09 0:41

                                                 null,       // Which rows to return (all rows)
                                                 null,       // Selection arguments (none)
                                                 // Put the results in ascending order by name
                                                 People.NAME + " ASC");

This query retrieves data from the People table of the Contacts content provider. It gets the name, primary phone
number, and unique record ID for each contact. It also reports the number of records that are returned as the _COUNT
field of each record.

The constants for the names of the columns are defined in various interfaces — _ID and _COUNT in BaseColumns,
NAME in PeopleColumns, and NUMBER in PhoneColumns. The Contacts.People class implements each of these
interfaces, which is why the code example above could refer to them using just the class name.


What a query returns
A query returns a set of zero or more database records. The names of the columns, their default order, and their data
types are specific to each content provider. But every provider has an _ID column, which holds a unique numeric ID
for each record. Every provider can also report the number of records returned as the _COUNT column; its value is the
same for all rows.

Here is an example result set for the query in the previous section:

  _ID        _COUNT            NAME               NUMBER

  44         3                 Alan Vain          212 555 1234

  13         3                 Bully Pulpit       425 555 6677

  53         3                 Rex Cars           201 555 4433

The retrieved data is exposed by a Cursor object that can be used to iterate backward or forward through the result
set. You can use this object only to read the data. To add, modify, or delete data, you must use a ContentResolver
object.


Reading retrieved data
The Cursor object returned by a query provides access to a recordset of results. If you have queried for a specific
record by ID, this set will contain only one value. Otherwise, it can contain multiple values. (If there are no matches, it
can also be empty.) You can read data from specific fields in the record, but you must know the data type of the field,
because the Cursor object has a separate method for reading each type of data — such as getString(),
getInt(), and getFloat(). (However, for most types, if you call the method for reading strings, the Cursor object
will give you the String representation of the data.) The Cursor lets you request the column name from the index of the
column, or the index number from the column name.

The following snippet demonstrates reading names and phone numbers from the query illustrated earlier:


     import android.provider.Contacts.People;
     private void getColumnData(Cursor cur){
         if (cur.moveToFirst()) {

                   String name;
                   String phoneNumber;
                   int nameColumn = cur.getColumnIndex(People.NAME);
                   int phoneColumn = cur.getColumnIndex(People.NUMBER);
                   String imagePath;

                   do {
                           // Get the field values
                           name = cur.getString(nameColumn);
                           phoneNumber = cur.getString(phoneColumn);

http://developer.android.com/guide/topics/providers/content-providers.html                                       Page 4 of 10
Content Providers | Android Developers                                                                            29.04.09 0:41

                           phoneNumber = cur.getString(phoneColumn);
                           // Do something with the values.
                           ...

                   } while (cur.moveToNext());

            }
     }

If a query can return binary data, such as an image or sound, the data may be directly entered in the table or the
table entry for that data may be a string specifying a content: URI that you can use to get the data. In general,
smaller amounts of data (say, from 20 to 50K or less) are most often directly entered in the table and can be read by
calling Cursor.getBlob(). It returns a byte array.

If the table entry is a content: URI, you should never try to open and read the file directly (for one thing,
permissions problems can make this fail). Instead, you should call ContentResolver.openInputStream() to get
an InputStream object that you can use to read the data.



Modifying Data
Data kept by a content provider can be modified by:

     Adding new records
     Adding new values to existing records
     Batch updating existing records
     Deleting records

All data modification is accomplished using ContentResolver methods. Some content providers require a more
restrictive permission for writing data than they do for reading it. If you don't have permission to write to a content
provider, the ContentResolver methods will fail.


Adding records
To add a new record to a content provider, first set up a map of key-value pairs in a ContentValues object, where
each key matches the name of a column in the content provider and the value is the desired value for the new record
in that column. Then call ContentResolver.insert() and pass it the URI of the provider and the ContentValues
map. This method returns the full URI of the new record — that is, the provider's URI with the appended ID for the
new record. You can then use this URI to query and get a Cursor over the new record, and to further modify the
record. Here's an example:


     import android.provider.Contacts.People;
     import android.content.ContentResolver;
     import android.content.ContentValues;

     ContentValues values = new ContentValues();

     // Add Abraham Lincoln to contacts and make him a favorite.
     values.put(People.NAME, "Abraham Lincoln");
     // 1 = the new contact is added to favorites
     // 0 = the new contact is not added to favorites
     values.put(People.STARRED, 1);

     Uri uri = getContentResolver().insert(People.CONTENT_URI, values);


Adding new values

http://developer.android.com/guide/topics/providers/content-providers.html                                         Page 5 of 10
Content Providers | Android Developers                                                                      29.04.09 0:41


Once a record exists, you can add new information to it or modify existing information. For example, the next step in
the example above would be to add contact information — like a phone number or an IM or e-mail address — to the
new entry.

The best way to add to a record in the Contacts database is to append the name of the table where the new data
goes to the URI for the record, then use the amended URI to add the new data values. Each Contacts table exposes
a name for this purpose as a CONTENT_DIRECTORY constant. The following code continues the previous example by
adding a phone number and e-mail address for the record just created:


     Uri phoneUri = null;
     Uri emailUri = null;

     // Add a phone number for Abraham Lincoln. Begin with the URI for
     // the new record just returned by insert(); it ends with the _ID
     // of the new record, so we don't have to add the ID ourselves.
     // Then append the designation for the phone table to this URI,
     // and use the resulting URI to insert the phone number.
     phoneUri = Uri.withAppendedPath(uri, People.Phones.CONTENT_DIRECTORY);

     values.clear();
     values.put(People.Phones.TYPE, People.Phones.TYPE_MOBILE);
     values.put(People.Phones.NUMBER, "1233214567");
     getContentResolver().insert(phoneUri, values);

     // Now add an email address in the same way.
     emailUri = Uri.withAppendedPath(uri, People.ContactMethods.CONTENT_DIRECTORY);
     values.clear();
     // ContactMethods.KIND is used to distinguish different kinds of
     // contact methods, such as email, IM, etc.
     values.put(People.ContactMethods.KIND, Contacts.KIND_EMAIL);
     values.put(People.ContactMethods.DATA, "test@example.com");
     values.put(People.ContactMethods.TYPE, People.ContactMethods.TYPE_HOME);
     getContentResolver().insert(emailUri, values);

You can place small amounts of binary data into a table by calling the version of ContentValues.put() that takes
a byte array. That would work for a small icon-like image or a short audio clip, for example. However, if you have a
large amount of binary data to add, such as a photograph or a complete song, put a content: URI for the data in
the table and call ContentResolver.openOutputStream() with the file's URI. (That causes the content provider
to store the data in a file and record the file path in a hidden field of the record.)

In this regard, the MediaStore content provider, the main provider that dispenses image, audio, and video data,
employs a special convention: The same URI that is used with query() or managedQuery() to get meta-
information about the binary data (such as, the caption of a photograph or the date it was taken) is used with
openInputStream() to get the data itself. Similarly, the same URI that is used with insert() to put meta-
information into a MediaStore record is used with openOutputStream() to place the binary data there. The
following code snippet illustrates this convention:


     import android.provider.MediaStore.Images.Media;
     import android.content.ContentValues;
     import java.io.OutputStream;

     // Save the name and description of an image in a ContentValues map.
     ContentValues values = new ContentValues(3);
     values.put(Media.DISPLAY_NAME, "road_trip_1");
     values.put(Media.DESCRIPTION, "Day 1, trip to Los Angeles");
     values.put(Media.MIME_TYPE, "image/jpeg");

     // Add a new record without the bitmap, but with the values just set.
     // insert() returns the URI of the new record.
     Uri uri = getContentResolver().insert(Media.EXTERNAL_CONTENT_URI, values);

     // Now get a handle to the file for that record, and save the data into it.


http://developer.android.com/guide/topics/providers/content-providers.html                                    Page 6 of 10
Content Providers | Android Developers                                                                       29.04.09 0:41

     // Now get a handle to the file for that record, and save the data into it.
     // Here, sourceBitmap is a Bitmap object representing the file to save to the
     database.
     try {
         OutputStream outStream = getContentResolver().openOutputStream(uri);
         sourceBitmap.compress(Bitmap.CompressFormat.JPEG, 50, outStream);
         outStream.close();
     } catch (Exception e) {
         Log.e(TAG, "exception while writing image", e);
     }


Batch updating records
To batch update a group of records (for example, to change "NY" to "New York" in all fields), call the
ContentResolver.update() method with the columns and values to change.


Deleting a record
To delete a single record, call {ContentResolver.delete() with the URI of a specific row.

To delete multiple rows, call ContentResolver.delete() with the URI of the type of record to delete (for example,
android.provider.Contacts.People.CONTENT_URI) and an SQL WHERE clause defining which rows to delete.
(Caution: Be sure to include a valid WHERE clause if you're deleting a general type, or you risk deleting more records
than you intended!).



Creating a Content Provider
To create a content provider, you must:

     Set up a system for storing the data. Most content providers store their data using Android's file storage methods
     or SQLite databases, but you can store your data any way you want. Android provides the SQLiteOpenHelper
     class to help you create a database and SQLiteDatabase to manage it.

     Extend the ContentProvider class to provide access to the data.

     Declare the content provider in the manifest file for your application (AndroidManifest.xml).

The following sections have notes on the last two of these tasks.


Extending the ContentProvider class
You define a ContentProvider subclass to expose your data to others using the conventions expected by
ContentResolver and Cursor objects. Principally, this means implementing six abstract methods declared in the
ContentProvider class:

     query()
     insert()
     update()
     delete()
     getType()
     onCreate()

The query() method must return a Cursor object that can iterate over the requested data. Cursor itself is an
interface, but Android provides some ready-made Cursor objects that you can use. For example, SQLiteCursor can
iterate over data stored in an SQLite database. You get the Cursor object by calling any of the SQLiteDatabase
class's query() methods. There are other Cursor implementations — such as MatrixCursor — for data not stored in a
database.


http://developer.android.com/guide/topics/providers/content-providers.html                                     Page 7 of 10
Content Providers | Android Developers                                                                         29.04.09 0:41


Because these ContentProvider methods can be called from various ContentResolver objects in different processes
and threads, they must be implemented in a thread-safe manner.

As a courtesy, you might also want to call ContentResolver.notifyChange() to notify listeners when there are
modifications to the data.

Beyond defining the subclass itself, there are other steps you should take to simplify the work of clients and make the
class more accessible:

     Define a public static final Uri named CONTENT_URI. This is the string that represents the full content:
     URI that your content provider handles. You must define a unique string for this value. The best solution is to use
     the fully-qualified class name of the content provider (made lowercase). So, for example, the URI for a
     TransportationProvider class could be defined as follows:

           public static final Uri CONTENT_URI =
           Uri.parse("content://com.example.codelab.transporationprovider");

     If the provider has subtables, also define CONTENT_URI constants for each of the subtables. These URIs should
     all have the same authority (since that identifies the content provider), and be distinguished only by their paths.
     For example:
           content://com.example.codelab.transporationprovider/train
           content://com.example.codelab.transporationprovider/air/domestic
           content://com.example.codelab.transporationprovider/air/international
     For an overview of content: URIs, see the Content URI Summary at the end of this document.

     Define the column names that the content provider will return to clients. If you are using an underlying database,
     these column names are typically identical to the SQL database column names they represent. Also define
     public static String constants that clients can use to specify the columns in queries and other instructions.
     Be sure to include an integer column named "_id" (with the constant _ID) for the IDs of the records. You should
     have this field whether or not you have another field (such as a URL) that is also unique among all records. If
     you're using the SQLite database, the _ID field should be the following type:
           INTEGER PRIMARY KEY AUTOINCREMENT
     The AUTOINCREMENT descriptor is optional. But without it, SQLite increments an ID counter field to the next
     number above the largest existing number in the column. If you delete the last row, the next row added will have
     the same ID as the deleted row. AUTOINCREMENT avoids this by having SQLite increment to the next largest
     value whether deleted or not.

     Carefully document the data type of each column. Clients need this information to read the data.

     If you are handling a new data type, you must define a new MIME type to return in your implementation of
     ContentProvider.getType(). The type depends in part on whether or not the content: URI submitted to
     getType() limits the request to a specific record. There's one form of the MIME type for a single record and
     another for multiple records. Use the Uri methods to help determine what is being requested. Here is the general
     format for each type:

           For a single record:          vnd.android.cursor.item/vnd.yourcompanyname.contenttype
           For example, a request for train record 122, like this URI,
                 content://com.example.transportationprovider/trains/122
           might return this MIME type:
                 vnd.android.cursor.item/vnd.example.rail

           For multiple records:         vnd.android.cursor.dir/vnd.yourcompanyname.contenttype
           For example, a request for all train records, like the following URI,
                 content://com.example.transportationprovider/trains


http://developer.android.com/guide/topics/providers/content-providers.html                                      Page 8 of 10
Content Providers | Android Developers                                                                           29.04.09 0:41


           might return this MIME type:
                 vnd.android.cursor.dir/vnd.example.rail

     If you are exposing byte data that's too big to put in the table itself — such as a large bitmap file — the field that
     exposes the data to clients should actually contain a content: URI string. This is the field that gives clients
     access to the data file. The record should also have another field, named "_data" that lists the exact file path on
     the device for that file. This field is not intended to be read by the client, but by the ContentResolver. The client
     will call ContentResolver.openInputStream() on the user-facing field holding the URI for the item. The
     ContentResolver will request the "_data" field for that record, and because it has higher permissions than a
     client, it should be able to access that file directly and return a read wrapper for the file to the client.

For an example of a private content provider implementation, see the NodePadProvider class in the Notepad sample
application that ships with the SDK.


Declaring the content provider
To let the Android system know about the content provider you've developed, declare it with a <provider> element
in the application's AndroidManifest.xml file. Content providers that are not declared in the manifest are not visible to
the Android system

The name attribute is the fully qualified name of the ContentProvider subclass. The authorities attribute is the
authority part of the content: URI that identifies the provider. For example if the ContentProvider subclass is
AutoInfoProvider, the <provider> element might look like this:


     <provider name="com.example.autos.AutoInfoProvider"
               authorities="com.example.autos.autoinfoprovider"
               . . . />
     </provider>

Note that the authorities attribute omits the path part of a content: URI. For example, if AutoInfoProvider
controlled subtables for different types of autos or different manufacturers,

     content://com.example.autos.autoinfoprovider/honda
     content://com.example.autos.autoinfoprovider/gm/compact
     content://com.example.autos.autoinfoprovider/gm/suv

those paths would not be declared in the manifest. The authority is what identifies the provider, not the path; your
provider can interpret the path part of the URI in any way you choose.

Other <provider> attributes can set permissions to read and write data, provide for an icon and text that can be
displayed to users, enable and disable the provider, and so on. Set the multiprocess attribute to "true" if data
does not need to be synchronized between multiple running versions of the content provider. This permits an instance
of the provider to be created in each client process, eliminating the need to perform IPC.



Content URI Summary
Here is a recap of the important parts of a content URI:




http://developer.android.com/guide/topics/providers/content-providers.html                                        Page 9 of 10
Content Providers | Android Developers                                                                                29.04.09 0:41


 A. Standard prefix indicating that the data is controlled by a content provider. It's never modified.

 B. The authority part of the URI; it identifies the content provider. For third-party applications, this should be a fully-
    qualified class name (reduced to lowercase) to ensure uniqueness. The authority is declared in the <provider>
    element's authorities attribute:

           <provider name=".TransportationProvider"
                     authorities="com.example.transportationprovider"
                     . . . >

C. The path that the content provider uses to determine what kind of data is being requested. This can be zero or
   more segments long. If the content provider exposes only one type of data (only trains, for example), it can be
   absent. If the provider exposes several types, including subtypes, it can be several segments long — for example,
   "land/bus", "land/train", "sea/ship", and "sea/submarine" to give four possibilities.

D. The ID of the specific record being requested, if any. This is the _ID value of the requested record. If the request
   is not limited to a single record, this segment and the trailing slash are omitted:
           content://com.example.transportationprovider/trains

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/providers/content-providers.html                                            Page 10 of 10
Security and Permissions | Android Developers                                                                       29.04.09 0:41




Security and Permissions

Android is a multi-process system, in which each application (and parts of the system) runs in its own process. Most
security between applications and the system is enforced at the process level through standard Linux facilities, such as
user and group IDs that are assigned to applications. Additional finer-grained security features are provided through a
"permission" mechanism that enforces restrictions on the specific operations that a particular process can perform, and
per-URI permissions for granting ad-hoc access to specific pieces of data.



Security Architecture
A central design point of the Android security architecture is that no application, by default, has permission to perform
any operations that would adversely impact other applications, the operating system, or the user. This includes reading
or writing the user's private data (such as contacts or e-mails), reading or writing another application's files, performing
network access, keeping the device awake, etc.

An application's process is a secure sandbox. It can't disrupt other applications, except by explicitly declaring the
permissions it needs for additional capabilities not provided by the basic sandbox. These permissions it requests can
be handled by the operating in various ways, typically by automatically allowing or disallowing based on certificates or
by prompting the user. The permissions required by an application are declared statically in that application, so they
can be known up-front at install time and will not change after that.



Application Signing
All Android applications (.apk files) must be signed with a certificate whose private key is held by their developer. This
certificate identifies the author of the application. The certificate does not need to be signed by a certificate authority: it
is perfectly allowable, and typical, for Android applications to use self-signed certificates. The certificate is used only to
establish trust relationships between applications, not for wholesale control over whether an application can be
installed. The most significant ways that signatures impact security is by determining who can access signature-based
permissions and who can share user IDs.



User IDs and File Access
Each Android package (.apk) file installed on the device is given its own unique Linux user ID, creating a sandbox for
it and preventing it from touching other applications (or other applications from touching it). This user ID is assigned to
it when the application is installed on the device, and remains constant for the duration of its life on that device.

Because security enforcement happens at the process level, the code of any two packages can not normally run in the
same process, since they need to run as different Linux users. You can use the sharedUserId attribute in the
AndroidManifest.xml's manifest tag of each package to have them assigned the same user ID. By doing this, for
purposes of security the two packages are then treated as being the same application, with the same user ID and file
permissions. Note that in order to retain security, only two applications signed with the same signature (and requesting
the same sharedUserId) will be given the same user ID.

Any data stored by an application will be assigned that application's user ID, and not normally accessible to other
packages. When creating a new file with getSharedPreferences(String, int), openFileOutput(String, int), or

http://developer.android.com/guide/topics/security/security.html                                                      Page 1 of 5
Security and Permissions | Android Developers                                                                   29.04.09 0:41



openOrCreateDatabase(String, int, SQLiteDatabase.CursorFactory), you can use the MODE_WORLD_READABLE
and/or MODE_WORLD_WRITEABLE flags to allow any other package to read/write the file. When setting these flags,
the file is still owned by your application, but its global read and/or write permissions have been set appropriately so
any other application can see it.



Using Permissions
A basic Android application has no permissions associated with it, meaning it can not do anything that would adversely
impact the user experience or any data on the device. To make use of protected features of the device, you must
include in your AndroidManifest.xml one or more <uses-permission> tags declaring the permissions that your
application needs.

For example, an application that needs to monitor incoming SMS messages would specify:

     <manifest xmlns:android="http://schemas.android.com/apk/res/android"
         package="com.android.app.myapp" >

            <uses-permission android:name="android.permission.RECEIVE_SMS" />
     </manifest>

At application install time, permissions requested by the application are granted to it by the package installer, based
on checks against the signatures of the applications declaring those permissions and/or interaction with the user. No
checks with the user are done while an application is running: it either was granted a particular permission when
installed, and can use that feature as desired, or the permission was not granted and any attempt to use the feature
will fail without prompting the user.

Often times a permission failure will result in a SecurityException being thrown back to the application. However, this
is not guaranteed to occur everywhere. For example, the sendBroadcast(Intent) method checks permissions as data is
being delivered to each receiver, after the method call has returned, so you will not receive an exception if there are
permission failures. In almost all cases, however, a permission failure will be printed to the system log.

The permissions provided by the Android system can be found at Manifest.permission. Any application may also define
and enforce its own permissions, so this is not a comprehensive list of all possible permissions.

A particular permission may be enforced at a number of places during your program's operation:

     At the time of a call into the system, to prevent an application from executing certain functions.
     When starting an activity, to prevent applications from launching activities of other applications.
     Both sending and receiving broadcasts, to control who can receive your broadcast or who can send a broadcast to
     you.
     When accessing and operating on a content provider.
     Binding or starting a service.




Declaring and Enforcing Permissions
To enforce your own permissions, you must first declare them in your AndroidManifest.xml using one or more
<permission> tags.

For example, an application that wants to control who can start one of its activities could declare a permission for this
operation as follows:



http://developer.android.com/guide/topics/security/security.html                                                  Page 2 of 5
Security and Permissions | Android Developers                                                                   29.04.09 0:41


     <manifest xmlns:android="http://schemas.android.com/apk/res/android"
         package="com.me.app.myapp" >

            <permission android:name="com.me.app.myapp.permission.DEADLY_ACTIVITY"
                android:label="@string/permlab_deadlyActivity"
                android:description="@string/permdesc_deadlyActivity"
                android:permissionGroup="android.permission-group.COST_MONEY"
                android:protectionLevel="dangerous" />

     </manifest>

The <protectionLevel> attribute is required, telling the system how the user is to be informed of applications requiring
the permission, or who is allowed to hold that permission, as described in the linked documentation.

The <permissionGroup> attribute is optional, and only used to help the system display permissions to the user. You
will usually want to set this to either a standard system group (listed in android.Manifest.permission_group) or in more
rare cases to one defined by yourself. It is preferred to use an existing group, as this simplifies the permission UI
shown to the user.

Note that both a label and description should be supplied for the permission. These are string resources that can be
displayed to the user when they are viewing a list of permissions (android:label) or details on a single permission
( android:description). The label should be short, a few words describing the key piece of functionality the
permission is protecting. The description should be a couple sentences describing what the permission allows a holder
to do. Our convention for the description is two sentences, the first describing the permission, the second warning the
user of what bad things can happen if an application is granted the permission.

Here is an example of a label and description for the CALL_PHONE permission:

            <string name="permlab_callPhone">directly call phone numbers</string>
            <string name="permdesc_callPhone">Allows the application to call
                phone numbers without your intervention. Malicious applications may
                cause unexpected calls on your phone bill. Note that this does not
                allow the application to call emergency numbers.</string>

You can look at the permissions currently defined in the system with the shell command adb shell pm list
permissions. In particular, the '-s' option displays the permissions in a form roughly similar to how the user will see
them:

     $ adb shell pm list permissions -s
     All Permissions:

     Network communication: view Wi-Fi state, create Bluetooth connections, full
     Internet access, view network state
     Your location: access extra location provider commands, fine (GPS) location,
     mock location sources for testing, coarse (network-based) location

     Services that cost you money: send SMS messages, directly call phone numbers

     ...


Enforcing Permissions in AndroidManifest.xml
High-level permissions restricting access to entire components of the system or application can be applied through
your AndroidManifest.xml. All that this requires is including an android:permission attribute on the desired
component, naming the permission that will be used to control access to it.

Activity permissions (applied to the <activity> tag) restrict who can start the associated activity. The permission is
checked during Context.startActivity() and Activity.startActivityForResult(); if the caller does not have the required
permission then SecurityException is thrown from the call.

http://developer.android.com/guide/topics/security/security.html                                                   Page 3 of 5
Security and Permissions | Android Developers                                                                    29.04.09 0:41



Service permissions (applied to the <service> tag) restrict who can start or bind to the associated service. The
permission is checked during Context.startService(), Context.stopService() and Context.bindService(); if the caller does
not have the required permission then SecurityException is thrown from the call.

BroadcastReceiver permissions (applied to the <receiver> tag) restrict who can send broadcasts to the associated
receiver. The permission is checked after Context.sendBroadcast() returns, as the system tries to deliver the submitted
broadcast to the given receiver. As a result, a permission failure will not result in an exception being thrown back to
the caller; it will just not deliver the intent. In the same way, a permission can be supplied to Context.registerReceiver()
to control who can broadcast to a programmatically registered receiver. Going the other way, a permission can be
supplied when calling Context.sendBroadcast() to restrict which BroadcastReceiver objects are allowed to receive the
broadcast (see below).

ContentProvider permissions (applied to the <provider> tag) restrict who can access the data in a ContentProvider.
(Content providers have an important additional security facility available to them called URI permissions which is
described later.) Unlike the other components, there are two separate permission attributes you can set:
android:readPermission restricts who can read from the provider, and android:writePermission restricts who can write to
it. Note that if a provider is protected with both a read and write permission, holding only the write permission does not
mean you can read from a provider. The permissions are checked when you first retrieve a provider (if you don't have
either permission, a SecurityException will be thrown), and as you perform operations on the provider. Using
ContentResolver.query() requires holding the read permission; using ContentResolver.insert(),
ContentResolver.update(), ContentResolver.delete() requires the write permission. In all of these cases, not holding the
required permission results in a SecurityException being thrown from the call.


Enforcing Permissions when Sending Broadcasts
In addition to the permission enforcing who can send Intents to a registered BroadcastReceiver (as described above),
you can also specify a required permission when sending a broadcast. By calling Context.sendBroadcast() with a
permission string, you require that a receiver's application must hold that permission in order to receive your broadcast.

Note that both a receiver and a broadcaster can require a permission. When this happens, both permission checks
must pass for the Intent to be delivered to the associated target.


Other Permission Enforcement
Arbitrarily fine-grained permissions can be enforced at any call into a service. This is accomplished with the
Context.checkCallingPermission() method. Call with a desired permission string and it will return an integer indicating
whether that permission has been granted to the current calling process. Note that this can only be used when you are
executing a call coming in from another process, usually through an IDL interface published from a service or in some
other way given to another process.

There are a number of other useful ways to check permissions. If you have the pid of another process, you can use
the Context method Context.checkPermission(String, int, int) to check a permission against that pid. If you have the
package name of another application, you can use the direct PackageManager method
PackageManager.checkPermission(String, String) to find out whether that particular package has been granted a
specific permission.



URI Permissions
The standard permission system described so far is often not sufficient when used with content providers. A content
provider may want to protect itself with read and write permissions, while its direct clients also need to hand specific
URIs to other applications for them to operate on. A typical example is attachments in a mail application. Access to the
mail should be protected by permissions, since this is sensitive user data. However, if a URI to an image attachment is
given to an image viewer, that image viewer will not have permission to open the attachment since it has no reason to
hold a permission to access all e-mail.


http://developer.android.com/guide/topics/security/security.html                                                   Page 4 of 5
Security and Permissions | Android Developers                                                                         29.04.09 0:41


The solution to this problem is per-URI permissions: when starting an activity or returning a result to an activity, the
caller can set Intent.FLAG_GRANT_READ_URI_PERMISSION and/or
Intent.FLAG_GRANT_WRITE_URI_PERMISSION. This grants the receiving activity permission access the specific
data URI in the Intent, regardless of whether it has any permission to access data in the content provider
corresponding to the Intent.

This mechanism allows a common capability-style model where user interaction (opening an attachment, selecting a
contact from a list, etc) drives ad-hoc granting of fine-grained permission. This can be a key facility for reducing the
permissions needed by applications to only those directly related to their behavior.

The granting of fine-grained URI permissions does, however, require some cooperation with the content provider
holding those URIs. It is strongly recommended that content providers implement this facility, and declare that they
support it through the android:grantUriPermissions attribute or <grant-uri-permissions> tag.

More information can be found in the Context.grantUriPermission(), Context.revokeUriPermission(), and
Context.checkUriPermission() methods.

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/security/security.html                                                        Page 5 of 5
The AndroidManifest.xml File | Android Developers                                                                29.04.09 0:43




The AndroidManifest.xml File

Every application must have an AndroidManifest.xml file (with precisely that name) in its root directory. The manifest
presents essential information about the application to the Android system, information the system must have before it
can run any of the application's code. Among other things, the manifest does the following:

     It names the Java package for the application. The package name serves as a unique identifier for the
     application.
     It describes the components of the application — the activities, services, broadcast receivers, and content
     providers that the application is composed of. It names the classes that implement each of the components and
     publishes their capabilities (for example, which Intent messages they can handle). These declarations let the
     Android system know what the components are and under what conditions they can be launched.
     It determines which processes will host application components.
     It declares which permissions the application must have in order to access protected parts of the API and interact
     with other applications.
     It also declares the permissions that others are required to have in order to interact with the application's
     components.
     It lists the Instrumentation classes that provide profiling and other information as the application is running. These
     declarations are present in the manifest only while the application is being developed and tested; they're removed
     before the application is published.
     It declares the minimum level of the Android API that the application requires.
     It lists the libraries that the application must be linked against.




Structure of the Manifest File
The diagram below shows the general structure of the manifest file and every element that it can contain. Each
element, along with all of its attributes, is documented in full in a separate file. To view detailed information about any
element, click on the element name in the diagram, in the alphabetical list of elements that follows the diagram, or on
any other mention of the element name.


     <?xml version="1.0" encoding="utf-8"?>
     <manifest>
            <uses-permission />
            <permission />
            <permission-tree />
            <permission-group />

            <instrumentation />
            <uses-sdk />

            <application>
                   <activity>
                       <intent-filter>
                           <action />

http://developer.android.com/guide/topics/manifest/manifest-intro.html                                               Page 1 of 6
The AndroidManifest.xml File | Android Developers                                                              29.04.09 0:43

                           <action />
                           <category />
                           <data />
                       </intent-filter>
                       <meta-data />
                   </activity>
                   <activity-alias>
                       <intent-filter> . . . </intent-filter>
                       <meta-data />
                   </activity-alias>

                   <service>
                       <intent-filter> . . . </intent-filter>
                       <meta-data/>
                   </service>
                   <receiver>
                       <intent-filter> . . . </intent-filter>
                       <meta-data />
                   </receiver>

                   <provider>
                       <grant-uri-permission />
                       <meta-data />
                   </provider>
                   <uses-library />
                   <uses-configuration />

            </application>
     </manifest>

All the elements that can appear in the manifest file are listed below in alphabetical order. These are the only legal
elements; you cannot add your own elements or attributes.

     <action>
     <activity>
     <activity-alias>
     <application>
     <category>
     <data>
     <grant-uri-permission>
     <instrumentation>
     <intent-filter>
     <manifest>
     <meta-data>
     <permission>
     <permission-group>
     <permission-tree>
     <provider>
     <receiver>
     <service>
     <uses-configuration>
     <uses-library>
     <uses-permission>
     <uses-sdk>



File Conventions
Some conventions and rules apply generally to all elements and attributes in the manifest:

http://developer.android.com/guide/topics/manifest/manifest-intro.html                                            Page 2 of 6
The AndroidManifest.xml File | Android Developers                                                                 29.04.09 0:43




Elements
    Only the <manifest> and <application> elements are required, they each must be present and can occur
    only once. Most of the others can occur many times or not at all — although at least some of them must be
    present for the manifest to accomplish anything meaningful.

     If an element contains anything at all, it contains other elements. All values are set through attributes, not as
     character data within an element.

     Elements at the same level are generally not ordered. For example, <activity>, <provider>, and
     <service> elements can be intermixed in any sequence. (An <activity-alias> element is the exception to
     this rule: It must follow the <activity> it is an alias for.)

Attributes
     In a formal sense, all attributes are optional. However, there are some that must be specified for an element to
     accomplish its purpose. Use the documentation as a guide. For truly optional attributes, it mentions a default
     value or states what happens in the absence of a specification.

     Except for some attributes of the root <manifest> element, all attribute names begin with an android: prefix
     — for example, android:alwaysRetainTaskState. Because the prefix is universal, the documentation
     generally omits it when referring to attributes by name.

Declaring class names
    Many elements correspond to Java objects, including elements for the application itself (the <application>
    element) and its principal components — activities (<activity>), services (<service>), broadcast receivers
    (<receiver>), and content providers (<provider>).

     If you define a subclass, as you almost always would for the component classes (Activity, Service,
     BroadcastReceiver, and ContentProvider), the subclass is declared through a name attribute. The name must
     include the full package designation. For example, an Service subclass might be declared as follows:


           <manifest . . . >
               <application . . . >
                   <service android:name="com.example.project.SecretService" . . . >
                       . . .
                   </service>
                   . . .
               </application>
           </manifest>

     However, as a shorthand, if the first character of the string is a period, the string is appended to the application's
     package name (as specified by the <manifest> element's package attribute). The following assignment is the
     same as the one above:


           <manifest package="com.example.project" . . . >
               <application . . . >
                   <service android:name=".SecretService" . . . >
                       . . .
                   </service>
                   . . .
               </application>
           </manifest>

     When starting a component, Android creates an instance of the named subclass. If a subclass isn't specified, it
     creates an instance of the base class.

Multiple values
    If more than one value can be specified, the element is almost always repeated, rather than listing multiple values
    within a single element. For example, an intent filter can list several actions:


http://developer.android.com/guide/topics/manifest/manifest-intro.html                                              Page 3 of 6
The AndroidManifest.xml File | Android Developers                                                               29.04.09 0:43



           <intent-filter . . . >
               <action android:name="android.intent.action.EDIT" />
               <action android:name="android.intent.action.INSERT" />
               <action android:name="android.intent.action.DELETE" />
               . . .
           </intent-filter>

Resource values
   Some attributes have values that can be displayed to users — for example, a label and an icon for an activity. The
   values of these attributes should be localized and therefore set from a resource or theme. Resource values are
   expressed in the following format,

           @[package:]type:name

     where the package name can be omitted if the resource is in the same package as the application, type is a type
     of resource — such as "string" or "drawable" — and name is the name that identifies the specific resource. For
     example:


           <activity android:icon="@drawable/smallPic" . . . >

     Values from a theme are expressed in a similar manner, but with an initial '?' rather than '@':

           ?[package:]type:name

String values
     Where an attribute value is a string, double backslashes ('\\') must be used to escape characters — for example,
     '\\n' for a newline or '\\uxxxx' for a Unicode character.



File Features
The following sections describe how some Android features are reflected in the manifest file.


Intent Filters
The core components of an application (its activities, services, and broadcast receivers) are activated by intents. An
intent is a bundle of information (an Intent object) describing a desired action — including the data to be acted upon,
the category of component that should perform the action, and other pertinent instructions. Android locates an
appropriate component to respond to the intent, launches a new instance of the component if one is needed, and
passes it the Intent object.

Components advertise their capabilities — the kinds of intents they can respond to — through intent filters. Since the
Android system must learn which intents a component can handle before it launches the component, intent filters are
specified in the manifest as <intent-filter> elements. A component may have any number of filters, each one
describing a different capability.

An intent that explicitly names a target component will activate that component; the filter doesn't play a role. But an
intent that doesn't specify a target by name can activate a component only if it can pass through one of the
component's filters.

For information on how Intent objects are tested against intent filters, see a separate document, Intents and Intent
Filters.


Icons and Labels
A number of elements have icon and label attributes for a small icon and a text label that can be displayed to
users. Some also have a description attribute for longer explanatory text that can also be shown on-screen. For
http://developer.android.com/guide/topics/manifest/manifest-intro.html                                            Page 4 of 6
The AndroidManifest.xml File | Android Developers                                                                 29.04.09 0:43


users. Some also have a description attribute for longer explanatory text that can also be shown on-screen. For
example, the <permission> element has all three of these attributes, so that when the user is asked whether to
grant the permission to an application that has requested it, an icon representing the permission, the name of the
permission, and a description of what it entails can all be presented to the user.

In every case, the icon and label set in a containing element become the default icon and label settings for all of
the container's subelements. Thus, the icon and label set in the <application> element are the default icon and
label for each of the application's components. Similarly, the icon and label set for a component — for example, an
<activity> element — are the default settings for each of the component's <intent-filter> elements. If an
<application> element sets a label, but an activity and its intent filter do not, the application label is treated as the
label for both the activity and the intent filter.

The icon and label set for an intent filter are used to represent a component whenever the component is presented to
the user as fulfilling the function advertised by the filter. For example, a filter with "android.intent.action.MAIN"
and "android.intent.category.LAUNCHER" settings advertises an activity as one that initiates an application —
that is, as one that should be displayed in the application launcher. The icon and label set in the filter are therefore the
ones displayed in the launcher.


Permissions
A permission is a restriction limiting access to a part of the code or to data on the device. The limitation is imposed to
protect critical data and code that could be misused to distort or damage the user experience.

Each permission is identified by a unique label. Often the label indicates the action that's restricted. For example, here
are some permissions defined by Android:

     android.permission.CALL_EMERGENCY_NUMBERS
     android.permission.READ_OWNER_DATA
     android.permission.SET_WALLPAPER
     android.permission.DEVICE_POWER

A feature can be protected by at most one permission.

If an application needs access to a feature protected by a permission, it must declare that it requires that permission
with a <uses-permission> element in the manifest. Then, when the application is installed on the device, the
installer determines whether or not to grant the requested permission by checking the authorities that signed the
application's certificates and, in some cases, asking the user. If the permission is granted, the application is able to
use the protected features. If not, its attempts to access those features will simply fail without any notification to the
user.

An application can also protect its own components (activities, services, broadcast receivers, and content providers)
with permissions. It can employ any of the permissions defined by Android (listed in android.Manifest.permission) or
declared by other applications. Or it can define its own. A new permission is declared with the <permission>
element. For example, an activity could be protected as follows:

     <manifest . . . >
         <permission android:name="com.example.project.DEBIT_ACCT" . . . />
         . . .
         <application . . .>
             <activity android:name="com.example.project.FreneticActivity" . . . >
                        android:permission="com.example.project.DEBIT_ACCT"
                        . . . >
                 . . .
             </activity>
         </application>
         . . .
         <uses-permission android:name="com.example.project.DEBIT_ACCT" />
         . . .
     </manifest>



http://developer.android.com/guide/topics/manifest/manifest-intro.html                                              Page 5 of 6
The AndroidManifest.xml File | Android Developers                                                                     29.04.09 0:43


Note that, in this example, the DEBIT_ACCT permission is not only declared with the <permission> element, its use
is also requested with the <uses-permission> element. Its use must be requested in order for other components of
the application to launch the protected activity, even though the protection is imposed by the application itself.

If, in the same example, the permission attribute was set to a permission declared elsewhere (such as
android.permission.CALL_EMERGENCY_NUMBERS, it would not have been necessary to declare it again with a
<permission> element. However, it would still have been necessary to request its use with <uses-permission>.

The <permission-tree> element declares a namespace for a group of permissions that will be defined in code.
And <permission-group> defines a label for a set of permissions (both those declared in the manifest with
<permission> elements and those declared elsewhere). It affects only how the permissions are grouped when
presented to the user. The <permission-group> element does not specify which permissions belong to the group;
it just gives the group a name. A permission is placed in the group by assigning the group name to the
<permission> element's permissionGroup attribute.


Libraries
Every application is linked against the default Android library, which includes the basic packages for building
applications (with common classes such as Activity, Service, Intent, View, Button, Application, ContentProvider, and so
on).

However, some packages reside in their own libraries. If your application uses code from any of these packages, it
must explicitly asked to be linked against them. The manifest must contain a separate <uses-library> element to
name each of the libraries. (The library name can be found in the documentation for the package.)

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/manifest/manifest-intro.html                                                  Page 6 of 6
<action> | Android Developers                                                                                         29.04.09 0:43




<action>

SYNTAX:


          <action android:name="string" />


CONTAINED IN:
     <intent-filter>

DESCRIPTION:
     Adds an action to an intent filter. An <intent-filter> element must contain one or more <action> elements.
     If it doesn't contain any, no Intent objects will get through the filter. See Intents and Intent Filters for details on
     intent filters and the role of action specifications within a filter.

ATTRIBUTES:
     android:name
        The name of the action. Some standard actions are defined in the Intent class as ACTION_string
        constants. To assign one of these actions to this attribute, prepend "android.intent.action." to the
        string that follows ACTION_. For example, for ACTION_MAIN, use "android.intent.action.MAIN"
        and for ACTION_WEB_SEARCH, use "android.intent.action.WEB_SEARCH".

           For actions you define, it's best to use the package name as a prefix to ensure uniqueness. For example, a
           TRANSMOGRIFY action might be specified as follows:

                <action android:name="com.example.project.TRANSMOGRIFY" />


INTRODUCED IN:
     API Level 1

SEE ALSO:
     <intent-filter>

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/manifest/action-element.html                                                  Page 1 of 1
<activity> | Android Developers                                                                              29.04.09 0:43




<activity>

SYNTAX:


           <activity android:allowTaskReparenting=["true" | "false"]
                     android:alwaysRetainTaskState=["true" | "false"]
                     android:clearTaskOnLaunch=["true"" | "false"]
                     android:configChanges=[one or more of: "mcc" "mnc" "locale"
                                            "touchscreen" "keyboard" "keyboardHidden"
                                            "navigation" "orientation" "fontScale"]
                     android:enabled=["true" | "false"]
                     android:excludeFromRecents=["true" | "false"]
                     android:exported=["true" | "false"]
                     android:finishOnTaskLaunch=["true" | "false"]
                     android:icon="drawable resource"
                     android:label="string resource"
                     android:launchMode=["multiple" | "singleTop" |
                                         "singleTask" | "singleInstance"]
                     android:multiprocess=["true" | "false"]
                     android:name="string"
                     android:noHistory=["true" | "false"]
                     android:permission="string"
                     android:process="string"
                     android:screenOrientation=["unspecified" | "user" | "behind" |
                                                 "landscape" | "portrait" |
                                                 "sensor" | "nonsensor"]
                     android:stateNotNeeded=["true" | "false"]
                     android:taskAffinity="string"
                     android:theme="resource or theme"
                     android:windowSoftInputMode=[one or more of: "stateUnspecified"
                                                   "stateUnchanged" "stateHidden"
                                                   "stateAlwaysHidden" "stateVisible"
                                                   "stateAlwaysVisible" "adjustUnspecified"
                                                   "adjustResize" "adjustPan"] >
               . . .
           </activity>


CONTAINED IN:
     <application>

CAN CONTAIN:
     <intent-filter>
     <meta-data>

DESCRIPTION:
     Declares an activity (an Activity subclass) that implements part of the application's visual user interface. All
     activities must be represented by <activity> elements in the manifest file. Any that are not declared there will
     not be seen by the system and will never be run.

ATTRIBUTES:
     android:allowTaskReparenting
        Whether or not the activity can move from the task that started it to the task it has an affinity for when that
        task is next brought to the front — "true" if it can move, and "false" if it must remain with the task where it
        started.

http://developer.android.com/guide/topics/manifest/activity-element.html                                       Page 1 of 8
<activity> | Android Developers                                                                                        29.04.09 0:43



           If this attribute is not set, the value set by the corresponding allowTaskReparenting attribute of the
           <application> element applies to the activity. The default value is "false".

           Normally when an activity is started, it's associated with the task of the activity that started it and it stays
           there for its entire lifetime. You can use this attribute to force it to be re-parented to the task it has an affinity
           for when its current task is no longer displayed. Typically, it's used to cause the activities of an application to
           move to the main task associated with that application.

           For example, if an e-mail message contains a link to a web page, clicking the link brings up an activity that
           can display the page. That activity is defined by the browser application, but is launched as part of the e-mail
           task. If it's reparented to the browser task, it will be shown when the browser next comes to the front, and will
           be absent when the e-mail task again comes forward.

           The affinity of an activity is defined by the taskAffinity attribute. The affinity of a task is determined by
           reading the affinity of its root activity. Therefore, by definition, a root activity is always in a task with the same
           affinity. Since activities with "singleTask" or "singleInstance" launch modes can only be at the root of
           a task, re-parenting is limited to the "standard" and "singleTop" modes. (See also the launchMode
           attribute.)

     android:alwaysRetainTaskState
        Whether or not the state of the task that the activity is in will always be maintained by the system — "true"
        if it will be, and "false" if the system is allowed to reset the task to its initial state in certain situations. The
        default value is "false". This attribute is meaningful only for the root activity of a task; it's ignored for all
        other activities.

           Normally, the system clears a task (removes all activities from the stack above the root activity) in certain
           situations when the user re-selects that task from the home screen. Typically, this is done if the user hasn't
           visited the task for a certain amount of time, such as 30 minutes.

           However, when this attribute is "true", users will always return to the task in its last state, regardless of how
           they get there. This is useful, for example, in an application like the web browser where there is a lot of state
           (such as multiple open tabs) that users would not like to lose.

     android:clearTaskOnLaunch
        Whether or not all activities will be removed from the task, except for the root activity, whenever it is re-
        launched from the home screen — "true" if the task is always stripped down to its root activity, and "false"
        if not. The default value is "false". This attribute is meaningful only for activities that start a new task (the
        root activity); it's ignored for all other activities in the task.

           When the value is "true", every time users start the task again, they are brought to its root activity,
           regardless of what they were last doing in the task and regardless of whether they used BACK or HOME to
           last leave it. When the value is "false", the task may be cleared of activities in some situations (see the
           alwaysRetainTaskState attribute), but not always.

           Suppose, for example, that someone launches activity P from the home screen, and from there goes to
           activity Q. The user next presses HOME, and then returns to activity P. Normally, the user would see activity
           Q, since that is what they were last doing in P's task. However, if P set this flag to "true", all of the activities
           on top of it (Q in this case) were removed when the user pressed HOME and the task went to the
           background. So the user sees only P when returning to the task.

           If this attribute and allowTaskReparenting are both "true", any activities that can be re-parented are
           moved to the task they share an affinity with; the remaining activities are then dropped, as described above.

     android:configChanges
        Lists configuration changes that the activity will handle itself. When changes that are not listed occur, the
        activity is shut down and restarted. When a listed change occurs, the activity remains running and its
        onConfigurationChanged() method is called.

           Any or all of the following strings can be used to set this attribute. Values are separated by '|' — for example,
           "locale|navigation|orientation".
http://developer.android.com/guide/topics/manifest/activity-element.html                                                 Page 2 of 8
<activity> | Android Developers                                                                                        29.04.09 0:43


           "locale|navigation|orientation".

                 Value                            Description

                 "mcc"                            The IMSI mobile country code (MCC) has changed — that is, a SIM has been
                                                  detected and updated the MCC.

                 "mnc"                            The IMSI mobile network code (MNC) has changed — that is, a SIM has been
                                                  detected and updated the MNC.

                 "locale"                         The locale has changed — for example, the user has selected a new
                                                  language that text should be displayed in.

                 "touchscreen"                    The touchscreen has changed. (This should never normally happen.)

                 "keyboard"                       The keyboard type has changed — for example, the user has plugged in an
                                                  external keyboard.

                 "keyboardHidden"                 The keyboard accessibility has changed — for example, the user has slid the
                                                  keyboard out to expose it.

                 "navigation"                     The navigation type has changed. (This should never normally happen.)

                 "orientation"                    The screen orientation has changed — that is, the user has rotated the
                                                  device.

                 "fontScale"                      The font scaling factor has changed — that is, the user has selected a new
                                                  global font size.

           All of these configuration changes can impact the resource values seen by the application. Therefore, when
           onConfigurationChanged() is called, it will generally be necessary to again retrieve all resources
           (including view layouts, drawables, and so on) to correctly handle the change.

     android:enabled
        Whether or not the activity can be instantiated by the system — "true" if it can be, and "false" if not. The
        default value is "true".

           The <application> element has its own enabled attribute that applies to all application components,
           including activities. The <application> and <activity> attributes must both be "true" (as they both are
           by default) for the system to be able to instantiate the activity. If either is "false", it cannot be instantiated.

     android:excludeFromRecents
        Whether or not the activity should be excluded from the list of recently launched activities that can be
        displayed to users — "true" if it should be excluded, and "false" if it should be included. The default value
        is "false".

     android:exported
        Whether or not the activity can be launched by components of other applications — "true" if it can be, and
        "false" if not. If "false", the activity can be launched only by components of the same application or
        applications with the same user ID.

           The default value depends on whether the activity contains intent filters. The absence of any filters means
           that the activity can be invoked only by specifying its exact class name. This implies that the activity is
           intended only for application-internal use (since others would not know the class name). So in this case, the
           default value is "false". On the other hand, the presence of at least one filter implies that the activity is
           intended for external use, so the default value is "true".

           This attribute is not the only way to limit an activity's exposure to other applications. You can also use a
           permission to limit the external entities that can invoke the activity (see the permission attribute).


http://developer.android.com/guide/topics/manifest/activity-element.html                                                   Page 3 of 8
<activity> | Android Developers                                                                                    29.04.09 0:43



     android:finishOnTaskLaunch
        Whether or not an existing instance of the activity should be shut down (finished) whenever the user again
        launches its task (chooses the task on the home screen) — "true" if it should be shut down, and "false" if
        not. The default value is "false".

           If this attribute and allowTaskReparenting are both "true", this attribute trumps the other. The affinity of
           the activity is ignored. The activity is not re-parented, but destroyed.

     android:icon
        An icon representing the activity. The icon is displayed to users when a representation of the activity is
        required on-screen. For example, icons for activities that initiate tasks are displayed in the launcher window.
        The icon is often accompanied by a label (see the label attribute).

           This attribute must be set as a reference to a drawable resource containing the image definition. If it is not
           set, the icon specified for the application as a whole is used instead (see the <application> element's
           icon attribute).

           The activity's icon — whether set here or by the <application> element — is also the default icon for all
           the activity's intent filters (see the <intent-filter> element's icon attribute).

     android:label
        A user-readable label for the activity. The label is displayed on-screen when the activity must be represented
        to the user. It's often displayed along with the activity icon.

           If this attribute is not set, the label set for the application as a whole is used instead (see the
           <application> element's label attribute).

           The activity's label — whether set here or by the <application> element — is also the default label for all
           the activity's intent filters (see the <intent-filter> element's label attribute).

           The label should be set as a reference to a string resource, so that it can be localized like other strings in the
           user interface. However, as a convenience while you're developing the application, it can also be set as a raw
           string.

     android:launchMode
        An instruction on how the activity should be launched. There are four modes that work in conjunction with
        activity flags (FLAG_ACTIVITY_* constants) in Intent objects to determine what should happen when the
        activity is called upon to handle an intent. They are:

                 "standard"
                 "singleTop"
                 "singleTask"
                 "singleInstance"

           The default mode is "standard".

           The modes fall into two main groups, with "standard" and "singleTop" activities on one side, and
           "singleTask" and "singleInstance" activities on the other. An activity with the "standard" or
           "singleTop" launch mode can be instantiated multiple times. The instances can belong to any task and can
           be located anywhere in the activity stack. Typically, they're launched into the task that called
           startActivity() (unless the Intent object contains a FLAG_ACTIVITY_NEW_TASK instruction, in which
           case a different task is chosen — see the taskAffinity attribute).

           In contrast, "singleTask" and "singleInstance" activities can only begin a task. They are always at the
           root of the activity stack. Moreover, the device can hold only one instance of the activity at a time — only one
           such task.

           The "standard" and "singleTop" modes differ from each other in just one respect: Every time there's new
           intent for a "standard" activity, a new instance of the class is created to respond to that intent. Each
           instance handles a single intent. Similarly, a new instance of a "singleTop" activity may also be created to
           handle a new intent. However, if the target task already has an existing instance of the activity at the top of its
http://developer.android.com/guide/topics/manifest/activity-element.html                                             Page 4 of 8
<activity> | Android Developers                                                                                      29.04.09 0:43


           handle a new intent. However, if the target task already has an existing instance of the activity at the top of its
           stack, that instance will receive the new intent (in an onNewIntent() call); a new instance is not created. In
           other circumstances — for example, if an existing instance of the "singleTop" activity is in the target task,
           but not at the top of the stack, or if it's at the top of a stack, but not in the target task — a new instance
           would be created and pushed on the stack.

           The "singleTask" and "singleInstance" modes also differ from each other in only one respect: A
           "singleTask" activity allows other activities to be part of its task. It's at the root of the activity stack, but
           other activities (necessarily "standard" and "singleTop" activities) can be launched into the same task. A
           "singleInstance" activity, on the other hand, permits no other activities to be part of its task. It's the only
           activity in the task. If it starts another activity, that activity is assigned to a different task — as if
           FLAG_ACTIVITY_NEW_TASK was in the intent.

           For more information on launch modes and their interaction with Intent flags, see the Activities and Tasks
           section of the Application Fundamentals document.

     android:multiprocess
        Whether an instance of the activity can be launched into the process of the component that started it —
        "true" if it can be, and "false" if not. The default value is "false".

           Normally, a new instance of an activity is launched into the process of the application that defined it, so all
           instances of the activity run in the same process. However, if this flag is set to "true", instances of the
           activity can run in multiple processes, allowing the system to create instances wherever they are used
           (provided permissions allow it), something that is almost never necessary or desirable.

     android:name
        The name of the class that implements the activity, a subclass of Activity. The attribute value should be a
        fully qualified class name (such as, "com.example.project.ExtracurricularActivity"). However,
        as a shorthand, if the first character of the name is a period (for example, ".ExtracurricularActivity"),
        it is appended to the package name specified in the <manifest> element.

           There is no default. The name must be specified.

     android:noHistory
        Whether or not the activity should be removed from the activity stack and finished (its finish() method
        called) when the user navigates away from it and it's no longer visible on screen — "true" if it should be
        finished, and "false" if not. The default value is "false".

           A value of "true" means that the activity will not leave a historical trace. It will not remain in the activity
           stack for the task, so the user will not be able to return to it.

           This attribute was introduced in API Level 3.

     android:permission
        The name of a permission that clients must have to launch the activity or otherwise get it to respond to an
        intent. If a caller of startActivity() or startActivityForResult() has not been granted the
        specified permission, its intent will not be delivered to the activity.

           If this attribute is not set, the permission set by the <application> element's permission attribute
           applies to the activity. If neither attribute is set, the activity is not protected by a permission.

           For more information on permissions, see the Permissions section in the introduction and another document,
           Security and Permissions.

     android:process
        The name of the process in which the activity should run. Normally, all components of an application run in
        the default process created for the application. It has the same name as the application package. The
        <application> element's process attribute can set a different default for all components. But each
        component can override the default, allowing you to spread your application across multiple processes.


http://developer.android.com/guide/topics/manifest/activity-element.html                                               Page 5 of 8
<activity> | Android Developers                                                                                          29.04.09 0:43


           If the name assigned to this attribute begins with a colon (':'), a new process, private to the application, is
           created when it's needed and the activity runs in that process. If the process name begins with a lowercase
           character, the activity will run in a global process of that name, provided that it has permission to do so. This
           allows components in different applications to share a process, reducing resource usage.

     android:screenOrientation
        The orientation of the activity's display on the device. The value can be any one of the following strings:

                 "unspecified"              The default value. The system chooses the orientation. The policy it uses, and
                                            therefore the choices made in specific contexts, may differ from device to device.

                 "landscape"                Landscape orientation (the display is wider than it is tall).

                 "portrait"                 Portrait orientation (the display is taller than it is wide).

                 "user"                     The user's current preferred orientation.

                 "behind"                   The same orientation as the activity that's immediately beneath it in the activity
                                            stack.

                 "sensor"                   The orientation determined by a physical orientation sensor. The orientation of the
                                            display depends on how the user is holding the device; it changes when the user
                                            rotates the device.

                 "nosensor"                 An orientation determined without reference to a physical orientation sensor. The
                                            sensor is ignored, so the display will not rotate based on how the user moves the
                                            device. Except for this distinction, the system chooses the orientation using the
                                            same policy as for the "unspecified" setting.

     android:stateNotNeeded
        Whether or not the activity can be killed and successfully restarted without having saved its state — "true" if
        it can be restarted without reference to its previous state, and "false" if its previous state is required. The
        default value is "false".

           Normally, before an activity is temporarily shut down to save resources, its onSaveInstanceState()
           method is called. This method stores the current state of the activity in a Bundle object, which is then passed
           to onCreate() when the activity is restarted. If this attribute is set to "true", onSaveInstanceState()
           may not be called and onCreate() will be passed null instead of the Bundle — just as it was when the
           activity started for the first time.

           A "true" setting ensures that the activity can be restarted in the absence of retained state. For example, the
           activity that displays the home screen uses this setting to make sure that it does not get removed if it crashes
           for some reason.

     android:taskAffinity
        The task that the activity has an affinity for. Activities with the same affinity conceptually belong to the same
        task (to the same "application" from the user's perspective). The affinity of a task is determined by the affinity
        of its root activity.

           The affinity determines two things — the task that the activity is re-parented to (see the
           allowTaskReparenting attribute) and the task that will house the activity when it is launched with the
           FLAG_ACTIVITY_NEW_TASK flag.

           By default, all activities in an application have the same affinity. You can set this attribute to group them
           differently, and even place activities defined in different applications within the same task. To specify that the
           activity does not have an affinity for any task, set it to an empty string.

           If this attribute is not set, the activity inherits the affinity set for the application (see the <application>
           element's taskAffinity attribute). The name of the default affinity for an application is the package name
           set by the <manifest> element.
http://developer.android.com/guide/topics/manifest/activity-element.html                                                   Page 6 of 8
<activity> | Android Developers                                                                                               29.04.09 0:43


           set by the <manifest> element.

     android:theme
        A reference to a style resource defining an overall theme for the activity. This automatically sets the activity's
        context to use this theme (see setTheme(), and may also cause "starting" animations prior to the activity
        being launched (to better match what the activity actually looks like).

           If this attribute is not set, the activity inherits the theme set for the application as a whole — see the
           <application> element's theme attribute. If that attribute is also not set, the default system theme is used.

     android:windowSoftInputMode
        How the main window of the activity interacts with the window containing the on-screen soft keyboard. The
        setting for this attribute affects two things:
                 The state of the soft keyboard — whether it is hidden or visible — when the activity becomes the focus
                 of user attention.
                 The adjustment made to the activity's main window — whether it is resized smaller to make room for the
                 soft keyboard or whether its contents pan to make the current focus visible when part of the window is
                 covered by the soft keyboard.

           The setting must be one of the values listed in the following table, or a combination of one "state..." value
           plus one "adjust..." value. Setting multiple values in either group — multiple "state..." values, for
           example — has undefined results. Individual values are separated by a vertical bar (|). For example:


                 <activity android:windowSoftInputMode="stateVisible|adjustResize" . . . >

           Values set here (other than "stateUnspecified" and "adjustUnspecified") override values set in the
           theme.

                 Value                                   Description

                 "stateUnspecified"                      The state of the soft keyboard (whether it is hidden or visible) is not
                                                         specified. The system will choose an appropriate state or rely on the
                                                         setting in the theme.

                                                         This is the default setting for the behavior of the soft keyboard.

                 "stateUnchanged"                        The soft keyboard is kept in whatever state it was last in, whether visible
                                                         or hidden, when the activity comes to the fore.

                 "stateHidden"                           The soft keyboard is hidden when the user chooses the activity — that
                                                         is, when the user affirmatively navigates forward to the activity, rather
                                                         than backs into it because of leaving another activity.

                 "stateAlwaysHidden"                     The soft keyboard is always hidden when the activity's main window has
                                                         input focus.

                 "stateVisible"                          The soft keyboard is visible when that's normally appropriate (when the
                                                         user is navigating forward to the activity's main window).

                 "stateAlwaysVisible"                    The soft keyboard is made visible when the user chooses the activity —
                                                         that is, when the user affirmatively navigates forward to the activity,
                                                         rather than backs into it because of leaving another activity.

                 "adjustUnspecified"                     It is unspecified whether the activity's main window resizes to make
                                                         room for the soft keyboard, or whether the contents of the window pan
                                                         to make the currentfocus visible on-screen. The system will
                                                         automatically select one of these modes depending on whether the
                                                         content of the window has any layout views that can scroll their contents.

http://developer.android.com/guide/topics/manifest/activity-element.html                                                        Page 7 of 8
<activity> | Android Developers                                                                                              29.04.09 0:43


                                                         content of the window has any layout views that can scroll their contents.
                                                         If there is such a view, the window will be resized, on the assumption
                                                         that scrolling can make all of the window's contents visible within a
                                                         smaller area.

                                                         This is the default setting for the behavior of the main window.

                 "adjustResize"                          The activity's main window is always resized to make room for the soft
                                                         keyboard on screen.

                 "adjustPan"                             The activity's main window is not resized to make room for the soft
                                                         keyboard. Rather, the contents of the window are automatically panned
                                                         so that the current focus is never obscured by the keyboard and users
                                                         can always see what they are typing. This is generally less desireable
                                                         than resizing, because the user may need to close the soft keyboard to
                                                         get at and interact with obscured parts of the window.

           This attribute was introduced in API Level 3.

INTRODUCED IN:
     API Level 1 for all attributes except for noHistory and windowSoftInputMode, which were added in API
     Level 3.

SEE ALSO:
     <application>
     <activity-alias>

                                                                                                                            ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/manifest/activity-element.html                                                       Page 8 of 8
<activity-alias> | Android Developers                                                                               29.04.09 0:43




<activity-alias>

SYNTAX:


           <activity-alias android:enabled=["true" | "false"]
                           android:exported=["true" | "false"]
                           android:icon="drawable resource"
                           android:label="string resource"
                           android:name="string"
                           android:permission="string"
                           android:targetActivity="string" >
               . . .
           </activity-alias>


CONTAINED IN:
     <application>

CAN CONTAIN:
     <intent-filter>
     <meta-data>

DESCRIPTION:
     An alias for an activity, named by the targetActivity attribute. The target must be in the same application as
     the alias and it must be declared before the alias in the manifest.

     The alias presents the target activity as a independent entity. It can have its own set of intent filters, and they,
     rather than the intent filters on the target activity itself, determine which intents can activate the target through the
     alias and how the system treats the alias. For example, the intent filters on the alias may specify the
     "android.intent.action.MAIN" and "android.intent.category.LAUNCHER" flags, causing it to be
     represented in the application launcher, even though none of the filters on the target activity itself set these flags.

     With the exception of targetActivity, <activity-alias> attributes are a subset of <activity> attributes.
     For attributes in the subset, none of the values set for the target carry over to the alias. However, for attributes
     not in the subset, the values set for the target activity also apply to the alias.

ATTRIBUTES:
     android:enabled
        Whether or not the target activity can be instantiated by the system through this alias — "true" if it can be,
        and "false" if not. The default value is "true".

           The <application> element has its own enabled attribute that applies to all application components,
           including activity aliases. The <application> and <activity-alias> attributes must both be "true" for
           the system to be able to instantiate the target activity through the alias. If either is "false", the alias does
           not work.

     android:exported
        Whether or not components of other applications can launch the target activity through this alias — "true" if
        they can, and "false" if not. If "false", the target activity can be launched through the alias only by
        components of the same application as the alias or applications with the same user ID.

           The default value depends on whether the alias contains intent filters. The absence of any filters means that
           the activity can be invoked through the alias only by specifying the exact name of the alias. This implies that
http://developer.android.com/guide/topics/manifest/activity-alias-element.html                                        Page 1 of 2
<activity-alias> | Android Developers                                                                                  29.04.09 0:43


           the activity can be invoked through the alias only by specifying the exact name of the alias. This implies that
           the alias is intended only for application-internal use (since others would not know its name) — so the default
           value is "false". On the other hand, the presence of at least one filter implies that the alias is intended for
           external use — so the default value is "true".

     android:icon
        An icon for the target activity when presented to users through the alias. See the <activity> element's
        icon attribute for more information.

     android:label
        A user-readable label for the alias when presented to users through the alias. See the the <activity>
        element's label attribute for more information.

     android:name
        A unique name for the alias. The name should resemble a fully qualified class name. But, unlike the name of
        the target activity, the alias name is arbitrary; it does not refer to an actual class.

     android:permission
        The name of a permission that clients must have to launch the target activity or get it to do something via the
        alias. If a caller of startActivity() or startActivityForResult() has not been granted the
        specified permission, the target activity will not be activated.

           This attribute supplants any permission set for the target activity itself. If it is not set, a permission is not
           needed to activate the target through the alias.

           For more information on permissions, see the Permissions section in the introduction.

     android:targetActivity
        The name of the activity that can be activated through the alias. This name must match the name attribute of
        an <activity> element that precedes the alias in the manifest.

INTRODUCED IN:
     API Level 1

SEE ALSO:
     <activity>

                                                                                                                      ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/manifest/activity-alias-element.html                                           Page 2 of 2
<application> | Android Developers                                                                            29.04.09 0:43




<application>

SYNTAX:


           <application android:allowClearUserData=["true" | "false"]
                        android:allowTaskReparenting=["true" | "false"]
                        android:debuggable=["true" | "false"]
                        android:description="string resource"
                        android:enabled=["true" | "false"]
                        android:hasCode=["true" | "false"]
                        android:icon="drawable resource"
                        android:label="string resource"
                        android:manageSpaceActivity="string"
                        android:name="string"
                        android:permission="string"
                        android:persistent=["true" | "false"]
                        android:process="string"
                        android:taskAffinity="string"
                        android:theme="resource or theme" >
               . . .
           </application>


CONTAINED IN:
     <manifest>

CAN CONTAIN:
     <activity>
     <activity-alias>
     <service>
     <receiver>
     <provider>
     <uses-library>

DESCRIPTION:
     The declaration of the application. This element contains subelements that declare each of the application's
     components and has attributes that can affect all the components. Many of these attributes (such as icon,
     label, permission, process, taskAffinity, and allowTaskReparenting) set default values for
     corresponding attributes of the component elements. Others (such as debuggable, enabled, description,
     and allowClearUserData) set values for the application as a whole and cannot be overridden by the
     components.

ATTRIBUTES
     android:allowClearUserData
        Whether or not users are given the option to remove user data — "true" if they are, and "false" if not. If
        the value is "true", as it is by default, the application manager includes an option that allows users to clear
        the data.

     android:allowTaskReparenting
        Whether or not activities that the application defines can move from the task that started them to the task they
        have an affinity for when that task is next brought to the front — "true" if they can move, and "false" if
        they must remain with the task where they started. The default value is "false".


http://developer.android.com/guide/topics/manifest/application-element.html                                     Page 1 of 3
<application> | Android Developers                                                                                29.04.09 0:43


           The <activity> element has its own allowTaskReparenting attribute that can override the value set
           here. See that attribute for more information.

     android:debuggable
        Whether or not the application can be debugged, even when running on a device in user mode — "true" if it
        can be, and "false" if not. The default value is "false".

     android:description
        User-readable text about the application, longer and more descriptive than the application label. The value
        must be set as a reference to a string resource. Unlike the label, it cannot be a raw string. There is no default
        value.

     android:enabled
        Whether or not the Android system can instantiate components of the application — "true" if it can, and
        "false" if not. If the value is "true", each component's enabled attribute determines whether that
        component is enabled or not. If the value is "false", it overrides the component-specific values; all
        components are disabled.

           The default value is "true".

     android:hasCode
        Whether or not the application contains any code — "true" if it does, and "false" if not. When the value is
        "false", the system does not try to load any application code when launching components. The default
        value is "true".

           An application would not have any code of its own only if it's using nothing but built-in component classes,
           such as an activity that uses the AliasActivity class, a rare occurrence.

     android:icon
        An icon for the application as whole, and the default icon for each of the application's components. See the
        individual icon attributes for <activity>, <activity-alias>, <service>, <receiver>, and
        <provider> elements.

           This attribute must be set as a reference to a drawable resource containing the image definition. There is no
           default icon.

     android:label
        A user-readable label for the application as a whole, and a default label for each of the application's
        components. See the individual label attributes for <activity>, <activity-alias>, <service>,
        <receiver>, and <provider> elements.

           The label should be set as a reference to a string resource, so that it can be localized like other strings in the
           user interface. However, as a convenience while you're developing the application, it can also be set as a raw
           string.

     android:manageSpaceActivity
        The fully qualified name of an Activity subclass that the system can launch to let users manage the memory
        occupied by the application on the device. The activity should also be declared with an <activity>
        element.

     android:name
        The fully qualified name of an Application subclass implemented for the application. When the application
        process is started, this class is instantiated before any of the application's components.

           The subclass is optional; most applications won't need one. In the absence of a subclass, Android uses an
           instance of the base Application class.

     android:permission
        The name of a permission that clients must have in order to interact with the application. This attribute is a
        convenient way to set a permission that applies to all of the application's components. It can be overwritten by
        setting the permission attributes of individual components.
http://developer.android.com/guide/topics/manifest/application-element.html                                          Page 2 of 3
<application> | Android Developers                                                                                    29.04.09 0:43


           setting the permission attributes of individual components.

           For more information on permissions, see the Permissions section in the introduction and another document,
           Security and Permissions.

     android:persistent
        Whether or not the application should remain running at all times — "true" if it should, and "false" if not.
        The default value is "false". Applications should not normally set this flag; persistence mode is intended
        only for certain system applications.

     android:process
        The name of a process where all components of the application should run. Each component can override
        this default by setting its own process attribute.

           By default, Android creates a process for an application when the first of its components needs to run. All
           components then run in that process. The name of the default process matches the package name set by the
           <manifest> element.

           By setting this attribute to a process name that's shared with another application, you can arrange for
           components of both applications to run in the same process — but only if the two applications also share a
           user ID and be signed with the same certificate.

           If the name assigned to this attribute begins with a colon (':'), a new process, private to the application, is
           created when it's needed. If the process name begins with a lowercase character, a global process of that
           name is created. A global process can be shared with other applications, reducing resource usage.

     android:taskAffinity
        An affinity name that applies to all activities within the application, except for those that set a different affinity
        with their own taskAffinity attributes. See that attribute for more information.

           By default, all activities within an application share the same affinity. The name of that affinity is the same as
           the package name set by the <manifest> element.

     android:theme
        A reference to a style resource defining a default theme for all activities in the application. Individual activities
        can override the default by setting their own theme attributes; see that attribute for more information.

INTRODUCED IN:
     API Level 1

SEE ALSO:
     <activity>
     <service>
     <receiver>
     <provider>

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/manifest/application-element.html                                             Page 3 of 3
<category> | Android Developers                                                                                       29.04.09 0:43




<category>

SYNTAX:


          <category android:name="string" />


CONTAINED IN:
     <intent-filter>

DESCRIPTION:
     Adds a category name to an intent filter. See Intents and Intent Filters for details on intent filters and the role of
     category specifications within a filter.

ATTRIBUTES:
     android:name
        The name of the category. Standard categories are defined in the Intent class as CATEGORY_name constants.
        The name assigned here can be derived from those constants by prefixing "android.intent.category."
        to the name that follows CATEGORY_. For example, the string value for CATEGORY_LAUNCHER is
        "android.intent.category.LAUNCHER".

           Custom categories should use the package name as a prefix, to ensure that they are unique.

INTRODUCED IN:
     API Level 1

SEE ALSO:
     <action>
     <data>

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/manifest/category-element.html                                                Page 1 of 1
<data> | Android Developers                                                                                       29.04.09 0:44




<data>

SYNTAX:


          <data android:host="string"
                android:mimeType="string"
                android:path="string"
                android:pathPattern="string"
                android:pathPrefix="string"
                android:port="string"
                android:scheme="string" />


CONTAINED IN:
     <intent-filter>

DESCRIPTION:
     Adds a data specification to an intent filter. The specification can be just a data type (the mimeType attribute), just
     a URI, or both a data type and a URI. A URI is specified by separate attributes for each of its parts:

           scheme://host:port/path or pathPrefix or pathPattern

     These attributes are optional, but also mutually dependent: If a scheme is not specified for the intent filter, all the
     other URI attributes are ignored. If a host is not specified for the filer, the port attribute and all the path
     attributes are ignored.

     All the <data> elements contained within the same <intent-filter> element contribute to the same filter. So,
     for example, the following filter specification,

          <intent-filter . . . >
              <data android:scheme="something" android:host="project.example.com" />
              . . .
          </intent-filter>

     is equivalent to this one:

          <intent-filter . . . >
              <data android:scheme="something" />
              <data android:host="project.example.com" />
              . . .
          </intent-filter>

     You can place any number of <data> elements inside an <intent-filter> to give it multiple data options.
     None of its attributes have default values.

     Information on how intent filters work, including the rules for how Intent objects are matched against filters, can be
     found in another document, Intents and Intent Filters. See also the Intent Filters section in the introduction.

ATTRIBUTES:
     android:host
        The host part of a URI authority. This attribute is meaningless unless a scheme attribute is also specified for
        the filter.
http://developer.android.com/guide/topics/manifest/data-element.html                                                Page 1 of 2
<data> | Android Developers                                                                                           29.04.09 0:44


           the filter.

                Note: host name matching in the Android framework is case-sensitive, unlike the formal RFC. As a
                result, you should always specify host names using lowercase letters.

     android:mimeType
        A MIME media type, such as image/jpeg or audio/mpeg4-generic. The subtype can be the asterisk
        wildcard (*) to indicate that any subtype matches.

                Note: MIME type matching in the Android framework is case-sensitive, unlike formal RFC MIME types.
                As a result, you should always specify MIME types using lowercase letters.

     android:path
     android:pathPrefix
     android:pathPattern
        The path part of a URI. The path attribute specifies a complete path that is matched against the complete
        path in an Intent object. The pathPrefix attribute specifies a partial path that is matched against only the
        initial part of the path in the Intent object. The pathPattern attribute specifies a complete path that is
        matched against the complete path in the Intent object, but it can contain the following wildcards:
                 An asterisk ('*') matches a sequence of 0 to many occurrences of the immediately preceding character.
                 A period followed by an asterisk (".*") matches any sequence of 0 to many characters.

           Because '\' is used as an escape character when the string is read from XML (before it is parsed as a
           pattern), you will need to double-escape: For example, a literal '*' would be written as "\\*" and a literal '\'
           would be written as "\\\\". This is basically the same as what you would need to write if constructing the
           string in Java code.

           For more information on these three types of patterns, see the descriptions of PATTERN_LITERAL,
           PATTERN_PREFIX, and PATTERN_SIMPLE_GLOB in the PatternMatcher class.

           These attributes are meaningful only if the scheme and host attributes are also specified for the filter.

     android:port
        The port part of a URI authority. This attribute is meaningful only if the scheme and host attributes are also
        specified for the filter.

     android:scheme
        The scheme part of a URI. This is the minimal essential attribute for specifying a URI; at least one scheme
        attribute must be set for the filter, or none of the other URI attributes are meaningful.

           A scheme is specified without the trailing colon (for example, http, rather than http:).

           If the filter has a data type set (the mimeType attribute) but no scheme, the content: and file: schemes
           are assumed.

                Note: scheme matching in the Android framework is case-sensitive, unlike the RFC. As a result, you
                should always specify schemes using lowercase letters.

INTRODUCED IN:
     API Level 1

SEE ALSO:
     <action>
     <category>

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines



http://developer.android.com/guide/topics/manifest/data-element.html                                                    Page 2 of 2
<grant-uri-permission> | Android Developers                                                                       29.04.09 0:44




<grant-uri-permission>

SYNTAX:


          <grant-uri-permission android:path="string"
                                android:pathPattern="string"
                                android:pathPrefix="string" />


CONTAINED IN:
     <provider>

DESCRIPTION:
     Specifies which data subsets of the parent content provider permission can be granted for. Data subsets are
     indicated by the path part of a content: URI. (The authority part of the URI identifies the content provider.)
     Granting permission is a way of enabling clients of the provider that don't normally have permission to access its
     data to overcome that restriction on a one-time basis.

     If a content provider's grantUriPermissions attribute is "true", permission can be granted for any the data
     under the provider's purview. However, if that attribute is "false", permission can be granted only to data subsets
     that are specified by this element. A provider can contain any number of <grant-uri-permission> elements.
     Each one can specify only one path (only one of the three possible attributes).

     For information on how permission is granted, see the <intent-filter> element's grantUriPermissions
     attribute.

ATTRIBUTES:
     android:path
     android:pathPrefix
     android:pathPattern
        A path identifying the data subset or subsets that permission can be granted for. The path attribute specifies
        a complete path; permission can be granted only to the particular data subset identified by that path. The
        pathPrefix attribute specifies the initial part of a path; permission can be granted to all data subsets with
        paths that share that initial part. The pathPattern attribute specifies a complete path, but one that can
        contain the following wildcards:
                 An asterisk ('*') matches a sequence of 0 to many occurrences of the immediately preceding character.

                 A period followed by an asterisk (".*") matches any sequence of 0 to many characters.

           Because '\' is used as an escape character when the string is read from XML (before it is parsed as a
           pattern), you will need to double-escape: For example, a literal '*' would be written as "\\*" and a literal '\'
           would be written as "\\\\". This is basically the same as what you would need to write if constructing the
           string in Java code.

           For more information on these types of patterns, see the descriptions of PATTERN_LITERAL,
           PATTERN_PREFIX, and PATTERN_SIMPLE_GLOB in the PatternMatcher class.

INTRODUCED IN:
     API Level 1


http://developer.android.com/guide/topics/manifest/grant-uri-permission-element.html                                Page 1 of 2
<grant-uri-permission> | Android Developers                                                                           29.04.09 0:44



SEE ALSO:
     the grantUriPermissions attribute of the <provider> element

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/manifest/grant-uri-permission-element.html                                    Page 2 of 2
<instrumentation> | Android Developers                                                                                             29.04.09 0:44




<instrumentation>

SYNTAX:


          <instrumentation android:functionalTest=["true" | "false"]
                           android:handleProfiling=["true" | "false"]
                           android:icon="drawable resource"
                           android:label="string resource"
                           android:name="string"
                           android:targetPackage="string" />


CONTAINED IN:
     <manifest>

DESCRIPTION:
     Declares an Instrumentation class that enables you to monitor an application's interaction with the system. The
     Instrumentation object is instantiated before any of the application's components.

ATTRIBUTES:
     android:functionalTest
        Whether or not the Instrumentation class should run as a functional test — "true" if it should, and "false" if
        not. The default value is "false".

     android:handleProfiling
        Whether or not the Instrumentation object will turn profiling on and off — "true" if it determines when
        profiling starts and stops, and "false" if profiling continues the entire time it is running. A value of "true"
        enables the object to target profiling at a specific set of operations. The default value is "false".

     android:icon
        An icon that represents the Instrumentation class. This attribute must be set as a reference to a drawable
        resource.

     android:label
        A user-readable label for the Instrumentation class. The label can be set as a raw string or a reference to a
        string resource.

     android:name
        The name of the Instrumentation subclass. This should be a fully qualified class name (such as,
        "com.example.project.StringInstrumentation"). However, as a shorthand, if the first character of
        the name is a period, it is appended to the package name specified in the <manifest> element.

          There is no default. The name must be specified.

     introduced in:
          API Level 1

     android:targetPackage
        The application that the Instrumentation object will run against. An application is identified by the package
        name assigned in its manifest file by the <manifest> element.

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/manifest/instrumentation-element.html                                                      Page 1 of 1
<intent-filter> | Android Developers                                                                              29.04.09 0:44




<intent-filter>

SYNTAX:


           <intent-filter android:icon="drawable resource"
                          android:label="string resource"
                          android:priority="integer" >
               . . .
           </intent-filter>


CONTAINED IN:
     <activity>
     <activity-alias>
     <service>
     <receiver>

MUST CONTAIN:
     <action>

CAN CONTAIN:
     <category>
     <data>

DESCRIPTION:
     Specifies the types of intents that an activity, service, or broadcast receiver can respond to. An intent filter
     declares the capabilities of its parent component — what an activity or service can do and what types of
     broadcasts a receiver can handle. It opens the component to receiving intents of the advertised type, while filtering
     out those that are not meaningful for the component.

     Most of the contents of the filter are described by its <action>, <category>, and <data> subelements.

     For a more detailed discussion of filters, see the separate Intents and Intent Filters document, as well as the
     Intents Filters section in the introduction.

ATTRIBUTES:
     android:icon
        An icon that represents the parent activity, service, or broadcast receiver when that component is presented
        to the user as having the capability described by the filter.

           This attribute must be set as a reference to a drawable resource containing the image definition. The default
           value is the icon set by the parent component's icon attribute. If the parent does not specify an icon, the
           default is the icon set by the <application> element.

           For more on intent filter icons, see Icons and Labels in the introduction.

     android:label
        A user-readable label for the parent component. This label, rather than the one set by the parent component,
        is used when the component is presented to the user as having the capability described by the filter.

           The label should be set as a reference to a string resource, so that it can be localized like other strings in the
           user interface. However, as a convenience while you're developing the application, it can also be set as a raw
http://developer.android.com/guide/topics/manifest/intent-filter-element.html                                        Page 1 of 2
<intent-filter> | Android Developers                                                                                  29.04.09 0:44


           user interface. However, as a convenience while you're developing the application, it can also be set as a raw
           string.

           The default value is the label set by the parent component. If the parent does not specify a label, the default
           is the label set by the <application> element's label attribute.

           For more on intent filter labels, see Icons and Labels in the introduction.

     android:priority
        The priority that should be given to the parent component with regard to handling intents of the type
        described by the filter. This attribute has meaning for both activities and broadcast receivers:
                 It provides information about how able an activity is to respond to an intent that matches the filter, relative
                 to other activities that could also respond to the intent. When an intent could be handled by multiple
                 activities with different priorities, Android will consider only those with higher priority values as potential
                 targets for the intent.

                 It controls the order in which broadcast receivers are executed to receive broadcast messages. Those
                 with higher priority values are called before those with lower values. (The order applies only to
                 synchronous messages; it's ignored for asynchronous messages.)

           Use this attribute only if you really need to impose a specific order in which the broadcasts are received, or
           want to force Android to prefer one activity over others.

           The value must be an integer, such as "100". Higher numbers have a higher priority.

INTRODUCED IN:
     API Level 1

SEE ALSO:
     <action>
     <category>
     <data>

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/manifest/intent-filter-element.html                                           Page 2 of 2
<manifest> | Android Developers                                                                              29.04.09 0:44




<manifest>

SYNTAX:


          <manifest xmlns:android="http://schemas.android.com/apk/res/android"
                    package="string"
                    android:sharedUserId="string"
                    android:sharedUserLabel="string resource"
                    android:versionCode="integer"
                    android:versionName="string" >
              . . .
          </manifest>


CONTAINED IN:
     none

MUST CONTAIN:
     <application>

CAN CONTAIN:
     <instrumentation>
     <permission>
     <permission-group>
     <permission-tree>
     <uses-configuration>
     <uses-permission>


<uses-sdk>

DESCRIPTION:
     The root element of the AndroidManifest.xml file. It must contain an <application> element and specify
     xlmns:android and package attributes.

ATTRIBUTES:
     xmlns:android
        Defines the Android namespace. This attribute should always be set to
        "http://schemas.android.com/apk/res/android".

     package
        A full Java package name for the application. The name should be unique. For example, applications
        published by Google could have names in the form com.google.app.application_name.

           The package name serves as a unique identifier for the application. It's also the default name for the
           application process (see the <application> element's process process attribute) and the default task
           affinity of an activity (see the <activity> element's taskAffinity attribute).

     android:sharedUserId
        The name of a Linux user ID that will be shared with other applications. By default, Android assigns each
        application its own unique user ID. However, if this attribute is set to the same value for two or more
        applications, they will all share the same ID — provided that they are also signed by the same certificate.
http://developer.android.com/guide/topics/manifest/manifest-element.html                                       Page 1 of 2
<manifest> | Android Developers                                                                                       29.04.09 0:44


           applications, they will all share the same ID — provided that they are also signed by the same certificate.
           Application with the same user ID can access each other's data and, if desired, run in the same process.

     android:sharedUserLabel
        A user-readable label for the shared user ID. The label must be set as a reference to a string resource; it
        cannot be a raw string.

           This attribute was introduced in API Level 3. It is meaningful only if the sharedUserId attribute is also set.

     android:versionCode
        An internal version number. This number is used only to determine whether one version is more recent than
        another, with higher numbers indicating more recent versions. This is not the version number shown to users;
        that number is set by the versionName attribute.

           The value must be set as an integer, such as "100". You can define it however you want, as long as each
           successive version has a higher number. For example, it could be a build number. Or you could translate a
           version number in "x.y" format to an integer by encoding the "x" and "y" separately in the lower and upper 16
           bits. Or you could simply increase the number by one each time a new version is released.

     android:versionName
        The version number shown to users. This attribute can be set as a raw string or as a reference to a string
        resource. The string has no other purpose than to be displayed to users. The versionCode attribute holds
        the significant version number used internally.

INTRODUCED IN:
     API Level 1 for all attributes except for sharedUserLabel, which was added in level 3.

SEE ALSO:
     <application>

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/manifest/manifest-element.html                                                Page 2 of 2
<meta-data> | Android Developers                                                                            29.04.09 0:44




<meta-data>

SYNTAX:


          <meta-data android:name="string"
                     android:resource="resource specification"
                     android:value="string" />


CONTAINED IN:
     <activity>
     <activity-alias>
     <service>
     <receiver>

DESCRIPTION:
     A name-value pair for an item of additional, arbitrary data that can be supplied to the parent component. A
     component element can contain any number of <meta-data> subelements. The values from all of them are
     collected in a single Bundle object and made available to the component as the PackageItemInfo.metaData field.

     Ordinary values are specified through the value attribute. However, to assign a resource ID as the value, use the
     resource attribute instead. For example, the following code assigns whatever value is stored in the
     @string/kangaroo resource to the "zoo" name:

          <meta-data android:name="zoo" android:value="@string/kangaroo" />

     On the other hand, using the resource attribute would assign "zoo" the numeric ID of the resource, not the
     value stored in the resource:

          <meta-data android:name="zoo" android:resource="@string/kangaroo" />

     It is highly recommended that you avoid supplying related data as multiple separate <meta-data> entries.
     Instead, if you have complex data to associate with a component, store it as a resource and use the resource
     attribute to inform the component of its ID.

ATTRIBUTES:
     android:name
        A unique name for the item. To ensure that the name is unique, use a Java-style naming convention — for
        example, "com.example.project.activity.fred".

     android:resource
        A reference to a resource. The ID of the resource is the value assigned to the item. The ID can be retrieved
        from the meta-data Bundle by the Bundle.getInt() method.

     android:value
        The value assigned to the item. The data types that can be assigned as values and the Bundle methods that
        components use to retrieve those values are listed in the following table:



http://developer.android.com/guide/topics/manifest/meta-data-element.html                                     Page 1 of 2
<meta-data> | Android Developers                                                                                          29.04.09 0:44


                Type                                                                                                 Bundle
                                                                                                                     method

                String value, using double backslashes (\\) to escape characters — such as "\\n"                     getString()
                and "\\uxxxxx" for a Unicode character.

                Integer value, such as "100"                                                                         getInt()

                Boolean value, either "true" or "false"                                                              getBoolean()

                Color value, in the form "#rgb", "#argb", "#rrggbb", or "#aarrggbb"                                  getString()

                Float value, such as "1.23"                                                                          getFloat()

INTRODUCED IN:
     API Level 1

                                                                                                                         ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/manifest/meta-data-element.html                                                   Page 2 of 2
<permission> | Android Developers                                                                                29.04.09 0:44




<permission>

SYNTAX:


          <permission android:description="string resource"
                      android:icon="drawable resource"
                      android:label="string resource"
                      android:name="string"
                      android:permissionGroup="string"
                      android:protectionLevel=["normal" | "dangerous" |
                                               "signature" | "signatureOrSystem"] />


CONTAINED IN:
     <manifest>

DESCRIPTION:
     Declares a security permission that can be used to limit access to specific components or features of this or other
     applications. See the Permissions section in the introduction, and the Security and Permissions document for
     more information on how permissions work.

ATTRIBUTES:
     android:description
        A user-readable description of the permission, longer and more informative than the label. It may be
        displayed to explain the permission to the user — for example, when the user is asked whether to grant the
        permission to another application.

           This attribute must be set as a reference to a string resource; unlike the label attribute, it cannot be a raw
           string.

     android:icon
        A reference to a drawable resource for an icon that represents the permission.

     android:label
        A name for the permission, one that can be displayed to users.

           As a convenience, the label can be directly set as a raw string while you're developing the application.
           However, when the application is ready to be published, it should be set as a reference to a string resource,
           so that it can be localized like other strings in the user interface.

     android:name
        The name of the permission. This is the name that will be used in code to refer to the permission — for
        example, in a <uses-permission> element and the permission attributes of application components.

           The name must be unique, so it should use Java-style scoping — for example,
           "com.example.project.PERMITTED_ACTION".

     android:permissionGroup
        Assigns this permission to a group. The value of this attribute is the name of the group, which must be
        declared with the <permission-group> element in this or another application. If this attribute is not set,
        the permission does not belong to a group.


http://developer.android.com/guide/topics/manifest/permission-element.html                                         Page 1 of 2
<permission> | Android Developers                                                                                         29.04.09 0:44


     android:protectionLevel
        Characterizes the potential risk implied in the permission and indicates the procedure the system should
        follow when determining whether or not to grant the permission to an application requesting it. The value can
        be set to one of the following strings:

                Value                                 Meaning

                "normal"                              The default value. A lower-risk permission that gives requesting
                                                      applications access to isolated application-level features, with minimal risk
                                                      to other applications, the system, or the user. The system automatically
                                                      grants this type of permission to a requesting application at installation,
                                                      without asking for the user's explicit approval (though the user always has
                                                      the option to review these permissions before installing).

                "dangerous"                           A higher-risk permission that would give a requesting application access
                                                      to private user data or control over the device that can negatively impact
                                                      the user. Because this type of permission introduces potential risk, the
                                                      system may not automatically grant it to the requesting application. For
                                                      example, any dangerous permissions requested by an application may be
                                                      displayed to the user and require confirmation before proceeding, or some
                                                      other approach may be taken to avoid the user automatically allowing the
                                                      use of such facilities.

                "signature"                           A permission that the system grants only if the requesting application is
                                                      signed with the same certificate as the application that declared the
                                                      permission. If the certificates match, the system automatically grants the
                                                      permission without notifying the user or asking for the user's explicit
                                                      approval.

                "signatureOrSystem"                   A permission that the system grants only to applications that are in the
                                                      Android system image or that are signed with the same certificates as
                                                      those in the system image. Please avoid using this option, as the
                                                      signature protection level should be sufficient for most needs and
                                                      works regardless of exactly where applications are installed. The
                                                      "signatureOrSystem" permission is used for certain special situations
                                                      where multiple vendors have applications built into a system image and
                                                      need to share specific features explicitly because they are being built
                                                      together.

INTRODUCED IN:
     API Level 1

SEE ALSO:
     <uses-permission>
     <permission-tree>
     <permission-group>

                                                                                                                         ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/manifest/permission-element.html                                                   Page 2 of 2
<permission-group> | Android Developers                                                                                            29.04.09 0:45




<permission-group>

SYNTAX:


          <permission-group android:description="string resource"
                            android:icon="drawable resource"
                            android:label="string resource"
                            android:name="string" />


CONTAINED IN:
     <manifest>

DESCRIPTION:
     Declares a name for a logical grouping of related permissions. Individual permission join the group through the
     permissionGroup attribute of the <permission> element. Members of a group are presented together in the
     user interface.

     Note that this element does not declare a permission itself, only a category in which permissions can be placed.
     See the <permission> element for element for information on declaring permissions and assigning them to
     groups.

ATTRIBUTES:
     android:description
        User-readable text that describes the group. The text should be longer and more explanatory than the label.
        This attribute must be set as a reference to a string resource. Unlike the label attribute, it cannot be a raw
        string.

     android:icon
        An icon representing the permission. This attribute must be set as a reference to a drawable resource
        containing the image definition.

     android:label
        A user-readable name for the group. As a convenience, the label can be directly set as a raw string while
        you're developing the application. However, when the application is ready to be published, it should be set as
        a reference to a string resource, so that it can be localized like other strings in the user interface.

     android:name
        The name of the group. This is the name that can be assigned to a <permission> element's
        <permissionGroup> attribute.

INTRODUCED IN:
     API Level 1

SEE ALSO:
     <permission>
     <permission-tree>
     <uses-permission>

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/manifest/permission-group-element.html                                                     Page 1 of 1
<permission-tree> | Android Developers                                                                                             29.04.09 0:45




<permission-tree>

SYNTAX:


          <permission-tree android:icon="drawable resource"
                           android:label="string resource" ]
                           android:name="string" />


CONTAINED IN:
     <manifest>

DESCRIPTION:
     Declares the base name for a tree of permissions. The application takes ownership of all names within the tree. It
     can dynamically add new permissions to the tree by calling PackageManager.addPermission(). Names
     within the tree are separated by periods ('.'). For example, if the base name is com.example.project.taxes,
     permissions like the following might be added:

          com.example.project.taxes.CALCULATE
          com.example.project.taxes.deductions.MAKE_SOME_UP
          com.example.project.taxes.deductions.EXAGGERATE

     Note that this element does not declare a permission itself, only a namespace in which further permissions can be
     placed. See the <permission> element for information on declaring permissions.

ATTRIBUTES:
     android:icon
        An icon representing all the permissions in the tree. This attribute must be set as a reference to a drawable
        resource containing the image definition.

     android:label
        A user-readable name for the group. As a convenience, the label can be directly set as a raw string for quick
        and dirty programming. However, when the application is ready to be published, it should be set as a
        reference to a string resource, so that it can be localized like other strings in the user interface.

     android:name
        The name that's at the base of the permission tree. It serves as a prefix to all permission names in the tree.
        Java-style scoping should be used to ensure that the name is unique. The name must have more than two
        period-separated seqments in its path — for example, com.example.base is OK, but com.example is not.

INTRODUCED IN:
     API Level 1

SEE ALSO:
     <permission>
     <permission-group>
     <uses-permission>

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/manifest/permission-tree-element.html                                                      Page 1 of 1
<provider> | Android Developers                                                                                             29.04.09 0:45




<provider>

SYNTAX:


          <provider android:authorities="list"
                    android:enabled=["true" | "false"]
                    android:exported=["true" | "false"]
                    android:grantUriPermissions=["true" | "false"]
                    android:icon="drawable resource"
                    android:initOrder="integer"
                    android:label="string resource"
                    android:multiprocess=["true" | "false"]
                    android:name="string"
                    android:permission="string"
                    android:process="string"
                    android:readPermission="string"
                    android:syncable=["true" | "false"]
                    android:writePermission="string" >
              . . .
          </provider>


CONTAINED IN:
     <application>

CAN CONTAIN:
     <meta-data>
     <grant-uri-permission>

DESCRIPTION:
     Declares a content provider — a subclass of ContentProvider — that supplies structured access to data managed
     by the application. All content providers that are part of the application must be represented by <provider>
     elements in the manifest file. The system cannot see, and therefore will not run, any that are not declared. (You
     need to declare only those content providers that you develop as part of your application, not those developed by
     others that your application uses.)

     The Android system identifies content providers by the authority part of a content: URI. For example, suppose
     that the following URI is passed to ContentResolver.query():

          content://com.example.project.healthcareprovider/nurses/rn

     The content: scheme identifies the data as belonging to a content provider and the authority
     (com.example.project.healthcareprovider) identifies the particular provider. The authority therefore
     must be unique. Typically, as in this example, it's the fully qualified name of a ContentProvider subclass. The path
     part of a URI may be used by a content provider to identify particular data subsets, but those paths are not
     declared in the manifest.

     For information on using and developing content providers, see a separate document, Content Providers.

ATTRIBUTES:
     android:authorities
        A list of one or more URI authorities that identify data under the purview of the content provider. Multiple
        authorities are listed by separating their names with a semicolon. To avoid conflicts, authority names should
        use a Java-style naming convention (such as com.example.provider.cartoonprovider). Typically, it's
        the name of the ContentProvider subclass.

          There is no default. At least one authority must be specified.

     android:enabled

http://developer.android.com/guide/topics/manifest/provider-element.html                                                      Page 1 of 3
<provider> | Android Developers                                                                                                29.04.09 0:45


          Whether or not the content provider can be instantiated by the system — "true" if it can be, and "false" if
          not. The default value is "true".

          The <application> element has its own enabled attribute that applies to all application components,
          including content providers. The <application> and <provider> attributes must both be "true" (as they
          both are by default) for the content provider to be enabled. If either is "false", the provider is disabled; it
          cannot be instantiated.

     android:exported
        Whether or not the content provider can be used by components of other applications — "true" if it can be,
        and "false" if not. If "false", the provider is available only to components of the same application or
        applications with the same user ID. The default value is "true".

          You can export a content provider but still limit access to it with the permission attribute.

     android:grantUriPermissions
        Whether or not those who ordinarily would not have permission to access the content provider's data can be
        granted permission to do so, temporarily overcoming the restriction imposed by the readPermission,
        writePermission, and permission attributes — "true" if permission can be granted, and "{@ code
        false}" if not. If "true", permission can be granted to any of the content provider's data. If "false",
        permission can be granted only to the data subsets listed in <grant-uri-permission> subelements, if
        any. The default value is "false".

          Granting permission is a way of giving an application component one-time access to data protected by a
          permission. For example, when an e-mail message contains an attachment, the mail application may call
          upon the appropriate viewer to open it, even though the viewer doesn't have general permission to look at all
          the content provider's data.

          In such cases, permission is granted by FLAG_GRANT_READ_URI_PERMISSION and
          FLAG_GRANT_WRITE_URI_PERMISSION flags in the Intent object that activates the component. For
          example, the mail application might put FLAG_GRANT_READ_URI_PERMISSION in the Intent passed to
          Context.startActivity(). The permission is specific to the URI in the Intent.

          If you enable this feature, either by setting this attribute to "true" or by defining <grant-uri-
          permission> subelements, you must call Context.revokeUriPermission() when a covered URI is
          deleted from the provider.

          See also the <grant-uri-permission> element.

     android:icon
        An icon representing the content provider. This attribute must be set as a reference to a drawable resource
        containing the image definition. If it is not set, the icon specified for the application as a whole is used instead
        (see the <application> element's icon attribute).

     android:initOrder
        The order in which the content provider should be instantiated, relative to other content providers hosted by
        the same process. When there are dependencies among content providers, setting this attribute for each of
        them ensures that they are created in the order required by those dependencies. The value is a simple
        integer, with higher numbers being initialized first.

     android:label
        A user-readable label for the content provided. If this attribute is not set, the label set for the application as a
        whole is used instead (see the <application> element's label attribute).

          The label should be set as a reference to a string resource, so that it can be localized like other strings in the
          user interface. However, as a convenience while you're developing the application, it can also be set as a raw
          string.

     android:multiprocess
        Whether or not an instance of the content provider can be created in every client process — "true" if
        instances can run in multiple processes, and "false" if not. The default value is "false".

          Normally, a content provider is instantiated in the process of the application that defined it. However, if this
          flag is set to "true", the system can create an instance in every process where there's a client that wants to
          interact withit, thus avoiding the overhead of interprocess communication.


http://developer.android.com/guide/topics/manifest/provider-element.html                                                         Page 2 of 3
<provider> | Android Developers                                                                                                    29.04.09 0:45


     android:name
        The name of the class that implements the content provider, a subclass of ContentProvider. This should be a
        fully qualified class name (such as, "com.example.project.TransportationProvider"). However, as
        a shorthand, if the first character of the name is a period, it is appended to the package name specified in the
        <manifest> element.

          There is no default. The name must be specified.

     android:permission
        The name of a permission that clients must have to read or write the content provider's data. This attribute is
        a convenient way of setting a single permission for both reading and writing. However, the readPermission
        and writePermission attributes take precedence over this one. If the readPermission attribute is also
        set, it controls access for querying the content provider. And if the writePermission attribute is set, it
        controls access for modifying the provider's data.

          For more information on permissions, see the Permissions section in the introduction and a separate
          document, Security and Permissions.

     android:process
        The name of the process in which the content provider should run. Normally, all components of an application
        run in the default process created for the application. It has the same name as the application package. The
        <application> element's process attribute can set a different default for all components. But each
        component can override the default with its own process attribute, allowing you to spread your application
        across multiple processes.

          If the name assigned to this attribute begins with a colon (':'), a new process, private to the application, is
          created when it's needed and the activity runs in that process. If the process name begins with a lowercase
          character, the activity will run in a global process of that name, provided that it has permission to do so. This
          allows components in different applications to share a process, reducing resource usage.

     android:readPermission
        A permission that clients must have to query the content provider. See also the permission and
        writePermission attributes.

     android:syncable
        Whether or not the data under the content provider's control is to be synchronized with data on a server —
        "true" if it is to be synchronized, and "{@ code false}" if not.

     android:writePermission
        A permission that clients must have to make changes to the data controlled by the content provider. See also
        the permission and readPermission attributes.

INTRODUCED IN:
     API Level 1

SEE ALSO:
     Content Providers

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/manifest/provider-element.html                                                             Page 3 of 3
<receiver> | Android Developers                                                                                   29.04.09 0:45




<receiver>

SYNTAX:


           <receiver android:enabled=["true" | "false"]
                     android:exported=["true" | "false"]
                     android:icon="drawable resource"
                     android:label="string resource"
                     android:name="string"
                     android:permission="string"
                     android:process="string" >
               . . .
           </receiver>


CONTAINED IN:
     <application>

CAN CONTAIN:
     <intent-filer>
     <meta-data>

DESCRIPTION:
     Declares a broadcast receiver (a BroadcastReceiver subclass) as one of the application's components. Broadcast
     receivers enable applications to receive intents that are broadcast by the system or by other applications, even
     when other components of the application are not running.

     There are two ways to make a broadcast receiver known to the system: One is declare it in the manifest file with
     this element. The other is to create the receiver dynamically in code and register it with the
     Context.registerReceiver() method. See the BroadcastReceiver class description for more on dynamically
     created receivers.

ATTRIBUTES:
     android:enabled
        Whether or not the broadcast receiver can be instantiated by the system — "true" if it can be, and "false"
        if not. The default value is "true".

           The <application> element has its own enabled attribute that applies to all application components,
           including broadcast receivers. The <application> and <receiver> attributes must both be "true" for
           the broadcast receiver to be enabled. If either is "false", it is disabled; it cannot be instantiated.

     android:exported
        Whether or not the broadcast receiver can receive messages from sources outside its application — "true" if
        it can, and "false" if not. If "false", the only messages the broadcast receiver can receive are those sent
        by components of the same application or applications with the same user ID.

           The default value depends on whether the broadcast receiver contains intent filters. The absence of any
           filters means that it can be invoked only by Intent objects that specify its exact class name. This implies that
           the receiver is intended only for application-internal use (since others would not normally know the class
           name). So in this case, the default value is "false". On the other hand, the presence of at least one filter
           implies that the broadcast receiver is intended to receive intents broadcast by the system or other
           applications, so the default value is "true".

http://developer.android.com/guide/topics/manifest/receiver-element.html                                            Page 1 of 2
<receiver> | Android Developers                                                                                       29.04.09 0:45




           This attribute is not the only way to limit a broadcast receiver's external exposure. You can also use a
           permission to limit the external entities that can send it messages (see the permission attribute).

     android:icon
        An icon representing the broadcast receiver. This attribute must be set as a reference to a drawable resource
        containing the image definition. If it is not set, the icon specified for the application as a whole is used instead
        (see the <application> element's icon attribute).

           The broadcast receiver's icon — whether set here or by the <application> element — is also the default
           icon for all the receiver's intent filters (see the <intent-filter> element's icon attribute).

     android:label
        A user-readable label for the broadcast receiver. If this attribute is not set, the label set for the application as
        a whole is used instead (see the <application> element's label attribute).

           The broadcast receiver's label — whether set here or by the <application> element — is also the default
           label for all the receiver's intent filters (see the <intent-filter> element's label attribute).

           The label should be set as a reference to a string resource, so that it can be localized like other strings in the
           user interface. However, as a convenience while you're developing the application, it can also be set as a raw
           string.

     android:name
        The name of the class that implements the broadcast receiver, a subclass of BroadcastReceiver. This should
        be a fully qualified class name (such as, "com.example.project.ReportReceiver"). However, as a
        shorthand, if the first character of the name is a period (for example, ". ReportReceiver"), it is appended
        to the package name specified in the <manifest> element.

           There is no default. The name must be specified.

     android:permission
        The name of a permission that broadcasters must have to send a message to the broadcast receiver. If this
        attribute is not set, the permission set by the <application> element's permission attribute applies to
        the broadcast receiver. If neither attribute is set, the receiver is not protected by a permission.

           For more information on permissions, see the Permissions section in the introduction and a separate
           document, Security and Permissions.

     android:process
        The name of the process in which the broadcast receiver should run. Normally, all components of an
        application run in the default process created for the application. It has the same name as the application
        package. The <application> element's process attribute can set a different default for all components.
        But each component can override the default with its own process attribute, allowing you to spread your
        application across multiple processes.

           If the name assigned to this attribute begins with a colon (':'), a new process, private to the application, is
           created when it's needed and the broadcast receiver runs in that process. If the process name begins with a
           lowercase character, the receiver will run in a global process of that name, provided that it has permission to
           do so. This allows components in different applications to share a process, reducing resource usage.

INTRODUCED IN:
     API Level 1

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/manifest/receiver-element.html                                                Page 2 of 2
<service> | Android Developers                                                                                                 29.04.09 0:45




<service>

SYNTAX:


          <service android:enabled=["true" | "false"]
                    android:exported[="true" | "false"]
                    android:icon="drawable resource"
                    android:label="string resource"
                    android:name="string"
                    android:permission="string"
                    android:process="string" >
              . . .
          </service>


CONTAINED IN:
     <application>

CAN CONTAIN:
     <intent-filer>
     <meta-data>

DESCRIPTION:
     Declares a service (a Service subclass) as one of the application's components. Unlike activities, services lack a
     visual user interface. They're used to implement long-running background operations or a rich communications API
     that can be called by other applications.

     All services must be represented by <service> elements in the manifest file. Any that are not declared there will
     not be seen by the system and will never be run.

ATTRIBUTES:
     android:enabled
        Whether or not the service can be instantiated by the system — "true" if it can be, and "false" if not. The
        default value is "true".

          The <application> element has its own enabled attribute that applies to all application components,
          including services. The <application> and <service> attributes must both be "true" (as they both are
          by default) for the service to be enabled. If either is "false", the service is disabled; it cannot be
          instantiated.

     android:exported
        Whether or not components of other applications can invoke the service or interact with it — "true" if they
        can, and "false" if not. When the value is "false", only components of the same application or applications
        with the same user ID can start the service or bind to it.

          The default value depends on whether the service contains intent filters. The absence of any filters means
          that it can be invoked only by specifying its exact class name. This implies that the service is intended only for
          application-internal use (since others would not know the class name). So in this case, the default value is
          "false". On the other hand, the presence of at least one filter implies that the service is intended for external
          use, so the default value is "true".

          This attribute is not the only way to limit the exposure of a service to other applications. You can also use a
          permission to limit the external entities that can interact with the service (see the permission attribute).

     android:icon
        An icon representing the service. This attribute must be set as a reference to a drawable resource containing
        the image definition. If it is not set, the icon specified for the application as a whole is used instead (see the
        <application> element's icon attribute).

http://developer.android.com/guide/topics/manifest/service-element.html                                                          Page 1 of 2
<service> | Android Developers                                                                                                     29.04.09 0:45




          The service's icon — whether set here or by the <application> element — is also the default icon for all
          the service's intent filters (see the <intent-filter> element's icon attribute).

     android:label
        A name for the service that can be displayed to users. If this attribute is not set, the label set for the
        application as a whole is used instead (see the <application> element's label attribute).

          The service's label — whether set here or by the <application> element — is also the default label for all
          the service's intent filters (see the <intent-filter> element's label attribute).

          The label should be set as a reference to a string resource, so that it can be localized like other strings in the
          user interface. However, as a convenience while you're developing the application, it can also be set as a raw
          string.

     android:name
        The name of the Service subclass that implements the service. This should be a fully qualified class name
        (such as, "com.example.project.RoomService"). However, as a shorthand, if the first character of the
        name is a period (for example, ".RoomService"), it is appended to the package name specified in the
        <manifest> element.

          There is no default. The name must be specified.

     android:permission
        The name of a permission that that an entity must have in order to launch the service or bind to it. If a caller
        of startService(), bindService(), or stopService(), has not been granted this permission, the
        method will not work and the Intent object will not be delivered to the service.

          If this attribute is not set, the permission set by the <application> element's permission attribute
          applies to the service. If neither attribute is set, the service is not protected by a permission.

          For more information on permissions, see the Permissions section in the introduction and a separate
          document, Security and Permissions.

     android:process
        The name of the process where the service is to run. Normally, all components of an application run in the
        default process created for the application. It has the same name as the application package. The
        <application> element's process attribute can set a different default for all components. But component
        can override the default with its own process attribute, allowing you to spread your application across
        multiple processes.

          If the name assigned to this attribute begins with a colon (':'), a new process, private to the application, is
          created when it's needed and the service runs in that process. If the process name begins with a lowercase
          character, the service will run in a global process of that name, provided that it has permission to do so. This
          allows components in different applications to share a process, reducing resource usage.

SEE ALSO:
     <application>
     <activity>

INTRODUCED IN:
     API Level 1

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/manifest/service-element.html                                                              Page 2 of 2
<uses-configuration> | Android Developers                                                                                          29.04.09 0:45




<uses-configuration>

SYNTAX:


          <uses-configuration android:reqFiveWayNav=["true" | "false"]
                              android:reqHardKeyboard=["true" | "false"]
                              android:reqKeyboardType=["undefined" | "nokeys" | "qwerty"
          |
                                                       "twelvekey"]
                              android:reqNavigation=["undefined" | "nonav" | "dpad" |
                                                     "trackball" | "wheel"]
                              android:reqTouchScreen=["undefined" | "notouch" | "stylus"
          |
                                                      "finger"] />


CONTAINED IN:
     <manifest>

DESCRIPTION:
     Indicates what hardware and software features the application requires. For example, an application might specify
     that it requires a physical keyboard or a particular navigation device, like a trackball. The specification is used to
     avoid installing the application on devices where it will not work.

     If an application can work with different device configurations, it should include separate <uses-
     configuration> declarations for each one. Each declaration must be complete. For example, if an application
     requires a five-way navigation control, a touch screen that can be operated with a finger, and either a standard
     QWERTY keyboard or a numeric 12-key keypad like those found on most phones, it would specify these
     requirements with two <uses-configuration> elements as follows:

          <uses-configuration android:reqFiveWayNav="true"
          android:reqTouchScreen="finger"
                              android:reqKeyboardType="qwerty" />
          <uses-configuration android:reqFiveWayNav="true"
          android:reqTouchScreen="finger"
                              android:reqKeyboardType="twelvekey" />


ATTRIBUTES:
     android:reqFiveWayNav
        Whether or not the application requires a five-way navigation control — "true" if it does, and "false" if not.
        A five-way control is one that can move the selection up, down, right, or left, and also provides a way of
        invoking the current selection. It could be a D-pad (directional pad), trackball, or other device.

          If an application requires a directional control, but not a control of a particular type, it can set this attribute to
          "true" and ignore the reqNavigation attribute. However, if it requires a particular type of directional
          control, it can ignore this attribute and set reqNavigation instead.

     android:reqHardKeyboard
        Whether or not the application requires a hardware keyboard — "true" if it does, and "false" if not.

     android:reqKeyboardType
        The type of keyboard the application requires, if any at all. This attribute does not distinguish between
        hardware and software keyboards. If a hardware keyboard of a certain type is required, specify the type here
        and also set the reqHardKeyboard attribute to "true".

          The value must be one of the following strings:




http://developer.android.com/guide/topics/manifest/uses-configuration-element.html                                                   Page 1 of 2
<uses-configuration> | Android Developers                                                                                          29.04.09 0:45


               Value                 Description

               "undefined"           The application does not require a keyboard. (A keyboard requirement is not
                                     defined.) This is the default value.

               "nokeys"              The application does not require a keyboard.

               "qwerty"              The application requires a standard QWERTY keyboard.

               "twelvekey"           The application requires a twelve-key keypad, like those on most phones — with
                                     keys for the digits from 0 through 9 plus star (*) and pound (#) keys.

     android:reqNavigation
        The navigation device required by the application, if any. The value must be one of the following strings:

               Value                 Description

               "undefined"           The application does not require any type of navigation control. (The navigation
                                     requirement is not defined.) This is the default value.

               "nonav"               The application does not require a navigation control.

               "dpad"                The application requires a D-pad (directional pad) for navigation.

               "trackball"           The application requires a trackball for navigation.

               "wheel"               The application requires a navigation wheel.

          If an application requires a navigational control, but the exact type of control doesn't matter, it can set the
          reqFiveWayNav attribute to "true" rather than set this one.

     android:reqTouchScreen
        The type of touch screen the application requires, if any at all. The value must be one of the following strings:

               Value                 Description

               "undefined"           The application doesn't require a touch screen. (The touch screen requirement is
                                     undefined.) This is the default value.

               "notouch"             The application doesn't require a touch screen.

               "stylus"              The application requires a touch screen that's operated with a stylus.

               "finger"              The application requires a touch screen that can be operated with a finger.


INTRODUCED IN:
     API Level 3

SEE ALSO:
     configChanges attribute of the <activity> element

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/manifest/uses-configuration-element.html                                                   Page 2 of 2
<uses-library> | Android Developers                                                                                   29.04.09 0:45




<uses-library>

SYNTAX:


           <uses-library android:name="string" />


CONTAINED IN:
     <application>

DESCRIPTION:
     Specifies a shared library that the application must be linked against. This element tells the system to include the
     library's code in the class loader for the package.

     All of the android packages (such as android.app, android.content, android.view, and android.widget) are in the
     default library that all applications are automatically linked against. However, some packages (such as maps and
     awt are in separate libraries that are not automatically linked. Consult the documentation for the packages you're
     using to determine which library contains the package code.

ATTRIBUTES:
     android:name
        The name of the library.

INTRODUCED IN:
     API Level 1

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/manifest/uses-library-element.html                                            Page 1 of 1
<uses-permission> | Android Developers                                                                                29.04.09 0:46




<uses-permission>

SYNTAX:


          <uses-permission android:name="string" />


CONTAINED IN:
     <manifest>

DESCRIPTION:
     Requests a permission that the application must be granted in order for it to operate correctly. Permissions are
     granted when the application is installed, not while it's running.

     For more information on permissions, see the Permissions section in the introduction and the separate Security
     and Permissions document. A list of permissions defined by the base platform can be found at
     android.Manifest.permission.

ATTRIBUTES:
     android:name
        The name of the permission. It can be a permission defined by the application with the <permission>
        element, a permission defined by another application, or one of the standard system permissions, such as
        "android.permission.CAMERA" or "android.permission.READ_CONTACTS". As these examples
        show, a permission name typically includes the package name as a prefix.

INTRODUCED IN:
     API Level 1

SEE ALSO:
     <permission>

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/manifest/uses-permission-element.html                                         Page 1 of 1
<uses-sdk> | Android Developers                                                                                       29.04.09 0:46




<uses-sdk>

SYNTAX:


          <uses-sdk android:minSdkVersion="integer" />


CONTAINED IN:
     <manifest>

DESCRIPTION:
     Lets you express an application's compatibility with one or more versions of the Android platform, by means of an
     API Level integer. The API Level expressed by an application will be compared to the API Level of a given
     Android system, which may vary among different Android devices. To declare your application's minimum API
     Level compatibility, use the minSdkVersion attribute.

     The default level is 1.

     For more information on the API level, see the Specifying Minimum System API Version section of Versioning
     Your Applications.

ATTRIBUTES:
     android:minSdkVersion
        An integer designating the minimum level of the Android API that's required for the application to run.

           Despite its name, this attribute specifies the API Level, not the version number of the SDK (software
           development kit). The API Level is always a single integer; the SDK version may be split into major and minor
           components (such as 1.5). You cannot derive the API Level from the SDK version number (for example, it is
           not the same as the major version or the sum of the major and minor versions). To learn what the API Level
           is, check the notes that came with the SDK you're using.

           Prior to installing an application, the Android system checks the value of this attribute and allows the
           installation only if the API Level is less than or equal to the API Level used by the system itself.

           If you do not declare this attribute, then a value of "1" is assumed, which indicates that your application is
           compatible with all versions of Android. If your application is not universally compatible (for instance if it uses
           APIs introduced in Android 1.5) and you have not declared the proper minSdkVersion, then when installed
           on a system with a lower API Level, the application will crash during runtime. For this reason, be certain to
           declare the appropriate API Level in the minSdkVersion attribute.

INTRODUCED IN:
     API Level 1

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/manifest/uses-sdk-element.html                                                Page 1 of 1
Graphics | Android Developers                                                                                  29.04.09 0:49




Graphics

Android graphics are powered by a custom 2D graphics library and OpenGL ES 1.0 for high performance 3D graphics.
The most common 2D graphics APIs can be found in the drawable package. OpenGL APIs are available from the
Khronos OpenGL ES package, plus some Android OpenGL utilities.

When starting a project, it's important to consider exactly what your graphical demands will be. Varying graphical tasks
are best accomplished with varying techniques. For example, graphics and animations for a rather static application
should be implemented much differently than graphics and animations for an interactive game or 3D rendering.

Here, we'll discuss a few of the options you have for drawing graphics on Android, and which tasks they're best suited
for.

If you're specifically looking for information on drawing 3D graphics, this page won't help a lot. However, the
information below, on Drawing with a Canvas (and the section on SurfaceView), will give you a quick idea of how you
should draw to the View hierarchy. For more information on Android's 3D graphic utilities (provided by the OpenGL ES
API), read 3D with OpenGL and refer to other OpenGL documentation.



Consider your Options
When drawing 2D graphics, you'll typically do so in one of two ways:

 a. Draw your graphics or animations into a View object from your layout. In this manner, the drawing (and any
    animation) of your graphics is handled by the system's normal View hierarchy drawing process — you simply
    define the graphics to go inside the View.
 b. Draw your graphics directly to a Canvas. This way, you personally call the appropriate class's draw() method
    (passing it your Canvas), or one of the Canvas draw...() methods (like drawPicture()). In doing so, you are
    also in control of any animation.

Option "a," drawing to a View, is your best choice when you want to draw simple graphics that do not need to change
dynamically and are not part of a performance-intensive game. For example, you should draw your graphics into a
View when you want to display a static graphic or predefined animation, within an otherwise static application. Read
Simple Graphics Inside a View.

Option "b," drawing to a Canvas, is better when you're application needs to regularly re-draw itself. Basically, any
video game should be drawing to the Canvas on its own. However, there's more than one way to do this:

     In the same thread as your UI Activity, wherein you create a custom View component in your layout, call
     invalidate() and then handle the onDraw() callback..
     Or, in a separate thread, wherein you manage a SurfaceView and perform draws to the Canvas as fast as your
     thread is capable (you do not need to request invalidate()).

...Begin by reading Draw with a Canvas.



Simple Graphics Inside a View


http://developer.android.com/guide/topics/graphics/index.html                                                    Page 1 of 3
Graphics | Android Developers                                                                                  29.04.09 0:49


If you'll be drawing some simple graphics (images, shapes, colors, pre-defined animations, etc.), then you should
probably just draw to the background of a View or to the content of an ImageView in your layout. In this case, you can
skip the rest of this document and learn how to draw graphics and animations in the 2D Graphics document.



Draw with a Canvas
When you're writing an application in which you would like to perform specialized drawing and/or control the animation
of graphics, you should do so by drawing through a Canvas. A Canvas works for you as a pretense, or interface, to
the actual surface upon which your graphics will be drawn — it holds all of your "draw" calls. Via the Canvas, your
drawing is actually performed upon an underlying Bitmap, which is placed into the window.

In the event that you're drawing within the onDraw() callback method, the Canvas is provided for you and you need
only place your drawing calls upon it. You can also acquire a Canvas from SurfaceHolder.lockCanvas(), when
dealing with a SurfaceView object. (Both of these scenarios are discussed in the following sections.) However, if you
need to create a new Canvas, then you must define the Bitmap upon which drawing will actually be performed. The
Bitmap is always required for a Canvas. You can set up a new Canvas like this:

     Bitmap b = Bitmap.createBitmap(100, 100, Bitmap.Config.ARGB_8888);
     Canvas c = new Canvas(b);

Now your Canvas will draw onto the defined Bitmap. After drawing upon it with the Canvas, you can then carry your
Bitmap to another Canvas with one of the Canvas.drawBitmap(Bitmap,...) methods. It's recommended that
you ultimately draw your final graphics through a Canvas offered to you by View.onDraw() or
SurfaceHolder.lockCanvas() (see the following sections).

The Canvas class has its own set of drawing methods that you can use, like drawBitmap(...), drawRect(...),
drawText(...), and many more. Other classes that you might use also have draw() methods. For example, you'll
probably have some Drawable objects that you want to put on the Canvas. Drawable has its own draw() method that
takes your Canvas as an arguement.


On a View
If you're application does not require a significant amount of processing or frame-rate speed (perhaps for a chess
game, a snake game, or another slowly-animated application), then you should consider creating a custom View
component and drawing with a Canvas in View.onDraw(). The most convenient aspect of doing so is that the
Android framework will provide you with a pre-defined Canvas to which you will place your drawing calls.

To start, extend the View class (or descendent thereof) and define the onDraw() callback method. This method will
be called by the Android framework to request that your View draw itself. This is where you will perform all your calls
to draw through the Canvas, which is passed to you through the onDraw() callback.

The Android framework will only call onDraw() as necessary. Each time that your application is prepared to be
drawn, you must request your View be invalidated by calling invalidate(). This indicates that you'd like your View
to be drawn and Android will then call your onDraw() method (though is not guaranteed that the callback will be
instantaneous).

Inside your View component's onDraw(), use the Canvas given to you for all your drawing, using various
Canvas.draw...() methods, or other class draw() methods that take your Canvas as an argument. Once your
onDraw() is complete, the Android framework will use your Canvas to draw a Bitmap handled by the system.

     Note: In order to request an invalidate from a thread other than your main Activity's thread, you must call
     postInvalidate().

Also read Building Custom Components for a guide to extending a View class, and 2D Graphics: Drawables for
information on using Drawable objects like images from your resources and other primitive shapes.


http://developer.android.com/guide/topics/graphics/index.html                                                      Page 2 of 3
Graphics | Android Developers                                                                                         29.04.09 0:49


For a sample application, see the Snake game, in the SDK samples folder: <your-sdk-
directory>/samples/Snake/.


On a SurfaceView
The SurfaceView is a special subclass of View that offers a dedicated drawing surface within the View hierarchy. The
aim is to offer this drawing surface to an application's secondary thread, so that the application isn't required to wait
until the system's View hierarchy is ready to draw. Instead, a secondary thread that has reference to a SurfaceView
can draw to its own Canvas at its own pace.

To begin, you need to create a new class that extends SurfaceView. The class should also implement
SurfaceHolder.Callback. This subclass is an interface that will notify you with information about the underlying Surface,
such as when it is created, changed, or destroyed. These events are important so that you know when you can start
drawing, whether you need to make adjustments based on new surface properties, and when to stop drawing and
potentially kill some tasks. Inside your SurfaceView class is also a good place to define your secondary Thread class,
which will perform all the drawing procedures to your Canvas.

Instead of handling the Surface object directly, you should handle it via a SurfaceHolder. So, when your SurfaceView
is initialized, get the SurfaceHolder by calling getHolder(). You should then notify the SurfaceHolder that you'd like
to receive SurfaceHolder callbacks (from SurfaceHolder.Callback) by calling addCallback() (pass it this). Then override
each of the SurfaceHolder.Callback methods inside your SurfaceView class.

In order to draw to the Surface Canvas from within your second thread, you must pass the thread your SurfaceHandler
and retrieve the Canvas with lockCanvas(). You can now take the Canvas given to you by the SurfaceHolder and
do your necessary drawing upon it. Once you're done drawing with the Canvas, call unlockCanvasAndPost(),
passing it your Canvas object. The Surface will now draw the Canvas as you left it. Perform this sequence of locking
and unlocking the canvas each time you want to redraw.

     Note: On each pass you retrieve the Canvas from the SurfaceHolder, the previous state of the Canvas will be
     retained. In order to properly animate your graphics, you must re-paint the entire surface. For example, you can
     clear the previous state of the Canvas by filling in a color with drawColor() or setting a background image
     with drawBitmap(). Otherwise, you will see traces of the drawings you previously performed.

For a sample application, see the Lunar Landar game, in the SDK samples folder: <your-sdk-
directory>/samples/LunarLander/. Or, browse the source in the Sample Code section.

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/graphics/index.html                                                           Page 3 of 3
2D Graphics | Android Developers                                                                                  29.04.09 0:49




2D and 3D Graphics >

2D Graphics

Android offers a custom 2D graphics library for drawing and animating shapes and images. The
android.graphics.drawable and android.view.animation packages are where you'll find the common classes used for
drawing and animating in two-dimensions.

This document offers an introduction to drawing graphics in your Android application. We'll discuss the basics of using
Drawable objects to draw graphics, how to use a couple subclasses of the Drawable class, and how to create
animations that either tween (move, stretch, rotate) a single graphic or animate a series of graphics (like a roll of film).



Drawables
A Drawable is a general abstraction for "something that can be drawn." You'll discover that the Drawable class extends
to define a variety of specific kinds of drawable graphics, including BitmapDrawable, ShapeDrawable, PictureDrawable,
LayerDrawable, and several more. Of course, you can also extend these to define your own custom Drawable objects
that behave in unique ways.

There are three ways to define and instantiate a Drawable: using an image saved in your project resouces; using an
XML file that defines the Drawable properties; or using the normal class constructors. Below, we'll discuss each the
first two techniques (using constructors is nothing new for an experienced developer).


Creating from resource images
A simple way to add graphics to your application is by referencing an image file from your project resources.
Supported file types are PNG (preferred), JPG (acceptable) and GIF (discouraged). This technique would obviously be
preferred for application icons, logos, or other graphics such as those used in a game.

To use an image resource, just add your file to the res/drawable/ directory of your project. From there, you can
reference it from your code or your XML layout. Either way, it is referred using a resource ID, which is the file name
without the file type extension (E.g., my_image.png is referenced as my_image).

Example code
The following code snippet demonstrates how to build an ImageView that uses an image from drawable resources and
add it to the layout.

     LinearLayout mLinearLayout;
     protected void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
            // Create a LinearLayout in which to add the ImageView
            mLinearLayout = new LinearLayout(this);
         // Instantiate an ImageView and define its properties
         ImageView i = new ImageView(this);
         i.setImageResource(R.drawable.my_image);
         i.setAdjustViewBounds(true); // set the ImageView bounds to match the
     Drawable's dimensions
         i.setLayoutParams(new Gallery.LayoutParams(LayoutParams.WRAP_CONTENT,
     LayoutParams.WRAP_CONTENT));

http://developer.android.com/guide/topics/graphics/2d-graphics.html                                                 Page 1 of 8
2D Graphics | Android Developers                                                                              29.04.09 0:49

     LayoutParams.WRAP_CONTENT));

            // Add the ImageView to the layout and set the layout as the content view
            mLinearLayout.addView(i);
            setContentView(mLinearLayout);
     }

In other cases, you may want to handle your image resource as a Drawable object. To do so, create a Drawable from
the resource like so:

     Resources res = mContext.getResources();
     Drawable myImage = res.getDrawable(R.drawable.my_image);

     Caution: Each unique resource in your project can maintain only one state, no matter how many different
     objects you may instantiate for it. For example, if you instantiate two Drawable objects from the same image
     resource, then change a property (such as the alpha) for one of the Drawables, then it will also affect the other.
     So when dealing with multiple instances of an image resource, instead of directly transforming the Drawable, you
     should perform a tween animation.

Example XML
The XML snippet below shows how to add a resource Drawable to an ImageView in the XML layout (with some red tint
just for fun).

     <ImageView
       android:layout_width="wrap_content"
       android:layout_height="wrap_content"
       android:tint="#55ff0000"
       android:src="@drawable/my_image"/>

For more information on using project resources, read about Resources and Assets.


Creating from resource XML
By now, you should be familiar with Android's principles of developing a User Interface. Hence, you understand the
power and flexibility inherent in defining objects in XML. This philosophy caries over from Views to Drawables. If there
is a Drawable object that you'd like to create, which is not initially dependent on variables defined by your applicaton
code or user interaction, then defining the Drawable in XML is a good option. Even if you expect your Drawable to
change its properties during the user's experience with your application, you should consider defining the object in
XML, as you can always modify properties once it is instantiated.

Once you've defined your Drawable in XML, save the file in the res/drawable/ directory of your project. Then,
retrieve and instantiate the object by calling Resources.getDrawable(), passing it the resource ID of your XML file. (See
the example below.)

Any Drawable subclass that supports the inflate() method can be defined in XML and instantiated by your
application. Each Drawable that supports XML inflation utilizes specific XML attributes that help define the object
properties (see the class reference to see what these are). See the class documentation for each Drawable subclass
for information on how to define it in XML.

Example
Here's some XML that defines a TransitionDrawable:

     <transition xmlns:android="http://schemas.android.com/apk/res/android">
       <item android:drawable="@drawable/image_expand">
       <item android:drawable="@drawable/image_collapse">
     </transition>



http://developer.android.com/guide/topics/graphics/2d-graphics.html                                              Page 2 of 8
2D Graphics | Android Developers                                                                           29.04.09 0:49


With this XML saved in the file res/drawable/expand_collapse.xml, the following code will instantiate the
TransitionDrawable and set it as the content of an ImageView:


     Resources res = mContext.getResources();
     TransitionDrawable transition = (TransitionDrawable)
     res.getDrawable(R.drawable.expand_collapse);
     ImageView image = (ImageView) findViewById(R.id.toggle_image);
     image.setImageDrawable(transition);

Then this transition can be run forward (for 1 second) with:


     transition.startTransition(1000);

Refer to the Drawable classes listed above for more information on the XML attributes supported by each.



ShapeDrawable
When you want to dynamically draw some two-dimensional graphics, a ShapeDrawable object will probably suit your
needs. With a ShapeDrawable, you can programmatically draw primitive shapes and style them in any way imaginable.

A ShapeDrawable is an extension of Drawable, so you can use one where ever a Drawable is expected — perhaps for
the background of a View, set with setBackgroundDrawable(). Of course, you can also draw your shape as its own
custom View, to be added to your layout however you please. Because the ShapeDrawable has its own draw()
method, you can create a subclass of View that draws the ShapeDrawable during the View.onDraw() method.
Here's a basic extension of the View class that does just this, to draw a ShapeDrawable as a View:


     public class CustomDrawableView extends View {
         private ShapeDrawable mDrawable;

            public CustomDrawableView(Context context) {
                super(context);

                   int    x = 10;
                   int    y = 10;
                   int    width = 300;
                   int    height = 50;

                   mDrawable = new ShapeDrawable(new OvalShape());
                   mDrawable.getPaint().setColor(0xff74AC23);
                   mDrawable.setBounds(x, y, x + width, y + height);
            }
            protected void onDraw(Canvas canvas) {
                mDrawable.draw(canvas);
            }
     }

In the constructor, a ShapeDrawable is defines as an OvalShape. It's then given a color and the bounds of the shape
are set. If you do not set the bounds, then the shape will not be drawn, whereas if you don't set the color, it will
default to black.

With the custom View defined, it can be drawn any way you like. With the sample above, we can draw the shape
progammatically in an Activity:


     CustomDrawableView mCustomDrawableView;
     protected void onCreate(Bundle savedInstanceState) {


http://developer.android.com/guide/topics/graphics/2d-graphics.html                                          Page 3 of 8
2D Graphics | Android Developers                                                                                  29.04.09 0:49

     protected void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
         mCustomDrawableView = new CustomDrawableView(this);

            setContentView(mCustomDrawableView);
     }

If you'd like to draw this custom drawable from the XML layout instead of from the Activity, then the CustomDrawable
class must override the View(Context, AttributeSet) constructor, which is called when instantiating a View via inflation
from XML. Then add a CustomDrawable element to the XML, like so:

     <com.example.shapedrawable.CustomDrawableView
         android:layout_width="fill_parent"
         android:layout_height="wrap_content"
         />

The ShapeDrawable class (like many other Drawable types in the android.graphics.drawable package) allows you to
define various properties of the drawable with public methods. Some properties you might want to adjust include alpha
transparency, color filter, dither, opacity and color.



NinePatchDrawable
A NinePatchDrawable graphic is a stretchable bitmap image, which Android will automatically resize to accomodate the
contents of the View in which you have placed it as the background. An example use of a NinePatch is the
backgrounds used by standard Android buttons — buttons must stretch to accommodate strings of various lengths. A
NinePatch drawable is a standard PNG image that includes an extra 1-pixel-wide border. It must be saved with the
extension .9.png, and saved into the res/drawable/ directory of your project.

The border is used to define the stretchable and static areas of the image. You indicate a stretchable section by
drawing one (or more) 1-pixel-wide black line(s) in the left and top part of the border. (You can have as many
stretchable sections as you want.) The relative size of the stretchable sections stays the same, so the largest sections
always remain the largest.

You can also define an optional drawable section of the image (effectively, the padding lines) by drawing a line on the
right and bottom lines. If a View object sets the NinePatch as its background and then specifies the View's text, it will
stretch itself so that all the text fits inside only the area designated by the right and bottom lines (if included). If the
padding lines are not included, Android uses the left and top lines to define this drawable area.

To clarify the difference between the different lines, the left and top lines define which pixels of the image are allowed
to be replicated in order to strech the image. The bottom and right lines define the relative area within the image that
the contents of the View are allowed to lie within.

Here is a sample NinePatch file used to define a button:




http://developer.android.com/guide/topics/graphics/2d-graphics.html                                                 Page 4 of 8
2D Graphics | Android Developers                                                                                  29.04.09 0:49




This NinePatch defines one stretchable area with the left and top lines and the drawable area with the bottom and
right lines. In the top image, the dotted grey lines identify the regions of the image that will be replicated in order to
strech the image. The pink rectangle in the bottom image identifies the region in which the contents of the View are
allowed. If the contents don't fit in this region, then the image will be stretched so that they do.

The Draw 9-patch tool offers an extremely handy way to create your NinePatch images, using a WYSIWYG graphics
editor. It even raises warnings if the region you've defined for the stretchable area is at risk of producing drawing
artifacts as a result of the pixel replication.


Example XML
Here's some sample layout XML that demonstrates how to add a NinePatch image to a couple of buttons. (The
NinePatch image is saved as res/drawable/my_button_background.9.png

     <Button id="@+id/tiny"
             android:layout_width="wrap_content"
             android:layout_height="wrap_content"
             android:layout_alignParentTop="true"
             android:layout_centerInParent="true"
             android:text="Tiny"
             android:textSize="8sp"
             android:background="@drawable/my_button_background"/>

     <Button id="@+id/big"
             android:layout_width="wrap_content"
             android:layout_height="wrap_content"
             android:layout_alignParentBottom="true"
             android:layout_centerInParent="true"
             android:text="Biiiiiiig text!"
             android:textSize="30sp"
             android:background="@drawable/my_button_background"/>

Note that the width and height are set to "wrap_content" to make the button fit neatly around the text.

Below are the two buttons rendered from the XML and NinePatch image shown above. Notice how the width and
height of the button varies with the text, and the background image stretches to accommodate it.


http://developer.android.com/guide/topics/graphics/2d-graphics.html                                                 Page 5 of 8
2D Graphics | Android Developers                                                                               29.04.09 0:49




Tween Animation
A tween animation can perform a series of simple transformations (position, size, rotation, and transparency) on the
contents of a View object. So, if you have a TextView object, you can move, rotate, grow, or shrink the text. If it has a
background image, the background image will be transformed along with the text. The animation package provides all
the classes used in a tween animation.

A sequence of animation instructions defines the twen animation, defined by either XML or Android code. Like defining
a layout, an XML file is recommended because it's more readable, reusable, and swappable than hard-coding the
animation. In the example below, we use XML. (To learn more about defining an animation in your application code,
instead of XML, refer to the AnimationSet class and other Animation subclasses.)

The animation instructions define the transformations that you want to occur, when they will occur, and how long they
should take to apply. Transformations can be sequential or simultaneous — for example, you can have the contents of
a TextView move from left to right, and then rotate 180 degrees, or you can have the text move and rotate
simultaneously. Each transformation takes a set of parameters specific for that transformation (starting size and ending
size for size change, starting angle and ending angle for rotation, and so on), and also a set of common parameters
(for instance, start time and duration). To make several transformations happen simultaneously, give them the same
start time; to make them sequential, calculate the start time plus the duration of the preceding transformation.

The animation XML file belongs in the res/anim/ directory of your Android project. The file must have a single root
element: this will be either a single <alpha>, <scale>, <translate>, <rotate>, interpolator element, or <set>
element that holds groups of these elements (which may include another <set>). By default, all animation instructions
are applied simultaneously. To make them occur sequentially, you must specify the startOffset attribute, as shown
in the example below.

The following XML from one of the ApiDemos is used to stretch, then simultaneously spin and rotate a View object.

     <set android:shareInterpolator="false">
        <scale
               android:interpolator="@android:anim/accelerate_decelerate_interpolator"
               android:fromXScale="1.0"
               android:toXScale="1.4"
               android:fromYScale="1.0"
               android:toYScale="0.6"
               android:pivotX="50%"
               android:pivotY="50%"
               android:fillAfter="false"
               android:duration="700" />
        <set android:interpolator="@android:anim/decelerate_interpolator">
           <scale
                   android:fromXScale="1.4"
                   android:toXScale="0.0"
                   android:fromYScale="0.6"
                   android:toYScale="0.0"
                   android:pivotX="50%"
                   android:pivotY="50%"
                   android:startOffset="700"
                   android:duration="400"
                   android:fillBefore="false" />
           <rotate
                   android:fromDegrees="0"
                   android:toDegrees="-45"
                   android:toYScale="0.0"
                   android:pivotX="50%"

http://developer.android.com/guide/topics/graphics/2d-graphics.html                                              Page 6 of 8
2D Graphics | Android Developers                                                                                 29.04.09 0:49

                            android:pivotX="50%"
                            android:pivotY="50%"
                            android:startOffset="700"
                            android:duration="400" />
        </set>
     </set>

Screen coordinates (not used in this example) are (0,0) at the upper left hand corner, and increase as you go down
and to the right.

Some values, such as pivotX, can be specified relative to the object itself or relative to the parent. Be sure to use the
proper format for what you want ("50" for 50% relative to the parent, or "50%" for 50% relative to itself).

You can determine how a transformation is applied over time by assigning an Interpolator. Android includes several
Interpolator subclasses that specify various speed curves: for instance, AccelerateInterpolator tells a transformation to
start slow and speed up. Each one has an attribute value that can be applied in the XML.

With this XML saved as hyperspace_jump.xml in the res/anim/ directory of the project, the following Java code
will reference it and apply it to an ImageView object from the layout.

     ImageView spaceshipImage = (ImageView) findViewById(R.id.spaceshipImage);
     Animation hyperspaceJumpAnimation = AnimationUtils.loadAnimation(this,
     R.anim.hyperspace_jump);
     spaceshipImage.startAnimation(hyperspaceJumpAnimation);

As an alternative to startAnimation(), you can define a starting time for the animation with
Animation.setStartTime(), then assign the animation to the View with View.setAnimation().

For more information on the XML syntax, available tags and attributes, see the discussion on animation in the
Available Resources.

     Note: Regardless of how your animation may move or resize, the bounds of the View that holds your animation
     will not automatically adjust to accomodate it. Even so, the animation will still be drawn beyond the bounds of its
     View and will not be clipped. However, clipping will occur if the animation exceeds the bounds of the parent
     View.



Frame Animation
This is a traditional animation in the sense that it is created with a sequence of different images, played in order, like a
roll of film. The AnimationDrawable class is the basis for frame animations.

While you can define the frames of an animation in your code, using the AnimationDrawable class API, it's more
simply accomplished with a single XML file that lists the frames that compose the animation. Like the tween animation
above, the XML file for this kind of animation belongs in the res/anim/ directory of your Android project. In this case,
the instructions are the order and duration for each frame of the animation.

The XML file consists of an <animation-list> element as the root node and a series of child <item> nodes that
each define a frame: a drawable resource for the frame and the frame duration. Here's an example XML file for a
frame-by-frame animation:

     <animation-list xmlns:android="http://schemas.android.com/apk/res/android"
         android:oneshot="true">
         <item android:drawable="@drawable/rocket_thrust1" android:duration="200" />
         <item android:drawable="@drawable/rocket_thrust2" android:duration="200" />
         <item android:drawable="@drawable/rocket_thrust3" android:duration="200" />
     </animation-list>

This animation runs for just three frames. By setting the android:oneshot attribute of the list to true, it will cycle
just once then stop and hold on the last frame. If it is set false then the animation will loop. With this XML saved as
http://developer.android.com/guide/topics/graphics/2d-graphics.html                                                Page 7 of 8
2D Graphics | Android Developers                                                                                      29.04.09 0:49


just once then stop and hold on the last frame. If it is set false then the animation will loop. With this XML saved as
rocket_thrust.xml in the res/anim/ directory of the project, it can be added as the background image to a View
and then called to play. Here's an example Activity, in which the animation is added to an ImageView and then
animated when the screen is touched:

     AnimationDrawable rocketAnimation;

     public void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       setContentView(R.layout.main);

         ImageView rocketImage = (ImageView) findViewById(R.id.rocket_image);
         rocketImage.setBackgroundResource(R.anim.rocket_thrust);
         rocketAnimation = (AnimationDrawable) rocketImage.getBackground();
     }

     public boolean onTouchEvent(MotionEvent event) {
       if (event.getAction() == MotionEvent.ACTION_DOWN) {
         rocketAnimation.start();
         return true;
       }
       return super.onTouchEvent(event);
     }

It's important to note that the start() method called on the AnimationDrawable cannot be called during the
onCreate() method of your Activity, because the AnimationDrawable is not yet fully attached to the window. If you
want to play the animation immediately, without requiring interaction, then you might want to call it from the
onWindowFocusChanged() method in your Activity, which will get called when Android brings your window into
focus.

" Back to 2D and 3D Graphics                                                                                         ! Go to top

Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/graphics/2d-graphics.html                                                     Page 8 of 8
3D with OpenGL | Android Developers                                                                                   29.04.09 0:49




2D and 3D Graphics >

3D with OpenGL

Android includes support for high performance 3D graphics via the OpenGL API — specifically, the OpenGL ES API.

OpenGL ES is a flavor of the OpenGL specification intended for embedded devices. Versions of OpenGL ES are
loosely peered to versions of the primary OpenGL standard. Android currently supports OpenGL ES 1.0, which
corresponds to OpenGL 1.3. So, if the application you have in mind is possible with OpenGL 1.3 on a desktop system,
it should be possible on Android.

The specific API provided by Android is similar to the J2ME JSR239 OpenGL ES API. However, it may not be
identical, so watch out for deviations.



Using the API
Here's how to use the API at an extremely high level:

 1. Write a custom View subclass.
 2. Obtain a handle to an OpenGLContext, which provides access to the OpenGL functionality.
 3. In your View's onDraw() method, get a handle to a GL object, and use its methods to perform GL operations.

For an example of this usage model (based on the classic GL ColorCube), showing how to use it with threads can be
found in com.android.samples.graphics.GLSurfaceViewActivity.java.

Writing a summary of how to actually write 3D applications using OpenGL is beyond the scope of this text and is left
as an exercise for the reader.



Links to Additional Information
Information about OpenGL ES can be found at http://www.khronos.org/opengles/.

Information specifically about OpenGL ES 1.0 (including a detailed specification) can be found at
http://www.khronos.org/opengles/1_X/.

The documentation for the Android OpenGL ES implementations are also available.

Finally, note that though Android does include some basic support for OpenGL ES 1.1, the support is not complete,
and should not be relied upon at this time.

" Back to 2D and 3D Graphics                                                                                         ! Go to top

Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/graphics/opengl.html                                                          Page 1 of 1
Audio and Video | Android Developers                                                                            29.04.09 0:49




Audio and Video

The Android platform offers built-in encoding/decoding for a variety of common media types, so that you can easily
integrate audio, video, and images into your applications. Accessing the platform's media capabilities is fairly
straightforward — you do so using the same intents and activities mechanism that the rest of Android uses.

Android lets you play audio and video from several types of data sources. You can play audio or video from media files
stored in the application's resources (raw resources), from standalone files in the filesystem, or from a data stream
arriving over a network connection. To play audio or video from your application, use the MediaPlayer class.

The platform also lets you record audio and video, where supported by the mobile device hardware. To record audio or
video, use the MediaRecorder class. Note that the emulator doesn't have hardware to capture audio or video, but
actual mobile devices are likely to provide these capabilities, accessible through the MediaRecorder class.

For a list of media formats for which Android offers built-in support, see the Android Media Formats appendix.



Audio and Video Playback
Media can be played from anywhere: from a raw resource, from a file from the system, or from an available network
(URL).

You can play back the audio data only to the standard output device; currently, that is the mobile device speaker or
Bluetooth headset. You cannot play sound files in the conversation audio.


Playing from a Raw Resource
Perhaps the most common thing to want to do is play back media (notably sound) within your own applications. Doing
this is easy:

 1. Put the sound (or other media resource) file into the res/raw folder of your project, where the Eclipse plugin (or
    aapt) will find it and make it into a resource that can be referenced from your R class
 2. Create an instance of MediaPlayer, referencing that resource using MediaPlayer.create, and then call start() on
    the instance:


            MediaPlayer mp = MediaPlayer.create(context, R.raw.sound_file_1);
            mp.start();

To stop playback, call stop(). If you wish to later replay the media, then you must reset() and prepare() the
MediaPlayer object before calling start() again. (create() calls prepare() the first time.)

To pause playback, call pause(). Resume playback from where you paused with start().


Playing from a File or Stream
You can play back media files from the filesystem or a web URL:

 1. Create an instance of the MediaPlayer using new


http://developer.android.com/guide/topics/media/index.html                                                        Page 1 of 3
Audio and Video | Android Developers                                                                            29.04.09 0:49


 2. Call setDataSource() with a String containing the path (local filesystem or URL) to the file you want to play
 3. First prepare() then start() on the instance:


            MediaPlayer mp = new MediaPlayer();
            mp.setDataSource(PATH_TO_FILE);
            mp.prepare();
            mp.start();

stop() and pause() work the same as discussed above.

     Note: It is possible that mp could be null, so good code should null check after the new. Also,
     IllegalArgumentException and IOException either need to be caught or passed on when using
     setDataSource(), since the file you are referencing may not exist.

     Note: If you're passing a URL to an online media file, the file must be capable of progressive download.


Playing JET content
The Android platform includes a JET engine that lets you add interactive playback of JET audio content in your
applications. You can create JET content for interactive playback using the JetCreator authoring application that ships
with the SDK. To play and manage JET content from your application, use the JetPlayer class.

For a description of JET concepts and instructions on how to use the JetCreator authoring tool, see the JetCreator
User Manual. The tool is available fully-featured on the OS X and Windows platforms and the Linux version supports
all the content creation features, but not the auditioning of the imported assets.

Here's an example of how to set up JET playback from a .jet file stored on the SD card:


     JetPlayer myJet = JetPlayer.getJetPlayer();
     myJet.loadJetFile("/sdcard/level1.jet");
     byte segmentId = 0;
     // queue segment 5, repeat once, use General MIDI, transpose by -1 octave
     myJet.queueJetSegment(5, -1, 1, -1, 0, segmentId++);
     // queue segment 2
     myJet.queueJetSegment(2, -1, 0, 0, 0, segmentId++);

     myJet.play();

The SDK includes an example application — JetBoy — that shows how to use JetPlayer to create an interactive music
soundtrack in your game. It also illustrates how to use JET events to synchronize music and game logic. The
application is located at <sdk>/platforms/android-1.5/samples/JetBoy.



Audio Capture
Audio capture from the device is a bit more complicated than audio/video playback, but still fairly simple:

 1. Create a new instance of android.media.MediaRecorder using new
 2. Create a new instance of android.content.ContentValues and put in some standard properties like TITLE,
    TIMESTAMP, and the all important MIME_TYPE
 3. Create a file path for the data to go to (you can use android.content.ContentResolver to create an entry in the
    Content database and get it to assign a path automatically which you can then use)
 4. Set the audio source using MediaRecorder.setAudioSource(). You will probably want to use
    MediaRecorder.AudioSource.MIC


http://developer.android.com/guide/topics/media/index.html                                                          Page 2 of 3
Audio and Video | Android Developers                                                                                  29.04.09 0:49


 5. Set output file format using MediaRecorder.setOutputFormat()
 6. Set the audio encoder using MediaRecorder.setAudioEncoder()
 7. Call prepare() on the MediaRecorder instance.
 8. To start audio capture, call start().
 9. To stop audio capture, call stop().
10. When you are done with the MediaRecorder instance, call release() on it.


Example: Audio Capture Setup and Start
The example below illustrates how to set up, then start audio capture.


            recorder = new MediaRecorder();
            ContentValues values = new ContentValues(3);
            values.put(MediaStore.MediaColumns.TITLE, SOME_NAME_HERE);
            values.put(MediaStore.MediaColumns.TIMESTAMP, System.currentTimeMillis());
            values.put(MediaStore.MediaColumns.MIME_TYPE, recorder.getMimeContentType());

            ContentResolver contentResolver = new ContentResolver();
            Uri base = MediaStore.Audio.INTERNAL_CONTENT_URI;
            Uri newUri = contentResolver.insert(base, values);

            if (newUri == null) {
                // need to handle exception here - we were not able to create a new
                // content entry
            }

            String path = contentResolver.getDataFilePath(newUri);

            // could use setPreviewDisplay() to display a preview to suitable View here

            recorder.setAudioSource(MediaRecorder.AudioSource.MIC);
            recorder.setOutputFormat(MediaRecorder.OutputFormat.THREE_GPP);
            recorder.setAudioEncoder(MediaRecorder.AudioEncoder.AMR_NB);
            recorder.setOutputFile(path);

            recorder.prepare();
            recorder.start();


Stop Recording
Based on the example above, here's how you would stop audio capture.


            recorder.stop();
            recorder.release();

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/media/index.html                                                              Page 3 of 3
Location and Maps | Android Developers                                                                           29.04.09 0:49




Location and Maps

Location- and maps-based applications and services are compelling for mobile device users. You can build these
capabilities into your applications using the classes of the android.location package and the Google Maps external
library. The sections below provide details.



Location Services
Android gives your applications access to the location services supported by the device through the classes in the
android.location package. The central component of the location framework is the LocationManager system
service, which provides an API to determine location and bearing if the underlying device (if it supports location
capabilities).

As with other system services, you do not instantiate a LocationManager directly. Rather, you request an
LocationManager instance from the system by calling getSystemService(Context.LOCATION_SERVICE). The method
returns a handle to a new LocationManager instance.

Once your application has a handle to a LocationManager instance, your application will be able to do three things:

     Query for the list of all LocationProviders known to the LocationManager for its last known location.
     Register/unregister for periodic updates of current location from a LocationProvider (specified either by Criteria or
     name).
     Register/unregister for a given Intent to be fired if the device comes within a given proximity (specified by radius
     in meters) of a given lat/long.

However, during initial development in the emulator, you may not have access to real data from a real location
provider (Network or GPS). In that case, it may be necessary to spoof some data for your application using a mock
location provider.

     Note: If you've used mock LocationProviders in previous versions of the SDK, you can no longer provide
     canned LocationProviders in the /system/etc/location directory. These directories will be wiped during boot-up.
     Please follow the new procedures outlined below.


Providing Mock Location Data
When testing your application on the Android emulator, there are a couple different ways to send it some mock
location data: you can use the DDMS tool or the "geo" command option in the emulator console.

Using DDMS
With the DDMS tool, you can simulate location data a few different ways:

     Manually send individual longitude/latitude coordinates to the device.
     Use a GPX file describing a route for playback to the device.
     Use a KML file describing individual placemarks for sequenced playback to the device.

For more information on using DDMS to spoof location data, see the Using DDMS guide.


http://developer.android.com/guide/topics/location/index.html                                                      Page 1 of 2
Location and Maps | Android Developers                                                                                29.04.09 0:49



Using the "geo" command in the emulator console
Launch your application in the Android emulator and open a terminal/console in your SDK's /tools directory.
Connect to the emulator console. Now you can use:

     geo fix to send a fixed geo-location.
     This command accepts a longitude and latitude in decimal degrees, and an optional altitude in meters. For
     example:

           geo fix -121.45356 46.51119 4392

     geo nmea to send an NMEA 0183 sentence.
     This command accepts a single NMEA sentence of type '$GPGGA' (fix data) or '$GPRMC' (transit data). For
     example:

           geo nmea $GPRMC,081836,A,3751.65,S,14507.36,E,000.0,360.0,130998,011.3,E*62


For information about how to connect to the emulator console, see Using the Emulator Console.



Google Maps External Library
To make it easier for you to add powerful mapping capabilities to your application, Google provides a Maps external
library that includes the com.google.android.maps package. The classes of the com.google.android.maps package
offer built-in downloading, rendering, and caching of Maps tiles, as well as a variety of display options and controls.

The key class in the Maps package is com.google.android.maps.MapView, a subclass of ViewGroup. A
MapView displays a map with data obtained from the Google Maps service. When the MapView has focus, it will
capture keypresses and touch gestures to pan and zoom the map automatically, including handling network requests
for additional maps tiles. It also provides all of the UI elements necessary for users to control the map. Your
application can also use MapView class methods to control the MapView programmatically and draw a number of
Overlay types on top of the map.

In general, the MapView class provides a wrapper around the Google Maps API that lets your application manipulate
Google Maps data through class methods, and it lets you work with Maps data as you would other types of Views.

The Maps external library is not part of the standard Android library, so it may not be present on some compliant
Android-powered devices (although it is likely to be present on most devices). Similarly, the Maps external library is
not included in the standard Android library provided in the SDK. So that you can develop using the classes of the
com.google.android.maps package, the Maps external library is made available to you as part of the Google APIs add-
on for the Android SDK.

To learn more about the Maps external library and how to download and use the Google APIs add-on, visit

     http://code.google.com/android/add-ons/google-apis

For your convenience, the Google APIs add-on is also included in the Android SDK.

     Note: In order to display Google Maps data in a MapView, you must register with the Google Maps service and
     obtain a Maps API Key. For information about how to get a Maps API Key, see Obtaining a Maps API Key.

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/location/index.html                                                           Page 2 of 2
AppWidgets | Android Developers                                                                             29.04.09 0:49




AppWidgets

AppWidgets are miniature application views that can be embedded in other applications (e.g., the Home). These views
are called "widgets" and you can publish one with an "AppWidget provider." An application component that is able to
hold other widgets is called an "AppWidget host."



AppWidget Providers
Any application can publish widgets. All an application needs to do to publish a widget is to have a BroadcastReceiver
that receives the AppWidgetManager.ACTION_APPWIDGET_UPDATE intent, and provide some meta-data about the
widget. Android provides the AppWidgetProvider class, which extends BroadcastReceiver, as a convenience class to
aid in handling the broadcasts.


Declaring a widget in the AndroidManifest
First, declare the BroadcastReceiver in your application's AndroidManifest.xml file.


     <receiver android:name="TestAppWidgetProvider"
                 android:label="@string/oh_hai"
                 android:icon="@drawable/oh_hai_icon"
                 >
         <intent-filter>
             <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
         </intent-filter>
         <meta-data android:name="android.appwidget.provider"
                     android:resource="@xml/appwidget_info"
                     />
     </receiver>

The <receiver> element has the following attributes:

     android:name - specifies the BroadcastReceiver or AppWidgetProvider class.
     android:label - specifies the string resource that will be shown by the widget picker as the label.
     android:icon - specifies the drawable resource that will be shown by the widget picker as the icon.

The <intent-filter> element tells the PackageManager that this BroadcastReceiver receives the
AppWidgetManager.ACTION_APPWIDGET_UPDATE broadcast. The widget manager will send other broadcasts
directly to your widget provider as required. It is only necessary to explicitly declare that you accept the
AppWidgetManager.ACTION_APPWIDGET_UPDATE broadcast.

The <meta-data> element tells the widget manager which xml resource to read to find the AppWidgetProviderInfo
for your widget provider. It has the following attributes:

     android:name="android.appwidget.provider" - identifies this meta-data as the AppWidgetProviderInfo
     descriptor.
     android:resource - is the xml resource to use as that descriptor.




http://developer.android.com/guide/topics/appwidgets/index.html                                               Page 1 of 3
AppWidgets | Android Developers                                                                                 29.04.09 0:49



Adding the AppWidgetProviderInfo meta-data
For a widget, the values in the AppWidgetProviderInfo structure are supplied in an XML resource. In the example
above, the xml resource is referenced with android:resource="@xml/appwidget_info". That XML file would
go in your application's directory at res/xml/appwidget_info.xml. Here is a simple example.

     <appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
         android:minWidth="40dp"
         android:minHeight="30dp"
         android:updatePeriodMillis="86400000"
         android:initialLayout="@layout/test_appwidget"
         android:configure="com.android.tests.appwidgethost.TestAppWidgetConfigure"
         >
     </appwidget-provider>

The attributes are as documented in the AppWidgetProviderInfo class.


Using the AppWidgetProvider class
The AppWidgetProvider class is the easiest way to handle the widget provider intent broadcasts. See the
src/com/example/android/apis/appwidget/ExampleAppWidgetProvider.java sample class in
ApiDemos for an example.

     Keep in mind that since the the AppWidgetProvider is a BroadcastReceiver, your process is not guaranteed to
     keep running after the callback methods return. See Application Fundamentals > Broadcast Receiver Lifecycle
     for more information.


AppWidget Configuration UI
Widget hosts have the ability to start a configuration activity when a widget is instantiated. The activity should be
declared as normal in AndroidManifest.xml, and it should be listed in the AppWidgetProviderInfo XML file in the
android:configure attribute.

The activity you specified will be launched with the ACTION_APPWIDGET_CONFIGURE action. See the
documentation for that action for more info.

See the src/com/example/android/apis/appwidget/ExampleAppWidgetConfigure.java sample class in
ApiDemos for an example.


AppWidget Broadcast Intents
AppWidgetProvider is just a convenience class. If you would like to receive the widget broadcasts directly, you can.
The four intents you need to care about are:

     ACTION_APPWIDGET_UPDATE
     ACTION_APPWIDGET_DELETED
     ACTION_APPWIDGET_ENABLED
     ACTION_APPWIDGET_DISABLED

By way of example, the implementation of onReceive(Context, Intent) is quite simple:


     public void onReceive(Context context, Intent intent) {
         // Protect against rogue update broadcasts (not really a security issue,
         // just filter bad broacasts out so subclasses are less likely to crash).
         String action = intent.getAction();
         if (AppWidgetManager.ACTION_APPWIDGET_UPDATE.equals(action)) {
             Bundle extras = intent.getExtras();


http://developer.android.com/guide/topics/appwidgets/index.html                                                   Page 2 of 3
AppWidgets | Android Developers                                                                                       29.04.09 0:49

             Bundle extras = intent.getExtras();
             if (extras != null) {
                 int[] appWidgetIds =
     extras.getIntArray(AppWidgetManager.EXTRA_APPWIDGET_IDS);
                 if (appWidgetIds != null && appWidgetIds.length > 0) {
                     this.onUpdate(context, AppWidgetManager.getInstance(context),
     appWidgetIds);
                 }
             }
         }
         else if (AppWidgetManager.ACTION_APPWIDGET_DELETED.equals(action)) {
             Bundle extras = intent.getExtras();
             if (extras != null) {
                 int[] appWidgetIds =
     extras.getIntArray(AppWidgetManager.EXTRA_APPWIDGET_IDS);
                 if (appWidgetIds != null && appWidgetIds.length > 0) {
                     this.onDeleted(context, appWidgetIds);
                 }
             }
         }
         else if (AppWidgetManager.ACTION_APPWIDGET_ENABLED.equals(action)) {
             this.onEnabled(context);
         }
         else if (AppWidgetManager.ACTION_APPWIDGET_DISABLED.equals(action)) {
             this.onDisabled(context);
         }
     }




AppWidget Hosts
Widget hosts are the containers in which widgets can be placed. Most of the look and feel details are left up to the
widget hosts. For example, the home screen has one way of viewing widgets, but the lock screen could also contain
widgets, and it would have a different way of adding, removing and otherwise managing widgets.

For more information on implementing your own widget host, see the AppWidgetHost class.

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/topics/appwidgets/index.html                                                         Page 3 of 3
Developing In Eclipse, with ADT | Android Developers                                                                        29.04.09 0:49




Developing In Eclipse, with ADT

The Android Development Tools (ADT) plugin for Eclipse adds powerful extensions to the Eclipse integrated
development environment. It allows you to create and debug Android applications easier and faster. If you use Eclipse,
the ADT plugin gives you an incredible boost in developing Android applications:

     It gives you access to other Android development tools from inside the Eclipse IDE. For example, ADT lets you
     access the many capabilities of the DDMS tool: take screenshots, manage port-forwarding, set breakpoints, and
     view thread and process informationd irectly from Eclipse.
     It provides a New Project Wizard, which helps you quickly create and set up all of the basic files you'll need for a
     new Android application.
     It automates and simplifies the process of building your Android application.
     It provides an Android code editor that helps you write valid XML for your Android manifest and resource files.
     It will even export your project into a signed APK, which can be distributed to users.

To begin developing Android applications in the Eclipse IDE with ADT, you first need to download the Eclipse IDE and
then download and install the ADT plugin. To do so, follow the steps given in Installing the ADT Plugin.

If you are already developing applications using a version of ADT earlier than 0.9, make sure to upgrade to the latest
version before continuing. See the guide to Update Your Eclipse ADT Plugin.

    Note: This guide assumes you are using the latest version of the ADT plugin (0.9). While most of the
    information covered also applies to previous versions, if you are using an older version, you may want to consult
    this document from the set of documentation included in your SDK package (instead of the online version).



Creating an Android Project
The ADT plugin provides a New Project Wizard that you can use to quickly create a new Android project (or a project
from existing code). To create a new project:

 1. Select File > New > Project.
 2. Select Android > Android Project, and click Next.
 3. Select the contents for the project:
          Enter a Project Name. This will be the name of the folder where your project is created.
          Under Contents, select Create new project in workspace. Select your project workspace location.
          Under Target, select an Android target to be used as the project's Build Target. The Build Target specifies
          which Android platform you'd like your application built against.
          Unless you know that you'll be using new APIs introduced in the latest SDK, you should select a target with
          the lowest platform version possible, such as Android 1.1.
             Note: You can change your the Build Target for your project at any time: Right-click the project in the
             Package Explorer, select Properties, select Android and then check the desired Project Target.
          Under Properties, fill in all necessary fields.
                Enter an Application name. This is the human-readable title for your application — the name that will
                appear on the Android device.
                Enter a Package name. This is the package namespace (following the same rules as for packages in the
                Java programming language) where all your source code will reside.
                Select Create Activity (optional, of course, but common) and enter a name for your main Activity class.
                Enter a Min SDK Version. This is an integer that indicates the minimum API Level required to properly
                run your application. Entering this here automatically sets the minSdkVersion attribute in the <uses-
http://developer.android.com/guide/developing/eclipse-adt.html                                                                Page 1 of 5
Developing In Eclipse, with ADT | Android Developers                                                                             29.04.09 0:49


                run your application. Entering this here automatically sets the minSdkVersion attribute in the <uses-
                sdk> of your Android Manifest file. If you're unsure of the appropriate API Level to use, copy the API
                Level listed for the Build Target you selected in the Target tab.

 4. Click Finish.

    Tip: You can also start the New Project Wizard from the New icon in the toolbar.

Once you complete the New Project Wizard, ADT creates the following folders and files in your new project:

src/
   Includes your stub Activity Java file. All other Java files for your application go here.

<Android Version>/ (e.g., Android 1.1/)
   Includes the android.jar file that your application will build against. This is determined by the build target that
   you have chosen in the New Project Wizard.

gen/
   This contains the Java files generated by ADT, such as your R.java file and interfaces created from AIDL files.

assets/
   This is empty. You can use it to store raw asset files. See Resources and Assets.

res/
   A folder for your application resources, such as drawable files, layout files, string values, etc. See Resources and
   Assets.

AndroidManifest.xml
   The Android Manifest for your project. See The AndroidManifest.xml File.

default.properties
   This file contains project settings, such as the build target. This files is integral to the project, as such, it should be
   maintained in a Source Revision Control system. It should never be edited manually — to edit project properties,
   right-click the project folder and select "Properties".



Running Your Application
Wait! Before you can run your application on the Android Emulator, you must create an Android Virtual Device (AVD).
An AVD is a configuration that specifies the Android platform to be used on the emulator. You can read more about
AVDs in the Developing Overview, but if you just want to get started, follow the simple guide below to create an AVD.

If you will be running your applications only on actual device hardware, you do not need an AVD — see Developing
On a Device for information on running your applicaiton.


Creating an AVD
To avoid some explanation that's beyond the scope of this document, here's the basic procedure to create an AVD:

 1. Open a command-line (e.g.,"Command Prompt" application on Windows, or "Terminal" on Mac/Linux) and
    navigate to your SDK package's tools/ directory.
 2. First, you need to select a Deployment Target. To view available targets, execute:

          android list targets

     This will output a list of available Android targets, such as:

          id:1
                 Name: Android 1.1
                 Type: platform
                 API level: 2
                 Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P
          id:2
                 Name: Android 1.5

http://developer.android.com/guide/developing/eclipse-adt.html                                                                     Page 2 of 5
Developing In Eclipse, with ADT | Android Developers                                                                         29.04.09 0:49

                 Name: Android 1.5
                 Type: platform
                 API level: 3
                 Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P

     Find the target that matches the Android platform upon which you'd like to run your application. Note the integer
     value of the id — you'll use this in the next step.
 3. Create a new AVD using your selected Deployment Target. Execute:

          android create avd --name <your_avd_name> --target <targetID>

 4. Next, you'll be asked whether you'd like to create a custom hardware profile. If you respond "yes," you'll be
    presented with a series of prompts to define various aspects of the device hardware (leave entries blank to use
    default values, which are shown in brackets). Otherwise, press return to use all default values ("no" is the default).

That's it; your AVD is ready. In the next section, you'll see how the AVD is used when launching your application on
an emulator.

To learn more about creating and managing AVDs, please read the Android Virtual Devices documentation.


Running your application

    Note: Before you can run your application, be sure that you have created an AVD with a target that satisfies
    your application's Build Target. If an AVD cannot be found that meets the requirements of your Build Target, you
    will see a console error telling you so and the launch will be aborted.

To run (or debug) your application, select Run > Run (or Run > Debug) from the Eclipse main menu. The ADT plugin
will automatically create a default launch configuration for the project.

When you choose to run or debug your application, Eclipse will perform the following:

 1. Compile the project (if there have been changes since the last build).
 2. Create a default launch configuration (if one does not already exist for the project).
 3. Install and start the application on an emulator or device (based on the Deployment Target defined by the run
    configuration).
     By default, Android application run configurations use an "automatic target" mode for selecting a device target. For
     information on how automatic target mode selects a deployment target, see Automatic and manual target modes
     below.

If debugging, the application will start in the "Waiting For Debugger" mode. Once the debugger is attached, Eclipse
will open the Debug perspective.

To set or change the launch configuration used for your project, use the launch configuration manager. See Creating a
Launch Configuration for information.



Creating a Run Configuration
The run configuration specifies the project to run, the Activity to start, the emulator options to use, and so on. When
you first run a project as an Android Application, ADT will automatically create a run configuration. The default run
configuration will launch the default project Activity and use automatic target mode for device selection (with no
preferred AVD). If the default setting don't suit your project, you can customize the launch configuration or even create
a new.

To create or modify a launch configuration, follow these steps as appropriate for your Eclipse version:

 1. Open the run configuration manager.
          In Eclipse 3.3 (Europa), select Run > Open Run Dialog (or Open Debug Dialog)
          In Eclipse 3.4 (Ganymede), select Run > Run Configurations (or Debug Configurations)

 2. Expand the Android Application item and create a new configuration or open an existing one.


http://developer.android.com/guide/developing/eclipse-adt.html                                                                 Page 3 of 5
Developing In Eclipse, with ADT | Android Developers                                                                            29.04.09 0:49


          To create a new configuration:
            1. Select Android Application and click the New launch configuration icon above the list (or, right-click
               Android Application and click New).
            2. Enter a Name for your configuration.
            3. In the Android tab, browse and select the project you'd like to run with the configuration.

          To open an existing configuration, select the configuration name from the list nested below Android
          Application.

 3. Adjust your desired launch configuration settings.
     In the Target tab, consider whether you'd like to use Manual or Automatic mode when selecting an AVD to run
     your application. See the following section on Automatic and manual target modes).


Automatic and manual target modes
By default, a run configuration uses the automatic target mode in order to select an AVD. In this mode, ADT will
select an AVD for the application in the following manner:

 1. If there's a device or emulator already running and its AVD configuration meets the requirements of the
    application's build target, the application is installed and run upon it.
 2. If there's more than one device or emulator running, each of which meets the requirements of the build target, a
    "device chooser" is shown to let you select which device to use.
 3. If there are no devices or emulators running that meet the requirements of the build target, ADT looks at the
    available AVDs. If one meets the requirements of the build target, the AVD is used to launch a new emulator,
    upon which the application is installed and run.
 4. If all else fails, the application will not be run and you will see a console error warning you that there is no existing
    AVD that meets the build target requirements.

However, if a "preferred AVD" is selected in the run configuration, then the application will always be deployed to that
AVD. If it's not already running, then a new emulator will be launched.

If your run configuration uses manual mode, then the "device chooser" is presented every time that your application is
run, so that you can select which AVD to use.



Signing your Applications
As you begin developing Android applications, understand that all Android applications must be digitally signed before
the system will install them on an emulator or an actual device. There are two ways to do this: with a debug key (for
immediate testing on an emulator or development device) or with a private key (for application distribution).

The ADT plugin helps you get started quickly by signing your .apk files with a debug key, prior to installing them on an
emulator or development device. This means that you can quickly run your application from Eclipse without having to
generate your own private key. No specific action on your part is needed, provided ADT has access to
Keytool.However, please note that if you intend to publish your application, you must sign the application with your
own private key, rather than the debug key generated by the SDK tools.

Please read Signing Your Applications, which provides a thorough guide to application signing on Android and what it
means to you as an Android application developer. The document also includes a guide to exporting and signing your
application with the ADT's Export Wizard.



Eclipse Tips

Executing arbitrary Java expressions in Eclipse
You can execute arbitrary code when paused at a breakpoint in Eclipse. For example, when in a function with a String
argument called "zip", you can get information about packages and call class methods. You can also invoke arbitrary
static methods: for example, entering android.os.Debug.startMethodTracing() will start dmTrace.

http://developer.android.com/guide/developing/eclipse-adt.html                                                                    Page 4 of 5
Developing In Eclipse, with ADT | Android Developers                                                                               29.04.09 0:49




Open a code execution window, select Window>Show View>Display from the main menu to open the Display
window, a simple text editor. Type your expression, highlight the text, and click the 'J' icon (or CTRL + SHIFT + D) to
run your code. The code runs in the context of the selected thread, which must be stopped at a breakpoint or single-
step point. (If you suspend the thread manually, you have to single-step once; this doesn't work if the thread is in
Object.wait().)

If you are currently paused on a breakpoint, you can simply highlight and execute a piece of source code by pressing
CTRL + SHIFT + D.

You can highlight a block of text within the same scope by pressing ALT +SHIFT + UP ARROW to select larger and
larger enclosing blocks, or DOWN ARROW to select smaller blocks.

Here are a few sample inputs and responses in Eclipse using the Display window.

  Input                                  Response

  zip                                    (java.lang.String) /work/device/out/linux-x86-
                                         debug/android/app/android_sdk.zip

  zip.endsWith(".zip")                   (boolean) true

  zip.endsWith(".jar")                   (boolean) false

You can also execute arbitrary code when not debugging by using a scrapbook page. Search the Eclipse
documentation for "scrapbook".


Running DDMS Manually
Although the recommended way to debug is to use the ADT plugin, you can manually run DDMS and configure
Eclipse to debug on port 8700. (Note: Be sure that you have first started DDMS).

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/developing/eclipse-adt.html                                                                       Page 5 of 5
Developing In Other IDEs | Android Developers                                                                  29.04.09 0:50




Developing In Other IDEs

The recommended way to develop an Android application is to use Eclipse with the ADT plugin. The ADT plugin
provides editing, building, debugging, and .apk packaging and signing functionality integrated right into the IDE.

However, if you'd rather develop your application in another IDE, such as IntelliJ, or in a basic editor, such as Emacs,
you can do that instead. The SDK includes all the tools you need to set up an Android project, build it, debug it and
then package it for distribution. This document is your guide to using these tools.



Essential Tools
When developing in IDEs or editors other than Eclipse, you'll require familiarity with the following Android SDK tools:

android
    To create/update Android projects and to create/move/delete AVDs.

Android Emulator
    To run your Android applications on an emulated Android platform.

Android Debug Bridge
    To interface with your emulator or connected device (install apps, shell the device, issue commands, etc.).

In addition to the above tools, included with the SDK, you'll use the following open source and third-party tools:

Ant
      To compile and build your Android project into an installable .apk file.

Keytool
    To generate a keystore and private key, used to sign your .apk file.

Jarsigner (or similar signing tool)
     To sign your .apk file with a private key generated by keytool.

In the topics that follow, you'll be introduced to each of these tools as necessary. For more advanced operations,
please read the respective documentation for each tool.



Creating an Android Project
To create an Android project, you must use the android tool. When you create a new project with android, it will
generate a project directory with some default application files, stub files, configuration files and a build file.


Creating a new Project
If you're starting a new project, use the android create project command to generate all the necessary files
and folders.

To create a new Android project, open a command-line, navigate to the tools/ directory of your SDK and run:


http://developer.android.com/guide/developing/other-ide.html                                                      Page 1 of 6
Developing In Other IDEs | Android Developers                                                                       29.04.09 0:50



     android create project \
     --target <targetID> \
     --path /path/to/your/project \
     --activity <your_activity_name> \
     --package <your_package_namespace>

     target is the "build target" for your application. It corresponds to an Android platform library (including any add-
     ons, such as Google APIs) that you would like to build your project against. To see a list of available targets and
     their corresponding IDs, execute: android list targets.
     path is the location of your project directory. If the directory does not exist, it will be created for you.
     activity is the name for your Activity class. This class file will be created for you inside
     <path_to_your_project>/src/<your_package_namespace_path>/.
     package is the package namespace for your project, following the same rules as for packages in the Java
     programming language.

Here's an example:

     android create project \
     --target 1 \
     --path ./myProject \
     --activity MyActivity \
     --package com.example.myproject

The tool generates the following files and directories:

     AndroidManifest.xml - The application manifest file, synced to the specified Activity class for the project.
     build.xml - Build file for Ant.
     default.properties - Properties for the build system. Do not modify this file.
     build.properties - Customizable properties for the build system. You can edit this file to overried default build
     settings used by Ant.
     src/your/package/namespace/ActivityName.java - The Activity class you specified during project
     creation.
     bin/ - Output directory for the build script.
     gen/ - Holds Ant-generated files, such as R.java.
     libs/ - Holds private libraries.
     res/ - Holds project resources.
     src/ - Holds source code.
     tests/ - Holds a duplicate of all-of-the-above, for testing purposes.

Once you've created your project, you're ready to begin development. You can move your project folder wherever you
want for development, but keep in mind that you must use the Android Debug Bridge (adb) — located in the SDK
tools/ directory — to send your application to the emulator (discussed later). So you need access between your
project solution and the tools/ folder.

     Note: You should refrain from moving the location of the SDK directory, because this will break the build scripts.
     (They will need to be manually updated to reflect the new SDK location before they will work again.)


Updating a project
If you're upgrading a project from an older version of the Android SDK or want to create a new project from existing
code, use the android update project command to update the project to the new development environment.
You can also use this command to revise the build target of an existing project (with the --target option). The
android tool will generate any files and folders (listed in the previous section) that are either missing or need to be
http://developer.android.com/guide/developing/other-ide.html                                                          Page 2 of 6
Developing In Other IDEs | Android Developers                                                                     29.04.09 0:50


android tool will generate any files and folders (listed in the previous section) that are either missing or need to be
updated, as needed for the Android project.

To update an existing Android project, open a command-line and navigate to the tools/ directory of your SDK. Now
run:

     android update project --target <targetID> --path path/to/your/project/

     target is the "build target" for your application. It corresponds to an Android platform library (including any add-
     ons, such as Google APIs) that you would like to build your project against. To see a list of available targets and
     their corresponding IDs, execute: android list targets.
     path is the location of your project directory.

Here's an example:

     android update project --target 2 --path ./myProject




Preparing to Sign Your Application
As you begin developing Android applications, understand that all Android applications must be digitally signed before
the system will install them on an emulator or device. There are two ways to do this: with a debug key (for immediate
testing on an emulator or development device) or with a private key (for application distribution).

The Android build tools help you get started by automatically signing your .apk files with a debug key at build time.
This means that you can compile your application and install it on the emulator without having to generate your own
private key. However, please note that if you intend to publish your application, you must sign the application with
your own private key, rather than the debug key generated by the SDK tools.

Please read Signing Your Applications, which provides a thorough guide to application signing on Android and what it
means to you as an Android application developer.



Building Your Application
There are two ways to build your application: one for testing/debugging your application — debug mode — and one for
building your final package for release — release mode. As described in the previous section, your application must
be signed before it can be installed on an emulator or device.

Whether you're building in debug mode or release mode, you need to use the Ant tool to compile and build your
project. This will create the .apk file that is installed onto the emulator or device. When you build in debug mode, the
.apk file is automatically signed by the SDK tools with a debug key, so it's instantly ready for installation (but only onto
an emulator or attached development device). When you build in release mode, the .apk file is unsigned, so you must
manually sign it with your own private key, using Keytool and Jarsigner.

It's important that you read and understand Signing Your Applications, particularly once you're ready to release your
application and share it with end-users. That document describes the procedure for generating a private key and then
using it to sign your .apk file. If you're just getting started, however, you can quickly run your applications on an
emulator or your own development device by building in debug mode.

If you don't have Ant, you can obtain it from the Apache Ant home page. Install it and make sure it is in your
executable PATH. Before calling Ant, you need to declare the JAVA_HOME environment variable to specify the path to
where the JDK is installed.



http://developer.android.com/guide/developing/other-ide.html                                                        Page 3 of 6
Developing In Other IDEs | Android Developers                                                                       29.04.09 0:50


     Note: When installing JDK on Windows, the default is to install in the "Program Files" directory. This location will
     cause ant to fail, because of the space. To fix the problem, you can specify the JAVA_HOME variable like this:
     set JAVA_HOME=c:\Prora~1\Java\. The easiest solution, however, is to install JDK in a non-space
     directory, for example: c:\java\jdk1.6.0_02.


Building in debug mode
For immediate application testing and debugging, you can build your application in debug mode and immediately install
it on an emulator. In debug mode, the build tools automatically sign your application with a debug key. However, you
can (and should) also test your application in release mode. Debug mode simply allows you to run your application
without manually signing the application.

To build in debug mode:

 1. Open a command-line and navigate to the root of your project directory.
 2. Use Ant to compile your project in debug mode:

           ant debug

     This creates your Android application .apk file inside the project bin/ directory, named
     <your_DefaultActivity_name>-debug.apk. The file is already signed with the debug key.

Each time you change a source file or resource, you must run Ant again in order to package up the latest version of
the application.

To install and run your application on an emulator, see the following section about Running Your Application.


Building in release mode
When you're ready to release and distribute your application to end-users, you must build your application in release
mode. Once you have built in release mode, it's a good idea to perform additional testing and debugging with the final
.apk.

To build in release mode:

 1. Open a command-line and navigate to the root of your project directory.
 2. Use Ant to compile your project in release mode:

           ant release

     This creates your Android application .apk file inside the project bin/ directory, named
     <your_DefaultActivity_name>.apk.
         Note: The .apk file is unsigned at this point. You can't install it on an emulator or device until you sign it with
         your private key.

Because release mode builds your application unsigned, your next step is to sign it with your private key, in order to
distribute it to end-users. To complete this procedure, read Signing Your Applications.

Once you have signed your application with a private key, you can install it on an emulator or device as discussed in
the following section about Running Your Application. You can also try installing it onto a device from a web server.
Simply upload the signed APK to a web site, then load the .apk URL in your Android web browser to download the
application and begin installation. (On your device, be sure you have enabled Settings > Applications > Unknown
sources.)



Running Your Application
http://developer.android.com/guide/developing/other-ide.html                                                           Page 4 of 6
Developing In Other IDEs | Android Developers                                                                  29.04.09 0:50




Unless you'll be running your application on device hardware, you need to launch an emulator upon which you will
install your application. An instance of the Android emulator runs a specific Android platform with specific device
configuration settings. The platform and configuration is defined with an Android Virtual Device (AVD). So before you
can launch your emulator, you must define an AVD.

If you'll be running your application on device hardware, please read about Developing On a Device instead.

 1. Create an AVD
       1. Open a command-line and navigate to your SDK package's tools/ directory.
       2. First, you need to select a "deployment target." To view available targets, execute:

                 android list targets

           This will output a list of available Android targets, such as:

                 id:1
                        Name: Android 1.1
                        Type: platform
                        API level: 2
                        Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P
                 id:2
                        Name: Android 1.5
                        Type: platform
                        API level: 3
                        Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P

           Find the target that matches the Android platform upon which you'd like to run your application. Note the
           integer value of the id — you'll use this in the next step.
       3. Create a new AVD using your selected deployment target:

                 android create avd --name <your_avd_name> --target <targetID>

       4. Next, you'll be asked whether you'd like to create a custom hardware profile. If you respond "yes," you'll be
          presented with a series of prompts to define various aspects of the device hardware (leave entries blank to
          use default values, which are shown in brackets). Otherwise, press return to use all default values ("no" is the
          default).

 2. Launch an emulator
     From your SDK's tools/ directory, launch an emulator using an existing AVD (created above):

           emulator -avd <your_avd_name>

     An instance of the emulator will now launch, running the target and configuration defined by your AVD.

 3. Install your application
     From your SDK's tools/ directory, install the .apk on the emulator:

           adb install /path/to/your/application.apk

     If there is more than one emulator running, you must specify the emulator upon which to install the application, by
     its serial number, with the -s option. For example:

           adb -s emulator-5554 install /my/project/path/myapp.apk

 4. Open your application
     In the emulator, open the list of available applications to find and open your application.

http://developer.android.com/guide/developing/other-ide.html                                                      Page 5 of 6
Developing In Other IDEs | Android Developers                                                                         29.04.09 0:50




If you don't see your application on the emulator. Try restarting the emulator (with the same AVD). Sometimes when
you install an Activity for the first time, it won't show up in the application launcher or be accessible by other
applications. This is because the package manager usually examines manifests completely only on emulator startup.

     Tip: If you have only one emulator running, you can build your application and install it on the emulator in one
     simple step. Navigate to the root of your project directory and use Ant to compile the project with install mode:
     ant install. This will build your application, sign it with the debug key, and install it on the currently running
     emulator. If there is more than one emulator currently running when using the install command, it will fail —
     it can't select between the multiple emulators.

For more information on the tools used above, please see the following documents:

     android Tool
     Android Emulator
     Android Debug Bridge (ADB)




Attaching a Debugger to Your Application
This section describes how to display debug information on the screen (such as CPU usage), as well as how to hook
up your IDE to debug running applications on the emulator.

Attaching a debugger is automated using the Eclipse plugin, but you can configure other IDEs to listen on a debugging
port to receive debugging information:

 1. Start the Dalvik Debug Monitor Server (DDMS) tool, which acts as a port forwarding service between your IDE
    and the emulator.
 2. Set optional debugging configurations on your emulator, such as blocking application startup for an Activity
    until a debugger is attached. Note that many of these debugging options can be used without DDMS, such as
    displaying CPU usage or screen refresh rate on the emulator.
 3. Configure your IDE to attach to port 8700 for debugging. Read about Configuring Your IDE to Attach to the
    Debugging Port.

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/developing/other-ide.html                                                            Page 6 of 6
Developing on a Device | Android Developers                                                                  29.04.09 0:50




Developing on a Device

When building mobile applications, it's vital to test them on real devices prior to releasing them to users. This page
covers what you need to know, including the types of devices that you can use, and how to set one up for developing
and debugging.



Available Devices
While developers can use regular consumer devices purchased at retail to test and use their apps, some developers
may choose not to use a retail device, preferring an unlocked or no-contract device. Here are some options for
obtaining devices capable of testing your applications.


T-Mobile G1
The T-Mobile G1 device makes an excellent development device. You can write applications in the SDK and install
them on the G1, then run them as users would, using the same hardware, system, and network.

For more information about obtaining a G1, visit the T-Mobile G1 site.


Android Dev Phone 1
The Android Dev Phone 1 is a SIM-unlocked and hardware-
unlocked device that is designed for advanced developers. The
                                                                         Selected specs for Android Dev Phone 1:
device ships with a system image that is fully compatible with
                                                                            Touch screen
Android 1.0, so you can rely on it when developing your
                                                                            Trackball
applications. You can use any SIM in the device and can flash
                                                                            3.2 megapixel camera with autofocus
custom Android builds that will work with the unlocked bootloader.          Wi-Fi
Unlike the bootloader on retail devices, the bootloader on the              GPS-enabled
Android Dev Phone 1 does not enforce signed system images. The              Bluetooth v2.0
Android Dev Phone 1 should also appeal to developers who live                  Handsfree profile v1.5
outside of T-Mobile geographies.                                               Headset profile v1.0
                                                                            3G WCDMA (1700/2100 MHz)
To purchase an Android Dev Phone 1 device, you must first                   Quad-band GSM (850/900/1800/1900 MHz)
register as an Android developer on the Android Market site, if you         QWERTY slider keyboard
haven't done so already. Once you've logged into your developer             Includes 1GB MicroSD card (can be
account on Android Market, you can purchase the device by                   replaced with up to 16GB card)
following the link to "Development phones." To accommodate
demand, there is a limit of 1 device per developer account, for now.

The device currently costs $399 (USD) (including free shipping in the US), and is available for purchase in 18
international markets, including the US, UK, Germany, Japan, India, Canada, France, Taiwan, Spain, Australia,
Singapore, Switzerland, Netherlands, Austria, Sweden, Finland, Poland, and Hungary. We will continue to expand this
program into new geographies over time. Check this page for updated information.

Note that Android Dev Phone 1 devices are not intended for non-developer end-users. Because the device can be
configured with system software not provided by or supported by Google or any other company, end-users operate
these devices at their own risk.



http://developer.android.com/guide/developing/device.html                                                      Page 1 of 3
Developing on a Device | Android Developers                                                                    29.04.09 0:50


For full device specs and more information about obtaining an Android Dev Phone 1 device, see the Android Market
site.



Setting up a Device for Development
With a T-mobile G1 or Android Dev Phone 1, you can develop and debug your Android applications just as you would
on the emulator. There are just a few things to do before you can start.

 1. Declare your application as "debuggable" in your Android Manifest.
     In Eclipse, you can do this from the Application tab when viewing the Manifest (on the right side, set
     Debuggable to true). Otherwise, in the AndroidManifest.xml file, add android:debuggable="true" to
     the <application> element.
 2. Turn on "USB Debugging" on your device.
     On the device, go to the home screen, press MENU, select Applications > Development, then enable USB
     debugging.
 3. Setup your system to detect your device.
           If you're developing on 32-bit Windows, you need to install the 32-bit USB driver for adb. The USB driver is
           included in the SDK package. To install it, follow these steps:
            1. Connect your Android device via USB. When the Found New Hardware Wizard appears, you'll be asked
               if you'd like Windows Update to search for software. Select No, not this time and click Next.
            2. Select Install from a list or specified location and click Next.
            3. Select Search for the best driver in these locations. Browse to the usb_driver/x86 in the SDK
               package (<sdk>\usb_driver\x86).
            4. Click Finish. The system should install the driver files as necessary. Your machine may require a reboot.

           If you're developing on 64-bit Windows Vista, you need to install the 64-bit USB driver for adb. The USB
           driver is included in the SDK package. To install it, follow these steps:
            1. Connect your Android device via USB. When the Found New Hardware Wizard appears, you'll be asked
               if you'd like Windows Update to search for software. Select No, not this time and click Next.
            2. Select Install from a list or specified location and click Next.
            3. Select Search for the best driver in these locations. Browse to the usb_driver/amd64 in the SDK
               package (<sdk>\usb_driver\amd64).
            4. Click Finish. The system should install the driver files as necessary. Your machine may require a reboot.

           If you're developing on Mac OS X, it just works. Skip this step.
           If you're developing on Ubuntu Linux, you need to add a rules file:
            1. Login as root and create this file: /etc/udev/rules.d/50-android.rules.
                 For Gusty/Hardy, edit the file to read:
                 SUBSYSTEM=="usb", SYSFS{idVendor}=="0bb4", MODE="0666"
                 For Dapper, edit the file to read:
                 SUBSYSTEM=="usb_device", SYSFS{idVendor}=="0bb4", MODE="0666"
            2. Now execute:
               chmod a+rx /etc/udev/rules.d/50-android.rules


You can verify that your device is connected by executing adb devices from your SDK tools/ directory. If connected,
you'll see the device name listed as a "device."

If using Eclipse, select run or debug as usual. You will be presented with a Device Chooser dialog that lists the
available emulator(s) and connected device(s). Select the device to install and run the application there.

http://developer.android.com/guide/developing/device.html                                                        Page 2 of 3
Developing on a Device | Android Developers                                                                           29.04.09 0:50




If using the Android Debug Bridge (adb), you can issue commands with the -d flag to target your connected device.

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/developing/device.html                                                               Page 3 of 3
Debugging Tasks | Android Developers                                                                          29.04.09 0:50




Debugging Tasks

This document offers some helpful guidance to debugging applications on Android.



Tools
The Android SDK includes a fairly extensive set of tools to help you debug your programs:

     DDMS - A graphical program that supports port forwarding (so you can set up breakpoints in your code in your
     IDE), screen captures on the emulator, thread and stack information, and many other features. You can also run
     logcat to retrieve your Log messages. See the linked topic for more information.
     logcat - Dumps a log of system messages. The messages include a stack trace when the emulator throws an
     error, as well as Log messages. To run logcat, see the linked topic.

          ...
          I/MemoryDealer( 763): MemoryDealer (this=0x54bda0): Creating 2621440 bytes heap
          at 0x438db000
          I/Logger( 1858): getView() requesting item number 0
          I/Logger( 1858): getView() requesting item number 1
          I/Logger( 1858): getView() requesting item number 2
          D/ActivityManager( 763): Stopping: HistoryRecord{409dbb20
          com.android.home.AllApps}
          ...

     Android Log- A logging class to print out messages to a log file on the emulator. You can read messages in real
     time if you run logcat on DDMS (covered next). Add a few logging method calls to your code.
     To use the Log class, you just call Log.v() (verbose), Log.d() (debug), Log.i() (information), Log.w()
     (warning) or Log.e (error) depending on the importance you wish to assign the log message.
     Log.i("MyActivity", "MyClass.getView() — Requesting item number " + position)
     You can use logcat to read these messages
     Traceview - Android can save a log of method calls and times to a logging file that you can view in a graphical
     reader called Traceview. See the linked topic for more information.

     Eclipse plugin - The ADT Plugin for Eclipse integrates a number of these tools (ADB, DDMS, logcat output, and
     other functionality). See the linked topic for more information.
     Debug and Test Device Settings - Android exposes several settings that expose useful information such as CPU
     usage and frame rate. See Debug and Test Settings on the Emulator below.

Also, see the Troubleshooting section of the doc to figure out why your application isn't appearing on the emulator, or
why it's not starting.



Debug and Test Settings
With the Dev Tools application, you can turn on a number of settings that will make it easier to test and debug your
applications. To get to the development settings page on the emulator, launch the Dev Tools application and open
Development Settings. This will open the development settings page with the following options (among others):

http://developer.android.com/guide/developing/debug-tasks.html                                                  Page 1 of 3
Debugging Tasks | Android Developers                                                                            29.04.09 0:50


Development Settings. This will open the development settings page with the following options (among others):

     Debug app Selects the application that will be debugged. You do not need to set this to attach a debugger, but
     setting this value has two effects:
           It will prevent Android from throwing an error if you pause on a breakpoint for a long time while debugging.
           It will enable you to select the Wait for Debugger option to pause application startup until your debugger
           attaches (described next).

     Wait for debugger Blocks the selected application from loading until a debugger attaches. This way you can set
     a breakpoint in onCreate(), which is important to debug the startup process of an Activity. When you change this
     option, any currently running instances of the selected application will be killed. In order to check this box, you
     must have selected a debug application as described in the previous option. You can do the same thing by
     adding waitForDebugger() to your code.
     Immediately destroy activities Tells the system to destroy an activity as soon as it is stopped (as if Android
     had to reclaim memory). This is very useful for testing the onSaveInstanceState(Bundle) /
     onCreate(android.os.Bundle) code path, which would otherwise be difficult to force. Choosing this option will
     probably reveal a number of problems in your application due to not saving state.
     Show screen updates Flashes a momentary pink rectangle on any screen sections that are being redrawn.
     This is very useful for discovering unnecessary screen drawing.
     Show CPU usage Displays CPU meters at the top of the screen, showing how much the CPU is being used.
     The top red bar shows overall CPU usage, and the green bar underneath it shows the CPU time spent in
     compositing the screen. Note: You cannot turn this feature off once it is on, without restarting the emulator.
     Show background Displays a background pattern when no activity screens are visible. This typically does not
     happen, but can happen during debugging.

These settings will be remembered across emulator restarts.



Top Debugging Tips
Quick stack dump
    To obtain a stack dump from emulator, you can log in with adb shell, use "ps" to find the process you want,
    and then "kill -3 ". The stack trace appears in the log file.

Displaying useful info on the emulator screen
    The device can display useful information such as CPU usage or highlights around redrawn areas. Turn these
    features on and off in the developer settings window as described in Setting debug and test configurations on the
    emulator.

Getting system state information from the emulator (dumpstate)
    You can access dumpstate information from the Dalvik Debug Monitor Service tool. See dumpsys and dumpstate
    on the adb topic page.

Getting application state information from the emulator (dumpsys)
    You can access dumpsys information from the Dalvik Debug Monitor Service tool. See dumpsys and dumpstate
    on the adb topic page.

Getting wireless connectivity information
    You can get information about wireless connectivity using the Dalvik Debug Monitor Service tool. From the Device
    menu, select "Dump radio state".

Logging Trace Data
    You can log method calls and other tracing data in an activity by calling android.os.Debug.startMethodTracing().
    See Running the Traceview Debugging Program for details.



http://developer.android.com/guide/developing/debug-tasks.html                                                    Page 2 of 3
Debugging Tasks | Android Developers                                                                                  29.04.09 0:50


Logging Radio Data
    By default, radio information is not logged to the system (it is a lot of data). However, you can enable radio
    logging using the following commands:


          adb shell
          logcat -b radio

Running adb
   Android ships with a tool called adb that provides various capabilities, including moving and syncing files to the
   emulator, forwarding ports, and running a UNIX shell on the emulator. See Using adb for details.

Getting screen captures from the emulator
    Dalvik Debug Monitor Server (DDMS) can capture screenshots from the emulator.

Using debugging helper classes
    Android provides debug helper classes such as util.Log and Debug for your convenience.



Configuring Your IDE to Attach to the Debugging Port
DDMS will assign a specific debugging port to every virtual machine that it finds on the emulator. You must either
attach your IDE to that port (listed on the Info tab for that VM), or you can use a default port 8700 to connect to
whatever application is currently selected on the list of discovered virtual machines.

Your IDE should attach to your application running on the emulator, showing you its threads and allowing you to
suspend them, inspect their state, and set breakpoints. If you selected "Wait for debugger" in the Development settings
panel the application will run when Eclipse connects, so you will need to set any breakpoints you want before
connecting.

Changing either the application being debugged or the "Wait for debugger" option causes the system to kill the
selected application if it is currently running. You can use this to kill your application if it is in a bad state by simply
going to the settings and toggling the checkbox.

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/developing/debug-tasks.html                                                          Page 3 of 3
Tools Overview | Android Developers                                                                           29.04.09 0:53




Tools Overview

The Android SDK includes a variety of custom tools that help you develop mobile applications on
the Android platform. The most important of these are the Android Emulator and the Android
Development Tools plugin for Eclipse, but the SDK also includes a variety of other tools for
debugging, packaging, and installing your applications on the emulator.

Android Development Tools Plugin (for the Eclipse IDE)
    The ADT plugin adds powerful extensions to the Eclipse integrated environment, making
    creating and debugging your Android applications easier and faster. If you use Eclipse, the
    ADT plugin gives you an incredible boost in developing Android applications.

Android Emulator
    A QEMU-based device-emulation tool that you can use to design, debug, and test your applications in an actual
    Android run-time environment.

Android Virtual Devices (AVDs)
    Virtual device configurations that you create, to model device characteristics in the Android Emulator. In each
    configuration, you can specify the Android platform to run, the hardware options, and the emulator skin to use.
    Each AVD functions as an independent device with it's own storage for user data, SD card, and so on.

Hierarchy Viewer
    The Hierarchy Viewer tool allows you to debug and optimize your user interface. It provides a visual
    representation of your layout's hierarchy of Views and a magnified inspector of the current display with a pixel
    grid, so you can get your layout just right.

Draw 9-patch
    The Draw 9-patch tool allows you to easily create a NinePatch graphic using a WYSIWYG editor. It also previews
    stretched versions of the image, and highlights the area in which content is allowed.

Dalvik Debug Monitor Service (ddms)
    Integrated with Dalvik, the Android platform's custom VM, this tool lets you manage processes on an emulator or
    device and assists in debugging. You can use it to kill processes, select a specific process to debug, generate
    trace data, view heap and thread information, take screenshots of the emulator or device, and more.

Android Debug Bridge (adb)
    The adb tool lets you install your application's .apk files on an emulator or device and access the emulator or
    device from a command line. You can also use it to link a standard debugger to application code running on an
    Android emulator or device.

Android Asset Packaging Tool (aapt)
    The aapt tool lets you create .apk files containing the binaries and resources of Android applications.

Android Interface Description Language (aidl)
    Lets you generate code for an interprocess interface, such as what a service might use.

sqlite3
     Included as a convenience, this tool lets you access the SQLite data files created and used by Android
     applications.

Traceview
    This tool produces graphical analysis views of trace log data that you can generate from your Android application.

http://developer.android.com/guide/developing/tools/index.html                                                  Page 1 of 2
Tools Overview | Android Developers                                                                                   29.04.09 0:53



mksdcard
   Helps you create a disk image that you can use with the emulator, to simulate the presence of an external storage
   card (such as an SD card).

dx
     The dx tool rewrites .class bytecode into Android bytecode (stored in .dex files.)

UI/Application Exerciser Monkey
    The Monkey is a program that runs on your emulator or device and generates pseudo-random streams of user
    events such as clicks, touches, or gestures, as well as a number of system- level events. You can use the
    Monkey to stress-test applications that you are developing, in a random yet repeatable manner.

android
    A script that lets you manage AVDs and generate Ant build files that you can use to compile your Android
    applications.

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/developing/tools/index.html                                                          Page 2 of 2
Using aapt | Android Developers                                                                                       29.04.09 0:53




Using aapt

aapt stands for Android Asset Packaging Tool and is included in the tools/ directory of the SDK. This tool allows
you to view, create, and update Zip-compatible archives (zip, jar, apk). It can also compile resources into binary
assets.

Though you probably won't often use aapt directly, build scripts and IDE plugins can utilize this tool to package the apk
file that constitutes an Android application.

For more usage details, open a terminal, go to the tools/ directory, and run the command:

     Linux or Mac OS X:

           ./aapt

     Windows:

           aapt.exe


                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/developing/tools/aapt.html                                                           Page 1 of 1
Android Debug Bridge | Android Developers                                                                       29.04.09 0:53




Android Debug Bridge
Android Debug Bridge (adb) is a versatile tool lets you manage the state of an emulator instance or Android-powered
device. It is a client-server program that includes three components:

     A client, which runs on your development machine. You can invoke a client from a shell by issuing an adb
     command. Other Android tools such as the ADT plugin and DDMS also create adb clients.
     A server, which runs as a background process on your development machine. The server manages
     communication between the client and the adb daemon running on an emulator or device.
     A daemon, which runs as a background process on each emulator or device instance.

When you start an adb client, the client first checks whether there is an adb server process already running. If there
isn't, it starts the server process. When the server starts, it binds to local TCP port 5037 and listens for commands
sent from adb clients—all adb clients use port 5037 to communicate with the adb server.

The server then sets up connections to all running emulator/device instances. It locates emulator/device instances by
scanning odd-numbered ports in the range 5555 to 5585, the range used by emulators/devices. Where the server
finds an adb daemon, it sets up a connection to that port. Note that each emulator/device instance acquires a pair of
sequential ports — an even-numbered port for console connections and an odd-numbered port for adb connections.
For example:

        Emulator    1,   console: 5554
        Emulator    1,   adb: 5555
        Emulator    2,   console: 5556
        Emulator    2,   adb: 5557 ...

As shown, the emulator instance connected to adb on port 5555 is the same as the instance whose console listens on
port 5554.

Once the server has set up connections to all emulator instances, you can use adb commands to control and access
those instances. Because the server manages connections to emulator/device instances and handles commands from
multiple adb clients, you can control any emulator/device instance from any client (or from a script).

The sections below describe the commands that you can use to access adb capabilities and manage the state of an
emulator/device. Note that if you are developing Android applications in Eclipse and have installed the ADT plugin, you
do not need to access adb from the command line. The ADT plugin provides a trasparent integration of adb into the
Eclipse IDE. However, you can still use adb directly as necessary, such as for debugging.



Issuing adb Commands
You can issue adb commands from a command line on your development machine or from a script. The usage is:


     adb [-d|-e|-s <serialNumber>] <command>

When you issue a command, the program invokes an adb client. The client is not specifically associated with any
emulator instance, so if multiple emulators/devices are running, you need to use the -d option to specify the target
instance to which the command should be directed. For more information about using this option, see Directing
Commands to a Specific Emulator/Device Instance.


http://developer.android.com/guide/developing/tools/adb.html                                                      Page 1 of 11
Android Debug Bridge | Android Developers                                                                         29.04.09 0:53




Querying for Emulator/Device Instances
Before issuing adb commands, it is helpful to know what emulator/device instances are connected to the adb server.
You can generate a list of attached emulators/devices using the devices command:


     adb devices

In response, adb prints this status information for each instance:

     Serial number — A string created by adb to uniquely identify an emulator/device instance by its console port
     number. The format of the serial number is <type>-<consolePort>. Here's an example serial number:
     emulator-5554
     State — The connection state of the instance. Three states are supported:
           offline — the instance is not connected to adb or is not responding.
           device — the instance is now connected to the adb server. Note that this state does not imply that the
           Android system is fully booted and operational, since the instance connects to adb while the system is still
           booting. However, after boot-up, this is the normal operational state of an emulator/device instance.

The output for each instance is formatted like this:

     [serialNumber] [state]

Here's an example showing the devices command and its output:


     $ adb devices
     List of devices attached
     emulator-5554 device
     emulator-5556 device
     emulator-5558 device

If there is no emulator/device running, adb returns no device.



Directing Commands to a Specific Emulator/Device Instance
If multiple emulator/device instances are running, you need to specify a target instance when issuing adb commands.
To so so, use the -s option in the commands. The usage for the -s option is:


     adb -s <serialNumber> <command>

As shown, you specify the target instance for a command using its adb-assigned serial number. You can use the
devices command to obtain the serial numbers of running emulator/device instances.

Here is an example:


     adb -s emulator-5556 install helloWorld.apk

Note that, if you issue a command without specifying a target emulator/device instance using -s, adb generates an
error.



http://developer.android.com/guide/developing/tools/adb.html                                                       Page 2 of 11
Android Debug Bridge | Android Developers                                                                      29.04.09 0:53




Installing an Application
You can use adb to copy an application from your development computer and install it on an emulator/device instance.
To do so, use the install command. With the command, you must specify the path to the .apk file that you want to
install:


     adb install <path_to_apk>

For more information about how to create an .apk file that you can install on an emulator/device instance, see Android
Asset Packaging Tool (aapt).

Note that, if you are using the Eclipse IDE and have the ADT plugin installed, you do not need to use adb (or aapt)
directly to install your application on the emulator/device. Instead, the ADT plugin handles the packaging and
installation of the application for you.



Forwarding Ports
You can use the forward command to set up arbitrary port forwarding — forwarding of requests on a specific host
port to a different port on an emulator/device instance. Here's how you would set up forwarding of host port 6100 to
emulator/device port 7100:


     adb forward tcp:6100 tcp:7100

You can also use adb to set up forwarding to named abstract UNIX domain sockets, as illustrated here:


     adb forward tcp:6100 local:logd




Copying Files to or from an Emulator/Device Instance
You can use the adb commands pull and push to copy files to and from an emulator/device instance's data file.
Unlike the install command, which only copies an .apk file to a specific location, the pull and push commands let
you copy arbitrary directories and files to any location in an emulator/device instance.

To copy a file or directory (recursively) from the emulator or device, use


     adb pull <remote> <local>

To copy a file or directory (recursively) to the emulator or device, use

     adb push <local> <remote>

In the commands, <local> and <remote> refer to the paths to the target files/directory on your development
machine (local) and on the emulator/device instance (remote).

Here's an example:


     adb push foo.txt /sdcard/foo.txt




http://developer.android.com/guide/developing/tools/adb.html                                                    Page 3 of 11
Android Debug Bridge | Android Developers                                                                              29.04.09 0:53




Listing of adb Commands
The table below lists all of the supported adb commands and explains their meaning and usage.

  Category            Command                                  Description                             Comments

  Options             -d                                       Direct an adb command to the only       Returns an error if
                                                               attached USB device.                    more than one USB
                                                                                                       device is attached.

                      -e                                       Direct an adb command to the only       Returns an error if
                                                               running emulator instance.              more than one
                                                                                                       emulator instance is
                                                                                                       running.

                      -s <serialNumber>                        Direct an adb command a specific        If not specified, adb
                                                               emulator/device instance, referred to   generates an error.
                                                               by its adb-assigned serial number
                                                               (such as "emulator-5556").

  General             devices                                  Prints a list of all attached           See Querying for
                                                               emulator/device instances.              Emulator/Device
                                                                                                       Instances for more
                                                                                                       information.

                      help                                     Prints a list of supported adb
                                                               commands.

                      version                                  Prints the adb version number.

  Debug               logcat [<option>]                        Prints log data to the screen.
                      [<filter-specs>]

                      bugreport                                Prints dumpsys, dumpstate, and
                                                               logcat data to the screen, for the
                                                               purposes of bug reporting.

                      jdwp                                     Prints a list of available JDWP         You can use the
                                                               processes on a given device.            forward
                                                                                                       jdwp:<pid> port-
                                                                                                       forwarding specification
                                                                                                       to connect to a specific
                                                                                                       JDWP process. For
                                                                                                       example:
                                                                                                       adb forward
                                                                                                       tcp:8000 jdwp:472
                                                                                                       jdb -attach
                                                                                                       localhost:8000


  Data                install <path-to-apk>                    Pushes an Android application
                                                               (specified as a full path to an .apk
                                                               file) to the data file of an
                                                               emulator/device.

                      pull <remote> <local>                    Copies a specified file from an
                                                               emulator/device instance to your
                                                               development computer.

                      push <local> <remote>                    Copies a specified file from your
                                                               development computer to an
                                                               emulator/device instance.

http://developer.android.com/guide/developing/tools/adb.html                                                            Page 4 of 11
Android Debug Bridge | Android Developers                                                                             29.04.09 0:53



  Ports and           forward <local> <remote>                 Forwards socket connections from a     Port specifications can
  Networking                                                   specified local port to a specified    use these schemes:
                                                               remote port on the emulator/device          tcp:<portnum>
                                                               instance.
                                                                                                          local:<UNIX
                                                                                                          domain socket
                                                                                                          name>
                                                                                                          dev:<character
                                                                                                          device name>
                                                                                                          jdwp:<pid>


                      ppp <tty> [parm]...                      Run PPP over USB.
                                                                   <tty> — the tty for PPP
                                                                   stream. For example
                                                                   dev:/dev/omap_csmi_ttyl.
                                                                   [parm]... — zero or more
                                                                   PPP/PPPD options, such as
                                                                   defaultroute, local,
                                                                   notty, etc.

                                                               Note that you should not
                                                               automatically start a PDP
                                                               connection.


  Scripting           get-serialno                             Prints the adb instance serial         See Querying for
                                                               number string.                         Emulator/Device
                                                                                                      Instances for more
                      get-state                                Prints the adb state of an             information.
                                                               emulator/device instance.

                      wait-for-device                          Blocks execution until the device is   You can prepend this
                                                               online — that is, until the instance   command to other adb
                                                               state is device.                       commands, in which
                                                                                                      case adb will wait until
                                                                                                      the emulator/device
                                                                                                      instance is connected
                                                                                                      before issuing the
                                                                                                      other commands.
                                                                                                      Here's an example:
                                                                                                          adb wait-
                                                                                                          for-device
                                                                                                          shell
                                                                                                          getprop

                                                                                                      Note that this
                                                                                                      command does not
                                                                                                      cause adb to wait until
                                                                                                      the entire system is
                                                                                                      fully booted. For that
                                                                                                      reason, you should not
                                                                                                      prepend it to other
                                                                                                      commands that require
                                                                                                      a fully booted system.
                                                                                                      As an example, the
                                                                                                      install requires the
                                                                                                      Android package
                                                                                                      manager, which is


http://developer.android.com/guide/developing/tools/adb.html                                                           Page 5 of 11
Android Debug Bridge | Android Developers                                                                             29.04.09 0:53


                                                                                                      available only after the
                                                                                                      system is fully booted.
                                                                                                      A command such as
                                                                                                          adb wait-
                                                                                                          for-device
                                                                                                          install
                                                                                                          <app>.apk

                                                                                                      would issue the
                                                                                                      install command as
                                                                                                      soon as the emulator
                                                                                                      or device instance
                                                                                                      connected to the adb
                                                                                                      server, but before the
                                                                                                      Android system was
                                                                                                      fully booted, so it
                                                                                                      would result in an
                                                                                                      error.

  Server              start-server                             Checks whether the adb server
                                                               process is running and starts it, if
                                                               not.

                      kill-server                              Terminates the adb server process.

  Shell               shell                                    Starts a remote shell in the target    See Issuing Shell
                                                               emulator/device instance.              Commands for more
                                                                                                      information.
                      shell [<shellCommand>]                   Issues a shell command in the
                                                               target emulator/device instance and
                                                               then exits the remote shell.




Issuing Shell Commands
Adb provides an ash shell that you can use to run a variety of commands on an emulator or device. The command
binaries are stored in the file system of the emulator or device, in this location:


     /system/bin/...

You can use the shell command to issue commands, with or without entering the adb remote shell on the
emulator/device.

To issue a single command without entering a remote shell, use the shell command like this:


     adb [-d|-e|-s {<serialNumber>}] shell <shellCommand>

To drop into a remote shell on a emulator/device instance, use the shell command like this:


     adb [-d|-e|-s {<serialNumber>}] shell

When you are ready to exit the remote shell, use CTRL+D or exit to end the shell session.

The sections below provide more information about shell commands that you can use.


Examining sqlite3 Databases from a Remote Shell
http://developer.android.com/guide/developing/tools/adb.html                                                           Page 6 of 11
Android Debug Bridge | Android Developers                                                                               29.04.09 0:53




From an adb remote shell, you can use the sqlite3 command-line program to manage SQLite databases created by
Android applications. The sqlite3 tool includes many useful commands, such as .dump to print out the contents of a
table and .schema to print the SQL CREATE statement for an existing table. The tool also gives you the ability to
execute SQLite commands on the fly.

To use sqlite3, enter a remote shell on the emulator instance, as described above, then invoke the tool using the
sqlite3 command. Optionally, when invoking sqlite3 you can specify the full path to the database you want to
explore. Emulator/device instances store SQLite3 databases in the folder
/data/data/<package_name>/databases/.

Here's an example:


     $ adb -s emulator-5554 shell
     # sqlite3 /data/data/com.example.google.rss.rssexample/databases/rssitems.db
     SQLite version 3.3.12
     Enter ".help" for instructions
     .... enter commands, then quit...
     sqlite> .exit

Once you've invoked sqlite3, you can issue sqlite3 commands in the shell. To exit and return to the adb remote
shell, use exit or CTRL+D.


UI/Application Exerciser Monkey
The Monkey is a program that runs on your emulator or device and generates pseudo-random streams of user events
such as clicks, touches, or gestures, as well as a number of system-level events. You can use the Monkey to stress-
test applications that you are developing, in a random yet repeatable manner.

The simplest way to use the monkey is with the following command, which will launch your application and send 500
pseudo-random events to it.


     $ adb shell monkey -v -p your.package.name 500

For more information about command options for Monkey, see the complete UI/Application Exerciser Monkey
documentation page.


Other Shell Commands
The table below lists several of the adb shell commands available. For a complete list of commands and programs,
start an emulator instance and use the adb -help command.


     adb shell ls /system/bin

Help is available for most of the commands.

  Shell Command                                            Description           Comments

  dumpsys                                                  Dumps system          The Dalvik Debug Monitor Service (DDMS)
                                                           data to the screen.   tool offers integrated debug environment that
                                                                                 you may find easier to use.
  dumpstate                                                Dumps state to a
                                                           file.

  logcat [<option>]... [<filter-                           Enables radio
  spec>]...                                                logging and prints
                                                           output to the
                                                           screen.

http://developer.android.com/guide/developing/tools/adb.html                                                             Page 7 of 11
Android Debug Bridge | Android Developers                                                                   29.04.09 0:53




  dmesg                                                    Prints kernel
                                                           debugging
                                                           messages to the
                                                           screen.

  start                                                    Starts (restarts) an
                                                           emulator/device
                                                           instance.

  stop                                                     Stops execution of
                                                           an emulator/device
                                                           instance.




Enabling logcat Logging
The Android logging system provides a mechanism for collecting and viewing system debug output. Logs from various
applications and portions of the system are collected in a series of circular buffers, which then can be viewed and
filtered by the logcat command.


Using logcat Commands
You can use the logcat command to view and follow the contents of the system's log buffers. The general usage is:


     [adb] logcat [<option>] ... [<filter-spec>] ...

The sections below explain filter specifications and the command options. See Listing of logcat Command Options for
a summary of options.

You can use the logcat command from your development computer or from a remote adb shell in an emulator/device
instance. To view log output in your development computer, you use


     $ adb logcat

and from a remote adb shell you use


     # logcat


Filtering Log Output
Every Android log message has a tag and a priority associated with it.

     The tag of a log message is a short string indicating the system component from which the message originates
     (for example, "View" for the view system).
     The priority is one of the following character values, ordered from lowest to highest priority:
           V — Verbose (lowest priority)
           D — Debug
           I — Info
           W — Warning
           E — Error
           F — Fatal


http://developer.android.com/guide/developing/tools/adb.html                                                 Page 8 of 11
Android Debug Bridge | Android Developers                                                                          29.04.09 0:53


           S — Silent (highest priority, on which nothing is ever printed)

You can obtain a list of tags used in the system, together with priorities, by running logcat and observing the first
two columns of each message, given as <priority>/<tag>.

Here's an example of logcat output that shows that the message relates to priority level "I" and tag "ActivityManager":


     I/ActivityManager( 585): Starting activity: Intent {
     action=android.intent.action...}

To reduce the log output to a manageable level, you can restrict log output using filter expressions. Filter expressions
let you indicate to the system the tags-priority combinations that you are interested in — the system suppresses other
messages for the specified tags.

A filter expression follows this format tag:priority ..., where tag indicates the tag of interest and priority
indicates the minimum level of priority to report for that tag. Messages for that tag at or above the specified priority are
written to the log. You can supply any number of tag:priority specifications in a single filter expression. The
series of specifications is whitespace-delimited.

Here's an example of a filter expression that suppresses all log messages except those with the tag "ActivityManager",
at priority "Info" or above, and all log messages with tag "MyApp", with priority "Debug" or above:

     adb logcat ActivityManager:I MyApp:D *:S

The final element in the above expression, *:S, sets the priority level for all tags to "silent", thus ensuring only log
messages with "View" and "MyApp" are displayed. Using *:S is an excellent way to ensure that log output is restricted
to the filters that you have explicitly specified — it lets your filters serve as a "whitelist" for log output.

The following filter expression displays all log messages with priority level "warning" and higher, on all tags:


     adb logcat *:W

If you're running logcat from your development computer (versus running it on a remote adb shell), you can also set
a default filter expression by exporting a value for the environment variable ANDROID_LOG_TAGS:


     export ANDROID_LOG_TAGS="ActivityManager:I MyApp:D *:S"

Note that ANDROID_LOG_TAGS filter is not exported to the emulator/device instance, if you are running logcat from a
remote shell or using adb shell logcat.


Controlling Log Output Format
Log messages contain a number of metadata fields, in addition to the tag and priority. You can modify the output
format for messages so that they display a specific metadata field. To do so, you use the -v option and specify one of
the supported output formats listed below.

     brief — Display priority/tag and PID of originating process (the default format).
     process — Display PID only.
     tag — Display the priority/tag only.
     thread — Display process:thread and priority/tag only.
     raw — Display the raw log message, with no other metadata fields.
     time — Display the date, invocation time, priority/tag, and PID of the originating process.
     long — Display all metadata fields and separate messages with a blank lines.


http://developer.android.com/guide/developing/tools/adb.html                                                        Page 9 of 11
Android Debug Bridge | Android Developers                                                                       29.04.09 0:53



When starting logcat, you can specify the output format you want by using the -v option:


     [adb] logcat [-v <format>]

Here's an example that shows how to generate messages in thread output format:


     adb logcat -v thread

Note that you can only specify one output format with the -v option.


Viewing Alternative Log Buffers
The Android logging system keeps multiple circular buffers for log messages, and not all of the log messages are sent
to the default circular buffer. To see additional log messages, you can start logcat with the -b option, to request
viewing of an alternate circular buffer. You can view any of these alternate buffers:

     radio — View the buffer that contains radio/telephony related messages.
     events — View the buffer containing events-related messages.
     main — View the main log buffer (default)

The usage of the -b option is:


     [adb] logcat [-b <buffer>]

Here's an example of how to view a log buffer containing radio and telephony messages:


     adb logcat -b radio


Viewing stdout and stderr
By default, the Android system sends stdout and stderr (System.out and System.err) output to /dev/null.
In processes that run the Dalvik VM, you can have the system write a copy of the output to the log file. In this case,
the system writes the messages to the log using the log tags stdout and stderr, both with priority I.

To route the output in this way, you stop a running emulator/device instance and then use the shell command
setprop to enable the redirection of output. Here's how you do it:


     $ adb shell stop
     $ adb shell setprop log.redirect-stdio true
     $ adb shell start

The system retains this setting until you terminate the emulator/device instance. To use the setting as a default on the
emulator/device instance, you can add an entry to /data/local.prop on the device.


Listing of logcat Command Options

  Option                    Description

  -b <buffer>               Loads an alternate log buffer for viewing, such as event or radio. The main buffer is used
                            by default. See Viewing Alternative Log Buffers.

  -c                        Clears (flushes) the entire log and exits.


http://developer.android.com/guide/developing/tools/adb.html                                                     Page 10 of 11
Android Debug Bridge | Android Developers                                                                              29.04.09 0:53


  -d                        Dumps the log to the screen and exits.

  -                         Writes log message output to <filename>. The default is stdout.
  f <filename>

  -g                        Prints the size of the specified log buffer and exits.

  -n <count>                Sets the maximum number of rotated logs to <count>. The default value is 4. Requires the
                            -r option.

  -r <kbytes>               Rotates the log file every <kbytes> of output. The default value is 16. Requires the -f
                            option.

  -s                        Sets the default filter spec to silent.

  -v <format>               Sets the output format for log messages. The default is brief format. For a list of supported
                            formats, see Controlling Log Output Format.




Stopping the adb Server
In some cases, you might need to terminate the adb server process and then restart it. For example, if adb does not
respond to a command, you can terminate the server and restart it and that may resolve the problem.

To stop the adb server, use the kill-server. You can then restart the server by issuing any adb command.

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/developing/tools/adb.html                                                            Page 11 of 11
Other Tools | Android Developers                                                                                    29.04.09 0:54




Other Tools

The sections below describe other tools that you can use when building Android applications.

All of the tools are included in the Android SDK and are accessible from the <sdk>/tools/ directory.



Contents
android
mksdcard
dx



android
The android tool is a script that lets you create and manage Android Virtual Devices (AVDs) and, if you are developing
using Ant, generate template Android projects to help you get started quickly.

For information about how to use the android tool to manage AVDs, see Android Virtual Devices.

For information about how to use the android tool to create or update a project, see Developing in Other IDEs.

Note that if you are developing in Eclipse with the ADT plugin, you will use the android tool to manage the AVDs you
create, but you will not use the android tool for creating a project. The ADT plugin provides a New Project Wizard that
helps you set up an Android project in Eclipse.

If you are developing in Ant, you will use the android tool to manage your AVDs, and you can also use it to create or
update a project.

     Note: The android tool replaces the activitycreator tool provided in previous SDK releases.



mksdcard
The mksdcard tool lets you quickly create a FAT32 disk image that you can load in the emulator, to simulate the
presence of an SD card in the device. Here is the usage for mksdcard:

     mksdcard [-l label] <size>[K|M] <file>

The table below lists the available options/arguments

  Argument            Description

  -l                  A volume label for the disk image to create.

  size                An integer that specifies the size (in bytes) of disk image to create. You can also specify size in
                      kilobytes or megabytes, by appending a "K" or "M" to <size>. For example, 1048576K, 1024M.

http://developer.android.com/guide/developing/tools/othertools.html#android                                            Page 1 of 2
Other Tools | Android Developers                                                                                      29.04.09 0:54




  file                The path/filename of the disk image to create.

Once you have created the disk image file, you can load it in the emulator at startup using the emulator's -sdcard
option. For more information, see Android Emulator.

     emulator -sdcard <file>




dx
The dx tool lets you generate Android bytecode from .class files. The tool converts target files and/or directories to
Dalvik executable format (.dex) files, so that they can run in the Android environment. It can also dump the class files
in a human-readable format and run a target unit test. You can get the usage and options for this tool by using dx --
help.

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/developing/tools/othertools.html#android                                             Page 2 of 2
Designing a Remote Interface Using AIDL | Android Developers                                                    29.04.09 0:54




Designing a Remote Interface Using AIDL

Since each application runs in its own process, and you can write a service that runs in a different process from your
Application's UI, sometimes you need to pass objects between processes. On the Android platform, one process can
not normally access the memory of another process. So to talk, they need to decompose their objects into primitives
that the operating system can understand, and "marshall" the object across that boundary for you.

The code to do that marshalling is tedious to write, so we provide the AIDL tool to do it for you.

AIDL (Android Interface Definition Language) is an IDL language used to generate code that enables two processes
on an Android-powered device to talk using interprocess communication (IPC). If you have code in one process (for
example, in an Activity) that needs to call methods on an object in another process (for example, a Service), you would
use AIDL to generate code to marshall the parameters.

The AIDL IPC mechanism is interface-based, similar to COM or Corba, but lighter weight. It uses a proxy class to
pass values between the client and the implementation.

This page includes the following main topics:

     Implementing IPC Using AIDL
     Calling an .aidl (IPC) Class




Implementing IPC Using AIDL
Follow these steps to implement an IPC service using AIDL.

 1. Create your .aidl file - This file defines an interface (YourInterface.aidl) that defines the methods and fields
    available to a client.
 2. Add the .aidl file to your makefile - (the ADT Plugin for Eclipse manages this for you). Android includes the
    compiler, called AIDL, in the tools/ directory.
 3. Implement your interface methods - The AIDL compiler creates an interface in the Java programming language
    from your AIDL interface. This interface has an inner abstract class named Stub that inherits the interface (and
    implements a few additional methods necessary for the IPC call). You must create a class that extends
    YourInterface.Stub and implements the methods you declared in your .aidl file.
 4. Expose your interface to clients - If you're writing a service, you should extend Service and override
    Service.onBind(Intent) to return an instance of your class that implements your interface.


Create an .aidl File
AIDL is a simple syntax that lets you declare an interface with one or more methods, that can take parameters and
return values. These parameters and return values can be of any type, even other AIDL-generated interfaces.
However, it is important to note that you must import all non-built-in types, even if they are defined in the same
package as your interface. Here are the data types that AIDL can support:

     Primitive Java programming language types (int, boolean, etc) — No import statement is needed.
     One of the following classes (no import statements needed):


http://developer.android.com/guide/developing/tools/aidl.html                                                     Page 1 of 9
Designing a Remote Interface Using AIDL | Android Developers                                                    29.04.09 0:54


           String
           List - All elements in the List must be one of the types in this list, including other AIDL-generated interfaces
           and parcelables. List may optionally be used as a "generic" class (e.g. List<String>). The actual concrete
           class that the other side will receive will always be an ArrayList, although the method will be generated to use
           the List interface.
           Map - All elements in the Map must be of one of the types in this list, including other AIDL-generated
           interfaces and parcelables. Generic maps, (e.g. of the form Map<String,Integer> are not supported. The
           actual concrete class that the other side will receive will always be a HashMap, although the method will be
           generated to use the Map interface.
           CharSequence - This is useful for the CharSequence types used by TextView and other widget objects.

     Other AIDL-generated interfaces, which are always passed by reference. An import statement is always needed
     for these.
     Custom classes that implement the Parcelable protocol and are passed by value. An import statement is always
     needed for these.

Here is the basic AIDL syntax:

     //   My AIDL file, named SomeClass.aidl
     //   Note that standard comment syntax is respected.
     //   Comments before the import or package statements are not bubbled up
     //   to the generated interface, but comments above interface/method/field
     //   declarations are added to the generated interface.

     // Include your fully-qualified package statement.
     package com.android.sample;
     // See the list above for which classes need
     // import statements (hint--most of them)
     import com.android.sample.IAtmService;

     // Declare the interface.
     interface IBankAccountService {
            // Methods can take 0 or more parameters, and
            // return a value or void.
            int getAccountBalance();
            void setOwnerNames(in List<String> names);

         // Methods can even take other AIDL-defined parameters.
         BankAccount createAccount(in String name, int startingDeposit, in IAtmService
     atmService);

         // All non-Java primitive parameters (e.g., int, bool, etc) require
         // a directional tag indicating which way the data will go. Available
         // values are in, out, inout. (Primitives are in by default, and cannot be
     otherwise).
         // Limit the direction to what is truly needed, because marshalling parameters
         // is expensive.
         int getCustomerList(in String branch, out String[] customerList);
     }


Implementing the Interface
AIDL generates an interface file for you with the same name as your .aidl file. If you are using the Eclipse plugin, AIDL
will automatically be run as part of the build process (you don't need to run AIDL first and then build your project). If
you are not using the plugin, you should run AIDL first.

The generated interface includes an abstract inner class named Stub that declares all the methods that you declared in
your .aidl file. Stub also defines a few helper methods, most notably asInterface(), which takes an IBinder (passed to a
client's onServiceConnected() implementation when applicationContext.bindService() succeeds), and returns an
instance of the interface used to call the IPC methods. See the section Calling an IPC Method for more details on how
http://developer.android.com/guide/developing/tools/aidl.html                                                      Page 2 of 9
Designing a Remote Interface Using AIDL | Android Developers                                                  29.04.09 0:54


instance of the interface used to call the IPC methods. See the section Calling an IPC Method for more details on how
to make this cast.

To implement your interface, extend YourInterface.Stub, and implement the methods. (You can create the .aidl file and
implement the stub methods without building between--the Android build process will process .aidl files before .java
files.)

Here is an example of implementing an interface called IRemoteService, which exposes a single method, getPid(),
using an anonymous instance:

     // No need to import IRemoteService if it's in the same project.
     private final IRemoteService.Stub mBinder = new IRemoteService.Stub(){
         public int getPid(){
             return Process.myPid();
         }
     }

A few rules about implementing your interface:

     No exceptions that you throw will be sent back to the caller.
     IPC calls are synchronous. If you know that an IPC service takes more than a few milliseconds to complete, you
     should not call it in the Activity/View thread, because it might hang the application (Android might display an
     "Application is Not Responding" dialog). Try to call them in a separate thread.
     Only methods are supported; you cannot declare static fields in an AIDL interface.


Exposing Your Interface to Clients
Now that you've got your interface implementation, you need to expose it to clients. This is known as "publishing your
service." To publish a service, inherit Service and implement Service.onBind(Intent) to return an instance of the class
that implements your interface. Here's a code snippet of a service that exposes the IRemoteService interface to
clients.


     public class RemoteService extends Service {
     ...
         @Override
         public IBinder onBind(Intent intent) {
             // Select the interface to return. If your service only implements
             // a single interface, you can just return it here without checking
             // the Intent.
             if (IRemoteService.class.getName().equals(intent.getAction())) {
                 return mBinder;
             }
             if (ISecondary.class.getName().equals(intent.getAction())) {
                 return mSecondaryBinder;
             }
             return null;
         }
            /**
             * The IRemoteInterface is defined through IDL
             */
            private final IRemoteService.Stub mBinder = new IRemoteService.Stub() {
                public void registerCallback(IRemoteServiceCallback cb) {
                    if (cb != null) mCallbacks.register(cb);
                }
                public void unregisterCallback(IRemoteServiceCallback cb) {
                    if (cb != null) mCallbacks.unregister(cb);
                }
            };
            /**
             * A secondary interface to the service.

http://developer.android.com/guide/developing/tools/aidl.html                                                   Page 3 of 9
Designing a Remote Interface Using AIDL | Android Developers                                                           29.04.09 0:54

             * A secondary interface to the service.
             */
            private final ISecondary.Stub mSecondaryBinder = new ISecondary.Stub() {
                public int getPid() {
                    return Process.myPid();
                }
                public void basicTypes(int anInt, long aLong, boolean aBoolean,
                        float aFloat, double aDouble, String aString) {
                }
            };
     }


Pass by value Parameters using Parcelables
If you have a class that you would like to send from one process to another through an AIDL interface, you can do
that. You must ensure that the code for your class is available to the other side of the IPC. Generally, that means that
you're talking to a service that you started.

There are five parts to making a class support the Parcelable protocol:

 1. Make your class implement the Parcelable interface.
 2. Implement the method public void writeToParcel(Parcel out) that takes the current state of the object
    and writes it to a parcel.
 3. Implement the method public void readFromParcel(Parcel in) that reads the value in a parcel into
    your object.
 4. Add a static field called CREATOR to your class which is an object implementing the Parcelable.Creator interface.
 5. Last but not least:
           If you are developing with Eclipse/ADT, follow these steps:
             a. In the Package Explorer view, right-click on the project.
             b. Choose Android Tools > Create Aidl preprocess file for Parcelable classes.
             c. This will create a file called "project.aidl" in the root of the project. The file will be automatically used
                when compiling an aidl file that uses the parcelable classes.

           If you are developing with Ant or are using a custom build process, create an aidl file that declares your
           parcelable class (as shown below). If you are using a custom build process, do not add the aidl file to your
           build. Similar to a header file in C, the aidl file isn't compiled.

     AIDL will use these methods and fields in the code it generates to marshall and unmarshall your objects.

     Here is an example of how the Rect class implements the Parcelable protocol.


           import android.os.Parcel;
           import android.os.Parcelable;

           public final class Rect implements Parcelable {
               public int left;
               public int top;
               public int right;
               public int bottom;

               public static final Parcelable.Creator<Rect> CREATOR = new
           Parcelable.Creator<Rect>() {
                   public Rect createFromParcel(Parcel in) {
                       return new Rect(in);
                   }

                         public Rect[] newArray(int size) {
                             return new Rect[size];
                         }

http://developer.android.com/guide/developing/tools/aidl.html                                                             Page 4 of 9
Designing a Remote Interface Using AIDL | Android Developers                                                     29.04.09 0:54

                         }
                  };

                  public Rect() {
                  }

                  private Rect(Parcel in) {
                      readFromParcel(in);
                  }

                  public void writeToParcel(Parcel out) {
                      out.writeInt(left);
                      out.writeInt(top);
                      out.writeInt(right);
                      out.writeInt(bottom);
                  }

                  public void readFromParcel(Parcel in) {
                      left = in.readInt();
                      top = in.readInt();
                      right = in.readInt();
                      bottom = in.readInt();
                  }
           }

     Here is Rect.aidl for this example

           package android.graphics;

           // Declare Rect so AIDL can find it and knows that it implements
           // the parcelable protocol.
           parcelable Rect;

     The marshalling in the Rect class is pretty simple. Take a look at the other methods on Parcel to see the other
     kinds of values you can write to a Parcel.

           Warning: Don't forget the security implications of receiving data from other processes. In this case, the rect
           will read four numbers from the parcel, but it is up to you to ensure that these are within the acceptable
           range of values for whatever the caller is trying to do. See Security and Permissions for more on how to
           keep your application secure from malware.



     Calling an IPC Method
     Here are the steps a calling class should make to call your remote interface:

       1. Declare a variable of the interface type that your .aidl file defined.
       2. Implement ServiceConnection.
       3. Call Context.bindService(), passing in your ServiceConnection implementation.
       4. In your implementation of ServiceConnection.onServiceConnected(), you will receive an IBinder instance
          (called service). Call YourInterfaceName.Stub.asInterface((IBinder)service) to cast the
          returned parameter to YourInterface type.
       5. Call the methods that you defined on your interface. You should always trap DeadObjectException exceptions,
          which are thrown when the connection has broken; this will be the only exception thrown by remote methods.
       6. To disconnect, call Context.unbindService() with the instance of your interface.

     A few comments on calling an IPC service:

           Objects are reference counted across processes.


http://developer.android.com/guide/developing/tools/aidl.html                                                       Page 5 of 9
Designing a Remote Interface Using AIDL | Android Developers                                             29.04.09 0:54


           You can send anonymous objects as method arguments.

     Here is some sample code demonstrating calling an AIDL-created service, taken from the Remote Activity sample
     in the ApiDemos project.

           public class RemoteServiceBinding extends Activity {
               /** The primary interface we will be calling on the service. */
               IRemoteService mService = null;
               /** Another interface we use on the service. */
               ISecondary mSecondaryService = null;

                  Button mKillButton;
                  TextView mCallbackText;

                  private boolean mIsBound;

                  /**
                   * Standard initialization of this activity. Set up the UI, then wait
                   * for the user to poke it before doing anything.
                   */
                  @Override
                  protected void onCreate(Bundle savedInstanceState) {
                      super.onCreate(savedInstanceState);

                         setContentView(R.layout.remote_service_binding);

                         // Watch for button clicks.
                         Button button = (Button)findViewById(R.id.bind);
                         button.setOnClickListener(mBindListener);
                         button = (Button)findViewById(R.id.unbind);
                         button.setOnClickListener(mUnbindListener);
                         mKillButton = (Button)findViewById(R.id.kill);
                         mKillButton.setOnClickListener(mKillListener);
                         mKillButton.setEnabled(false);

                         mCallbackText = (TextView)findViewById(R.id.callback);
                         mCallbackText.setText("Not attached.");
                  }

                  /**
                   * Class for interacting with the main interface of the service.
                   */
                  private ServiceConnection mConnection = new ServiceConnection() {
                      public void onServiceConnected(ComponentName className,
                              IBinder service) {
                          // This is called when the connection with the service has been
                          // established, giving us the service object we can use to
                          // interact with the service. We are communicating with our
                          // service through an IDL interface, so get a client-side
                          // representation of that from the raw service object.
                          mService = IRemoteService.Stub.asInterface(service);
                          mKillButton.setEnabled(true);
                          mCallbackText.setText("Attached.");
                                // We want to monitor the service for as long as we are
                                // connected to it.
                                try {
                                    mService.registerCallback(mCallback);
                                } catch (RemoteException e) {
                                    // In this case the service has crashed before we could even
                                    // do anything with it; we can count on soon being
                                    // disconnected (and then reconnected if it can be restarted)
                                    // so there is no need to do anything here.
                                }
                       // As part of the sample, tell the user what happened.
                       Toast.makeText(RemoteServiceBinding.this,
           R.string.remote_service_connected,


http://developer.android.com/guide/developing/tools/aidl.html                                              Page 6 of 9
Designing a Remote Interface Using AIDL | Android Developers                              29.04.09 0:54

           R.string.remote_service_connected,
                               Toast.LENGTH_SHORT).show();
                   }

                         public void onServiceDisconnected(ComponentName className) {
                             // This is called when the connection with the service has been
                             // unexpectedly disconnected -- that is, its process crashed.
                             mService = null;
                             mKillButton.setEnabled(false);
                             mCallbackText.setText("Disconnected.");
                       // As part of the sample, tell the user what happened.
                       Toast.makeText(RemoteServiceBinding.this,
           R.string.remote_service_disconnected,
                               Toast.LENGTH_SHORT).show();
                   }
               };

                  /**
                   * Class for interacting with the secondary interface of the service.
                   */
                  private ServiceConnection mSecondaryConnection = new ServiceConnection() {
                      public void onServiceConnected(ComponentName className,
                              IBinder service) {
                          // Connecting to a secondary interface is the same as any
                          // other interface.
                          mSecondaryService = ISecondary.Stub.asInterface(service);
                          mKillButton.setEnabled(true);
                      }
                         public void onServiceDisconnected(ComponentName className) {
                             mSecondaryService = null;
                             mKillButton.setEnabled(false);
                         }
                  };
                  private OnClickListener mBindListener = new OnClickListener() {
                      public void onClick(View v) {
                          // Establish a couple connections with the service, binding
                          // by interface names. This allows other applications to be
                          // installed that replace the remote service by implementing
                          // the same interface.
                          bindService(new Intent(IRemoteService.class.getName()),
                                  mConnection, Context.BIND_AUTO_CREATE);
                          bindService(new Intent(ISecondary.class.getName()),
                                  mSecondaryConnection, Context.BIND_AUTO_CREATE);
                          mIsBound = true;
                          mCallbackText.setText("Binding.");
                      }
                  };

               private OnClickListener mUnbindListener = new OnClickListener() {
                   public void onClick(View v) {
                       if (mIsBound) {
                           // If we have received the service, and hence registered with
                           // it, then now is the time to unregister.
                           if (mService != null) {
                               try {
                                   mService.unregisterCallback(mCallback);
                               } catch (RemoteException e) {
                                   // There is nothing special we need to do if the
           service
                                   // has crashed.
                               }
                           }

                                       // Detach our existing connection.
                                       unbindService(mConnection);
                                       unbindService(mSecondaryConnection);
                                       mKillButton.setEnabled(false);
                                       mIsBound = false;

http://developer.android.com/guide/developing/tools/aidl.html                                  Page 7 of 9
Designing a Remote Interface Using AIDL | Android Developers                           29.04.09 0:54

                                       mIsBound = false;
                                       mCallbackText.setText("Unbinding.");
                                }
                         }
                  };

                  private OnClickListener mKillListener = new OnClickListener() {
                      public void onClick(View v) {
                          // To kill the process hosting our service, we need to know its
                          // PID. Conveniently our service has a call that will return
                          // to us that information.
                          if (mSecondaryService != null) {
                              try {
                                  int pid = mSecondaryService.getPid();
                                  // Note that, though this API allows us to request to
                                  // kill any process based on its PID, the kernel will
                                  // still impose standard restrictions on which PIDs you
                                  // are actually able to kill. Typically this means only
                                  // the process running your application and any additional
                                  // processes created by that app as shown here; packages
                                  // sharing a common UID will also be able to kill each
                                  // other's processes.
                                  Process.killProcess(pid);
                                  mCallbackText.setText("Killed service process.");
                              } catch (RemoteException ex) {
                                  // Recover gracefully from the process hosting the
                                  // server dying.
                                  // Just for purposes of the sample, put up a notification.
                                  Toast.makeText(RemoteServiceBinding.this,
                                          R.string.remote_call_failed,
                                          Toast.LENGTH_SHORT).show();
                              }
                          }
                      }
                  };
                  // ----------------------------------------------------------------------
                  // Code showing how to deal with callbacks.
                  // ----------------------------------------------------------------------
               /**
                * This implementation is used to receive callbacks from the remote
                * service.
                */
               private IRemoteServiceCallback mCallback = new
           IRemoteServiceCallback.Stub() {
                   /**
                     * This is called by the remote service regularly to tell us about
                     * new values. Note that IPC calls are dispatched through a thread
                     * pool running in each process, so the code executing here will
                     * NOT be running in our main thread like most other things -- so,
                     * to update the UI, we need to use a Handler to hop over there.
                     */
                   public void valueChanged(int value) {
                        mHandler.sendMessage(mHandler.obtainMessage(BUMP_MSG, value, 0));
                   }
               };
                  private static final int BUMP_MSG = 1;
               private Handler mHandler = new Handler() {
                   @Override public void handleMessage(Message msg) {
                       switch (msg.what) {
                           case BUMP_MSG:
                               mCallbackText.setText("Received from service: " +
           msg.arg1);
                               break;
                           default:
                               super.handleMessage(msg);
                       }
                   }

http://developer.android.com/guide/developing/tools/aidl.html                            Page 8 of 9
Designing a Remote Interface Using AIDL | Android Developers                                                          29.04.09 0:54

                         }
                  };
           }

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/developing/tools/aidl.html                                                           Page 9 of 9
Android Virtual Devices | Android Developers                                                                   29.04.09 0:54




Android Virtual Devices

Android Virtual Devices (AVDs) are configurations of emulator options that let you better model an actual device.

Each AVD is made up of:

     A hardware profile. You can set options to define the hardware features of the virtual device. For example, you
     can define whether the device has a camera, whether it uses a physical QWERTY keyboard or a dialing pad, how
     much memory it has, and so on.
     A mapping to a system image. You can define what version of the Android platform will run on the virtual device.
     You can choose a version of the standard Android platform or the system image packaged with an SDK add-on.
     Other options. You can specify the emulator skin you want to use with the AVD, which lets you control the screen
     dimensions, appearance, and so on. You can also specify the emulated SD card to use with the AVD.
     A dedicated storage area on your development machine, in which is stored the device's user data (installed
     applications, settings, and so on) and emulated SD card.

You can create as many AVDs as you need, based on the types of devices you want to model and the Android
platforms and external libraries you want to run your application on.

In addition to the options in an AVD configuration, you can also specify emulator command-line options at launch or by
using the emulator console to change behaviors or characteristics at run time. For a complete reference of emulator
options, please see the Emulator documentation.

To create and manage AVDs, you use the android tool provided in the Android SDK. For more information about how
to work with AVDs from inside your development environment, see Developing in Eclipse with ADT or Developing in
Other IDEs, as appropriate for your environment.



Creating an AVD
To create an AVD, you use the android tool, a command-line utility
available in the <sdk>/tools/ directory. Managing AVDs is one of          The Android SDK does not include any
the two main function of the android tool (the other is creating and      preconfigured AVDs, so you need to create an
updating Android projects). Open a terminal window and change to          AVD before you can run any application in the
the <sdk>/tools/ directory, if needed                                     emulator (even the Hello World application).

To create each AVD, you issue the command android create avd, with options that specify a name for the new
AVD and the system image you want to run on the emulator when the AVD is invoked. You can specify other options
on the command line also, such as to create an emulated SD card for the new AVD, set the emulator skin to use, or
set a custom location for the AVD's files.

Here's the command-line usage for creating an AVD:

     android create avd -n <name> -t <targetID> [-<option> <value>] ...

You can use any name you want for the AVD, but since you are likely to be creating multiple AVDs, you should choose
a name that lets you recognize the general characteristics offered by the AVD.



http://developer.android.com/guide/developing/tools/avd.html                                                     Page 1 of 6
Android Virtual Devices | Android Developers                                                                 29.04.09 0:54


As shown in the usage above, you must use the -t (or --target) argument when creating a new AVD. The
argument sets up a mapping between the AVD and the system image that you want to use whenever the AVD is
invoked. You can specify any Android system image that is available in your local SDK — it can be the system image
of a standard Android platform version or that of any SDK add-on. Later, when applications use the AVD, they'll be
running on the system that you specify in the -t argument.

To specify the system image to use, you refer to its target ID — an integer — as assigned by the android tool. The
target ID is not derived from the system image name, version, or API Level, or other attribute, so you need to have the
android tool list the available system images and the target ID of each, as described in the next section. You should
do this before you run the android create avd command.


Listing targets
To generate a list of system image targets, use this command:

     android list targets

The android tool scans the <sdk>/platforms and <sdk>/add-ons directories looking for valid system images and
then generates the list of targets. Here's an example of the command output:


     Available Android targets:
     id:1
          Name: Android 1.1
          Type: platform
          API level: 2
          Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P
     id:2
          Name: Android 1.5
          Type: platform
          API level: 3
          Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P
     id:3
          Name: Google APIs
          Type: add-on
          Vendor: Google Inc.
          Description: Android + Google APIs
          Based on Android 1.5 (API level 3)
          Libraries:
          * com.google.android.maps (maps.jar)
              API for Google Maps
          Skins: HVGA (default), HVGA-L, QVGA-P, HVGA-P, QVGA-L


Selecting a target
Once you have generated the list of targets available, you can look at the characteristics of each system image —
name, API Level, external libraries, and so on — and determine which target is appropriate for the new AVD.

Keep these points in mind when you are selecting a system image target for your AVD:

     The API Level of the target is important, because your application will not be able to run on a system image
     whose API Level is less than that required by your application, as specified in the minSdkVersion attribute of
     the application's manifest file. For more information about the relationship between system API Level and
     application minSdkVersion, see Specifying Minimum System API Version.
     Creating at least one AVD that uses a target whose API Level is greater than that required by your application is
     strongly encouraged, because it allows you to test the forward-compatibility of your application. Forward-
     compatibility testing ensures that, when users who have downloaded your application receive a system update,
     your application will continue to function normally.
     If your application declares a uses-library element in its manifest file, the application can only run on a
     system image in which that external library is present. If you want your application to run on the AVD you are
http://developer.android.com/guide/developing/tools/avd.html                                                    Page 2 of 6
Android Virtual Devices | Android Developers                                                                  29.04.09 0:54


     system image in which that external library is present. If you want your application to run on the AVD you are
     creating, check the application's uses-library element and select a system image target that includes that
     library.


Creating the AVD
When you've selected the target you want to use and made a note of its ID, use the android create avd
command to create the AVD, supplying the target ID as the -t argument. Here's an example that creates an AVD with
name "my_android1.5" and target ID "2" (the standard Android 1.5 system image in the list above):

     android create avd -n my_android1.5 -t 2

If the target you selected was a standard Android system image ("Type: platform"), the android tool next asks you
whether you want to create a custom hardware profile.


     Android 1.5 is a basic Android platform.
     Do you wish to create a custom hardware profile [no]

If you want to set custom hardware emulation options for the AVD, enter "yes" and set values as needed. If you want
to use the default hardware emulation options for the AVD, just press the return key (the default is "no"). The android
tool creates the AVD with name and system image mapping you requested, with the options you specified.

     If you are creating an AVD whose target is an SDK add-on, the android tool does not allow you to set hardware
     emulation options. It assumes that the provider of the add-on has set emulation options appropriately for the
     device that the add-on is modeling, and so prevents you from resetting the options.

For a list of options you can use in the android create avd command, see the table in Command-line options for
AVDs, at the bottom of this page.


Setting hardware emulation options
When are creating a new AVD that uses a standard Android system image ("Type: platform"), the android tool lets you
set hardware emulation options for virtual device. The table below lists the options available and the default values, as
well as the names of properties that store the emulated hardware options in the AVD's configuration file (the config.ini
file in the AVD's local directory).

  Characteristic                     Description                                           Property

  Device ram size                    The amount of physical RAM on the device, in          hw.ramSize
                                     megabytes. Default value is "96".

  Touch-screen                       Whether there is a touch screen or not on the         hw.touchScreen
  support                            device. Default value is "yes".

  Trackball support                  Whether there is a trackball on the device. Default   hw.trackBall
                                     value is "yes".

  Keyboard support                   Whether the device has a QWERTY keyboard.             hw.keyboard
                                     Default value is "yes".

  DPad support                       Whether the device has DPad keys. Default value is    hw.dPad
                                     "yes".

  GSM modem support                  Whether there is a GSM modem in the device.           hw.gsmModem
                                     Default value is "yes".

  Camera support                     Whether the device has a camera. Default value is     hw.camera


http://developer.android.com/guide/developing/tools/avd.html                                                     Page 3 of 6
Android Virtual Devices | Android Developers                                                                          29.04.09 0:54


                                     "no".

  Maximum horizontal                 Default value is "640".                               hw.camera.maxHorizontalPixels
  camera pixels

  Maximum vertical                   Default value is "480".                               hw.camera.maxVerticalPixels
  camera pixels

  GPS support                        Whether there is a GPS in the device. Default value   hw.gps
                                     is "yes".

  Battery support                    Whether the device can run on a battery. Default      hw.battery
                                     value is "yes".

  Accelerometer                      Whether there is an accelerometer in the device.      hw.accelerometer
                                     Default value is "yes".

  Audio recording                    Whether the device can record audio. Default value    hw.audioInput
  support                            is "yes".

  Audio playback                     Whether the device can play audio. Default value is   hw.audioOutput
  support                            "yes".

  SD Card support                    Whether the device supports insertion/removal of      hw.sdCard
                                     virtual SD Cards. Default value is "yes".

  Cache partition                    Whether we use a /cache partition on the device.      disk.cachePartition
  support                            Default value is "yes".

  Cache partition size               Default value is "66MB".                              disk.cachePartition.size


Default location of the AVD files
When you create an AVD, the android tool creates a dedicated directory for it on your development computer. The
directory contains the AVD configuration file, the user data image and SD card image (if available), and any other files
associated with the device. Note that the directory does not contain a system image — instead, the AVD configuration
file contains a mapping to the system image, which it loads when the AVD is launched.

The android tool also creates a <AVD name>.ini file for the AVD at the root of the .android/avd directory on your
computer. The file specifies the location of the AVD directory and always remains at the root the .android directory.

By default, the android tool creates the AVD directory inside ~/.android/avd/ (on Linux/Mac), C:\Documents
and Settings\<user>\.android\ on Windows XP, and C:\Users\<user>\.android\ on Windows Vista. If
you want to use a custom location for the AVD directory, you can do so by using the -p <path> option when you
create the AVD:

     android create avd -n my_android1.5 -t 2 -p path/to/my/avd

If the .android directory is hosted on a network drive, we recommend using the -p option to place the AVD directory in
another location. The AVD's .ini file remains in the .android directory on the network drive, regardless of the location of
the AVD directory.



Managing AVDs
The sections below provide more information about how to manage AVDs once you've created them.




http://developer.android.com/guide/developing/tools/avd.html                                                            Page 4 of 6
Android Virtual Devices | Android Developers                                                                         29.04.09 0:54



Moving an AVD
If you want to move or rename an AVD, you can do so using this command:


     android move avd -n <name> [-<option> <value>] ...

The options for this command are listed in Command-line options for AVDs at the bottom of this page.


Updating an AVD
If, for any reason, the platform/add-on root folder has its name changed (maybe because the user has installed an
update of the platform/add-on) then the AVD will not be able to load the system image that it is mapped to. In this
case, the android list targets command will produce this output:


     The following Android Virtual Devices could not be loaded:
     Name: foo
     Path: <path>/.android/avd/foo.avd
     Error: Invalid value in image.sysdir. Run 'android update avd -n foo'

To fix this error, use the android update avd command to recompute the path to the system images.


Deleting an AVD
You can use the android tool to delete an AVD. Here is the command usage:

     android delete avd -n <name>

When you issue the command, the android tool looks for an AVD matching the specified name deletes the AVD's
directory and files.



Command-line options for AVDs
The table below lists the command-line options you can use with the android tool.

  Action                    Option                       Description                     Comments

  list avds                                              List all known AVDs, with
                                                         name, path, target, and skin.

  create avd                -n <name> or                 The name for the AVD.           Required

                            -t <targetID>                Target ID of the system image   Required. To obtain a list of
                                                         to use with the new AVD.        available targets, use android
                                                                                         list targets.

                            -c <path> or                 The path to the SD card image   Examples: -c path/to/sdcard
                            -c <size>[K|M]               to use with this AVD or the     or -c 1000M
                                                         size of a new SD card image
                                                         to create for this AVD.

                            -f                           Force creation of the AVD       By default, if the name of the AVD
                                                                                         being created matches that of an
                                                                                         existing AVD, the android tool will
                                                                                         not create the new AVD or
                                                                                         overwrite the existing AVD. If you

http://developer.android.com/guide/developing/tools/avd.html                                                           Page 5 of 6
Android Virtual Devices | Android Developers                                                                               29.04.09 0:54


                                                                                                specify the -f option, however, the
                                                                                                android tool will automatically
                                                                                                overwrite any existing AVD that has
                                                                                                the same name as the new AVD.
                                                                                                The files and data of the existing
                                                                                                AVD are deleted.

                            -p <path>                    Path to the location at which to
                                                         create the directory for this
                                                         AVD's files.

                            -s <name> or                 The skin to use for this AVD,          The android tool scans for a
                            -s <width>-                  identified by name or                  matching skin by name or
                            <height>                     dimensions.                            dimension in the skins/ directory
                                                                                                of the target referenced in the -t
                                                                                                <targetID> argument. Example:
                                                                                                -s HVGA-L

  delete avd                -n <name>                    Delete the specified AVD.              Required

  move avd                  -n <name>                    The name of the AVD to move.           Required

                            -p <path>                    The path to the new location
                                                         for the AVD.

                            -r <new-name>                Rename the AVD.

  update avds                                            Recompute the paths to all
                                                         system images.

                                                                                                                          ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/developing/tools/avd.html                                                                 Page 6 of 6
Using Dalvik Debug Monitor Service (DDMS) | Android Developers                                                 29.04.09 0:54




Using Dalvik Debug Monitor Service (DDMS)

Android ships with a debugging tool called the Dalvik Debug Monitor Service (DDMS), which provides port-forwarding
services, screen capture on the device, thread and heap information on the device, logcat, process, and radio state
information, incoming call and SMS spoofing, location data spoofing, and more. This page provides a modest
discussion of DDMS features; it is not an exhaustive exploration of all the features and capabilities.

DDMS ships in the tools/ directory of the SDK. Enter this directory from a terminal/console and type ddms (or
./ddms on Mac/Linux) to run it. DDMS will work with both the emulator and a connected device. If both are connected
and running simultaneously, DDMS defaults to the emulator.



How DDMS works
DDMS acts as a middleman to connect the IDE to the applications running on the device. On Android, every
application runs in its own process, each of which hosts its own virtual machine (VM). And each process listens for a
debugger on a different port.

When it starts, DDMS connects to adb and starts a device monitoring service between the two, which will notify DDMS
when a device is connected or disconnected. When a device is connected, a VM monitoring service is created
between adb and DDMS, which will notify DDMS when a VM on the device is started or terminated. Once a VM is
running, DDMS retrieves the the VM's process ID (pid), via adb, and opens a connection to the VM's debugger,
through the adb daemon (adbd) on the device. DDMS can now talk to the VM using a custom wire protocol.

For each VM on the device, DDMS opens a port upon which it will listen for a debugger. For the first VM, DDMS
listens for a debugger on port 8600, the next on 8601, and so on. When a debugger connects to one of these ports, all
traffic is forwarded between the debugger and the associated VM. Debugging can then process like any remote
debugging session.

DDMS also opens another local port, the DDMS "base port" (8700, by default), upon which it also listens for a
debugger. When a debugger connects to this base port, all traffic is forwarded to the VM currently selected in DDMS,
so this is typically where you debugger should connect.

For more information on port-forwarding with DDMS, read Configuring your IDE to attach to port 8700 for debugging.

     Tip: You can set a number of DDMS preferences in File > Preferences. Preferences are saved to
     "$HOME/.ddmsrc".

     Known debugging issues with Dalvik
     Debugging an application in the Dalvik VM should work the same as it does in other VMs. However, when
     single-stepping out of synchronized code, the "current line" cursor may jump to the last line in the method for
     one step.



Left Pane
The left side of the Debug Monitor shows each emulator/device currently found, with a list of all the VMs currently
running within each. VMs are identified by the package name of the application it hosts.



http://developer.android.com/guide/developing/tools/ddms.html                                                    Page 1 of 5
Using Dalvik Debug Monitor Service (DDMS) | Android Developers                                                   29.04.09 0:54


Use this list to find and attach to the VM running the activity(ies) that you want to debug. Next to each VM in the list is
a "debugger pass-through" port (in the right-most column). If you connect your debugger to one of the the ports listed,
you will be connected to the corresponding VM on the device. However, when using DDMS, you need only connect to
port 8700, as DDMS forwards all traffic here to the currently selected VM. (Notice, as you select a VM in the list, the
listed port includes 8700.) This way, there's no need to reconfigure the debugger's port each time you switch between
VMs.

When an application running on the device calls waitForDebugger() (or you select this option in the developer options),
a red icon will be shown next to the client name, while it waits for the debugger to attach to the VM. When a debugger
is connected, the icon will turn green.

If you see a crossed-out bug icon, this means that the DDMS was unable to complete a connection between the
debugger and the VM because it was unable to open the VM's local port. If you see this for all VMs on the device, it is
likely because you have another instance of DDMS running (this includes the Eclipse plugin).

If you see a question mark in place of an application package, this means that, once DDMS received the application
pid from adb, it somehow failed to make a successful handshake with the VM process. Try restarting DDMS.



Right pane
On the right side, the Debug Monitor provides tabs that display useful information and some pretty cool tools.


Info
This view shows some general information about the selected VM, including the process ID, package name, and VM
version.


Threads
The threads view has a list of threads running in the process of the target VM. To reduce the amount of data sent
over the wire, the thread updates are only sent when explicitly enabled by toggling the "threads" button in the toolbar.
This toggle is maintained per VM. This tab includes the following information:

     ID - a VM-assigned unique thread ID. In Dalvik, these are odd numbers starting from 3.
     Tid - the Linux thread ID. For the main thread in a process, this will match the process ID.
     Status - the VM thread status. Daemon threads are shown with an asterisk (*). This will be one of the following:
           running - executing application code
           sleeping - called Thread.sleep()
           monitor - waiting to acquire a monitor lock
           wait - in Object.wait()
           native - executing native code
           vmwait - waiting on a VM resource
           zombie - thread is in the process of dying
           init - thread is initializing (you shouldn't see this)
           starting - thread is about to start (you shouldn't see this either)

     utime - cumulative time spent executing user code, in "jiffies" (usually 10ms). Only available under Linux.
     stime - cumulative time spent executing system code, in "jiffies" (usually 10ms).
     Name - the name of the thread

"ID" and "Name" are set when the thread is started. The remaining fields are updated periodically (default is every 4
seconds).
http://developer.android.com/guide/developing/tools/ddms.html                                                      Page 2 of 5
Using Dalvik Debug Monitor Service (DDMS) | Android Developers                                                   29.04.09 0:54


seconds).


VM Heap
Displays some heap stats, updated during garbage collection. If, when a VM is selected, the VM Heap view says that
heap updates are not enabled, click the "Show heap updates" button, located in the top-left toolbar. Back in the VM
Heap view, click Cause GC to perform garbage collection and update the heap stats.


Allocation Tracker
In this view, you can track the memory allocation of each virtual machine. With a VM selected in the left pane, click
Start Tracking, then Get Allocations to view all allocations since tracking started. The table below will be filled with
all the relevant data. Click it again to refresh the list.


Emulator Control
With these controls, you can simulate special device states and activities. Features include:

     Telephony Status - change the state of the phone's Voice and Data plans (home, roaming, searching, etc.), and
     simulate different kinds of network Speed and Latency (GPRS, EDGE, UTMS, etc.).
     Telephony Actions - perform simulated phone calls and SMS messages to the emulator.
     Location Controls - send mock location data to the emulator so that you can perform location-aware operations
     like GPS mapping.
     To use the Location Controls, launch your application in the Android emulator and open DDMS. Click the
     Emulator Controls tab and scroll down to Location Controls. From here, you can:
           Manually send individual longitude/latitude coordinates to the device.
           Click Manual, select the coordinate format, fill in the fields and click Send.
           Use a GPX file describing a route for playback to the device.
           Click GPX and load the file. Once loaded, click the play button to playback the route for your location-aware
           application.
           When performing playback from GPX, you can adjust the speed of playback from the DDMS panel and
           control playback with the pause and skip buttons. DDMS will parse both the waypoints (<wpt>, in the first
           table), and the tracks (<trk>, in the second table, with support for multiple segments, <trkseg>, although
           they are simply concatenated). Only the tracks can be played. Clicking a waypoint in the first list simply sends
           its coordinate to the device, while selecting a track lets you play it.
           Use a KML file describing individual placemarks for sequenced playback to the device.
           Click KML and load the file. Once loaded, click the play button to send the coordinates to your location-aware
           application.
           When using a KML file, it is parsed for a <coordinates> element. The value of which should be a single
           set of longitude, latitude and altitude figures. For example:

                <coordinates>-122.084143,37.421972,4</coordinates>

           In your file, you may include multiple <Placemark> elements, each containing a <coordinates> element.
           When you do so, the collection of placemarks will be added as tracks. DDMS will send one placemark per
           second to the device.
           One way to generate a suitable KML file is to find a location in Google Earth. Right-click the location entry
           that appears on the left and select "Save place as..." with the save format set to Kml.
              Note: DDMS does not support routes created with the <MultiGeometry><LineString>lat1,
              long1, lat2, long2, ....</LineString></MultiGeometry> methods. There is also currently
              no support for the <TimeStamp> node inside the <Placemark>. Future releases may support timed
              placement and routes within a single coordinate element.

http://developer.android.com/guide/developing/tools/ddms.html                                                      Page 3 of 5
Using Dalvik Debug Monitor Service (DDMS) | Android Developers                                                29.04.09 0:54




     For additional methods of setting up mocks of location-based data, see the Location topic.




File Explorer
With the File Explorer, you can view the device file system and perform basic management, like pushing and pulling
files. This circumvents using the adb push and pull commands, with a GUI experience.

With DDMS open, select Device > File Explorer... to open the File Explorer window. You can drag-and-drop into the
device directories, but cannot drag out of them. To copy files from the device, select the file and click the Pull File
from Device button in the toolbar. To delete files, use the Delete button in the toolbar.

If you're interested in using an SD card image on the emulator, you're still required to use the mksdcard command to
create an image, and then mount it during emulator bootup. For example, from the /tools directory, execute:

     $ mksdcard 1024M ./img
     $ emulator -sdcard ./img

Now, when the emulator is running, the DDMS File Explorer will be able to read and write to the sdcard directory.
However, your files may not appear automatically. For example, if you add an MP3 file to the sdcard, the media player
won't see them until you restart the emulator. (When restarting the emulator from command line, be sure to mount the
sdcard again.)

For more information on creating an SD card image, see the Other Tools document.



Screen Capture
You can capture screen images on the device or emulator by selecting Device > Screen capture... in the menu bar,
or press CTRL-S.



Exploring Processes
You can see the output of ps -x for a specific VM by selecting Device > Show process status... in the menu bar.



Cause a GC to Occur
Cause garbage collection to occury by pressing the trash can button on the toolbar.



Running Dumpsys and Dumpstate on the Device (logcat)
     To run dumpsys (logcat) from Dalvik, select Device > Run logcat... in the menu bar.
     To run dumpstate from Dalvik, select Device > Dump device state... in the menu bar.




Examine Radio State

http://developer.android.com/guide/developing/tools/ddms.html                                                   Page 4 of 5
Using Dalvik Debug Monitor Service (DDMS) | Android Developers                                                        29.04.09 0:54



By default, radio state is not output during a standard logcat (it is a lot of information). To see radio information, either
click Device > Dump radio state... or run logcat as described in Logging Radio Information.



Stop a Virtual Machine
You can stop a virtual machine by selecting Actions > Halt VM. Pressing this button causes the VM to call
System.exit(1).



Known issues with DDMS
DDMS has the following known limitations:

     If you connect and disconnect a debugger, ddms drops and reconnects the client so the VM realizes that the
     debugger has gone away. This will be fixed eventually.

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/developing/tools/ddms.html                                                           Page 5 of 5
Draw 9-patch | Android Developers                                                                          29.04.09 0:54




Draw 9-patch

The Draw 9-patch tool allows you to easily create a NinePatch graphic using a WYSIWYG editor.

For an introduction to Nine-patch graphics and how they work, please read the section on Nine-patch in the Ninepatch
Images topic.

Here's a quick guide to create a Nine-patch graphic
using the Draw 9-patch tool. You'll need the PNG
image with which you'd like to create a NinePatch.

 1. From a terminal, launch the draw9patch
    application from your SDK /tools directory.
 2. Drag your PNG image into the Draw 9-patch
    window (or File > Open 9-patch... to locate the
    file). Your workspace will now open.
     The left pane is your drawing area, in which you
     can edit the lines for the stretchable patches
     and content area. The right pane is the preview
     area, where you can preview your graphic when
     stretched.
 3. Click within the 1-pixel perimeter to draw the
    lines that define the stretchable patches and
    (optional) content area. Right-click (or hold Shift
    and click, on Mac) to erase previously drawn
    lines.
 4. When done, select File > Save 9-patch...
     Your image will be saved with the .9.png file name.

     Note: A normal PNG file (*.png) will be loaded with an empty one-pixel border added around the image, in
     which you can draw the stretchable patches and content area. A previously saved 9-patch file (*.9.png) will be
     loaded as-is, with no drawing area added, because it already exists.

Optional controls include:

     Zoom: Adjust the zoom level of the graphic in
     the drawing area.
     Patch scale: Adjust the scale of the images in
     the preview area.
     Show lock: Visualize the non-drawable area of
     the graphic on mouse-over.
     Show patches: Preview the stretchable patches
     in the drawing area (pink is a stretchable
     patch).
     Show content: Highlight the content area in the
     preview images (purple is the area in which
     content is allowed).


http://developer.android.com/guide/developing/tools/draw9patch.html                                          Page 1 of 2
Draw 9-patch | Android Developers                                                                                     29.04.09 0:54


     Show bad patches: Adds a red border around
     patch areas that may produce artifacts in the
     graphic when stretched. Visual coherence of
     your stretched image will be maintained if you
     eliminate all bad patches.

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/developing/tools/draw9patch.html                                                     Page 2 of 2
Android Emulator | Android Developers                                                                                    29.04.09 0:54




Android Emulator
The Android SDK includes a mobile device emulator -- a virtual mobile
device that runs on your computer. The emulator lets you prototype,
develop, and test Android applications without using a physical device.

The Android emulator mimics all of the typical hardware and software
features of a typical mobile device, except that it can not receive or
place actual phone calls. It provides a variety of navigation and control
keys, which you can "press" using your mouse or keyboard to generate
events for your application. It also provides a screen in which your
application is displayed, together with any other Android applications
running.

To let you model and test your application more easily, the emulator
supports Android Virtual Device (AVD) configurations. AVDs let you
specify the Android platform that you want to run on the emulator, as
well as the hardware options and emulator skin files tht you want to use.
Once your application is running on the emulator, it can use the services
of the Android platform to invoke other applications, access the network,
play audio and video, store and retrieve data, notify the user, and render
graphical transitions and themes.

The emulator also includes a variety of debug capabilities, such as a
console from which you can log kernel output, simulate application
interrupts (such as arriving SMS messages or phone calls), and simulate
latency effects and dropouts on the data channel.

In this document:
  Overview                                    Using the Emulator Console
                                               Port Redirections
  Starting and Stopping the Emulator
                                               Geo Location Provider
  Android Virtual Devices and the              Emulation
  Emulator                                     Sending Events
                                               Emulating Device Power Characteristics
  Controlling the Emulator
                                               Network Status
  Emulator Startup Options                     Network Delay Emulation
                                               Network Speed Emulation
  Working with Emulator Disk Images
                                               Telephony Emulation
   Default Images
   Runtime Images: User Data and SD            SMS Emulation
                                               VM State
   Card
   Temporary Images                            Emulator Window
                                               Terminating an Emulator Instance
  Emulator Networking
                                              Using Emulator Skins
   Network Address Space
   Local Networking Limitations               Running Multiple Instances of the Emulator
   Using Network Redirections
                                              Installing Applications on the Emulator
   Configuring the Emulator's DNS Settings
   Using the Emulator with a Proxy            SD Card Emulation
   Interconnecting Emulator Instances          Creating an SD card image using the android tool
   Sending a Voice Call or SMS to Another      Creating an SD card image using mksdcard
   Emulator Instance                           Copying Files to a Disk Image
                                               Loading the Disk Image at Emulator Startup
                                              Troubleshooting Emulator Problems
                                              Emulator Limitations



Overview
The Android emulator is a QEMU-based application that provides a virtual ARM mobile device on which you can run
your Android applications. It runs a full Android system stack, down to the kernel level, that includes a set of
preinstalled applications (such as the dialer) that you can access from your applications. You can choose what version
http://developer.android.com/guide/developing/tools/emulator.html                                                         Page 1 of 20
Android Emulator | Android Developers                                                                                        29.04.09 0:54


preinstalled applications (such as the dialer) that you can access from your applications. You can choose what version
of the Android system you want to run in the emulator by configuring AVDs, and you can also customize the mobile
device skin and key mappings. When launching the emulator and at runtime, you can use a variety of commands and
options to control the its behaviors.

The Android system image distributed in the SDK contains ARM machine code for the Android Linux kernel, the native
libraries, the Dalvik VM, and the various Android package files (such as for for the Android framework and preinstalled
applications). The emulator's QEMU layers provide dynamic binary translation of the ARM machine code to the OS and
processor architecture of your development machine.

Adding custom capabilities to the underlying QEMU services, the Android emulator supports many hardware features
likely to be found on mobile devices, including:

    An ARMv5 CPU and the corresponding memory-management unit (MMU)
    A 16-bit LCD display
    One or more keyboards (a Qwerty-based keyboard and associated Dpad/Phone buttons)
    A sound chip with output and input capabilities
    Flash memory partitions (emulated through disk image files on the development machine)
    A GSM modem, including a simulated SIM Card

The sections below provide more information about the emulator and how to use it for developing Android applications.



Starting and Stopping the Emulator
During development and testing of your application, you install and run your application in the Android emulator. You
can launch the emulator as a standalone application, from a command line, or you can use it as part of your Eclipse
development environment. In either case, you specify the AVD configuration to load and any startup options you want
to use, as described in this document.

You can run your application on a single instance of the emulator or, depending on your needs, you can start multiple
emulator instances and run your application in more than one emulated device. You can use the emulator's built-in
commands to simulate GSM phone calling or SMS between emulator instances, and you can set up network
redirections that allow emulators to send data to one another. For more information, see Telephony Emulation, SMS
Emulation, and Emulator Networking

To start an instance of the emulator from the command line, change to the tools/ folder of the SDK. Enter
emulator command like this:

    emulator -avd <avd_name>

This initializes the emulator and loads an AVD configuration (see the next section for more information about AVDs).
You will see the emulator window appear on your screen.

If you are working in Eclipse, the ADT plugin for Eclipse installs your application and starts the emulator automatically,
when you run or debug the application. You can specify emulator startup options in the Run/Debug dialog, in the
Target tab. When the emulator is running, you can issue console commands as described later in this document.

If you are not working in Eclipse, see Installing Applications on the Emulator for information about how to install your
application.

To stop an emulator instance, just close the emulator's window.



Android Virtual Devices and the Emulator
To use the emulator, you first must create one or more AVD configurations. In each configuration, you specify an
Android platform to run in the emulator and the set of hardware options and emulator skin you want to use. Then,
when you launch the emulator, you specify the AVD configuration that you want to load.

To specify the AVD you want to load when starting the emulator, you use the -avd argument, as shown in the
previous section.

Each AVD functions as an independent device, with its own private storage for user data, SD card, and so on. When
you launch the emulator with an AVD configuration, it automatically loads the user data and SD card data from the
AVD directory. By default, the emulator stores the user data, SD card data, and cache in the AVD directory.

http://developer.android.com/guide/developing/tools/emulator.html                                                             Page 2 of 20
Android Emulator | Android Developers                                                                                    29.04.09 0:54


AVD directory. By default, the emulator stores the user data, SD card data, and cache in the AVD directory.

To create and manage AVDs you use the android tool, a command-line utility included in the SDK. For complete
information about how to set up AVDs, see Android Virtual Devices.



Controlling the Emulator
You can use emulator startup options and console commands to control the behaviors and characteristics of the
emulated environment itself.

When the emulator is running, you can interact with the emulated mobile device just as you would an actual mobile
device, except that you use your mouse pointer to "touch" the touchscreen and your keyboard keys to "press" the
simulated device keys.

The table below summarizes the mappings between the emulator keys and and the keys of your keyboard.

  Emulated Device Key                                                    Keyboard Key

  Home                                                                   HOME

  Menu (left softkey)                                                    F2 or Page-up button

  Star (right softkey)                                                   Shift-F2 or Page Down

  Back                                                                   ESC

  Call/dial button                                                       F3

  Hangup/end call button                                                 F4

  Search                                                                 F5

  Power button                                                           F7

  Audio volume up button                                                 KEYPAD_PLUS, Ctrl-5

  Audio volume down button                                               KEYPAD_MINUS, Ctrl-F6

  Camera button                                                          Ctrl-KEYPAD_5, Ctrl-F3

  Switch to previous layout orientation (for example, portrait,          KEYPAD_7, F11
  landscape)

  Switch to next layout orientation (for example, portrait, landscape)   KEYPAD_9, F12

  Toggle cell networking on/off                                          F8

  Toggle code profiling                                                  F9 (only with -trace startup option)

  Toggle fullscreen mode                                                 Alt-Enter

  Toggle trackball mode                                                  F6

  Enter trackball mode temporarily (while key is pressed)                Delete

  DPad left/up/right/down                                                KEYPAD_4/8/6/2

  DPad center click                                                      KEYPAD_5

  Onion alpha increase/decrease                                          KEYPAD_MULTIPLY(*) /
                                                                         KEYPAD_DIVIDE(/)

Note that, to use keypad keys, you must first disable NumLock on your development computer.



Emulator Startup Options
The emulator supports a variety of options that you can specify when launching the emulator, to control its appearance
or behavior. Here's the command-line usage for launching the emulator with options:




http://developer.android.com/guide/developing/tools/emulator.html                                                         Page 3 of 20
Android Emulator | Android Developers                                                                                               29.04.09 0:54


    emulator -avd <avd_name> [-<option> [<value>]] ... [-<qemu args>]

The table below summarizes the available options.

  Category       Option                          Description                      Comments

  Help           -help                           Print a list of all emulator
                                                 options.

                 -help-all                       Print help for all startup
                                                 options.

                 -help-<option>                  Print help for a specific
                                                 startup option.

                 -help-debug-tags                Print a list of all tags for -
                                                 debug <tags>.

                 -help-disk-images               Print help for using emulator
                                                 disk images.

                 -help-environment               Print help for emulator
                                                 environment variables.

                 -help-keys                      Print the current mapping of
                                                 keys.

                 -help-keyset-file               Print help for defining a
                                                 custom key mappings file.

                 -help-virtual-                  Print help for Android Virtual
                 device                          Device usage.

  AVD            -avd <avd_name> or              Required. Specifies the AVD      You must create an AVD configuration before launching the
                 @<avd_name>                     to load for this emulator        emulator. For information, see Android Virtual Devices.
                                                 instance.

  Disk           -cache <filepath>               Use <filepath> as the            Optionally, you can specify a path relative to the current
  Images                                         working cache partition          working directory. If no cache file is specified, the
                                                 image.                           emulator's default behavior is to use a temporary file
                                                                                  instead.
                                                                                  For more information on disk images, use -help-disk-
                                                                                  images.


                 -data <filepath>                Use <filepath> as the            Optionally, you can specify a path relative to the current
                                                 working user-data disk           working directory. If -data is not used, the emulator looks
                                                 image.                           for a file named "userdata-qemu.img" in the storage area of
                                                                                  the AVD being used (see -avd).

                 -                               When resetting the user-data     Optionally, you can specify a path relative to the current
                 initdata <filepath>             image (through -wipe-            working directory. See also -wipe-data.
                                                 data), copy the contents of      For more information on disk images, use -help-disk-
                                                 this file to the new user-data   images.
                                                 disk image. By default, the
                                                 emulator copies the
                                                 <system>/userdata.img.

                 -nocache                        Start the emulator without a     See also -cache <file>.
                                                 cache partition.

                 -ramdisk <filepath>             Use <filepath> as the            Default value is <system>/ramdisk.img.
                                                 ramdisk image.                   Optionally, you can specify a path relative to the current
                                                                                  working directory. For more information on disk images, use
                                                                                  -help-disk-images.


                 -sdcard <filepath>              Use <file> as the SD card        Default value is <system>/sdcard.img.
                                                 image.                           Optionally, you can specify a path relative to the current
                                                                                  working directory. For more information on disk images, use
                                                                                  -help-disk-images.


                 -wipe-data                      Reset the current user-data      See also -initdata.

http://developer.android.com/guide/developing/tools/emulator.html                                                                    Page 4 of 20
Android Emulator | Android Developers                                                                                              29.04.09 0:54


                                                 disk image (that is, the file    For more information on disk images, use -help-disk-
                                                 specified by -datadir and        images.
                                                 -data, or the default file).
                                                 The emulator deletes all data
                                                 from the user data image
                                                 file, then copies the contents
                                                 of the file at -inidata data
                                                 to the image file before
                                                 starting.

  Debug          -debug <tags>                   Enable/disable debug             <tags> is a space/comma/column-separated list of debug
                                                 messages for the specified       component names. Use -help-debug-tags to print a list
                                                 debug tags.                      of debug component names that you can use.

                 -debug-<tag>                    Enable/disable debug             Use -help-debug-tags to print a list of debug
                                                 messages for the specified       component names that you can use in <tag>.
                                                 debug tag.

                 -debug-no-<tag>                 Disable debug messages for
                                                 the specified debug tag.

                 -logcat <logtags>               Enable logcat output with        If the environment variable ANDROID_LOG_TAGS is
                                                 given tags.                      defined and not empty, its value will be used to enable
                                                                                  logcat output by default.

                 -shell                          Create a root shell console      You can use this command even if the adb daemon in the
                                                 on the current terminal.         emulated system is broken. Pressing Ctrl-c from the shell
                                                                                  stops the emulator instead of the shell.

                 -shell-                         Enable the root shell (as in -   <device> must be a QEMU device type. See the
                 serial <device>                 shell and specify the            documentation for 'serial -dev' at
                                                 QEMU character device to         http://www.bellard.org/qemu/qemu-doc.html#SEC10 for a
                                                 use for communication with       list of device types.
                                                 the shell.
                                                                                  Here are some examples:

                                                                                      -shell-serial stdio is identical to -shell
                                                                                      -shell-serial tcp::4444,server,nowait lets
                                                                                      you communicate with the shell over TCP port 4444
                                                                                      -shell-serial fdpair:3:6 lets a parent process
                                                                                      communicate with the shell using fds 3 (in) and 6 (out)
                                                                                      -shell-serial fdpair:0:1 uses the normal stdin
                                                                                      and stdout fds, except that QEMU won't tty-cook the
                                                                                      data.


                 -show-kernel <name>             Display kernel messages.

                 -trace <name>                   Enable code profiling (press
                                                 F9 to start), written to a
                                                 specified file.

                 -verbose                        Enable verbose output.           Equivalent to -debug-init.
                                                                                  You can define the default verbose output options used by
                                                                                  emulator instances in the Android environment variable
                                                                                  ANDROID_VERBOSE. Define the options you want to use
                                                                                  in a comma-delimited list, specifying only the stem of each
                                                                                  option: -debug-<tags>.

                                                                                  Here's an example showing ANDROID_VERBOSE defined
                                                                                  with the -debug-init and -debug-modem options:

                                                                                  ANDROID_VERBOSE=init,modem

                                                                                  For more information about debug tags, use <-help-
                                                                                  debug-tags>.


  Media          -audio <backend>                Use the specified audio
                                                 backend.

                 -audio-in <backend>             Use the specified audio-


http://developer.android.com/guide/developing/tools/emulator.html                                                                    Page 5 of 20
Android Emulator | Android Developers                                                                                               29.04.09 0:54


                                                 input backend.

                 -audio-out                      Use the specified audio-
                 <backend>                       output backend.

                 -noaudio                        Disable audio support in the
                                                 current emulator instance.

                 -radio <device>                 Redirect radio modem
                                                 interface to a host character
                                                 device.

                 -useaudio                       Enable audio support in the     Enabled by default.
                                                 current emulator instance.

  Network        -dns-server                     Use the specified DNS           The value of <servers> must be a comma-separated list
                 <servers>                       server(s).                      of up to 4 DNS server names or IP addresses.

                 -http-proxy <proxy>             Make all TCP connections        The value of <proxy> can be one of the following:
                                                 through a specified             http://<server>:<port>
                                                 HTTP/HTTPS proxy                http://<username>:<password>@<server>:<port>
                                                                                 The http:// prefix can be omitted. If the -http-proxy
                                                                                 <proxy> command is not supplied, the emulator looks up
                                                                                 the http_proxy environment variable and automatically
                                                                                 uses any value matching the <proxy> format described
                                                                                 above.


                 -netdelay <delay>               Set network latency             Default value is none. See the table in Network Delay
                                                 emulation to <delay>.           Emulation for supported <delay> values.

                 -netfast                        Shortcut for -netspeed
                                                 full -netdelay none

                 -netspeed <speed>               Set network speed emulation     Default value is full. See the table in Network Speed
                                                 to <speed>.                     Emulation for supported <speed> values.

                 -port <port>                    Set the console port number     The console port number must be an even integer between
                                                 for this emulator instance to   5554 and 5584, inclusive. <port>+1 must also be free and
                                                 <port>.                         will be reserved for ADB.

                 -report-console                 Report the assigned console     <socket> must use one of these formats:
                 <socket>                        port for this emulator          tcp:<port>[,server][,max=<seconds>]
                                                 instance to a remote third      unix:<port>[,server][,max=<seconds>]
                                                 party before starting the
                                                 emulation.                      Use -help-report-console

                                                                                 to view more information about this topic.

  System         -cpu-delay <delay>              Slow down emulated CPU          Supported values for <delay> are integers between 0 and
                                                 speed by <delay>                1000.
                                                                                 Note that the <delay> does not correlate to clock speed or
                                                                                 other absolute metrics — it simply represents an abstract,
                                                                                 relative delay factor applied non-deterministically in the
                                                                                 emulator. Effective performance does not always scale in
                                                                                 direct relationship with <delay> values.


                 -gps <device>                   Redirect NMEA GPS to            Use this command to emulate an NMEA-compatible GPS
                                                 character device.               unit connected to an external character device or socket.
                                                                                 The format of <device> must be QEMU-specific serial
                                                                                 device specification. See the documentation for 'serial -dev'
                                                                                 at http://www.bellard.org/qemu/qemu-doc.html#SEC10.

                 -nojni                          Disable JNI checks in the
                                                 Dalvik runtime.

                 -qemu                           Pass arguments to qemu.

                 -qemu -h                        Display qemu help.

                 -radio <device>                 Redirect radio mode to the      The format of <device> must be QEMU-specific serial
                                                 specified character device.     device specification. See the documentation for 'serial -dev'
                                                                                 at http://www.bellard.org/qemu/qemu-doc.html#SEC10.


http://developer.android.com/guide/developing/tools/emulator.html                                                                    Page 6 of 20
Android Emulator | Android Developers                                                                                              29.04.09 0:54


                 -timezone                       Set the timezone for the        <timezone> must be specified in zoneinfo format. For
                 <timezone>                      emulated device to              example:
                                                 <timezone>, instead of the      "America/Los_Angeles"
                                                 host's timezone.                "Europe/Paris"


                 -version                        Display the emulator's
                                                 version number.

  UI             -dpi-device <dpi>               Scale the resolution of the     The default value is 165. See also -scale.
                                                 emulator to match the
                                                 screen size of a physical
                                                 device.

                 -no-boot-anim                   Disable the boot animation      Disabling the boot animation can speed the startup time for
                                                 during emulator startup.        the emulator.

                 -no-window                      Disable the emulator's
                                                 graphical window display.

                 -scale <scale>                  Scale the emulator window.      <scale> is a number between 0.1 and 3 that represents
                                                                                 the desired scaling factor. You can also specify scale as a
                                                                                 DPI value if you add the suffix "dpi" to the scale value. A
                                                                                 value of "auto" tells the emulator to select the best window
                                                                                 size.

                 -raw-keys                       Disable Unicode keyboard
                                                 reverse-mapping.

                 -noskin                         Don't use any emulator skin.

                 -keyset <file>                  Use the specified keyset file   The keyset file defines the list of key bindings between the
                                                 instead of the default.         emulator and the host keyboard. For more information, use
                                                                                 -help-keyset to print information about this topic.

                 -onion <image>                  Use overlay image over          No support for JPEG. Only PNG is supported.
                                                 screen.

                 -onion-alpha                    Specify onion skin              Default is 50.
                 <percent>                       translucency value (as
                                                 percent).

                 -onion-rotation                 Specify onion skin rotation.    <position> must be one of the values 0, 1, 2, 3.
                 <position>

                 -skin <skinID>                  Start the emulator with the     The standard Android platforms includes a choice of four
                                                 specified skin.                 skins:
                                                                                   HVGA-L (480x320, landscape)
                                                                                   HVGA-P (320x480, portrait) (default)
                                                                                   QVGA-L (320x240, landscape)
                                                                                   QVGA-P (240x320, portrait)

                 -skindir <dir>                  Search for emulator skins in
                                                 <dir>.




Working with Emulator Disk Images
The emulator uses mountable disk images stored on your development machine to simulate flash (or similar) partitions
on an actual device. For example, it uses disk image containing an emulator-specific kernel, the Android system, a
ramdisk image, and writeable images for user data and simulated SD card.

To run properly, the emulator requires access to a specific set of disk image files. By default, the Emulator always
looks for the disk images in the private storage area of the AVD in use. If no images exist there when the Emulator is
launched, it creates the images in the AVD directory based on default versions stored in the SDK.

    Note: The default storage location for AVDs is in ~/.android/avd on OS X and Linux, C:\Documents and
    Settings\<user>\.android\ on Windows XP, and C:\Users\<user>\.android\ on Windows Vista.

To let you use alternate or custom versions of the image files, the emulator provides startup options that override the
default locations and filenames of the image files. When you use the options, the emulator searches for the image file

http://developer.android.com/guide/developing/tools/emulator.html                                                                    Page 7 of 20
Android Emulator | Android Developers                                                                                        29.04.09 0:54


under the image name or location that you specify; if it can not locate the image, it reverts to using the default names
and location.

The emulator uses three types of image files: default image files, runtime image files, and temporary image files. The
sections below describe how to override the location/name of each type of file.


Default Images
When the emulator launches but does not find an existing user data image in the active AVD's storage area, it creates
a new one from a default version included in the SDK. The default user data image is read-only. The image files are
read-only.

The emulator provides the -system <dir> startup option to let you override the location under which the emulator
looks for the default user data image.

The emulator also provides a startup option that lets you override the name of the default user data image, as
described in the table below. When you use the option, the emulator looks in the default directory, or in a custom
location (if you specified -system <dir>).

  Name                    Description                                Comments

  userdata.img            The initial user-data disk image           Override using -initdata <file>. Also see -
                                                                     data <file>, below.


Runtime Images: User Data and SD Card
At runtime, the emulator reads and writes data on two disk images: a user-data image and (optionally) an SD card
image. This emulates the user-data partition and removable storage media on actual device.

The emulator provides a default user-data disk image. At startup, the emulator creates the default image as a copy of
the system user-data image (user-data.img), described above. The emulator stores the new image with the files of the
active AVD.

The emulator provides startup options to let you override the actual names and storage locations of the runtime images
to load, as described in the table below. When you use one of these options, the emulator looks for the specified file(s)
in the current working directory, in the AVD directory, or in a custom location (if you specified a path with the
filename).

  Name                  Description                                 Comments

  userdata-             An image to which the emulator              Override using -data <filepath>, where
  qemu.img              writes runtime user-data for a unique       <filepath> is the path the image, relative to the
                        user.                                       current working directory. If you supply a filename
                                                                    only, the emulator looks for the file in the current
                                                                    working directory. If the file at <filepath> does
                                                                    not exist, the emulator creates an image from the
                                                                    default userdata.img, stores it under the name you
                                                                    specified, and persists user data to it at shutdown.

  sdcard.img            An image representing an SD card            Override using -sdcard <filepath>, where
                        inserted into the emulated device.          <filepath> is the path the image, relative to the
                                                                    current working directory. If you supply a filename
                                                                    only, the emulator looks for the file in the current
                                                                    working directory.

User-Data Image
Each emulator instance uses a writeable user-data image to store user- and session-specific data. For example, it
uses the image to store a unique user's installed application data, settings, databases, and files.

At startup, the emulator attempts to load a user-data image stored during a previous session. It looks for the file in the
current working directory, in the AVD directory as described above, and at the custom location/name that you specified
at startup.

    If it finds a user-data image, it mounts the image and makes it available to the system for reading/writing of user
    data.
    If it does not find one, it creates an image by copying the system user-data image (userdata.img), described
    above. At device power-off, the system persists the user data to the image, so that it will be available in the next
    session. Note that the emulator stores the new disk image at the location/name that you specify in -data startup
    option.

http://developer.android.com/guide/developing/tools/emulator.html                                                             Page 8 of 20
Android Emulator | Android Developers                                                                                   29.04.09 0:54


    option.

    Note: Because of the AVD configurations used in the emulator, each emulator instance now gets its own
    dedicated storage. There is no need to use the -d option to specify an instance-specific storage area.

SD Card
Optionally, you can create a writeable disk image that the emulator can use to simulate removeable storage in an
actual device. For information about how to create an emulated SD card and load it in the emulator, see SD Card
Emulation

You can also use the android tool to automatically create an SD Card image for you, when creating an AVD. For more
information, see Command-line options for AVDs.


Temporary Images
The emulator creates two writeable images at startup that it deletes at device power-off. The images are:

    A writable copy of the Android system image
    The /cache partition image

The emulator does not permit renaming the temporary system image or persisting it at device power-off.

The /cache partition image is initially empty, and is used by the browser to cache downloaded web pages and
images. The emulator provides an -cache <file>, which specifies the name of the file at which to persist the
/cache image at device power-off. If <file> does not exist, the emulator creates it as an empty file.

You can also disable the use of the cache partition by specifying the -nocache option at startup.



Emulator Networking
The emulator provides versatile networking capabilities that you can use to set up complex modeling and testing
environments for your application. The sections below introduce the emulator's network architecture and capabilities.


Network Address Space
Each instance of the emulator runs behind a virtual router/firewall service that isolates it from your development
machine's network interfaces and settings and from the internet. An emulated device can not see your development
machine or other emulator instances on the network. Instead, it sees only that it is connected through Ethernet to a
router/firewall.

The virtual router for each instance manages the 10.0.2/24 network address space — all addresses managed by the
router are in the form of 10.0.2.<xx>, where <xx> is a number. Addresses within this space are pre-allocated by the
emulator/router as follows:

  Network Address                  Description

  10.0.2.1                         Router/gateway address

  10.0.2.2                         Special alias to your host loopback interface (i.e., 127.0.0.1 on your development
                                   machine)

  10.0.2.3                         First DNS server

  10.0.2.4 / 10.0.2.5 /            Optional second, third and fourth DNS server (if any)
  10.0.2.6

  10.0.2.15                        The emulated device's own network/ethernet interface

  127.0.0.1                        The emulated device's own loopback interface

Note that the same address assignments are used by all running emulator instances. That means that if you have two
instances running concurrently on your machine, each will have its own router and, behind that, each will have an IP
address of 10.0.2.15. The instances are isolated by a router and can not see each other on the same network. For
information about how to let emulator instances communicate over TCP/UDP, see Connecting Emulator Instances.

Also note that the address 127.0.0.1 on your development machine corresponds to the emulator's own loopback
interface. If you want to access services running on your development machine's loopback interface (a.k.a. 127.0.0.1
on your machine), you should use the special address 10.0.2.2 instead.

http://developer.android.com/guide/developing/tools/emulator.html                                                        Page 9 of 20
Android Emulator | Android Developers                                                                                        29.04.09 0:54


on your machine), you should use the special address 10.0.2.2 instead.

Finally, note that each emulated device's pre-allocated addresses are specific to the Android emulator and will
probably be very different on real devices (which are also very likely to be NAT-ed, i.e., behind a router/firewall)


Local Networking Limitations
Each emulator instance runs behind a virtual router, but unlike an actual device connected to a physical router, the
emulated device doesn't have access to a physical network. Instead it runs as part of a normal application on your
development machine. This means that it is subject to the same networking limitations as other applications on your
machine:

    Communication with the emulated device may be blocked by a firewall program running on your machine.
    Communication with the emulated device may be blocked by another (physical) firewall/router to which your
    machine is connected.

The emulator's virtual router should be able to handle all outbound TCP and UDP connections/messages on behalf of
the emulated device, provided your development machine's network environment allows it to do so. There are no built-
in limitations on port numbers or ranges except the one imposed by your host operating system and network.

Depending on the environment, the emulator may not be able to support other protocols (such as ICMP, used for
"ping") might not be supported. Currently, the emulator does not support IGMP or multicast.


Using Network Redirections
To communicate with an emulator instance behind its virtual router, you need to set up network redirections on the
virtual router. Clients can then connect to a specified guest port on the router, while the router directs traffic to/from
that port to the emulated device's host port.

To set up the network redirections, you create a mapping of host and guest ports/addresses on the the emulator
instance. There are two ways to set up network redirections: using emulator console commands and using the ADB
tool, as described below.

Setting up Redirections through the Emulator Console
Each emulator instance provides a control console the you can connect to, to issue commands that are specific to that
instance. You can use the redir console command to set up redirections as needed for an emulator instance.

First, determine the console port number for the target emulator instance. For example, the console port number for
the first emulator instance launched is 5554. Next, connect to the console of the target emulator instance, specifying its
console port number, as follows:


    telnet localhost 5554

Once connected, use the redir command to work with redirections. To add a redirection, use:.

    add <protocol>:<host-port>:<guest-port>

where <protocol> is either tcp or udp, and <host-port> and <guest-port> sets the mapping between your
own machine and the emulated system, respectively.

For example, the following command sets up a redirection that will handle all incoming TCP connections to your host
(development) machine on 127.0.0.1:5000 and will pass them through to the emulated system's 10.0.2.15:6000.:

    redir add tcp:5000:6000

To delete a redirection, you can use the redir del command. To list all redirections for a specific instance, you can
use redir list. For more information about these and other console commands, see Using the Emulator Console.

Note that port numbers are restricted by your local environment. this typically means that you cannot use host port
numbers under 1024 without special administrator privileges. Also, you won't be able to set up a redirection for a host
port that is already in use by another process on your machine. In that case, redir generates an error message to
that effect.

Setting Up Redirections through ADB
The Android Debug Bridge (ADB) tool provides port forwarding, an alternate way for you to set up network
redirections. For more information, see Forwarding Ports in the ADB documentation.

http://developer.android.com/guide/developing/tools/emulator.html                                                            Page 10 of 20
Android Emulator | Android Developers                                                                                    29.04.09 0:54


redirections. For more information, see Forwarding Ports in the ADB documentation.

Note that ADB does not currently offer any way to remove a redirection, except by killing the ADB server.


Configuring the Emulator's DNS Settings
At startup, the emulator reads the list of DNS servers that your system is currently using. It then stores the IP
addresses of up to four servers on this list and sets up aliases to them on the emulated addresses 10.0.2.3, 10.0.2.4,
10.0.2.5 and 10.0.2.6 as needed.

On Linux and OS X, the emulator obtains the DNS server addresses by parsing the file /etc/resolv.conf. On
Windows, the emulator obtains the addresses by calling the GetNetworkParams() API. Note that this usually means
that the emulator ignores the content of your "hosts" file (/etc/hosts on Linux/OS X,
%WINDOWS%/system32/HOSTS on Windows).

When starting the emulator at the command line, you can also use the -dns-server <serverList> option to
manually specify the addresses of DNS servers to use, where <serverList> is a comma-separated list of server names
or IP addresses. You might find this option useful if you encounter DNS resolution problems in the emulated network
(for example, an "Unknown Host error" message that appears when using the web browser).


Using the Emulator with a Proxy
If your emulator must access the Internet through a proxy server, you can use the -http-proxy <proxy> option
when starting the emulator, to set up the appropriate redirection. In this case, you specify proxy information in
<proxy> in one of these formats:


     http://<machineName>:<port>

or

     http://<username>:<password>@<machineName>:<port>

The -http-proxy option forces the emulator to use the specified HTTP/HTTPS proxy for all outgoing TCP
connections. Redirection for UDP is not currently supported.

Alternatively, you can define the environment variable http_proxy to the value you want to use for <proxy>. In this
case, you do not need to specify a value for <proxy> in the -http-proxy command — the emulator checks the
value of the http_proxy environment variable at startup and uses its value automatically, if defined.

You can use the -verbose-proxy option to diagnose proxy connection problems.


Interconnecting Emulator Instances
To allow one emulator instance to communicate with another, you must set up the necessary network redirections as
illustrated below.

Assume that your environment is

     A is you development machine
     B is your first emulator instance, running on A
     C is your second emulator instance, running on A too

and you want to run a server on B, to which C will connect, here is how you could set it up:

 1. Set up the server on B, listening to 10.0.2.15:<serverPort>
 2. On B's console, set up a redirection from A:localhost:<localPort> to B:10.0.2.15:<serverPort>
 3. On C, have the client connect to 10.0.2.2:<localPort>

For example, if you wanted to run an HTTP server, you can select <serverPort> as 80 and <localPort> as 8080:

     B listens on 10.0.2.15:80
     On B's console, issue redir add tcp:8080:80
     C connects to 10.0.2.2:8080




http://developer.android.com/guide/developing/tools/emulator.html                                                        Page 11 of 20
Android Emulator | Android Developers                                                                                    29.04.09 0:54


Sending a Voice Call or SMS to Another Emulator Instance
The emulator automatically forwards simulated voice calls and SMS messages from one instance to another. To send
a voice call or SMS, you use the dialer application and SMS application (if available) installed on one emulator

To initiate a simulated voice call to another emulator instance:

 1. Launch the dialer application on the originating emulator instance.
 2. As the number to dial, enter the console port number of the instance you'd like to call. You can determine the
    console port number of the target instance by checking its window title, where the console port number is reported
    as "Android Emulator (<port>).
 3. Press "Dial". A new inbound call appears in the target emulator instance.

To send an SMS message to another emulator instance, launch the SMS application (if available). Specify the console
port number of the target emulator instance as as the SMS address, enter the message text, and send the message.
The message is delivered to the target emulator instance.

You can also connect to an emulator instance's console to simulate an incoming voice call or SMS. For more
information, see Telephony Emulation and SMS Emulation.



Using the Emulator Console
Each running emulator instance includes a console facility that lets you dynamically query and control the simulated
device environment. For example, you can use the console to dynamically manage port redirections and network
characteristics and simulate telephony events. To access the console and enter commands, you use telnet to connect
to the console's port number.

To connect to the console of any running emulator instance at any time, use this command:


    telnet localhost <console-port>

An emulator instance occupies a pair of adjacent ports: a console port and an adb port. The port numbers differ by 1,
with the adb port having the higher port number. The console of the first emulator instance running on a given
machine uses console port 5554 and adb port 5555. Subsequent instances use port numbers increasing by two — for
example, 5556/5557, 5558/5559, and so on. Up to 16 concurrent emulator instances can run a console facility.

To connect to the emulator console, you must specify a valid console port. If multiple emulator instances are running,
you need to determine the console port of the emulator instance you want to connect to. You can find the instance's
console port listed in the title of the instance window. For example, here's the window title for an instance whose
console port is 5554:

Android Emulator (5554)

Alternatively, you can use the adb devices command, which prints a list of running emulator instances and their
console port numbers. For more information, see Querying for Emulator/Device Instances in the adb documentation.

    Note: The emulator listens for connections on ports 5554-5587 and accepts connections only from localhost.

Once you are connected to the console, you can then enter help [command] to see a list of console commands and
learn about specific commands.

To exit the console session, use quit or exit.

The sections below describe the major functional areas of the console.


Port Redirection
You can use the console to add and remove port redirections while the emulator is running. After connecting to the
console, you can manage port redirections in this way:


    redir <list|add|del>

The redir command supports the subcommands listed in the table below.

  Subcommand                            Description                         Comments


http://developer.android.com/guide/developing/tools/emulator.html                                                        Page 12 of 20
Android Emulator | Android Developers                                                                                         29.04.09 0:54


  list                                    List the current port redirections.

  add <protocol>:<host-                   Add a new port redirection.               <protocol> must be either "tcp" or
  port>:<guest-port>                                                              "udp"
                                                                                    <host-port> is the port number to
                                                                                  open on the host
                                                                                    <guest-port> is the port number to
                                                                                  route data to on the emulator/device

  del <protocol>:<host-                   Delete a port redirection.              See above for meanings of <protocol>
  port>                                                                           and <host-port>.


Geo Location Provider Emulation
The console provides commands to let you set the geo position used by an emulator emulated device. You can use
the geo command to send a simple GPS fix to the emulator, without needing to use NMEA 1083 formatting. The
usage for the command is:


    geo <fix|nmea>

The geo command supports the subcommands listed in the table below.

  Subcommand                            Description                              Comments

  fix <longitude>                       Send a simple GPS fix to the             Specify longitude and latitude in decimal
  <latitude>                            emulator instance.                       degrees. Specify altitude in meters.
  [<altitude>]

  nmea <sentence>                       Send an NMEA 0183 sentence to            <sentence> must begin with '$GP'. Only
                                        the emulated device, as if it were       '$GPGGA' and '$GPRCM' sentences are
                                        sent from an emulated GPS                currently supported.
                                        modem.

You can issue the geo command to fix the GPS location as soon as an emulator instance is running. The emulator
creates a mock location provider that sends it to GPS-aware applications as soon as they start and register location
listeners. Any application can query the location manager to obtain the current GPS fix for the emulated device by
calling:


    LocationManager.getLastKnownLocation("gps")

For more information about the Location Manager, see LocationManager and its methods.


Hardware Events Emulation
You can use the event command to send various events to the emulator.The usage for the command is:


    event <send|types|codes|text>

The event command supports the subcommands listed in the table below.

  Subcommand                                    Description                          Comments

  send <type>:<code>:<value>                    Send one or more events to           You can use text names or integers
  [...]                                         the Android kernel.                  for <type> and <value>.

  types                                         List all <type> string aliases
                                                supported by the event
                                                subcommands.

  codes <type>                                  List all <codes> string aliases
                                                supported by the event
                                                subcommands for the specified
                                                <type>.

  event text <message>                          Simulate keypresses to send          The message must be a UTF-8
                                                the specified string of              string. Unicode posts will be reverse-

http://developer.android.com/guide/developing/tools/emulator.html                                                             Page 13 of 20
Android Emulator | Android Developers                                                                                         29.04.09 0:54


                                               characters as a message,           mapped according to the current
                                                                                  device keyboard. Unsupported
                                                                                  characters will be discarded silently.


Device Power Characteristics
You can use the power command to control the simulated power state of the emulator instance.The usage for the
command is:


    power <display|ac|status|present|health|capactiy>

The event command supports the subcommands listed in the table below.

  Subcommand                                                              Description             Comments

  display                                                                 Display battery and
                                                                          charger state.

  ac <on|off>                                                             Set AC charging
                                                                          state to on or off.

  status <unknown|charging|discharging|not-                               Change battery
  charging|full>                                                          status as specified.

  present <true|false>                                                    Set battery
                                                                          presence state.

  health                                                                  Set battery health
  <unknown|good|overheat|dead|overvoltage|failure>                        state.

  power health <percent>                                                  Set remaining
                                                                          battery capacity
                                                                          state (0-100).


Network Status
You can use the console to check the network status and current delay and speed characteristics. To do so, connect
to the console and use the netstatus command. Here's an example of the command and its output.


    network status


Network Delay Emulation
The emulator lets you simulate various network latency levels, so that you can test your applicaton in an environment
more typical of the actual conditions in which it will run. You can set a latency level or range at emulator startup or you
can use the console to change the latency dynamically, while the application is running in the emulator.

To set latency at emulator startup, use the -netdelay emulator option with a supported <delay> value, as listed in
the table below. Here are some examples:


    emulator -netdelay gprs
    emulator -netdelay 40 100

To make dynamic changes to network delay while the emulator is running, connect to the console and use the
netdelay command with a supported <delay> value from the table below.


    network delay gprs

The format of network is one of the following (numbers are milliseconds):

  Value                                 Description                               Comments

  gprs                                  GPRS                                      (min 150, max 550)

  edge                                  EDGE/EGPRS                                (min 80, max 400)


http://developer.android.com/guide/developing/tools/emulator.html                                                             Page 14 of 20
Android Emulator | Android Developers                                                                                  29.04.09 0:54


  umts                                   UMTS/3G                               (min 35, max 200)

  none                                   No latency                            (min 0, max 0)

  <num>                                  Emulate an exact latency
                                         (milliseconds).

  <min>:<max>                            Emulate an specified latency range
                                         (min, max milliseconds).


Network Speed Emulation
The emulator also lets you simulate various network transfer rates. You can set a transfer rate or range at emulator
startup or you can use the console to change the rate dynamically, while the application is running in the emulator.

To set the network speed at emulator startup, use the -netspeed emulator option with a supported <speed> value,
as listed in the table below. Here are some examples:


    emulator -netspeed gsm
    emulator -netspeed 14.4 80

To make dynamic changes to network speed while the emulator is running, connect to the console and use the
netspeed command with a supported <speed> value from the table below.


    network speed 14.4 80

The format of network <speed> is one of the following (numbers are kilobits/sec):

  Value                                  Description                           Comments

  gsm                                    GSM/CSD                               (Up: 14.4, down: 14.4)

  hscsd                                  HSCSD                                 (Up: 14.4, down: 43.2)

  gprs                                   GPRS                                  (Up: 40.0, down: 80.0)

  edge                                   EDGE/EGPRS                            (Up: 118.4, down: 236.8)

  umts                                   UMTS/3G                               (Up: 128.0, down: 1920.0)

  hsdpa                                  HSDPA                                 (Up: 348.0, down: 14400.0)

  full                                   no limit                              (Up: 0.0, down: 0.0)

  <num>                                  Set an exact rate used for both
                                         upload and download.

  <up>:<down>                            Set exact rates for upload and
                                         download separately.


Telephony Emulation
The Android emulator includes its own GSM emulated modem that lets you simulate telephony functions in the
emulator. For example, you can simulate inbound phone calls and establish/terminate data connections. The Android
system handles simulated calls exactly as it would actual calls. The emulator does not support call audio in this
release.

You can use the console to access the emulator's telephony functions. After connecting to the console, you can use


    gsm <call|accept|busy|cancel|data|hold|list|voice|status>

to invoke telephony functions.

The gsm command supports the subcommands listed in the table below.

  Subcommand               Description                     Comments

  call                     Simulate an inbound


http://developer.android.com/guide/developing/tools/emulator.html                                                      Page 15 of 20
Android Emulator | Android Developers                                                                                          29.04.09 0:54


  <phonenumber>            phone call from
                           <phonenumber>.

  accept                   Accept an inbound call          You can change a call's state to "active" only if its current
  <phonenumber>            from <phonenumber>              state is "waiting" or "held".
                           and change the call's
                           state "active".

  busy                     Close an outbound call          You can change a call's state to "busy" only if its current
  <phonenumber>            to <phonenumber> and            state is "waiting".
                           change the call's state to
                           "busy".

  cancel                   Terminate an inbound or
  <phonenumber>            outbound phone call
                           to/from <phonenumber>.

  data <state>             Change the state of the         Supported <state> values are:
                           GPRS data connection to          unregistered -- No network available
                           <state>.
                                                             home -- On local network, non-roaming
                                                             roaming -- On roaming network
                                                             searching -- Searching networks
                                                             denied -- Emergency calls only
                                                             off -- Same as 'unregistered'
                                                             on -- same as 'home'

  hold                     Change the state of a           You can change a call's state to "held" only if its current state
                           call to "held".                 is "active" or "waiting".

  list                     List all inbound and
                           outbound calls and their
                           states.

  voice <state>            Change the state of the         Supported <state> values are:
                           GPRS voice connection            unregistered -- No network available
                           to <state>.
                                                             home -- On local network, non-roaming
                                                             roaming -- On roaming network
                                                             searching -- Searching networks
                                                             denied -- Emergency calls only
                                                             off -- Same as 'unregistered'
                                                             on -- Same as 'home'

  status                   Report the current GSM          Values are those described for the voice and data
                           voice/data state.               commands.


SMS Emulation
The Android emulator console lets you generate an SMS message and direct it to an emulator instance. Once you
connect to an emulator instance, you can generate an emulated incoming SMS using this command:


    sms send <senderPhoneNumber> <textmessage>

where <senderPhoneNumber> contains an arbitrary numeric string.

The console forwards the SMS message to the Android framework, which passes it through to an application that
handles that message type.


VM State
You can use the vm command to control the VM on an emulator instance.The usage for the command is:


    vm <start|stop|status>




http://developer.android.com/guide/developing/tools/emulator.html                                                              Page 16 of 20
Android Emulator | Android Developers                                                                                      29.04.09 0:54


The vm command supports the subcommands listed in the table below.

  Subcommand                            Description                         Comments

  start                                 Start the VM on the instance.

  stop                                  Stop the VM on the instance.

  start                                 Display the current status of the
                                        VM (running or stopped).


Emulator Window
You can use the window command to manage the emulator window. The usage for the command is:


    window <scale>

The vm command supports the subcommands listed in the table below.

  Subcommand                            Description                         Comments

  scale <scale>                         Scale the emulator window.          <scale> must be a number between 0.1
                                                                            and 3 that describes the desired scaling
                                                                            factor. You can also specify scale as a
                                                                            DPI value if you add the suffix "dpi" to the
                                                                            scale value. A value of "auto" tells the
                                                                            emulator to select the best window size.


Terminating an Emulator Instance
You can terminate an emulator instance through the console, using the kill command.



Using Emulator Skins
You can run the emulator with any of four default skins, as described in the table below. To specify a skin, use -skin
<skinID> when starting the emulator.

For example:


    emulator -skin HVGA-L

Note that you must enter the <skinID> in uppercase letters (if your development computer is case-sensitive).

  skinID             Description                       Skin

  HVGA-L             480x320, landscape




http://developer.android.com/guide/developing/tools/emulator.html                                                          Page 17 of 20
Android Emulator | Android Developers                                                                                         29.04.09 0:54


  HVGA-P             320x480, portrait (default)




  QVGA-L             320x240, landscape




  QVGA-P             240x320, portrait




Running Multiple Emulator Instances
Through the AVDs configurations used by the emulator, you can run multiple instances of the emulator concurrently,
each with its own AVD configuration and storage area for user data, SD card, and so on. You no longer need to use
the -d option when launching the emulator, to point to an instance-specific storage area.



Installing Applications on the Emulator
If you don't have access to Eclipse or the ADT Plugin, you can install your application on the emulator using the adb
utility. Before installing the application, you need to package it in a .apk file using the Android Asset Packaging Tool.
Once the application is installed, you can start the emulator from the command line, as described in this document,
using any startup options necessary. When the emulator is running, you can also connect to the emulator instance's
console to issue commands as needed.

As you update your code, you periodically package and install it on the emulator. The emulator preserves the
application and its state data across restarts, in a user-data disk partition. To ensure that the application runs properly
as you update it, you may need to delete the emulator's user-data partition. To do so, start the emulator with the -
wipe-data option. For more information about the user-data partition and other emulator storage, see Working with
Emulator Disk Images.


http://developer.android.com/guide/developing/tools/emulator.html                                                             Page 18 of 20
Android Emulator | Android Developers                                                                                      29.04.09 0:54




SD Card Emulation
You can create a disk image and then load it to the emulator at startup, to simulate the presence of a user's SD card
in the device. To do this, you can use the android tool to create a new SD card image with a new AVD, or you can
use the mksdcard utility included in the SDK.

The sections below describe how to create an SD card disk image, how to copy files to it, and how to load it in the
emulator at startup.

Note that you can only load disk image at emulator startup. Similarly, you can not remove a simulated SD card from a
running emulator. However, you can browse, send files to, and copy/remove files from a simulated SD card either with
adb or the emulator.

The emulator supports emulated SDHC cards, so you can create an SD card image of any size up to 128 gigabytes.


Creating an SD card image using the android tool
The easiest way to create a new SD card is to use the android tool. When creating an AVD, you simply specify the -c
option, like this:


    android create avd -n <avd_name> -t <targetID> -c <size>[K|M]

You can also use the -c option to specify a path to an SD card image to use in the new AVD. For more information,
see Android Virtual Devices.


Creating an SD card image using mksdcard
You can use the mksdcard tool, included in the SDK, to create a FAT32 disk image that you can load in the emulator
at startup. You can access mksdcard in the tools/ directory of the SDK and create a disk image like this:


    mksdcard <size> <file>

For example:

    mksdcard 1024M sdcard1.iso

For more information, see Other Tools.


Copying Files to a Disk Image
Once you have created the disk image, you can copy files to it prior to loading it in the emulator. To copy files, you
can mount the image as a loop device and then copy the files to it, or you can use a utility such as mtools to copy the
files directly to the image. The mtools package is available for Linux, Mac, and Windows.


Loading the Disk Image at Emulator Startup
By default, the emulator loads the SD card image that is stored with the active AVD (see the -avd startup option).

Alternatively, you ca start the emulator with the -sdcard flag and specify the name and path of your image (relative
to the current working directory):


    emulator -sdcard <filepath>




Troubleshooting Emulator Problems
The adb utility sees the emulator as an actual physical device. For this reason, you might have to use the -d flag with
some common adb commands, such as install. The -d flag lets you specify which of several connected devices to
use as the target of a command. If you don't specify -d, the emulator will target the first device in its list. For more
information about adb, see Android Debug Bridge.



http://developer.android.com/guide/developing/tools/emulator.html                                                          Page 19 of 20
Android Emulator | Android Developers                                                                                              29.04.09 0:54


For emulators running on Mac OS X, if you see an error "Warning: No DNS servers found" when starting the emulator,
check to see whether you have an /etc/resolv.conf file. If not, please run the following line in a command
window:


    ln -s /private/var/run/resolv.conf /etc/resolv.conf

See Frequently Asked Questions for more troubleshooting information.



Emulator Limitations
In this release, the limitations of the emulator include:

     No support for placing or receiving actual phone calls. You can simulate phone calls (placed and received)
     through the emulator console, however.
     No support for USB connections
     No support for camera/video capture (input).
     No support for device-attached headphones
     No support for determining connected state
     No support for determining battery charge level and AC charging state
     No support for determining SD card insert/eject
     No support for Bluetooth

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/developing/tools/emulator.html                                                                  Page 20 of 20
Hierarchy Viewer | Android Developers                                                                                 29.04.09 0:55




Hierarchy Viewer
The Hierarchy Viewer application allows you to debug and optimize your user interface. It provides a visual
representation of the layout's View hierarchy (the Layout View) and a magnified inspector of the display (the Pixel
Perfect View).

To get the Hierarchy Viewer started:

 1. Connect your device or launch an emulator.
 2. From a terminal, launch hierarchyviewer from your SDK /tools directory.
 3. In the window that opens, you'll see a list of Devices. When a device is selected, a list of currently active
    Windows is displayed on the right. The <Focused Window> is the window currently in the foreground, and also
    the default window loaded if you do not select another.
 4. Select the window that you'd like to inspect and click Load View Hierarchy. The Layout View will be loaded. You
    can then load the Pixel Perfect View by clicking the second icon at the bottom-left of the window.

If you've navigated to a different window on the device, press Refresh Windows to refresh the list of available
windows on the right.



Layout View
The Layout View offers a look at the View layout and properties. It has three views:

     Tree View: a hierarchy diagram of the Views, on the left.
     Properties View: a list of the selected View's properties, on the top-right.
     Wire-frame View: a wire-frame drawing of the layout, on the bottom-right.




http://developer.android.com/guide/developing/tools/hierarchy-viewer.html                                               Page 1 of 3
Hierarchy Viewer | Android Developers                                                                                 29.04.09 0:55




Select a node in the Tree View to display the properties of that element in the Properties View. When a node is
selected, the Wire-frame View also indicates the bounds of the element with a red rectangle. Double click a node in
the tree (or select it, and click Display View) to open a new window with a rendering of that element.

The Layout View includes a couple other helpful features for debugging your layout: Invalidate and Request Layout.
These buttons execute the respective View calls, invalidate() and requestLayout(), on the View element currently
selected in the tree. Calling these methods on any View can be very useful when simultaneously running a debugger
on your application.

The Tree View can be resized by adjusting the zoom slider, below the diagram. The number of View elements in the
window is also given here. You should look for ways to minimize the number of Views. The fewer View elements there
are in a window, the faster it will perform.

If you interact with the device and change the focused View, the diagram will not automatically refresh. You must
reload the Layout View by clicking Load View Hierarchy.



Pixel Perfect View
The Pixel Perfect View provides a magnified look at the current device window. It has three views:

     Explorer View: shows the View hierarchy as a list, on the left.
     Normal View: a normal view of the device window, in the middle.
     Loupe View: a magnified, pixel-grid view of the device window, on the right.




http://developer.android.com/guide/developing/tools/hierarchy-viewer.html                                               Page 2 of 3
Hierarchy Viewer | Android Developers                                                                                              29.04.09 0:55




Click on an element in the Explorer View and a "layout box" will be drawn in the Normal View to indicate the layout
position of that element. The layout box uses multiple rectangles, to indicate the normal bounds, the padding and the
margin (as needed). The purple or green rectangle indicates the normal bounds of the element (the height and width).
The inner white or black rectangle indicates the content bounds, when padding is present. A black or white rectangle
outside the normal purple/green rectangle indicates any present margins. (There are two colors for each rectangle, in
order to provide the best contrast based on the colors currently in the background.)

A very handy feature for designing your UI is the ability to overlay an image in the Normal and Loupe Views. For
example, you might have a mock-up image of how you'd like to layout your interface. By selecting Load... from the
controls in the Normal View, you can choose the image from your computer and it will be placed atop the preview.
Your chosen image will anchor at the bottom left corner of the screen. You can then adjust the opacity of the overlay
and begin fine-tuning your layout to match the mock-up.

The Normal View and Loupe View refresh at regular intervals (5 seconds by default), but the Explorer View does not.
If you navigate away and focus on a different View, then you should refresh the Explorer's hierarchy by clicking Load
View Hierarchy. This is even true when you're working in a window that holds multiple Views that are not always
visible. If you do not, although the previews will refresh, clicking a View in the Explorer will not provide the proper
layout box in the Normal View, because the hierarchy believes you are still focused on the prior View.

Optional controls include:

     Overlay: Load an overlay image onto the view and adjust its opacity.
     Refresh Rate: Adjust how often the Normal and Loupe View refresh their display.
     Zoom: Adjust the zoom level of the Loupe View.

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/developing/tools/hierarchy-viewer.html                                                            Page 3 of 3
UI/Application Exerciser Monkey | Android Developers                                                           29.04.09 0:55




UI/Application Exerciser Monkey

The Monkey is a program that runs on your emulator or device and generates pseudo-random streams of user events
such as clicks, touches, or gestures, as well as a number of system-level events. You can use the Monkey to stress-
test applications that you are developing, in a random yet repeatable manner.



Overview
The Monkey is a command-line tool that that you can run on any emulator instance or on a device. It sends a pseudo-
random stream of user events into the system, which acts as a stress test on the application software you are
developing.

The Monkey includes a number of options, but they break down into four primary categories:

     Basic configuration options, such as setting the number of events to attempt.
     Operational constraints, such as restricting the test to a single package.
     Event types and frequencies.
     Debugging options.

When the Monkey runs, it generates events and sends them to the system. It also watches the system under test and
looks for three conditions, which it treats specially:

     If you have constrained the Monkey to run in one or more specific packages, it watches for attempts to navigate to
     any other packages, and blocks them.
     If your application crashes or receives any sort of unhandled exception, the Monkey will stop and report the error.
     If your application generates an application not responding error, the Monkey will stop and report the error.

Depending on the verbosity level you have selected, you will also see reports on the progress of the Monkey and the
events being generated.



Basic Use of the Monkey
You can launch the Monkey using a command line on your development machine or from a script. Because the
Monkey runs in the emulator/device environment, you must launch it from a shell in that environment. You can do this
by prefacing adb shell to each command, or by entering the shell and entering Monkey commands directly.

The basic syntax is:

     $ adb shell monkey [options] <event-count>

With no options specified, the Monkey will launch in a quiet (non-verbose) mode, and will send events to any (and all)
packages installed on your target. Here is a more typical command line, which will launch your application and send
500 pseudo-random events to it:



http://developer.android.com/guide/developing/tools/monkey.html                                                  Page 1 of 3
UI/Application Exerciser Monkey | Android Developers                                                                         29.04.09 0:55



     $ adb shell monkey -p your.package.name -v 500




Command Options Reference
The table below lists all options you can include on the Monkey command line.

  Category             Option                          Description

  General              --help                          Prints a simple usage guide.

                       -v                              Each -v on the command line will increment the verbosity level. Level 0
                                                       (the default) provides little information beyond startup notification, test
                                                       completion, and final results. Level 1 provides more details about the test
                                                       as it runs, such as individual events being sent to your activities. Level 2
                                                       provides more detailed setup information such as activities selected or not
                                                       selected for testing.

  Events               -s <seed>                       Seed value for pseudo-random number generator. If you re-run the
                                                       Monkey with the same seed value, it will generate the same sequence of
                                                       events.

                       --throttle                      Inserts a fixed delay between events. You can use this option to slow down
                       <milliseconds>                  the Monkey. If not specified, there is no delay and the events are
                                                       generated as rapidly as possible.

                       --pct-touch                     Adjust percentage of touch events. (Touch events are a down-up event in
                       <percent>                       a single place on the screen.)

                       --pct-motion                    Adjust percentage of motion events. (Motion events consist of a down
                       <percent>                       event somewhere on the screen, a series of pseudo-random movements,
                                                       and an up event.)

                       --pct-                          Adjust percentage of trackball events. (Trackball events consist of one or
                       trackball                       more random movements, sometimes followed by a click.)
                       <percent>

                       --pct-nav                       Adjust percentage of "basic" navigation events. (Navigation events consist
                       <percent>                       of up/down/left/right, as input from a directional input device.)

                       --pct-majornav                  Adjust percentage of "major" navigation events. (These are navigation
                       <percent>                       events that will typically cause actions within your UI, such as the center
                                                       button in a 5-way pad, the back key, or the menu key.)

                       --pct-syskeys                   Adjust percentage of "system" key events. (These are keys that are
                       <percent>                       generally reserved for use by the system, such as Home, Back, Start Call,
                                                       End Call, or Volume controls.)

                       --pct-                          Adjust percentage of activity launches. At random intervals, the Monkey will
                       appswitch                       issue a startActivity() call, as a way of maximizing coverage of all activities
                       <percent>                       within your package.

                       --pct-anyevent                  Adjust percentage of other types of events. This is a catch-all for all other
                       <percent>                       types of events such as keypresses, other less-used buttons on the device,
                                                       and so forth.

  Constraints          -p <allowed-                    If you specify one or more packages this way, the Monkey will only allow
                       package-name>                   the system to visit activities within those packages. If your application
                                                       requires access to activities in other packages (e.g. to select a contact)
                                                       you'll need to specify those packages as well. If you don't specify any

http://developer.android.com/guide/developing/tools/monkey.html                                                                Page 2 of 3
UI/Application Exerciser Monkey | Android Developers                                                                            29.04.09 0:55


                                                       packages, the Monkey will allow the system to launch activities in all
                                                       packages. To specify multiple packages, use the -p option multiple times —
                                                       one -p option per package.

                       -c <main-                       If you specify one or more categories this way, the Monkey will only allow
                       category>                       the system to visit activities that are listed with one of the specified
                                                       categories. If you don't specify any categories, the Monkey will select
                                                       activities listed with the category Intent.CATEGORY_LAUNCHER or
                                                       Intent.CATEGORY_MONKEY. To specify multiple categories, use the -c
                                                       option multiple times — one -c option per category.

  Debugging            --dbg-no-                       When specified, the Monkey will perform the initial launch into a test
                       events                          activity, but will not generate any further events. For best results, combine
                                                       with -v, one or more package constraints, and a non-zero throttle to keep
                                                       the Monkey running for 30 seconds or more. This provides an environment
                                                       in which you can monitor package transitions invoked by your application.

                       --hprof                         If set, this option will generate profiling reports immediately before and after
                                                       the Monkey event sequence. This will generate large (~5Mb) files in
                                                       data/misc, so use with care. See Traceview for more information on trace
                                                       files.

                       --ignore-                       Normally, the Monkey will stop when the application crashes or
                       crashes                         experiences any type of unhandled exception. If you specify this option, the
                                                       Monkey will continue to send events to the system, until the count is
                                                       completed.

                       --ignore-                       Normally, the Monkey will stop when the application experiences any type
                       timeouts                        of timeout error such as a "Application Not Responding" dialog. If you
                                                       specify this option, the Monkey will continue to send events to the system,
                                                       until the count is completed.

                       --ignore-                       Normally, the Monkey will stop when the application experiences any type
                       security-                       of permissions error, for example if it attempts to launch an activity that
                       exceptions                      requires certain permissions. If you specify this option, the Monkey will
                                                       continue to send events to the system, until the count is completed.

                       --kill-                         Normally, when the Monkey stops due to an error, the application that
                       process-after-                  failed will be left running. When this option is set, it will signal the system to
                       error                           stop the process in which the error occurred. Note, under a normal
                                                       (successful) completion, the launched process(es) are not stopped, and the
                                                       device is simply left in the last state after the final event.

                       --monitor-                      Watches for and reports crashes occurring in the Android system native
                       native-crashes                  code. If --kill-process-after-error is set, the system will stop.

                       --wait-dbg                      Stops the Monkey from executing until a debugger is attached to it.

                                                                                                                               ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/developing/tools/monkey.html                                                                   Page 3 of 3
Traceview: A Graphical Log Viewer | Android Developers                                                                        29.04.09 0:55




Traceview: A Graphical Log Viewer
Traceview is a graphical viewer for execution logs saved by your application. The sections below describe how to use
the program.



Contents
Creating Trace Files
Copying Trace Files to a Host Machine
Viewing Trace Files in Traceview
    Timeline Panel

    Profile Panel

Traceview File Format
    Data File Format

    Key File Format

Traceview Known Issues
Using dmtracedump



Creating Trace Files
To use Traceview, you need to generate log files containing the trace information you want to analyze. To do that, you
include the Debug class in your code and call its methods to start and stop logging of trace information to disk. When
your application quits, you can then use Traceview to examine the log files for useful run-time information such as
method calls and run times.

To create the trace files, include the Debug class and call one of the startMethodTracing() methods. In the call, you
specify a base name for the trace files that the system generates. To stop tracing, call stopMethodTracing(). These
methods start and stop method tracing across the entire virtual machine. For example, you could call
startMethodTracing() in your activity's onCreate() method, and call stopMethodTracing() in that activity's onDestroy()
method.


         // start tracing to "/sdcard/calc.trace"
         Debug.startMethodTracing("calc");
         // ...
         // stop tracing
         Debug.stopMethodTracing();

When your application calls startMethodTracing(), the system creates a file called <trace-base-name>.trace. This
contains the binary method trace data and a mapping table with thread and method names.

The system then begins buffering the generated trace data, until your application calls stopMethodTracing(), at which
time it writes the buffered data to the output file. If the system reaches the maximum buffer size before
stopMethodTracing() is called, the system stops tracing and sends a notification to the console.

Interpreted code will run more slowly when profiling is enabled. Don't try to generate absolute timings from the profiler
results (i.e. "function X takes 2.5 seconds to run"). The times are only useful in relation to other profile output, so you
can see if changes have made the code faster or slower.

When using the Android emulator, you must create an SD card image upon which the trace files will be written. For
example, from the /tools directory, you can create an SD card image and mount it when launching the emulator like
so:


    $ mksdcard 1024M ./imgcd
    $ emulator -sdcard ./img

For more information, read about the mksdcard tool.

The format of the trace files is described later in this document.




http://developer.android.com/guide/developing/tools/traceview.html                                                              Page 1 of 5
Traceview: A Graphical Log Viewer | Android Developers                                                                     29.04.09 0:55



Copying Trace Files to a Host Machine
After your application has run and the system has created your trace files <trace-base-name>.trace on a device
or emulator, you must copy those files to your development computer. You can use adb pull to copy the files.
Here's an example that shows how to copy an example file, calc.trace, from the default location on the emulator to the
/tmp directory on the emulator host machine:


    adb pull /sdcard/calc.trace /tmp




Viewing Trace Files in Traceview
To run traceview and view the trace files, enter traceview <trace-base-name>. For example, to run Traceview
on the example files copied in the previous section, you would use:


    traceview /tmp/calc

Traceview loads the log files and displays their data in a window that has two panels:

    A timeline panel -- describes when each thread and method started and stopped
    A profile panel -- provides a summary of what happened inside a method

The sections below provide addition information about the traceview output panes.


Timeline Panel
The image below shows a close up of the timeline panel. Each thread’s execution is shown in its own row, with time
increasing to the right. Each method is shown in another color (colors are reused in a round-robin fashion starting with
the methods that have the most inclusive time). The thin lines underneath the first row show the extent (entry to exit)
of all the calls to the selected method. The method in this case is LoadListener.nativeFinished() and it was selected in
the profile view.




Profile Panel
The image below shows the profile pane. The profile pane shows a summary of all the time spent in a method. The
table shows both the inclusive and exclusive times (as well as the percentage of the total time). Exclusive time is the
time spent in the method. Inclusive time is the time spent in the method plus the time spent in any called functions.
We refer to calling methods as "parents" and called methods as "children." When a method is selected (by clicking on
it), it expands to show the parents and children. Parents are shown with a purple background and children with a
yellow background. The last column in the table shows the number of calls to this method plus the number of
recursive calls. The last column shows the number of calls out of the total number of calls made to that method. In this
view, we can see that there were 14 calls to LoadListener.nativeFinished(); looking at the timeline panel shows that
one of those calls took an unusually long time.




http://developer.android.com/guide/developing/tools/traceview.html                                                           Page 2 of 5
Traceview: A Graphical Log Viewer | Android Developers                                                                     29.04.09 0:55




Traceview File Format
Tracing creates two distinct pieces of output: a data file, which holds the trace data, and a key file, which provides a
mapping from binary identifiers to thread and method names. The files are concatenated when tracing completes, into
a single .trace file.

    Note: The previous version of Traceview did not concatenate these files for you. If you have old key and data
    files that you'd still like to trace, you can concatenate them yourself with cat mytrace.key mytrace.data
    > mytrace.trace.


Data File Format
The data file is binary, structured as follows (all values are stored in little-endian order):


    *   File format:
    *   header
    *   record 0
    *   record 1
    *   ...
    *
    *   Header format:
    *   u4 magic 0x574f4c53 ('SLOW')
    *   u2 version
    *   u2 offset to data
    *   u8 start date/time in usec
    *
    *   Record format:
    *   u1 thread ID
    *   u4 method ID | method action
    *   u4 time delta since start, in usec

The application is expected to parse all of the header fields, then seek to "offset to data" from the start of the file.
From there it just reads 9-byte records until EOF is reached.

http://developer.android.com/guide/developing/tools/traceview.html                                                           Page 3 of 5
Traceview: A Graphical Log Viewer | Android Developers                                                                           29.04.09 0:55



u8 start date/time in usec is the output from gettimeofday(). It's mainly there so that you can tell if the output was
generated yesterday or three months ago.

method action sits in the two least-significant bits of the method word. The currently defined meanings are:

    0 - method entry
    1 - method exit
    2 - method "exited" when unrolled by exception handling
    3 - (reserved)

An unsigned 32-bit integer can hold about 70 minutes of time in microseconds.


Key File Format
The key file is a plain text file divided into three sections. Each section starts with a keyword that begins with '*'. If you
see a '*' at the start of a line, you have found the start of a new section.

An example file might look like this:


    *version
    1
    clock=global
    *threads
    1 main
    6 JDWP Handler
    5 Async GC
    4 Reference Handler
    3 Finalizer
    2 Signal Handler
    *methods
    0x080f23f8 java/io/PrintStream write ([BII)V
    0x080f25d4 java/io/PrintStream print (Ljava/lang/String;)V
    0x080f27f4 java/io/PrintStream println (Ljava/lang/String;)V
    0x080da620 java/lang/RuntimeException    <init> ()V
    [...]
    0x080f630c android/os/Debug startMethodTracing ()V
    0x080f6350 android/os/Debug startMethodTracing
    (Ljava/lang/String;Ljava/lang/String;I)V
    *end

version section
    The first line is the file version number, currently 1. The second line, clock=global, indicates that we use a
    common clock across all threads. A future version may use per-thread CPU time counters that are independent for
    every thread.

threads section
    One line per thread. Each line consists of two parts: the thread ID, followed by a tab, followed by the thread name.
    There are few restrictions on what a valid thread name is, so include everything to the end of the line.

methods section
    One line per method entry or exit. A line consists of four pieces, separated by tab marks: method-ID [TAB] class-
    name [TAB] method-name [TAB] signature . Only the methods that were actually entered or exited are included in
    the list. Note that all three identifiers are required to uniquely identify a method.

Neither the threads nor methods sections are sorted.



Traceview Known Issues
Threads
    Traceview logging does not handle threads well, resulting in these two problems:
     1. If a thread exits during profiling, the thread name is not emitted;
     2. The VM reuses thread IDs. If a thread stops and another starts, they may get the same ID.



Using dmtracedump
The Android SDK includes dmtracedump, a tool that gives you an alternate way of generating graphical call-stack
diagrams from trace log files. The tool uses the Graphviz Dot utility to create the graphical output, so you need to
install Graphviz before running dmtracedump.

The dmtracedump tool generates the call stack data as a tree diagram, with each call represented as a node. It shows
call flow (from parent node to child nodes) using arrows. The diagram below shows an example of dmtracedump
output.


http://developer.android.com/guide/developing/tools/traceview.html                                                                 Page 4 of 5
Traceview: A Graphical Log Viewer | Android Developers                                                                             29.04.09 0:55




For each node, dmtracedump shows <ref> callname (<inc-ms>, <exc-ms>,<numcalls>), where

     <ref> -- Call reference number, as used in trace logs
     <inc-ms> -- Inclusive elapsed time (milliseconds spent in method, including all child methods)
     <exc-ms> -- Exclusive elapsed time (milliseconds spent in method, not including any child methods)
     <numcalls> -- Number of calls

The usage for dmtracedump is:


    dmtracedump [-ho] [-s sortable] [-d trace-base-name] [-g outfile] <trace-base-name>

The tool then loads trace log data from <trace-base-name>.data and <trace-base-name>.key. The table below lists
the options for dmtracedump.

  Option                 Description

  -d <trace-             Diff with this trace name
  base-name>

  -                      Generate output to <outfile>
  g <outfile>

  -h                     Turn on HTML output

  -o                     Dump the trace file instead of profiling

  -d <trace-             URL base to the location of the sortable javascript file
  base-name>

  -                      Minimum threshold for including child nodes in the graph (child's inclusive time as a
  t <percent>            percentage of parent inclusive time). If this option is not used, the default threshold is 20%.

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/developing/tools/traceview.html                                                                   Page 5 of 5
Signing Your Applications | Android Developers                                                                       29.04.09 0:57




Signing Your Applications

This document provides information about signing your Android applications prior to publishing them for mobile device
users.



Overview
The Android system requires that all installed applications be digitally signed with a certificate whose private key is
held by the application's developer. The Android system uses the certificate as a means of identifying the author of an
application and establishing trust relationships between applications. The certificate is not used to control which
applications the user can install. The certificate does not need to be signed by a certificate authority: it is perfectly
allowable, and typical, for Android applications to use self-signed certificates.

The important points to understand about signing Android applications are:

     All applications must be signed. The system will not install an application that is not signed.
     You can use self-signed certificates to sign your applications. No certificate authority is needed.
     When you are ready to release your application for end-users, you must sign it with a suitable private key. You
     can not publish an application that is signed with the debug key generated by the SDK tools.
     The system tests a signer certificate's expiration date only at install time. If an application's signer certificate
     expires after the application is installed, the application will continue to function normally.
     You can use standard tools — Keytool and Jarsigner — to generate keys and sign your application .apk files.

The Android system will not install or run an application that is not signed appropriately. This applies wherever the
Android system is run, whether on an actual device or on the emulator. For this reason, you must set up signing for
your application before you will be able to run or debug it on an emulator or device.

The Android SDK tools assist you in signing your applications when debugging. Both the ADT Plugin for Eclipse and
the Ant build tool offer two signing modes — debug mode and release mode.

     While developing and testing, you can compile in debug mode. In debug mode, the build tools use the Keytool
     utility, included in the JDK, to create a keystore and key with a known alias and password. At each compilation,
     the tools then use the debug key to sign the application .apk file. Because the password is known, the tools don't
     need to prompt you for the keystore/key password each time you compile.
     When your application is ready for release, you must compile in release mode and then sign the .apk with your
     private key. There are two ways to do this:
           Using Keytool and Jarsigner in the command-line. In this approach, you first compile your application to an
           unsigned .apk. You must then sign the .apk manually with your private key using Jarsigner (or similar tool). If
           you do not have a suitable private key already, you can run Keytool manually to generate your own
           keystore/key and then sign your application with Jarsigner.
           Using the ADT Export Wizard. If you are developing in Eclipse with the ADT plugin, you can use the Export
           Wizard to compile the application, generate a private key (if necessary), and sign the .apk, all in a single
           process using the Export Wizard.




http://developer.android.com/guide/publishing/app-signing.html                                                         Page 1 of 8
Signing Your Applications | Android Developers                                                                   29.04.09 0:57



Signing Strategies
Some aspects of application signing may affect how you approach the development of your application, especially if
you are planning to release multiple applications.

In general, the recommended strategy for all developers is to sign all of your applications with the same certificate,
throughout the expected lifespan of your applications. There are several reasons why you should do so:

     Application upgrade – As you release upgrades to your application, you will want to sign the upgrades with the
     same certificate, if you want users to upgrade seamlessly to the new version. When the system is installing an
     update to an application, if any of the certificates in the new version match any of the certificates in the old
     version, then the system allows the update. If you sign the version without using a matching certificate, you will
     also need to assign a different package name to the application — in this case, the user installs the new version
     as a completely new application.
     Application modularity – The Android system allows applications that are signed by the same certificate to run in
     the same process, if the applications so requests, so that the system treats them as a single application. In this
     way you can deploy your application in modules, and users can update each of the modules independently if
     needed.
     Code/data sharing through permissions – The Android system provides signature-based permissions enforcement,
     so that an application can expose functionality to another application that is signed with a specified certificate. By
     signing multiple applications with the same certificate and using signature-based permissions checks, your
     applications can share code and data in a secure manner.

Another important consideration in determining your signing strategy is how to set the validity period of the key that
you will use to sign your applications.

     If you plan to support upgrades for a single application, you should ensure that your key has a validity period that
     exceeds the expected lifespan of that application. A validity period of 25 years or more is recommended. When
     your key's validity period expires, users will no longer be able to seamlessly upgrade to new versions of your
     application.
     If you will sign multiple distinct applications with the same key, you should ensure that your key's validity period
     exceeds the expected lifespan of all versions of all of the applications, including dependent applications that may
     be added to the suite in the future.
     If you plan to publish your application(s) on Android Market, the key you use to sign the application(s) must have
     a validity period ending after 22 October 2033. The Market server enforces this requirement to ensure that users
     can seamlessly upgrade Market applications when new versions are available.

As you design your application, keep these points in mind and make sure to use a suitable certificate to sign your
applications.



Basic Setup for Signing
To support the generation of a keystore and debug key, you should first make sure that Keytool is available to the
SDK build tools. In most cases, you can tell the SDK build tools how to find Keytool by making sure that your
JAVA_HOME environment variable is set and that it references a suitable JDK. Alternatively, you can add the JDK
version of Keytool to your PATH variable.

If you are developing on a version of Linux that originally came with GNU Compiler for Java, make sure that the
system is using the JDK version of Keytool, rather than the gcj version. If Keytool is already in your PATH, it might be
pointing to a symlink at /usr/bin/keytool. In this case, check the symlink target to make sure that it points to the
Keytool in the JDK.

If you will release your application to the public, you will also need to have the Jarsigner tool available on your
machine. Both Jarsigner and Keytool are included in the JDK.

http://developer.android.com/guide/publishing/app-signing.html                                                        Page 2 of 8
Signing Your Applications | Android Developers                                                                 29.04.09 0:57




Signing in Debug Mode
The Android build tools provide a debug signing mode that makes it easier for you to develop and debug your
application, while still meeting the Android system requirement for signing your .apk when it is installed in the emulator
or a device. When you use debug mode, the SDK tools invoke Keytool to create a debug keystore and key.

The SDK tools create the debug keystore/key with predetermined names/passwords;

     Keystore name – "debug.keystore"
     Keystore password – "android"
     Key alias – "androiddebugkey"
     Key password – "android"
     CN – "CN=Android Debug,O=Android,C=US"

If necessary, you can change the location/name of the debug keystore/key or supply a custom debug keystore/key to
use. In Eclipse/ADT, you can use Windows > Prefs > Android > Build. However, any custom debug keystore/key
must use the same keystore/key names and passwords as the default debug key (as described above).

     Note: You cannot release your application to the public when signed with the debug certificate.


Eclipse Users
If you are developing in Eclipse/ADT and have set up Keytool as described above, signing in debug mode is enabled
by default. When you run or debug your application, ADT signs the .apk with the debug certificate and installs it on the
emulator. No specific action on your part is needed, provided ADT has access to Keytool.


Ant Users
If you use Ant to build your .apk files, debug signing mode is enabled by using the debug option, assuming that you
are using a build.xml file generated by the android tool. When you run ant debug to compile your app, the build
script generates a keystore/key and signs the .apk for you. No other action on your part is needed. Read Developing
In Other IDEs: Building in debug mode for more information.


Expiry of the Debug Certificate
The self-signed certificate used to sign your application in debug mode (the default on Eclipse/ADT and Ant builds)
will have an expiration date of 365 days from its creation date.

When the certificate expires, you will get a build error. On Ant builds, the error looks like this:


     debug:
     [echo] Packaging bin/samples-debug.apk, and signing it with a debug key...
     [exec] Debug Certificate expired on 8/4/08 3:43 PM

In Eclipse/ADT, you will see a similar error in the Android console.

To fix this problem, simply delete the debug.keystore file. The default storage location for AVDs is in
~/.android/avd on OS X and Linux, in C:\Documents and Settings\\.android\ on Windows XP, and in
C:\Users\\.android\ on Windows Vista.

The next time you build, the build tools will regenerate a new keystore and debug key.

Note that, if your development machine is using a non-Gregorian locale, the build tools may erroneously generate an
already-expired debug certificate, so that you get an error when trying to compile your application. For workaround
http://developer.android.com/guide/publishing/app-signing.html                                                    Page 3 of 8
Signing Your Applications | Android Developers                                                                   29.04.09 0:57


already-expired debug certificate, so that you get an error when trying to compile your application. For workaround
information, see the troubleshooting topic I can't compile my app because the build tools generated an expired debug
certificate.



Signing for Public Release
When your application is ready for release to other users, you must:

 1. Compile the application in release mode
 2. Obtain a suitable private key
 3. Sign the application with your private key

The sections below provide information about how to perform these steps.

If you use Eclipse with the ADT plugin, you can instead use the Export Wizard to compile and sign an .apk with your
private key. The Export Wizard even allows you to generate a new keystore and private key in the process. Skip to
Compiling and signing with Eclipse ADT.


Compiling for release
To prepare your application for release, you must first compile it in release mode. In release mode, the Android build
tools compile your application as usual, but without signing it with the debug key.

     Note: You can not release your application unsigned, or signed with the debug key.

Eclipse users
To export an unsigned .apk from Eclipse, right-click the project in the Package Explorer and select Android Tools >
Export Unsigned Application Package. Then simply specify the file location for the unsigned .apk. (Alternatively,
open your AndroidManifest.xml file in Eclipse, open the Overview tab, and click Export an unsigned .apk.)

You can also combine the compiling and signing steps with the Export Wizard. See Compiling and signing with Eclipse
ADT.

Ant users
If you are using Ant, all you need to do is specify the build target "release" in the Ant command. For example, if you
are running Ant from the directory containing your build.xml file, the command would look like this:

     $ ant release

The build script compiles the application .apk without signing it.


Obtaining a Suitable Private Key
In preparation for signing your application, you must first ensure that you have a suitable private key with which to
sign. A suitable private key is one that:

     Is in your possession
     Represents the personal, corporate, or organizational entity to be identified with the application
     Has a validity period that exceeds the expected lifespan of the application or application suite. A validity period of
     more than 25 years is recommended.
     If you plan to publish your application(s) on Android Market, note that a validity period ending after 22 October
     2033 is a requirement. You can not upload an application if it is signed with a key whose validity expires before
     that date.
http://developer.android.com/guide/publishing/app-signing.html                                                     Page 4 of 8
Signing Your Applications | Android Developers                                                                        29.04.09 0:57


     that date.
     Is not the debug key generated by the Android SDK tools.

The key may be self-signed. If you do not have a suitable key, you must generate one using Keytool. Make sure that
you have Keytool available, as described in Basic Setup.

To generate a self-signed key with Keytool, use the keytool command and pass any of the options listed below (and
any others, as needed).

     Note: Before you run Keytool, make sure to read Securing Your Private Key for a discussion of how to keep
     your key secure and why doing so is critically important to you and to users. In particular, when you are
     generating your key, you should select strong passwords for both the keystore and key.

  Keytool Option                           Description

  -genkey                                  Generate a key pair (public and private keys)

  -v                                       Enable verbose output.

  -                                        A name for the keystore containing the private key.
  keystore <keystore-
  name>.keystore

  -storepass                               A password for the keystore.
  <password>
                                           As a security precaution, do not include this option in your command line unless
                                           you are working at a secure computer. If not supplied, Keytool prompts you to enter
                                           the password. In this way, your password is not stored in your shell history.


  -alias <alias_name>                      An alias for the key.

  -keyalg <alg>                            The encryption algorithm to use when generating the key. Both DSA and RSA are
                                           supported.

  -dname <name>                            A Distinguished Name that describes who created the key. The value is used as the
                                           issuer and subject fields in the self-signed certificate.

                                           Note that you do not need to specify this option in the command line. If not
                                           supplied, Jarsigner prompts you to enter each of the Distinguished Name fields (CN,
                                           OU, and so on).


  -validity <valdays>                      The validity period for the key, in days.

                                           Note: A value of 10000 or greater is recommended.


  -keypass <password>                      The password for the key.

                                           As a security precaution, do not include this option in your command line unless
                                           you are working at a secure computer. If not supplied, Keytool prompts you to enter
                                           the password. In this way, your password is not stored in your shell history.


Here's an example of a Keytool command that generates a private key:

     $ keytool -genkey -v -keystore my-release-key.keystore
     -alias alias_name -keyalg RSA -validity 10000



http://developer.android.com/guide/publishing/app-signing.html                                                          Page 5 of 8
Signing Your Applications | Android Developers                                                                          29.04.09 0:57


Running the example command above, Keytool prompts you to provide passwords for the keystore and key, and to
provide the Distinguished Name fields for your key. It then generates the keystore as a file called my-release-
key.keystore. The keystore and key are protected by the passwords you entered. The keystore contains a single
key, valid for 10000 days. The alias is a name that you — will use later, to refer to this keystore when signing your
application.

For more information about Keytool, see the documentation at http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security


Signing your application
When you are ready to actually sign your .apk for release, you can do so using the Jarsigner tool. Make sure that you
have Jarsigner available on your machine, as described in Basic Setup. Also, make sure that the keystore containing
your private key is available.

To sign your application, you run Jarsigner, referencing both the application's .apk and the keystore containing the
private key with which to sign the .apk. The table below shows the options you could use.

  Jarsigner Option                         Description

  -                                        The name of the keystore containing your private key.
  keystore <keystore-
  name>.keystore

  -verbose                                 Enable verbose output.

  -storepass                               The password for the keystore.
  <password>
                                           As a security precaution, do not include this option in your command line unless
                                           you are working at a secure computer. If not supplied, Jarsigner prompts you to
                                           enter the password. In this way, your password is not stored in your shell history.


  -keypass <password>                      The password for the private key.

                                           As a security precaution, do not include this option in your command line unless
                                           you are working at a secure computer. If not supplied, Jarsigner prompts you to
                                           enter the password. In this way, your password is not stored in your shell history.


Here's how you would use Jarsigner to sign an application package called my_application.apk, using the example
keystore created above.


     $ jarsigner -verbose -keystore my-release-key.keystore
     my_application.apk alias_name

Running the example command above, Jarsigner prompts you to provide passwords for the keystore and key. It then
modifies the .apk in-place, meaning the .apk is now signed. Note that you can sign an .apk multiple times with different
keys.

To verify that your .apk is signed, you can use a command like this:


     $ jarsigner -verify my_signed.apk

If the .apk is signed properly, Jarsigner prints "jar verified". If you want more details, you can try one of these
commands:


     $ jarsigner -verify -verbose my_application.apk

http://developer.android.com/guide/publishing/app-signing.html                                                             Page 6 of 8
Signing Your Applications | Android Developers                                                                    29.04.09 0:57




or


     $ jarsigner -verify -verbose -certs my_application.apk

The command above, with the -certs option added, will show you the "CN=" line that describes who created the
key.

     Note: If you see "CN=Android Debug", this means the .apk was signed with the debug key generated by the
     Android SDK. If you intend to release your application, you must sign it with your private key instead of the
     debug key.

For more information about Jarsigner, see the documentation at http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security


Compiling and signing with Eclipse ADT
When using Eclipse with ADT, you can use the Export Wizard to export a signed .apk (and even create a new
keystore, if necessary). The Export Wizard performs all the interaction with the Keytool and Jarsigner for you, which
allows you to perform signing via a graphical interface instead of the command-line. Because the Export Wizard uses
both Keytool and Jarsigner, you should ensure that they are accessible on your computer, as described above in the
Basic Setup for Signing.

To create a signed .apk, right-click the project in the Package Explorer and select Android Tools > Export Signed
Application Package. (Alternatively, open your AndroidManifest.xml file in Eclipse, open the Overview tab, and
click Use the Export Wizard.) The window that appears will display any errors found while attempting to export your
application. If no errors are found, continue with the Export Wizard, which will guide you through the process of
signing your application, including steps for selecting the private key with which to sign the .apk, or creating a new
keystore and private key.

When you complete the Export Wizard, you'll have a signed .apk that's ready for distribution.



Securing Your Private Key
Maintaining the security of your private key is of critical importance, both to you and to the user. If you allow someone
to use your key, or if you leave your keystore and passwords in an unsecured location such that a third-party could
find and use them, your authoring identity and the trust of the user are compromised.

If a third party should manage to take your key without your knowledge or permission, that person could sign and
distribute applications that maliciously replace your authentic applications or corrupt them. Such a person could also
sign and distribute applications under your identity that attack other applications or the system itself, or corrupt or steal
user data.

Your reputation as a developer entity depends on your securing your private key properly, at all times, until the key is
expired. Here are some tips for keeping your key secure:

     Select strong passwords for the keystore and key.
     When you generate your key with Keytool, do not supply the -storepass and -keypass options at the
     command line. If you do so, your passwords will be available in your shell history, which any user on your
     computer could access.
     Similarly, when signing your applications with Jarsigner, do not supply the -storepass and -keypass options
     at the command line.
     Do not give or lend anyone your private key, and do not let unauthorized persons know your keystore and key
     passwords.



http://developer.android.com/guide/publishing/app-signing.html                                                       Page 7 of 8
Signing Your Applications | Android Developers                                                                        29.04.09 0:57


In general, if you follow common-sense precautions when generating, using, and storing your key, it will remain
secure.

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/publishing/app-signing.html                                                          Page 8 of 8
Versioning Your Applications | Android Developers                                                                 29.04.09 0:57




Versioning Your Applications

Versioning is a critical component of your application upgrade/maintenance strategy.

     Users need to have specific information about the application version that is installed on their devices and the
     upgrade versions available for installation.
     Other applications — including other applications that you publish as a suite — need to query the system for your
     application's version, to determine compatibility and identify dependencies.
     Services through which you will publish your application(s) may also need to query your application for its version,
     so that they can display the version to users. A publishing service may also need to check the application version
     to determine compatibility and establish upgrade/downgrade relationships.

The Android system itself does not ever check the application version information for an application, such as to
enforce restrictions on upgrades, compatibility, and so on. Instead, only users or applications themselves are
responsible for enforcing any version restrictions for applications themselves.

The Android system does check any system version compatibility expressed by an application in its manifest, in the
minSdkVersion attribute. This allows an application to specify the minimum system API with which is compatible.
For more information see Specifying Minimum System API Version.



Setting Application Version
To define the version information for your application, you set attributes in the application's manifest file. Two attributes
are available, and you should always define values for both of them:

     android:versionCode — An integer value that represents the version of the application code, relative to other
     versions.
     The value is an integer so that other applications can programatically evaluate it, for example to check an upgrade
     or downgrade relationship. You can set the value to any integer you want, however you should make sure that
     each successive release of your application uses a greater value. The system does not enforce this behavior, but
     increasing the value with successive releases is normative.
     Typically, you would release the first version of your application with versionCode set to 1, then monotonically
     increase the value with each release, regardless whether the release constitutes a major or minor release. This
     means that the android:versionCode value does not necessarily have a strong resemblence to the
     application release version that is visible to the user (see android:versionName, below). Applications and
     publishing services should not display this version value to users.
     android:versionName — A string value that represents the release version of the application code, as it
     should be shown to users.
     The value is a string so that you can describe the application version as a <major>.<minor>.<point> string, or as
     any other type of absolute or relative version identifier.
     As with android:versionCode, the system does not use this value for any internal purpose, other than to
     enable applications to display it to users. Publishing services may also extract the android:versionName value
     for display to users.

You define both of these version attributes in the <manifest> element of the manifest file.


http://developer.android.com/guide/publishing/versioning.html                                                       Page 1 of 2
Versioning Your Applications | Android Developers                                                                     29.04.09 0:57


Here's an example manifest that shows the android:versionCode and android:versionName attributes in the
<manifest> element.

     <?xml version="1.0" encoding="utf-8"?>
     <manifest xmlns:android="http://schemas.android.com/apk/res/android"
           package="com.example.package.name"
           android:versionCode="2"
           android:versionName="1.1">
         <application android:icon="@drawable/icon" android:label="@string/app_name">
             ...
         </application>
     </manifest>

In this example, note that android:versionCode value indicates that the current .apk contains the second release
of the application code, which corresponds to a minor follow-on release, as shown by the android:codeName string.

The Android framework provides an API to let applications query the system for version information about your
application. To obtain version information, applications use the getPackageInfo(java.lang.String, int) method of
PackageManager.



Specifying Minimum System API Version
If your application requires a specific minimum version of the Android platform, you can specify that version as an API
Level identifier in the application's manifest file. Doing so ensures that your application can only be installed on
devices that are running a compatible version of the Android system.

To specify the minimum system version in the manifest, use this attribute:

     android:minSdkVersion — An integer value corresponding to the code version of the Android platform.
     When preparing to install an application, the system checks the value of this attribute and compares it to the
     system version. If the android:minSdkVersion value is greater than the system version, the system aborts
     the installation of the application.
     If you do not specify this attribute in your manifest, the system assumes that your application is compatible with
     all platform versions.

To specify a minimum platform version for your application, add a <uses-sdk> element as a child of <manifest>,
then define the android:minSdkVersion as an attribute.

For more information, also see the Android System Image 1.1 Version Notes.

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/publishing/versioning.html                                                           Page 2 of 2
Preparing to Publish: A Checklist | Android Developers                                                           29.04.09 0:57




Preparing to Publish: A Checklist

Publishing an application means testing it, packaging it appropriately, and making it available to users of Android-
powered mobile devices.

If you plan to publish your application for installation on Android-powered devices, there are several things you need to
do, to get your application ready. This document highlights the significant checkpoints for preparing your application for
a successful release.

If you will publish your application on Android Market, please also see Publishing on Android Market for specific
preparation requirements for your application.

For general information about the ways that you can publish an applications, see the Publishing Your Applications
document.


   Before you consider your application ready for release:
    1. Test your application extensively on an actual device
    2. Consider adding an End User License Agreement in your application
    3. Specify an icon and label in the application's manifest
    4. Turn off logging and debugging and clean up data/files
   Before you do the final compile of your application:
    5. Version your application
    6. Obtain a suitable cryptographic key
    7. Register for a Maps API Key, if your application is using MapView elements
   Compile your application...
   After compiling your application:
    8. Sign your application
    9. Test your compiled application




Before you consider your application ready for release

1. Test your application extensively on an actual device
It's important to test your application as extensively as possible, in as many areas as possible. To help you do that,
Android provides a variety of testing classes and tools. You can use Instrumentation to run JUnit and other test cases,
and you can use testing tools such as the UI/Application Exerciser Monkey.

      To ensure that your application will run properly for users, you should make every effort to obtain one or more
      physical mobile device(s) of the type on which you expect the application to run. You should then test your
      application on the actual device, under realistic network conditions. Testing your application on a physical device
      is very important, because it enables you to verify that your user interface elements are sized correctly (especially
      for touch-screen UI) and that your application's performance and battery efficiency are acceptable.
      If you can not obtain a mobile device of the type you are targeting for your application, you can use emulator
      options such as -dpi, -device, -scale, -netspeed, -netdelay, -cpu-delay and others to model the
      emulator's screen, network performance, and other attributes to match the target device to the greatest extent
      possible. You can then test your application's UI and performance. However, we strongly recommend that you test
http://developer.android.com/guide/publishing/preparing.html                                                       Page 1 of 4
Preparing to Publish: A Checklist | Android Developers                                                          29.04.09 0:57


      possible. You can then test your application's UI and performance. However, we strongly recommend that you test
      your application on an actual target device before publishing it.
      If you are targeting the T-Mobile G1 device for your application, make sure that your UI handles screen orientation
      changes.


2. Consider adding an End User License Agreement in your application
To protect your person, organization, and intellectual property, you may want to provide an End User License
Agreement (EULA) with your application.


3. Specify an icon and label in the application's manifest
The icon and label that you specify in an application's manifest are important because they are displayed to users as
your application's icon and name. They are displayed on the device's Home screen, as well as in Manage Applications,
My Downloads, and elsewhere. Additionally, publishing services may display the icon and label to users.

To specify an icon and label, you define the attributes android:icon and android:label in the <application>
element of the manifest.

As regards the design of your icon, you should try to make it match as much as possible the style used by the built-in
Android applications.


4. Turn off logging and debugging and clean up data/files
For release, you should make sure that debug facilities are turned off and that debug and other unnecessary data/files
are removed from your application project.

      Remove the android:debuggable="true" attribute from the <application> element of the manifest.
      Remove log files, backup files, and other unnecessary files from the application project.
      Check for private or proprietary data and remove it as necessary.
      Deactivate any calls to Log methods in the source code.




Before you do the final compile of your application

5. Version your application
Before you compile your application, you must make sure that you have defined a version number for your application,
specifying an appropriate value for both the android:versionCode and android:versionName attributes of the
<manifest> element in the application's manifest file. Carefully consider your version numbering plans in the context
of your overall application upgrade strategy.

If you have previously released a version of your application, you must make sure to increment the version number of
the current application. You must increment both the android:versionCode and android:versionName
attributes of the <manifest> element in the application's manifest file, using appropriate values.

For detailed information about how to define version information for your application, see Versioning Your Applications.


6. Obtain a suitable cryptographic key
If you have read and followed all of the preparation steps up to this point, your application is compiled and ready for
signing. Inside the .apk, the application is properly versioned, and you've cleaned out extra files and private data, as
described above.


http://developer.android.com/guide/publishing/preparing.html                                                      Page 2 of 4
Preparing to Publish: A Checklist | Android Developers                                                           29.04.09 0:57


Before you sign your application, you need to make sure that you have a suitable private key. For complete information
about how to obtain (or generate) a private key, see Obtaining a Suitable Private Key.

Once you have obtained (or generated) a suitable private key, you will use it to:

      Register for a Maps API Key (see below), if your application uses MapView elements.
      Sign your application for release, later in the preparation process


7. Register for a Maps API Key, if your application is using MapView elements
If your application uses one or more Mapview elements, you will
need to register your application with the Google Maps service and          For complete information about getting a Maps
obtain a Maps API Key, before your MapView(s) will be able to               API Key, see Obtaining a Maps API Key.
retrieve data from Google Maps. To do so, you supply an MD5
fingerprint of your signer certificate to the Maps service.

During development, you can get a temporary Maps API Key by registering the debug key generated by the SDK
tools. However, before publishing your application, you must register for a new Maps API Key that is based on your
private key.

If your application uses MapView elements, the important points to understand are:

 1. You must obtain the Maps API Key before you compile your application for release, because you must add the
    Key to a special attribute in each MapView element — android:apiKey — in your application's layout files. If
    you are instantiating MapView objects directly from code, you must pass the Maps API Key as a parameter in the
    constructor.
 2. The Maps API Key referenced by your application's MapView elements must be registered (in Google Maps) to
    the certificate used to sign the application. This is particularly important when publishing your application — your
    MapView elements must reference a Key that is registered to the release certificate that you will use to sign your
    application.
 3. If you previously got a temporary Maps API Key by registering the debug certificate generated by the SDK tools,
    you must remember to obtain a new Maps API Key by registering your release certificate. You must then
    remember to change the MapView elements to reference the new Key, rather than the Key associated with the
    debug certificate. If you do not do so, your MapView elements will not have permission to download Maps data.
 4. If you change the private key that you will use to sign your application, you must remember to obtain a new Maps
    API Key from the Google Maps service. If you do not get a new Maps API Key and apply it to all MapView
    elements, any MapView elements referencing the old Key will not have permission to download Maps data.

For more information about signing and your private key, see Signing Your Applications.



Compile your application
When you've prepared your application as described in the previous sections, you can compile your application for
release.



After compiling your application

8. Sign your application
Sign your application using your private key. Signing your application correctly is critically important. Please see
Signing Your Applications for complete information.


http://developer.android.com/guide/publishing/preparing.html                                                        Page 3 of 4
Preparing to Publish: A Checklist | Android Developers                                                                29.04.09 0:57



9. Test your compiled and signed application
Before you release your compiled application, you should thoroughly test it on the target mobile device (and target
network, if possible). In particular, you should make sure that any MapView elements in your UI are receiving maps
data properly. If they are not, go back to Register for a Maps API Key and correct the problem. You should also
ensure that the application works correctly with any server-side services and data that you are providing or are relying
on and that the application handles any authentication requirements correctly.

After testing, you are now ready to publish your application to mobile device users.

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/publishing/preparing.html                                                            Page 4 of 4
Publishing Your Applications | Android Developers                                                              29.04.09 0:57




Publishing Your Applications

Publishing an application means testing it, packaging it appropriately, and making it available to users of Android-
powered mobile devices for download or sideload.

If you've followed the steps outlined in Preparing to Publish Your Applications, the result of the process is a compiled
.apk that is signed with your release private key. Inside the .apk, the application is properly versioned and any
MapView elements reference a Maps API Key that you obtained by registering the MD5 fingerprint of the same
certificate used to sign the .apk. Your application is now ready for publishing.

The sections below provide information about publishing your Android application to mobile device users.



Publishing on Android Market
Android Market is a hosted service that makes it easy for users to find and download Android applications to their
Android-powered devices, and makes it easy for developers to publish their applications to Android users.

To publish your application on Android Market, you first need to register with the service using your Google account
and agree to the terms of service. Once you are registered, you can upload your application to the service whenever
you want, as many times as you want, and then publish it when you are ready. Once published, users can see your
application, download it, and rate it using the Market application installed on their Android-powered devices.

To register as an Android Market developer and get started with publishing, visit the Android Market:

        http://market.android.com/publish

If you plan to publish your application on Android Market, you must make sure that it meets the requirements listed
below, which are enforced by the Market server when you upload the application.


  Requirements enforced by the Android Market server:
   1. Your application must be signed with a cryptographic private key whose validity period ends after 22 October
      2033.
   2. Your application must define both an android:versionCode and an android:versionName attribute in
      the <manifest> element of its manifest. The server uses the android:versionCode as the basis for
      identifying the application internally and handling upgrades, and it displays the android:versionName to
      users as the application's version.
   3. Your application must define both an android:icon and an android:label attribute in the
      <application> element of its manifest.



Publishing Upgrades on Android Market
The beta version of Android Market does not support notifying your users when you publish a new version of your
application. This capability will be added soon, but currently the user must independently initiate download of an
upgraded application. When you publish an upgrade, you can assist users by notifying them that the upgrade is
available and giving them a way to download the upgraded application from Android Market.

Here is a suggested way of tracking installed application versions and notifying users that an upgrade is available:


http://developer.android.com/guide/publishing/publishing.html                                                    Page 1 of 3
Publishing Your Applications | Android Developers                                                               29.04.09 0:57


 1. Have your app occasionally check in with a web-service that you're running. This web service should return two
    values: the latest available version number for the application (corresponding to android:versionCode) and a
    URI string that your application can later send in an Intent, to launch Market and search for the upgraded
    application for the user.
     The URI that your web service returns should be properly formatted to search Android Market for your upgraded
     application. See Using Intents to Launch the Market Application for more information. The URI should specify the
     upgraded application's package name as the query parameter, since the package name is guaranteed to be
     unique on Android Market. The URI format for the package name search is:
     http://market.android.com/search?q=pname:<package> or
     market://search?q=pname:<package>
 2. Your application can then compare its own version number against that retrieved. If the retrieved value is greater,
    your application can show a dialog informing the user that a new version is available. The dialog can offer buttons
    to begin the download or cancel.
 3. If the user clicks the button to begin the download, your application can call startActivity() using the
    ACTION_VIEW Intent, passing the URI received from your web service. The Intent launches the Market
    application on the device and initiates an immediate search on the Android Market site, based on the query
    parameters in the URI. When the result is displayed, the user can view the details of the upgraded application and
    begin the download.
     Note that, because the URI string is received from your web service and not hard-coded into your application, you
     can easily change the Market launch behaviors whenever needed, without having to change your application.

For more information about URIs you can pass to the Market application at launch, see Using Intents to Launch the
Market Application, below.


Using Intents to Launch the Market Application on a Device
Android-powered devices include a preinstalled Market application that gives users access to the Android Market site.
From Market, users can browse or search available applications, read ratings and reviews, and download/install
applications.

You can launch the Market application from another Android application by sending an Intent to the system. You might
want to do this, for example, to help the user locate and download an upgrade to an installed application, or to let the
user know about related applications that are available for download.

To launch Market, you send an ACTION_VIEW Intent, passing a Market-handled URI string as the Intent data. In most
cases, your application would call startActivity() to send the ACTION_VIEW Intent with the Market-handled URI.

The URI that you supply with the Intent lets the system route the intent properly and also expresses the type of action
that you want Market to perform after launch. Currently, you can have Market initiate a search for applications on
Android Market, based on query parameters that you provide. For example, you can specify URIs to search for
applications by:

     Package name
     Developer name
     String match across application name, developer name, and description, or
     Any combination of the above

Note that the URI queries return results from the public metadata supplied by developers in their Android Market
profiles or application publishing information, but not from the developer's private account or from the certificate used
to sign the application.

The table below provides a list of URIs and actions currently supported by the Market application.

  For this Result                            Pass this URI with the ACTION_VIEW       Comments
                                             Intent

http://developer.android.com/guide/publishing/publishing.html                                                     Page 2 of 3
Publishing Your Applications | Android Developers                                                                             29.04.09 0:57




  Search for an application                  http://market.android.com/search?                     Searches only the Java package
  by its fully qualified Java                q=pname:<package> or                                  name of applications. Returns
  package name and display                   market://search?q=pname:<package>                     only exact matches.
  the result.

  Search for applications by                 http://market.android.com/search?                     Searches only the "Developer
  developer name and                         q=pub:"<Developer Name>" or                           Name" fields of Market public
  display the results.                       market://search?q=pub:"<Developer                     profiles. Returns exact matches
                                             Name>"                                                only.

  Search for applications by                 http://market.android.com/search?                     Searches all public fields
  substring and display the                  q=<substring> or                                      (application title, developer name,
  results.                                   market://search?q=<substring>                         and application description) for
                                                                                                   all applications. Returns exact
                                                                                                   and partial matches.

  Search using multiple                      Example:                                              Returns a list of applications
  query parameters and                       http://market.android.com/search?                     meeting all the supplied
  display the results.                       q=world pname:com.android.hello                       parameters.
                                             pub:Android


Note that these URIs work only when passed as intent data — you can't currently load the URIs in a web browser,
either on a desktop machine or on the device.

                                                                                                                             ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/publishing/publishing.html                                                                   Page 3 of 3
User Interface Guidelines | Android Developers                                              29.04.09 0:58




User Interface Guidelines

The Android UI team has begun developing guidelines for the interaction and
design of Android applications. Look here for articles that describe these visual
guidelines as we release them.

Widget Design Guidelines
    Widgets are a new feature introduced in Cupcake. A widget displays an
    application's most important or timely information at a glance, on a user's
    Home screen. These design guidelines describe how to design widgets that fit
    with others on the Home screen. They include links to graphics files and
    templates that will make your designer's life easier.

                                                                              ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and
restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/practices/ui_guidelines/index.html                         Page 1 of 1
Widget Design Guidelines | Android Developers                                                                             29.04.09 0:58




Widget Design Guidelines

Widgets are a new feature introduced in Android™ mobile technology platform 1.5 ("Cupcake"). A widget displays an
application's most important or timely information at a glance, on a user's Home screen. The Android open source
code includes several examples of widgets, including widgets for Calendar, Music, and other applications.

Users pick the widgets they want to display on their Home screens by touching & holding an empty area of the Home
screen, selecting Widgets from the menu, and then selecting the widget they want.




This document describes how to design a widget so it fits graphically with other widgets and with the other elements of
the Android Home screen. It also describes some standards for widget artwork and some widget graphics tips and
tricks from the Android team.

For information about developing widgets, see the AppWidgets section of the Developer's Guide and the AddWidgets
blog post.



Standard widget anatomy
Typical Android widgets have three main components: A bounding box, a frame, and the widget's graphical controls
and other elements. Well-designed widgets leave some padding between the edges of the bounding box and the
frame, and between the inner edges of the frame and the widget's controls. Widgets designed to fit visually with other
widgets on the Home screen take cues from the other elements on the Home screen for alignment; they also use
standard shading effects. All of these details are described in this document.

Standard Widget Sizes in Portrait Orientation




http://developer.android.com/guide/practices/ui_guidelines/widget_design.html                                               Page 1 of 7
Widget Design Guidelines | Android Developers                                                                               29.04.09 0:58




Standard Widget Sizes in Landscape Orientation




Designing a widget
1. Select a bounding box size for your widget.
   The most effective widgets display your application's most useful or timely data in the smallest widget size. Users
   will weigh the usefulness or your widget against the portion of the Home screen it covers, so the smaller the
   better.

   All widgets must fit within the bounding box of one of the six supported widget sizes, or better yet, within a pair of
   portrait and landscape orientation sizes, so your widget looks good when the user switches screen orientations.

   Standard widget sizes illustrates the bounding dimensions of the six widget sizes (three in portrait and three in
   landscape orientation).

2. Select a matching frame.
   Standard widget frames illustrates the standard frames for the six widget sizes, with links so you can download
   copies for your own use. You don't have to use these frames for your widget, but if you do, your widgets are more
   likely to fit visually with other widgets.

3. Apply standard shadow effect to your graphics.
   Again, you don't have to use this effect, but Standard widget shadows shows the Photoshop settings used for
   standard widgets.


http://developer.android.com/guide/practices/ui_guidelines/widget_design.html                                                 Page 2 of 7
Widget Design Guidelines | Android Developers                                                                                 29.04.09 0:58


    standard widgets.

 4. If your widget includes buttons, draw them in three states (default, pressed, and selected).
    You can download a Photoshop file that contains the three states of the Play button, taken from the Music widget,
    to analyze the Photoshop settings used for the three standard button effects.




 5. Finish drawing your artwork and then scale and align it to fit.
    Widget alignment tips and tricks describes some techniques for aligning your widget's graphics inside the standard
    frames, along with a few other widget graphics tricks.

 6. Save your widget with the correct graphics file settings.
    Windows graphics file format describes the correct settings for your widget graphics files.



Standard widget sizes
There are six standard widget sizes, based on a Home screen grid of 4 x 4 (portrait) or 4 x 4 (landscape) cells. These
dimensions are the bounding boxes for the six standard widget sizes. The contents of typical widgets don't draw to the
edge of these dimensions, but fit inside a frame withing the bounding box, as described in Designing a widget.

In portrait orientation, each cell is 80 pixels wide by 100 pixels tall (the diagram shows a cell in portrait orientation).
The three supported widget sizes in portrait orientation are:

  Cells     Pixels

  4x1       320 x 100

  3x3       240 x 300

  2x2       160 x 200




In landscape orientation, each cell is 106 pixels wide by 74 pixels tall. The three supported widget sizes in landscape
orientation are:

  Cells     Pixels

  4x1       424 x 74

  3x3       318 x 222

  2x2       212 x 148




http://developer.android.com/guide/practices/ui_guidelines/widget_design.html                                                   Page 3 of 7
Widget Design Guidelines | Android Developers                                                                         29.04.09 0:58




Standard widget frames
For each of the six standard widget sizes there is a standard frame. You can click the images of the frames in this
section to download a Photoshop file for that frame, which you can use for your own widgets.




4x1_Widget_Frame_Portrait.psd




3x3_Widget_Frame_Portrait.psd




2x2_Widget_Frame_Portrait.psd




http://developer.android.com/guide/practices/ui_guidelines/widget_design.html                                           Page 4 of 7
Widget Design Guidelines | Android Developers                                                                          29.04.09 0:58




4x1_Widget_Frame_Landscape.psd




3x3_Widget_Frame_Landscape.psd




2x2_Widget_Frame_Landscape.psd



Standard widget shadows
You can apply a shadow effect to your widget's artwork, so it matches other standard Android widgets, using the
following settings in the Photoshop Layer Style dialog box.




Widget graphics tips and tricks
The Android team has developed a few tricks for aligning widget artwork within standard widget bounding boxes and
frames, so the widget aligns visually with other widgets and the other elements of the Home screen, as well as other
techniques for creating widgets.

    Use a screen shot from the Android SDK emulator to align both the shapes and shadows of your widget controls
    with the Search widget and with other elements on the Home screen.


http://developer.android.com/guide/practices/ui_guidelines/widget_design.html                                            Page 5 of 7
Widget Design Guidelines | Android Developers                                                                               29.04.09 0:58


    Cut the widget artwork asset" based on the full size of a cell, including any padding you want. (That is, for a 4 x 1
    widget, cut the asset at 320 by 100 pixels.)




    To reduce banding when exporting a widget, apply the following Photoshop Add Noise setting to your graphic.




    Apply 9-patch techniques to shrink the graphic and set the padding of the content area. (See the detailed guide
    here.)
    Note: The current Android widget templates were designed using a custom gradient angle, which means the 9-
    patch techniques can't be used to optimize the size of the asset. However, 9-patch techniques were used to set
    the content area padding.

    In some cases, devices have low pixel depths that can cause visual banding and dithering issues. To solve this,
    application developers should pass assets through a "proxy" drawable defined as XML:. This technique references
    the original artwork, in this case "background.9.png", and instructs the device to dither it as needed.




Widget graphics file format
Save your widget artwork using the appropriate bounding box size in PNG-24 format on a transparent background and
in 8-bit color.




http://developer.android.com/guide/practices/ui_guidelines/widget_design.html                                                 Page 6 of 7
Widget Design Guidelines | Android Developers                                                                                      29.04.09 0:58




                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/practices/ui_guidelines/widget_design.html                                                        Page 7 of 7
Designing for Performance | Android Developers                                                                 29.04.09 0:58




Designing for Performance

An Android application should be fast. Well, it's probably more accurate to say that it should be efficient. That is, it
should execute as efficiently as possible in the mobile device environment, with its limited computing power and data
storage, smaller screen, and constrained battery life.

As you develop your application, keep in mind that, while the application may perform well enough in your emulator,
running on your dual-core development computer, it will not perform that well when run a mobile device — even the
most powerful mobile device can't match the capabilities of a typical desktop system. For that reason, you should
strive to write efficient code, to ensure the best possible performance on a variety of mobile devices.

Generally speaking, writing fast or efficient code means keeping memory allocations to a minimum, writing tight code,
and avoiding certain language and programming idioms that can subtly cripple performance. In object-oriented terms,
most of this work takes place at the method level, on the order of actual lines of code, loops, and so on.

This document covers these topics:

     Introduction
     Avoid Creating Objects
     Use Native Methods
     Prefer Virtual Over Interface
     Prefer Static Over Virtual
     Avoid Internal Getters/Setters
     Cache Field Lookups
     Declare Constants Final
     Use Enhanced For Loop Syntax With Caution
     Avoid Enums
     Use Package Scope with Inner Classes
     Avoid Float
     Some Sample Performance Numbers
     Closing Notes




Introduction
There are two basic rules for resource-constrained systems:

     Don't do work that you don't need to do.
     Don't allocate memory if you can avoid it.

All the tips below follow from these two basic tenets.

Some would argue that much of the advice on this page amounts to "premature optimization." While it's true that micro-
optimizations sometimes make it harder to develop efficient data structures and algorithms, on embedded devices like
handsets you often simply have no choice. For instance, if you bring your assumptions about VM performance on

http://developer.android.com/guide/practices/design/performance.html                                             Page 1 of 8
Designing for Performance | Android Developers                                                                      29.04.09 0:58


handsets you often simply have no choice. For instance, if you bring your assumptions about VM performance on
desktop machines to Android, you're quite likely to write code that exhausts system memory. This will bring your
application to a crawl — let alone what it will do to other programs running on the system!

That's why these guidelines are important. Android's success depends on the user experience that your applications
provide, and that user experience depends in part on whether your code is responsive and snappy, or slow and
aggravating. Since all our applications will run on the same devices, we're all in this together, in a way. Think of this
document as like the rules of the road you had to learn when you got your driver's license: things run smoothly when
everybody follows them, but when you don't, you get your car smashed up.

Before we get down to brass tacks, a brief observation: nearly all issues described below are valid whether or not the
VM features a JIT compiler. If I have two methods that accomplish the same thing, and the interpreted execution of
foo() is faster than bar(), then the compiled version of foo() will probably be as fast or faster than compiled bar(). It is
unwise to rely on a compiler to "save" you and make your code fast enough.



Avoid Creating Objects
Object creation is never free. A generational GC with per-thread allocation pools for temporary objects can make
allocation cheaper, but allocating memory is always more expensive than not allocating memory.

If you allocate objects in a user interface loop, you will force a periodic garbage collection, creating little "hiccups" in
the user experience.

Thus, you should avoid creating object instances you don't need to. Some examples of things that can help:

     When extracting strings from a set of input data, try to return a substring of the original data, instead of creating a
     copy. You will create a new String object, but it will share the char[] with the data.
     If you have a method returning a string, and you know that its result will always be appended to a StringBuffer
     anyway, change your signature and implementation so that the function does the append directly, instead of
     creating a short-lived temporary object.

A somewhat more radical idea is to slice up multidimensional arrays into parallel single one-dimension arrays:

     An array of ints is a much better than an array of Integers, but this also generalizes to the fact that two parallel
     arrays of ints are also a lot more efficient than an array of (int,int) objects. The same goes for any combination of
     primitive types.
     If you need to implement a container that stores tuples of (Foo,Bar) objects, try to remember that two parallel Foo[]
     and Bar[] arrays are generally much better than a single array of custom (Foo,Bar) objects. (The exception to this,
     of course, is when you're designing an API for other code to access; in those cases, it's usually better to trade
     correct API design for a small hit in speed. But in your own internal code, you should try and be as efficient as
     possible.)

Generally speaking, avoid creating short-term temporary objects if you can. Fewer objects created mean less-frequent
garbage collection, which has a direct impact on user experience.



Use Native Methods
When processing strings, don't hesitate to use specialty methods like String.indexOf(), String.lastIndexOf(), and their
cousins. These are typically implemented in C/C++ code that easily runs 10-100x faster than doing the same thing in
a Java loop.

The flip side of that advice is that punching through to a native method is more expensive than calling an interpreted
method. Don't use native methods for trivial computation, if you can avoid it.


http://developer.android.com/guide/practices/design/performance.html                                                  Page 2 of 8
Designing for Performance | Android Developers                                                                 29.04.09 0:58




Prefer Virtual Over Interface
Suppose you have a HashMap object. You can declare it as a HashMap or as a generic Map:


     Map myMap1 = new HashMap();
     HashMap myMap2 = new HashMap();

Which is better?

Conventional wisdom says that you should prefer Map, because it allows you to change the underlying implementation
to anything that implements the Map interface. Conventional wisdom is correct for conventional programming, but isn't
so great for embedded systems. Calling through an interface reference can take 2x longer than a virtual method call
through a concrete reference.

If you have chosen a HashMap because it fits what you're doing, there is little value in calling it a Map. Given the
availability of IDEs that refactor your code for you, there's not much value in calling it a Map even if you're not sure
where the code is headed. (Again, though, public APIs are an exception: a good API usually trumps small performance
concerns.)



Prefer Static Over Virtual
If you don't need to access an object's fields, make your method static. It can be called faster, because it doesn't
require a virtual method table indirection. It's also good practice, because you can tell from the method signature that
calling the method can't alter the object's state.



Avoid Internal Getters/Setters
In native languages like C++ it's common practice to use getters (e.g. i = getCount()) instead of accessing the
field directly (i = mCount). This is an excellent habit for C++, because the compiler can usually inline the access,
and if you need to restrict or debug field access you can add the code at any time.

On Android, this is a bad idea. Virtual method calls are expensive, much more so than instance field lookups. It's
reasonable to follow common object-oriented programming practices and have getters and setters in the public
interface, but within a class you should always access fields directly.



Cache Field Lookups
Accessing object fields is much slower than accessing local variables. Instead of writing:

     for (int i = 0; i < this.mCount; i++)
           dumpItem(this.mItems[i]);

You should write:

        int count = this.mCount;
        Item[] items = this.mItems;

        for (int i = 0; i < count; i++)
            dumpItems(items[i]);

http://developer.android.com/guide/practices/design/performance.html                                             Page 3 of 8
Designing for Performance | Android Developers                                                                 29.04.09 0:58




(We're using an explicit "this" to make it clear that these are member variables.)

A similar guideline is never call a method in the second clause of a "for" statement. For example, the following code
will execute the getCount() method once per iteration, which is a huge waste when you could have simply cached the
value as an int:


     for (int i = 0; i < this.getCount(); i++)
         dumpItems(this.getItem(i));

It's also usually a good idea to create a local variable if you're going to be accessing an instance field more than once.
For example:

            protected void drawHorizontalScrollBar(Canvas canvas, int width, int height) {
                if (isHorizontalScrollBarEnabled()) {
                    int size = mScrollBar.getSize(false);
                    if (size <= 0) {
                        size = mScrollBarSize;
                    }
                    mScrollBar.setBounds(0, height - size, width, height);
                    mScrollBar.setParams(
                            computeHorizontalScrollRange(),
                            computeHorizontalScrollOffset(),
                            computeHorizontalScrollExtent(), false);
                    mScrollBar.draw(canvas);
                }
            }

That's four separate lookups of the member field mScrollBar. By caching mScrollBar in a local stack variable, the
four member field lookups become four stack variable references, which are much more efficient.

Incidentally, method arguments have the same performance characteristics as local variables.



Declare Constants Final
Consider the following declaration at the top of a class:

     static int intVal = 42;
     static String strVal = "Hello, world!";

The compiler generates a class initializer method, called <clinit>, that is executed when the class is first used. The
method stores the value 42 into intVal, and extracts a reference from the classfile string constant table for strVal.
When these values are referenced later on, they are accessed with field lookups.

We can improve matters with the "final" keyword:


     static final int intVal = 42;
     static final String strVal = "Hello, world!";

The class no longer requires a <clinit> method, because the constants go into classfile static field initializers, which
are handled directly by the VM. Code accessing intVal will use the integer value 42 directly, and accesses to
strVal will use a relatively inexpensive "string constant" instruction instead of a field lookup.

Declaring a method or class "final" does not confer any immediate performance benefits, but it does allow certain
optimizations. For example, if the compiler knows that a "getter" method can't be overridden by a sub-class, it can
inline the method call.

http://developer.android.com/guide/practices/design/performance.html                                              Page 4 of 8
Designing for Performance | Android Developers                                                                   29.04.09 0:58




You can also declare local variables final. However, this has no definitive performance benefits. For local variables,
only use "final" if it makes the code clearer (or you have to, e.g. for use in an anonymous inner class).



Use Enhanced For Loop Syntax With Caution
The enhanced for loop (also sometimes known as "for-each" loop) can be used for collections that implement the
Iterable interface. With these objects, an iterator is allocated to make interface calls to hasNext() and next(). With an
ArrayList, you're better off walking through it directly, but for other collections the enhanced for loop syntax will be
equivalent to explicit iterator usage.

Nevertheless, the following code shows an acceptable use of the enhanced for loop:

     public class Foo {
         int mSplat;
         static Foo mArray[] = new Foo[27];

            public static void zero() {
                int sum = 0;
                for (int i = 0; i < mArray.length; i++) {
                    sum += mArray[i].mSplat;
                }
            }

            public static void one() {
                int sum = 0;
                Foo[] localArray = mArray;
                int len = localArray.length;

                   for (int i = 0; i < len; i++) {
                       sum += localArray[i].mSplat;
                   }
            }

            public static void two() {
                int sum = 0;
                for (Foo a: mArray) {
                    sum += a.mSplat;
                }
            }
     }

zero() retrieves the static field twice and gets the array length once for every iteration through the loop.

one() pulls everything out into local variables, avoiding the lookups.

two() uses the enhanced for loop syntax introduced in version 1.5 of the Java programming language. The code
generated by the compiler takes care of copying the array reference and the array length to local variables, making it a
good choice for walking through all elements of an array. It does generate an extra local load/store in the main loop
(apparently preserving "a"), making it a teensy bit slower and 4 bytes longer than one().

To summarize all that a bit more clearly: enhanced for loop syntax performs well with arrays, but be cautious when
using it with Iterable objects since there is additional object creation.



Avoid Enums
Enums are very convenient, but unfortunately can be painful when size and speed matter. For example, this:



http://developer.android.com/guide/practices/design/performance.html                                               Page 5 of 8
Designing for Performance | Android Developers                                                                  29.04.09 0:58


     public class Foo {
        public enum Shrubbery { GROUND, CRAWLING, HANGING }
     }

turns into a 900 byte .class file (Foo$Shrubbery.class). On first use, the class initializer invokes the <init> method on
objects representing each of the enumerated values. Each object gets its own static field, and the full set is stored in
an array (a static field called "$VALUES"). That's a lot of code and data, just for three integers.

This:


     Shrubbery shrub = Shrubbery.GROUND;

causes a static field lookup. If "GROUND" were a static final int, the compiler would treat it as a known constant and
inline it.

The flip side, of course, is that with enums you get nicer APIs and some compile-time value checking. So, the usual
trade-off applies: you should by all means use enums for public APIs, but try to avoid them when performance
matters.

In some circumstances it can be helpful to get enum integer values through the ordinal() method. For example,
replace:


     for (int n = 0; n < list.size(); n++) {
         if (list.items[n].e == MyEnum.VAL_X)
            // do stuff 1
         else if (list.items[n].e == MyEnum.VAL_Y)
            // do stuff 2
     }

with:

          int valX = MyEnum.VAL_X.ordinal();
          int valY = MyEnum.VAL_Y.ordinal();
          int count = list.size();
          MyItem items = list.items();
          for (int          n = 0; n < count; n++)
          {
               int          valItem = items[n].e.ordinal();
                   if (valItem == valX)
                     // do stuff 1
                   else if (valItem == valY)
                     // do stuff 2
          }

In some cases, this will be faster, though this is not guaranteed.



Use Package Scope with Inner Classes
Consider the following class definition:


     public class Foo {
         private int mValue;

              public void run() {
                  Inner in = new Inner();

http://developer.android.com/guide/practices/design/performance.html                                              Page 6 of 8
Designing for Performance | Android Developers                                                               29.04.09 0:58

                   Inner in = new Inner();
                   mValue = 27;
                   in.stuff();
            }

            private void doStuff(int value) {
                System.out.println("Value is " + value);
            }

            private class Inner {
                void stuff() {
                    Foo.this.doStuff(Foo.this.mValue);
                }
            }
     }

The key things to note here are that we define an inner class (Foo$Inner) that directly accesses a private method and
a private instance field in the outer class. This is legal, and the code prints "Value is 27" as expected.

The problem is that Foo$Inner is technically (behind the scenes) a totally separate class, which makes direct access to
Foo's private members illegal. To bridge that gap, the compiler generates a couple of synthetic methods:


     /*package*/ static int Foo.access$100(Foo foo) {
         return foo.mValue;
     }
     /*package*/ static void Foo.access$200(Foo foo, int value) {
         foo.doStuff(value);
     }

The inner-class code calls these static methods whenever it needs to access the "mValue" field or invoke the "doStuff"
method in the outer class. What this means is that the code above really boils down to a case where you're accessing
member fields through accessor methods instead of directly. Earlier we talked about how accessors are slower than
direct field accesses, so this is an example of a certain language idiom resulting in an "invisible" performance hit.

We can avoid this problem by declaring fields and methods accessed by inner classes to have package scope, rather
than private scope. This runs faster and removes the overhead of the generated methods. (Unfortunately it also means
the fields could be accessed directly by other classes in the same package, which runs counter to the standard OO
practice of making all fields private. Once again, if you're designing a public API you might want to carefully consider
using this optimization.)



Avoid Float
Before the release of the Pentium CPU, it was common for game authors to do as much as possible with integer
math. With the Pentium, the floating point math co-processor became a built-in feature, and by interleaving integer and
floating-point operations your game would actually go faster than it would with purely integer math. The common
practice on desktop systems is to use floating point freely.

Unfortunately, embedded processors frequently do not have hardware floating point support, so all operations on "float"
and "double" are performed in software. Some basic floating point operations can take on the order of a millisecond to
complete.

Also, even for integers, some chips have hardware multiply but lack hardware divide. In such cases, integer division
and modulus operations are performed in software — something to think about if you're designing a hash table or
doing lots of math.



Some Sample Performance Numbers


http://developer.android.com/guide/practices/design/performance.html                                           Page 7 of 8
Designing for Performance | Android Developers                                                                        29.04.09 0:58


To illustrate some of our ideas, here is a table listing the approximate run times for a few basic actions. Note that
these values should NOT be taken as absolute numbers: they are a combination of CPU and wall clock time, and will
change as improvements are made to the system. However, it is worth noting how these values apply relative to each
other — for example, adding a member variable currently takes about four times as long as adding a local variable.

  Action                                                               Time

  Add a local variable                                                 1

  Add a member variable                                                4

  Call String.length()                                                 5

  Call empty static native method                                      5

  Call empty static method                                             12

  Call empty virtual method                                            12.5

  Call empty interface method                                          15

  Call Iterator:next() on a HashMap                                    165

  Call put() on a HashMap                                              600

  Inflate 1 View from XML                                              22,000

  Inflate 1 LinearLayout containing 1 TextView                         25,000

  Inflate 1 LinearLayout containing 6 View objects                     100,000

  Inflate 1 LinearLayout containing 6 TextView objects                 135,000

  Launch an empty activity                                             3,000,000




Closing Notes
The best way to write good, efficient code for embedded systems is to understand what the code you write really
does. If you really want to allocate an iterator, by all means use enhanced for loop syntax on a List; just make it a
deliberate choice, not an inadvertent side effect.

Forewarned is forearmed! Know what you're getting into! Insert your favorite maxim here, but always think carefully
about what your code is doing, and be on the lookout for ways to speed it up.

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/practices/design/performance.html                                                    Page 8 of 8
Designing for Responsiveness | Android Developers                                                                29.04.09 0:58




Designing for Responsiveness

It's possible to write code that wins every performance test in the world, but still sends users in a fiery rage when they
try to use the application. These are the applications that aren't responsive enough — the ones that feel sluggish, hang
or freeze for significant periods, or take too long to process input.

In Android, the system guards against applications that are insufficiently responsive for a period of time by displaying a
dialog to the user, called the Application Not Responding (ANR) dialog. The user can choose to let the application
continue, but the user won't appreciate having to act on this dialog every time he or she uses your application. So it's
important to design responsiveness into your application, so that the system never has cause to display an ANR to the
user.

Generally, the system displays an ANR if an application cannot respond to user input. For example, if an application
blocks on some I/O operation (frequently a network access), then the main application thread won't be able to process
incoming user input events. After a time, the system concludes that the application has hung, and displays the ANR to
give the user the option to kill it.

Similarly, if your application spends too much time building an elaborate in-memory structure, or perhaps computing
the next move in a game, the system will conclude that your application has hung. It's always important to make sure
these computations are efficient using the techniques above, but even the most efficient code still takes time to run.

In both of these cases, the fix is usually to create a child thread, and do most of your work there. This keeps the main
thread (which drives the user interface event loop) running, and prevents the system from concluding your code has
frozen. Since such threading usually is accomplished at the class level, you can think of responsiveness as a class
problem. (Compare this with basic performance, which was described above as a method-level concern.)

This document discusses how the Android system determines
whether an application is not responding and provides guidelines for
ensuring that your application is responsive.

This document covers these topics:

     What Triggers ANR?
     How to Avoid ANR
     Reinforcing Responsiveness




What Triggers ANR?
In Android, application responsiveness is monitored by the Activity
Manager and Window Manager system services. Android will display
the ANR dialog for a particular application when it detects one of the
following conditions:

     No response to an input event (e.g. key press, screen touch)
     within 5 seconds
     A BroadcastReceiver hasn't finished executing within 10
     seconds
                                                                               An ANR dialog displayed to the user.


http://developer.android.com/guide/practices/design/responsiveness.html                                               Page 1 of 2
Designing for Responsiveness | Android Developers                                                                     29.04.09 0:58




How to Avoid ANR
Given the above definition for ANR, let's examine why this can occur in Android applications and how best to structure
your application to avoid ANR.

Android applications normally run entirely on a single (i.e. main) thread. This means that anything your application is
doing in the main thread that takes a long time to complete can trigger the ANR dialog because your application is not
giving itself a chance to handle the input event or Intent broadcast.

Therefore any method that runs in the main thread should do as little work as possible. In particular, Activities should
do as little as possible to set up in key life-cycle methods such as onCreate() and onResume(). Potentially long
running operations such as network or database operations, or computationally expensive calculations such as resizing
bitmaps should be done in a child thread (or in the case of databases operations, via an asynchronous request).
However, this does not mean that your main thread should block while waiting for the child thread to complete — nor
should you call Thread.wait() or Thread.sleep(). Instead of blocking while waiting for a child thread to
complete, your main thread should provide a Handler for child threads to post back to upon completion. Designing your
application in this way will allow your main thread to remain responsive to input and thus avoid ANR dialogs caused by
the 5 second input event timeout. These same practices should be followed for any other threads that display UI, as
they are also subject to the same timeouts.

The specific constraint on IntentReciever execution time emphasizes what they were meant to do: small, discrete
amounts of work in the background such as saving a setting or registering a Notification. So as with other methods
called in the main thread, applications should avoid potentially long-running operations or calculations in
BroadcastReceivers. But instead of doing intensive tasks via child threads (as the life of a BroadcastReceiver is short),
your application should start a Service if a potentially long running action needs to be taken in response to an Intent
broadcast. As a side note, you should also avoid starting an Activity from an Intent Receiver, as it will spawn a new
screen that will steal focus from whatever application the user is currently has running. If your application has
something to show the user in response to an Intent broadcast, it should do so using the Notification Manager.



Reinforcing Responsiveness
Generally, 100 to 200ms is the threshold beyond which users will perceive lag (or lack of "snappiness," if you will) in
an application. As such, here are some additional tips beyond what you should do to avoid ANR that will help make
your application seem responsive to users.

     If your application is doing work in the background in response to user input, show that progress is being made
     (ProgressBar and ProgressDialog are useful for this).
     For games specifically, do calculations for moves in a child thread.
     If your application has a time-consuming initial setup phase, consider showing a splash screen or rendering the
     main view as quickly as possible and filling in the information asynchronously. In either case, you should indicate
     somehow that progress is being made, lest the user perceive that the application is frozen.

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/practices/design/responsiveness.html                                                 Page 2 of 2
Designing for Seamlessness | Android Developers                                                                 29.04.09 0:58




Designing for Seamlessness

Even if your application is fast and responsive, certain design decisions can still cause problems for users — because
of unplanned interactions with other applications or dialogs, inadvertent loss of data, unintended blocking, and so on.
To avoid these problems, it helps to understand the context in which your applications run and the system interactions
that can affect your application. In short, you should strive to develop an application that interacts seamlessly with the
system and with other applications.

A common seamlessness problem is when an application's background process — for example, a service or broadcast
receiver — pops up a dialog in response to some event. This may seem like harmless behavior, especially when you
are building and testing your application in isolation, on the emulator. However, when your application is run on an
actual device, your application may not have user focus at the time your background process displays the dialog. So it
could end up that your application would display it's dialog behind the active application, or it could take focus from the
current application and display the dialog in front of whatever the user was doing (such as dialing a phone call, for
example). That behavior would not work for your application or for the user.

To avoid these problems, your application should use the proper system facility for notifying the user — the
Notification classes. Using notifications, your application can signal the user that an event has taken place, by
displaying an icon in the status bar rather than taking focus and interrupting the user.

Another example of a seamlessness problem is when an activity inadvertently loses state or user data because it
doesn't correctly implement the onPause() and other lifecycle methods. Or, if your application exposes data intended to
be used by other applications, you should expose it via a ContentProvider, rather than (for example) doing so through
a world-readable raw file or database.

What those examples have in common is that they involve cooperating nicely with the system and other applications.
The Android system is designed to treat applications as a sort of federation of loosely-coupled components, rather than
chunks of black-box code. This allows you as the developer to view the entire system as just an even-larger
federation of these components. This benefits you by allowing you to integrate cleanly and seamlessly with other
applications, and so you should design your own code to return the favor.

This document discusses common seamlessness problems and how to avoid them. It covers these topics:

     Don't Drop Data
     Don't Expose Raw Data
     Don't Interrupt the User
     Got a Lot to Do? Do it in a Thread
     Don't Overload a Single Activity Screen
     Extend System Themes
     Design Your UI to Work with Multiple Screen Resolutions
     Assume the Network is Slow
     Don't Assume Touchscreen or Keyboard
     Do Conserve the Device Battery




Don't Drop Data

http://developer.android.com/guide/practices/design/seamlessness.html                                               Page 1 of 4
Designing for Seamlessness | Android Developers                                                                  29.04.09 0:58



Always keep in mind that Android is a mobile platform. It may seem obvious to say it, but it's important to remember
that another Activity (such as the "Incoming Phone Call" app) can pop up over your own Activity at any moment. This
will fire the onSaveInstanceState() and onPause() methods, and will likely result in your application being killed.

If the user was editing data in your application when the other Activity appeared, your application will likely lose that
data when your application is killed. Unless, of course, you save the work in progress first. The "Android Way" is to do
just that: Android applications that accept or edit input should override the onSaveInstanceState() method and save
their state in some appropriate fashion. When the user revisits the application, she should be able to retrieve her data.

A classic example of a good use of this behavior is a mail application. If the user was composing an email when
another Activity started up, the application should save the in-process email as a draft.



Don't Expose Raw Data
If you wouldn't walk down the street in your underwear, neither should your data. While it's possible to expose certain
kinds of application to the world to read, this is usually not the best idea. Exposing raw data requires other applications
to understand your data format; if you change that format, you'll break any other applications that aren't similarly
updated.

The "Android Way" is to create a ContentProvider to expose your data to other applications via a clean, well-thought-
out, and maintainable API. Using a ContentProvider is much like inserting a Java language interface to split up and
componentize two tightly-coupled pieces of code. This means you'll be able to modify the internal format of your data
without changing the interface exposed by the ContentProvider, and this without affecting other applications.



Don't Interrupt the User
If the user is running an application (such as the Phone application during a call) it's a pretty safe bet he did it on
purpose. That's why you should avoid spawning activities except in direct response to user input from the current
Activity.

That is, don't call startActivity() from BroadcastReceivers or Services running in the background. Doing so will interrupt
whatever application is currently running, and result in an annoyed user. Perhaps even worse, your Activity may
become a "keystroke bandit" and receive some of the input the user was in the middle of providing to the previous
Activity. Depending on what your application does, this could be bad news.

Instead of spawning Activity UIs directly from the background, you should instead use the NotificationManager to set
Notifications. These will appear in the status bar, and the user can then click on them at his leisure, to see what your
application has to show him.

(Note that all this doesn't apply to cases where your own Activity is already in the foreground: in that case, the user
expects to see your next Activity in response to input.)



Got a Lot to Do? Do it in a Thread
If your application needs to perform some expensive or long-running computation, you should probably move it to a
thread. This will prevent the dreaded "Application Not Responding" dialog from being displayed to the user, with the
ultimate result being the fiery demise of your application.

By default, all code in an Activity as well as all its Views run in the same thread. This is the same thread that also
handles UI events. For example, when the user presses a key, a key-down event is added to the Activity's main
thread's queue. The event handler system needs to dequeue and handle that event quickly; if it doesn't, the system
concludes after a few seconds that the application is hung and offers to kill it for the user.


http://developer.android.com/guide/practices/design/seamlessness.html                                               Page 2 of 4
Designing for Seamlessness | Android Developers                                                                  29.04.09 0:58



If you have long-running code, running it inline in your Activity will run it on the event handler thread, effectively
blocking the event handler. This will delay input processing, and result in the ANR dialogs. To avoid this, move your
computations to a thread. This Design for Responsiveness document discusses how to do that..



Don't Overload a Single Activity Screen
Any application worth using will probably have several different screens. When designing the screens of your UI, be
sure to make use of multiple Activity object instances.

Depending on your development background, you may interpret an Activity as similar to something like a Java Applet,
in that it is the entry point for your application. However, that's not quite accurate: where an Applet subclass is the
single entry point for a Java Applet, an Activity should be thought of as one of potentially several entry points to your
application. The only difference between your "main" Activity and any others you might have is that the "main" one just
happens to be the only one that expressed an interest in the "android.intent.action.MAIN" action in your
AndroidManifest..xml file.

So, when designing your application, think of your application as a federation of Activity objects. This will make your
code a lot more maintainable in the long run, and as a nice side effect also plays nicely with Android's application
history and "backstack" model.



Extend System Themes
When it comes to the look-and-feel of the user interface, it's important to blend in nicely. Users are jarred by
applications which contrast with the user interface they've come to expect. When designing your UIs, you should try
and avoid rolling your own as much as possible. Instead, use a Theme. You can override or extend those parts of the
theme that you need to, but at least you're starting from the same UI base as all the other applications. For all the
details, read Applying Styles and Themes.



Design Your UI to Work with Multiple Screen Resolutions
Different Android-powered devices will support different screen resolutions. Some will even be able to change
resolutions on the fly, such as by switching to landscape mode. It's important to make sure your layouts and drawables
are flexible enough to display properly on a variety of device screens.

Fortunately, this is very easy to do. In brief, what you must do is provide different versions of your artwork (if you use
any) for the key resolutions, and then design your layout to accommodate various dimensions. (For example, avoid
using hard-coded positions and instead use relative layouts.) If you do that much, the system handles the rest, and
your application looks great on any device.



Assume the Network is Slow
Android devices will come with a variety of network-connectivity options. All will have some data-access provision,
though some will be faster than others. The lowest common denominator, however, is GPRS, the non-3G data service
for GSM networks. Even 3G-capable devices will spend lots of time on non-3G networks, so slow networks will remain
a reality for quite a long time to come.

That's why you should always code your applications to minimize network accesses and bandwidth. You can't assume
the network is fast, so you should always plan for it to be slow. If your users happen to be on faster networks, then
that's great — their experience will only improve. You want to avoid the inverse case though: applications that are
usable some of the time, but frustratingly slow the rest based on where the user is at any given moment are likely to
be unpopular.
http://developer.android.com/guide/practices/design/seamlessness.html                                              Page 3 of 4
Designing for Seamlessness | Android Developers                                                                       29.04.09 0:58


be unpopular.

One potential gotcha here is that it's very easy to fall into this trap if you're using the emulator, since the emulator
uses your desktop computer's network connection. That's almost guaranteed to be much faster than a cell network, so
you'll want to change the settings on the emulator that simulate slower network speeds. You can do this in Eclipse, in
the "Emulator Settings" tab of your launch configuration or via a command-line option when starting the emulator.



Don't Assume Touchscreen or Keyboard
Android will support a variety of handset form-factors. That's a fancy way of saying that some Android devices will
have full "QWERTY" keyboards, while others will have 40-key, 12-key, or even other key configurations. Similarly,
some devices will have touch-screens, but many won't.

When building your applications, keep that in mind. Don't make assumptions about specific keyboard layouts -- unless,
of course, you're really interested in restricting your application so that it can only be used on those devices.



Do Conserve the Device Battery
A mobile device isn't very mobile if it's constantly plugged into the wall. Mobile devices are battery-powered, and the
longer we can make that battery last on a charge, the happier everyone is — especially the user. Two of the biggest
consumers of battery power are the processor, and the radio; that's why it's important to write your applications to do
as little work as possible, and use the network as infrequently as possible.

Minimizing the amount of processor time your application uses really comes down to writing efficient code. To
minimize the power drain from using the radio, be sure to handle error conditions gracefully, and only fetch what you
need. For example, don't constantly retry a network operation if one failed. If it failed once, it's likely because the user
has no reception, so it's probably going to fail again if you try right away; all you'll do is waste battery power.

Users are pretty smart: if your program is power-hungry, you can count on them noticing. The only thing you can be
sure of at that point is that your program won't stay installed very long.

                                                                                                                     ! Go to top
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
Android 1.5 r1 - 27 Apr 2009 0:19
Site Terms of Service - Privacy Policy - Brand Guidelines




http://developer.android.com/guide/practices/design/seamlessness.html                                                   Page 4 of 4
Hello, World | Android Developers                                                                               29.04.09 1:00




Hello, World

As a developer, you know that the first impression of a development framework is how easy it is to write "Hello,
World." Well, on Android, it's pretty easy. It's particularly easy if you're using Eclipse as your IDE, because we've
provided a great plugin that handles your project creation and management to greatly speed-up your development
cycles.

If you're not using Eclipse, that's okay. Familiarize yourself with Developing in Other IDEs. You can then return to this
tutorial and ignore anything about Eclipse.

Before you start, you should already have the very latest SDK installed, and if you're using Eclipse, you should have
installed the ADT plugin as well. If you have not installed these, see Installing the Android SDK and return here when
you've completed the installation.



Create an AVD
     Note: If you're developing with an Android SDK older than the one provided for Android 1.5, you can skip this
     step and continue with Create the Project.

In this tutorial, you will run your application in the Android Emulator. Before you can launch the emulator, you must
create an Android Virtual Device (AVD). An AVD defines the system image and device settings used by the emulator.

To create an AVD, use the "android" tool provided in the Android SDK. Open a command prompt or terminal, navigate
to the tools/ directory in the SDK package and execute:

     android create avd --target 2 --name my_avd

The tool now asks if you would like to create a custom hardware profile. For the time being, press Return to skip it
("no" is the default response). That's it. This configures an AVD named "my_avd" that uses the Android 1.5 platform.
The AVD is now ready for use in the emulator.

In the above command, the --target option is required and
specifies the deployment target to run on the emulator. The --
                                                                           To learn more about Android Virtual Devices
name option is also required and defines the name for the new
                                                                           (and targets), refer to the AVD document.
AVD.



Create a New Android Project
After you've created an AVD, the next step is to start a new Android project in Eclipse.

 1. From Eclipse, select File > New > Project.
     If the ADT Plugin for Eclipse has been successfully installed, the resulting dialog should have a folder labeled
     "Android" which should contain "Android Project". (After you create one or more Android projects, an entry for
     "Android XML File" will also be available.)




http://developer.android.com/guide/tutorials/hello-world.html                                                     Page 1 of 9
Hello, World | Android Developers                                                                            29.04.09 1:00




 2. Selected "Android Project" and click Next.
 3. Fill in the project details with the following values:
           Project name: HelloAndroid
           Application name: Hello, Android
           Package name: com.example.helloandroid (or your own private namespace)
           Create Activity: HelloAndroid
           Min SDK Version: 2

     Click Finish.




     Here is a description of each field:
     Project Name
         This is the Eclipse Project name — the name of the directory that will contain the project files.

     Application Name
         This is the human-readable title for your application — the name that will appear on the Android device.

     Package Name
         This is the package namespace (following the same rules as for packages in the Java programming
         language) that you want all your source code to reside under. This also sets the package name under which
         the stub Activity will be generated.

           Your package name must be unique across all packages installed on the Android system; for this reason, it's
           very important to use a standard domain-style package for your applications. The example above uses the
           "com.example" namespace, which is a namespace reserved for example documentation — when you develop
           your own applications, you should use a namespace that's appropriate to your organization or entity.



http://developer.android.com/guide/tutorials/hello-world.html                                                  Page 2 of 9
Hello, World | Android Developers                                                                                  29.04.09 1:00


     Create Activity
         This is the name for the class stub that will be generated by the plugin. This will be a subclass of Android's
         Activity class. An Activity is simply a class that can run and do work. It can create a UI if it chooses, but it
         doesn't need to. As the checkbox suggests, this is optional, but an Activity is almost always used as the basis
         for an application.

     Min SDK Version
         This value specifies the minimum API Level required by your application. If the API Level entered here
         matches the API Level provided by one of the available targets, then that Build Target will be automatically
         selected (in this case, entering "2" as the API Level will select the Android 1.1 target). With each new version
         of the Android system image and Android SDK, there have likely been additions or changes made to the
         APIs. When this occurs, a new API Level is assigned to the system image to regulate which applications are
         allowed to be run. If an application requires an API Level that is higher than the level supported by the
         device, then the application will not be installed.

     Other fields: The checkbox for "Use default location" allows you to change the location on disk where the project's
     files will be generated and stored. "Build Target" is the platform target that your application will be compiled
     against (this should be selected automatically, based on your Min SDK Version).
         Notice that the "Build Target" you've selected uses the Android 1.1 platform. This means that your application
         will be compiled against the Android 1.1 platform library. If you recall, the AVD created above runs on the
         Android 1.5 platform. These don't have to match; Android applications are forward-compatible, so an
         application built against the 1.1 platform library will run normally on the 1.5 platform. The reverse is not true.
     Your Android project is now ready. It should be visible in the Package Explorer on the left. Open the
     HelloAndroid.java file, located inside HelloAndroid > src > com.example.helloandroid). It should look like this:

           package com.example.helloandroid;
           import android.app.Activity;
           import android.os.Bundle;
           public class HelloAndroid extends Activity {
               /** Called when the activity is first created. */
               @Override
               public void onCreate(Bundle savedInstanceState) {
                   super.onCreate(savedInstanceState);
                   setContentView(R.layout.main);
               }
           }

     Notice that the class is based on the Activity class. An Activity is a single application entity that is used to perform
     actions. An application may have many separate activities, but the user interacts with them one at a time. The
     onCreate() method will be called by the Android system when your Activity starts — it is where you should
     perform all initialization and UI setup. An activity is not required to have a user interface, but usually will.

     Now let's modify some code!



     Construct the UI
     Take a look at the revised code below and then make the same changes to your HelloAndroid class. The bold
     items are lines that have been added.

           package com.android.helloandroid;

           import android.app.Activity;
           import android.os.Bundle;
           import android.widget.TextView;


http://developer.android.com/guide/tutorials/hello-world.html                                                        Page 3 of 9
Hello, World | Android Developers                                                                                    29.04.09 1:00


           public class HelloAndroid extends Activity {
              /** Called when the activity is first created. */
              @Override
              public void onCreate(Bundle savedInstanceState) {
                  super.onCreate(savedInstanceState);
                  TextView tv = new TextView(this);
                  tv.setText("Hello, Android");
                  setContentView(tv);
              }
           }

           Tip: An easy way to add import packages to your project is to press Ctrl-Shift-O (Cmd-Shift-O, on Mac).
           This is an Eclipse shortcut that identifies missing packages based on your code and adds them for you.

     An Android user interface is composed of hierarchies of objects called Views. A View is a drawable object used as
     an element in your UI layout, such as a button, image, or (in this case) a text label. Each of these objects is a
     subclass of the View class and the subclass that handles text is TextView.

     In this change, you create a TextView with the class constructor, which accepts an Android Context instance as its
     parameter. A Context is a handle to the system; it provides services like resolving resources, obtaining access to
     databases and preferences, and so on. The Activity class inherits from Context, and because your HelloAndroid
     class is a subclass of Activity, it is also a Context. So, you can pass this as your Context reference to the
     TextView.

     Next, you define the text content with setText(CharSequence) setText().

     Finally, you pass the TextView to setContentView() in order to display it as the content for the Activity UI. If your
     Activity doesn't call this method, then no UI is present and the system will display a blank screen.

     There it is — "Hello, World" in Android! The next step, of course, is to see it running.



     Run the Application
     The Eclipse plugin makes it very easy to run your applications:

       1. Select Run > Run.
       2. Select "Android Application".

     The Eclipse ADT will automatically create a new run
     configuration for your project and the Android Emulator will
                                                                             To learn more about creating and editing run
     automatically launch. Once the emulator is booted up, your
                                                                             configurations in Eclipse, refer to Developing In
     application will appear after a moment. You should now see              Eclipse, with ADT.
     something like this:




http://developer.android.com/guide/tutorials/hello-world.html                                                          Page 4 of 9
Hello, World | Android Developers                                                                                      29.04.09 1:00




     The "Hello, Android" you see in the grey bar is actually the application title. The Eclipse plugin creates this
     automatically (the string is defined in the res/values/strings.xml file and referenced by your
     AndroidManifest.xml file). The text below the title is the actual text that you have created in the TextView
     object.

     That concludes the basic "Hello World" tutorial, but you should continue reading for some more valuable
     information about developing Android applications.



     Upgrade the UI to an XML Layout
     The "Hello, World" example you just completed uses what is called a "programmatic" UI layout. This means that
     you constructed and built your application's UI directly in source code. If you've done much UI programming,
     you're probably familiar with how brittle that approach can sometimes be: small changes in layout can result in big
     source-code headaches. It's also very easy to forget to properly connect Views together, which can result in errors
     in your layout and wasted time debugging your code.

     That's why Android provides an alternate UI construction model: XML-based layout files. The easiest way to
     explain this concept is to show an example. Here's an XML layout file that is identical in behavior to the
     programmatically-constructed example:

           <?xml version="1.0" encoding="utf-8"?>
           <T