| page.title=Common Tasks and How to Do Them in Android |
| parent.title=FAQs, Tips, and How-to |
| parent.link=index.html |
| @jd:body |
| |
| <ul> |
| <li><a href="#neweclipseandroidproject">Creating an Android Application using |
| the Eclipse plugin</a></li> |
| <li><a href="#newandroidprojectnoeclipse">Creating an Android Application without |
| the Eclipse plugin</a></li> |
| <li><a href="#addexternallibrary">Adding an External Library (.jar) using Eclipse</a></li> |
| <li><a href="#implementcallbacks">Implementing Activity callbacks</a> (Android |
| calls your activity at various key moments in its life cycle. You must know |
| how to handle each of these to draw your screen, initialize class members, |
| and acquire data.)</li> |
| <li><a href="#opennewscreen">Opening a new screen</a></li> |
| <li><a href="#listening">Listening for button clicks </a></li> |
| <li><a href="#configurewindowproperties">Configuring general window properties </a></li> |
| <li><a href="#localhostalias">Referring to localhost from the emulated environment</a></li> |
| <li><a href="#appstate">Storing and retrieving state</a></li> |
| <li><a href="{@docRoot}guide/topics/data/data-storage.html#preferences">Storing and retrieving preferences</a></li> |
| <li><a href="#storingandretrieving">Storing and retrieving larger or more complex |
| persistent data</a> (files and data) </li> |
| <li><a href="#playback">Playing audio, video, still, or other media files</a></li> |
| <li><a href="#broadcastreceivers">Listening for and broadcasting global messages |
| and setting alarms</a></li> |
| <li><a href="#alerts">Displaying alerts </a></li> |
| <li><a href="#progressbar">Displaying a progress bar</a> </li> |
| <li><a href="#addmenuitems">Adding items to the screen menu</a> </li> |
| <li><a href="#webpage">Display a web page</a> </li> |
| <li><a href="#binding">Binding to data</a></li> |
| <li><a href="#handle">Getting a Handle to a Screen Element</a></li> |
| <li><a href="#captureimages">Capture images from the phone camera </a></li> |
| <li><a href="#threading">Handling expensive operations in the UI thread</a></li> |
| <li><a href="#selectingtext">Selecting, highlighting, or styling portions of |
| text</a></li> |
| <li><a href="#querymap">Utilizing attributes in a Map query</a></li> |
| <li><a href="#filelist">List of files for an Android application</a></li> |
| <li><a href="#logging">Print messages to a log file</a></li> |
| </ul> |
| <p>The ApiDemos sample application includes many, many examples of common |
| tasks and UI features. See the code inside |
| <code><sdk>samples/ApiDemos</code> and the other sample applications |
| under the <code>samples/</code> folder in the SDK.</p> |
| |
| |
| <h2 id="neweclipseandroidproject">Creating an Android Application using the Eclipse Plugin</h2> |
| |
| <p>Using the Android Eclipse plugin is the fastest and easiest way |
| to start creating a new Android application. The plugin automatically generates |
| the correct project structure for your application, and keeps the resources |
| compiled for you automatically.</p> |
| |
| <p>It is still a good idea to know what is going on though. Take a look at <a |
| href="{@docRoot}guide/topics/fundamentals.html">Application Fundamentals</a> |
| to understand the basics of how an Android application works.</p> |
| |
| <p>You should also take a look at the ApiDemos application and the other sample |
| applications included in the SDK, in the <code><sdk>/samples/</code> |
| folder in the SDK.</p> |
| |
| <p>Finally, a great way to started with Android development in Eclipse is to |
| follow both the <a href="{@docRoot}resources/tutorials/hello-world.html">Hello, |
| World</a> and <a |
| href="{@docRoot}resources/tutorials/notepad/index.html">Notepad</a> code |
| tutorials. In particular, the start of the Hello Android tutorial is an |
| excellent introduction to creating a new Android application in Eclipse.</p> |
| |
| <h2 id="newandroidprojectnoeclipse">Creating an Android Application without the Eclipse Plugin</h2> |
| |
| <p>This topic describes the manual steps in creating an Android application. |
| Before reading this, you should read <a |
| href="{@docRoot}guide/topics/fundamentals.html">Application Fundamentals</a> |
| to understand the basics of how an Android application works. You might also |
| want to look at the sample code included with the Android SDK, in the |
| <code><sdk>/samples/</code> directory. </p> |
| |
| <p>Here is a list of the basic steps in building an application.</p> |
| <ol> |
| <li><strong>Create your required resource files</strong> This includes |
| the AndroidManifest.xml global description file, string files that your application |
| needs, and layout files describing your user interface. A full list of optional |
| and required files and syntax details for each is given in <a href="#filelist">File |
| List for an Android Application</a>. </li> |
| <li><strong>Design your user interface</strong> See <a |
| href="{@docRoot}guide/topics/ui/index.html">User Interface</a> for |
| details on elements of the Android screen. </li> |
| <li><strong>Implement your Activity </strong>(this page)<strong> </strong> You |
| will create one class/file for each screen in your application. Screens will |
| inherit from an {@link android.app android.app} class, typically {@link android.app.Activity |
| android.app.Activity} for basic screens, {@link android.app.ListActivity |
| android.app.ListActivity} for list screens, or {@link android.app.Dialog |
| android.app.Dialog} for dialog boxes. You will implement the required callbacks |
| that let you draw your screen, query data, and commit changes, and also perform |
| any required tasks such as opening additional screens or reading data from |
| the device. Common tasks, such as opening a new screen or reading data from |
| the device, are described below. |
| The list of files you'll need for your application are described in <a href="#filelist">List |
| of Files for an Android Application</a>. </li> |
| <li><strong><a href="{@docRoot}guide/developing/building/building-cmdline.html">Build and install your |
| package</a>.</strong> The Android SDK has some nice tools for generating |
| projects and debugging code. </li> |
| </ol> |
| |
| <h2 id="addexternallibrary">Adding an External Library (.jar) using Eclipse</h2> |
| <p> |
| You can use a third party JAR in your application by adding it to your Eclipse project as follows: |
| </p> |
| <ol> |
| <li> |
| In the <strong>Package Explorer</strong> panel, right-click on your project and select <strong>Properties</strong>. |
| <li> |
| Select <strong>Java Build Path</strong>, then the tab <strong>Libraries</strong>. |
| <li> |
| Press the <strong>Add External JARs...</strong> button and select the JAR file. |
| </ol> |
| <p> |
| Alternatively, if you want to include third party JARs with your package, create a new directory for them within your project and select <strong>Add Library...</strong> instead.</p> |
| <p> |
| It is not necessary to put external JARs in the assets folder. |
| </p> |
| |
| <a name="implementcallbacks" id="implementcallbacks"></a> |
| <h2>Implementing Activity Callbacks</h2> |
| <p>Android calls a number of callbacks to let you draw your screen, store data before |
| pausing, and refresh data after closing. You must implement at least some of |
| these methods. Read the <a |
| href="{@docRoot}guide/topics/fundamentals/activities.html#Lifecycle">Activities</a> |
| document to learn when and in what order these methods |
| are called. Here are some of the standard types of screen classes that Android provides:</p> |
| <ul> |
| <li>{@link android.app.Activity android.app.Activity} - This is a standard screen, |
| with no specialization.</li> |
| <li>{@link android.app.ListActivity android.app.ListActivity} - This is a screen |
| that is used to display a list of something. It hosts a ListView object, |
| and exposes methods to let you identify the selected item, receive callbacks |
| when the selected item changes, and perform other list-related actions. </li> |
| <li>{@link android.app.Dialog android.app.Dialog} - This is a small, popup dialog-style |
| window that isn't intended to remain in the history stack. (It is not resizeable |
| or moveable by the user.)</li> |
| </ul> |
| |
| <a name="opennewscreen" id="opennewscreen"></a><h2>Opening a New Screen</h2> |
| <p>Your Activity will often need to open another Activity screen as it progresses. |
| This new screen can be part of the same application or part of another application, |
| the new screen can be floating or full screen, it can return a result, and you |
| can decide whether to close this screen and remove it from the history stack |
| when you are done with it, or to keep the screen open in history. These next |
| sections describe all these options. </p> |
| <h3>Floating or full?<a name="floatingorfull" id="floatingorfull"></a></h3> |
| <p>When you open a new screen you can decide whether to make it transparent or floating, |
| or full-screen. The choice of new screen affects the event sequence of events |
| in the old screen (if the new screen obscures the old screen, a different |
| series of events is called in the old screen). See the <a |
| href="{@docRoot}guide/topics/fundamentals/activities.html#Lifecycle">Activities</a> document for |
| details. </p> |
| <p>Transparent or floating windows are implemented in three |
| standard ways: </p> |
| <ul> |
| <li>Create an {@link android.app.Dialog app.Dialog} class </li> |
| <li>Create an {@link android.app.AlertDialog app.AlertDialog} class </li> |
| <li>Set the {@link android.R.style#Theme_Dialog} <em>theme</em> attribute to <code>@android:style/Theme.Dialog</code> |
| in your AndroidManifest.xml file. For example: |
| <pre><activity class="AddRssItem" android:label="Add an item" android:theme="@android:style/Theme.Dialog"/></pre></li> |
| </ul> |
| |
| <p>Calling startActivity() or startActivityForResult() will open a new screen in whatever |
| way it defines itself (if it uses a floating theme it will be floating, |
| otherwise it will be full screen). </p> |
| <h3>Opening a Screen </h3> |
| <p>When you want to open a new screen, you can either explicitly specify the activity |
| class to open, or you can let the operating system decide which screen to open, |
| based upon the data and various parameters you pass in. A screen is opened by |
| calling {@link android.app.Activity#startActivity(android.content.Intent) startActivity} |
| and passing in an {@link android.content.Intent Intent} object, which specifies |
| the criteria for the handling screen. To specify a specific screen, call Intent.setClass |
| or setClassName with the exact activity class to open. Otherwise, set a variety |
| of values and data, and let Android decide which screen is appropriate to open. |
| Android will find one or zero Activities that match the specified requirements; |
| it will never open multiple activities for a single request. More information |
| on Intents and how Android resolves them to a specific class is given in the |
| {@link android.content.Intent Intent} topic. </p> |
| <a name="intentexamples" id="intentexamples"></a><h3>Some Intent examples </h3> |
| <p>The following snippet loads the com.android.samples.Animation1 class, and |
| passes it some arbitrary data.:</p> |
| <pre>Intent myIntent = new Intent(); |
| myIntent.setClassName("com.android.samples", "com.android.samples.Animation1"); |
| myIntent.putExtra("com.android.samples.SpecialValue", "Hello, Joe!"); // key/value pair, where key needs current package prefix. |
| startActivity(myIntent); </pre> |
| <p>The next snippet requests that a Web page be opened by specifying the VIEW action, |
| and a URI data string starting with "http://" schema:</p> |
| <pre>Intent myIntent = new Intent(Intent.VIEW_ACTION, Uri.parse("http://www.google.com"));</pre> |
| <p>Here is the intent filter from the AndroidManifest.xml file for com.android.browser:</p> |
| <pre><intent-filter> |
| <action android:name="android.intent.action.VIEW" /> |
| <category android:name="android.intent.category.DEFAULT" /> |
| <scheme android:name="http" /> |
| <scheme android:name="https" /> |
| <scheme android:name="file" /> |
| </intent-filter> </pre> |
| <p>Android defines a number of standard values, for instance the action constants |
| defined by {@link android.content.Intent}. You can define custom values, but |
| both the caller and handler must use them. See the <intent-filter> |
| tag description in <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">The AndroidManifest.xml |
| File</a> for more information on the manifest syntax for the handling |
| application. </p> |
| <a name="returningaresult" id="returningaresult"></a><h3>Returning a Result from a Screen</h3> |
| <p>A window can return a result after it closes. This result will be passed back |
| into the calling Activity's {@link android.app.Activity#onActivityResult(int,int,android.content.Intent) |
| onActivityResult()} method, which can supply an Intent containing arbitrary data, along with |
| the request code passed to startActivityForResult(). Note that you must call the {@link |
| android.app.Activity#startActivityForResult(android.content.Intent,int) startActivityForResult()} |
| method that accepts a request code parameter to get this callback. The following |
| code demonstrates opening a new screen and retrieving a result. </p> |
| <pre>// Open the new screen. |
| public void onClick(View v){ |
| // Start the activity whose result we want to retrieve. The |
| // result will come back with request code GET_CODE. |
| Intent intent = new Intent(this, com.example.app.ChooseYourBoxer.class); |
| startActivityForResult(intent, CHOOSE_FIGHTER); |
| } |
| |
| // Listen for results. |
| protected void onActivityResult(int requestCode, int resultCode, Intent data){ |
| // See which child activity is calling us back. |
| switch (requestCode) { |
| case CHOOSE_FIGHTER: |
| // This is the standard resultCode that is sent back if the |
| // activity crashed or didn't doesn't supply an explicit result. |
| if (resultCode == RESULT_CANCELED){ |
| myMessageboxFunction("Fight cancelled"); |
| } |
| else { |
| myFightFunction(data); |
| } |
| default: |
| break; |
| } |
| } |
| |
| // Class SentResult |
| // Temporary screen to let the user choose something. |
| private OnClickListener mLincolnListener = new OnClickListener(){ |
| public void onClick(View v) { |
| Bundle stats = new Bundle(); |
| stats.putString("height","6\'4\""); |
| stats.putString("weight", "190 lbs"); |
| stats.putString("reach", "74\""); |
| setResult(RESULT_OK, "Lincoln", stats); |
| finish(); |
| } |
| }; |
| |
| private OnClickListener mWashingtonListener = new OnClickListener() { |
| public void onClick(View v){ |
| Bundle stats = new Bundle(); |
| stats.putString("height","6\'2\""); |
| stats.putString("weight", "190 lbs"); |
| stats.putString("reach", "73\""); |
| setResult(RESULT_OK, "Washington", stats); |
| finish(); |
| } |
| }; |
| </pre> |
| <h3>Lifetime of the new screen </h3> |
| <p>An activity can remove itself from the history stack by calling {@link android.app.Activity#finish() |
| Activity.finish()} on itself, or the activity that opened the screen can call |
| {@link android.app.Activity#finishActivity(int) Activity.finishActivity()} |
| on any screens that it opens to close them. </p> |
| <a name="listening" id="listening"></a><h2>Listening for Button Clicks</h2> |
| <p>Button click and other UI event capturing are covered in <a href="{@docRoot}guide/topics/ui/ui-events.html">Handling UI Events</a> on the UI Design page.</p> |
| <a name="configurewindowproperties" id="configurewindowproperties"></a><h2>Configuring General Window Properties</h2> |
| <p>You can set a number of general window properties, such as whether to display |
| a title, whether the window is floating, and whether it displays an icon, by |
| calling methods on the {@link android.view.Window Window} member |
| of the underlying View object for the window. Examples include calling {@link |
| android.app.Activity#getWindow() getWindow().requestFeature()} (or the convenience |
| method {@link android.app.Activity#requestWindowFeature(int) requestWindowFeature(<em>some_feature</em>)}) |
| to hide the title. Here is an example of hiding the title bar:</p> |
| <pre>//Hide the title bar |
| requestWindowFeature(Window.FEATURE_NO_TITLE); |
| </pre> |
| <p>A better way to achieve the same end is to specify a theme in your Android |
| Manifest file:</p> |
| <pre><application android:icon="@drawable/icon" android:theme="@android:style/Theme.NoTitleBar"> |
| </pre> |
| <p>This is preferable because it tells the system not to show a title bar while |
| your application is starting up. With the explicit method call, your application |
| will have a title bar visible to the user until <code>onCreate</code> runs.</p> |
| <p>(Note that this can be applied to either the <code><application></code> |
| tag or to individual <code><activity></code> tags.)</p> |
| <p class="caution"><strong>Caution:</strong> This theme will also hide the Action Bar on Android |
| 3.0 and higher. If you want to keep the Action Bar, but hide the title bar, see how you can <a |
| href="{@docRoot}guide/topics/ui/themes.html#SelectATheme">select a theme based on platform |
| version</a>.</p> |
| <a name="localhostalias" id="localhostalias"></a><h2>Referring to localhost from the emulated |
| environment</h2> |
| <p> |
| If you need to refer to your host computer's <em>localhost</em>, such as when you |
| want the emulator client to contact a server running on the same host, use the alias |
| <code>10.0.2.2</code> to refer to the host computer's loopback interface. |
| From the emulator's perspective, localhost (<code>127.0.0.1</code>) refers to its own |
| loopback interface. |
| </p> |
| <a name="appstate" id="appstate"></a><h2>Storing and Retrieving State</h2> |
| <p>If your application is dumped from memory because of space concerns, it will lose |
| all user interface state information such as checkbox state and text box values |
| as well as class member values. Android calls {@link android.app.Activity#onSaveInstanceState(android.os.Bundle) |
| Activity.onSaveInstanceState} before it pauses the application. This method hands in a {@link |
| android.os.Bundle Bundle} that can be used to store name/value pairs that will |
| persist and be handed back to the application even if it is dropped from memory. |
| Android will pass this Bundle back to you when it calls {@link android.app.Activity#onCreate(android.os.Bundle) |
| onCreate()}. This Bundle only exists while the application is still in the history |
| stack (whether or not it has been removed from memory) and will be lost when |
| the application is finalized. See the topics for {@link android.app.Activity#onSaveInstanceState} and |
| {@link android.app.Activity#onCreate} for |
| examples of storing and retrieving state.</p> |
| <p>Read more about the lifecycle of an activity in <a |
| href="{@docRoot}guide/topics/fundamentals/activities.html">Activities</a> document.</p> |
| <h3>Storing and Retrieving Larger or More Complex Persistent Data<a name="storingandretrieving" id="storingandretrieving"></a></h3> |
| <p>Your application can store files or complex collection objects, and reserve them |
| for private use by itself or other activities in the application, or it can expose |
| its data to all other applications on the device. See <a href="{@docRoot}guide/topics/data/data-storage.html">Storing, |
| Retrieving, and Exposing Data</a> to learn how to store and retrieve private data, |
| how to store and retrieve common data from the device, and how to expose your |
| private data to other applications.</p> |
| <a name="playback" id="playback"></a><h2>Playing Media Files</h2> |
| <p>Please see the document <a href="{@docRoot}guide/topics/media/index.html">Audio and Video</a> for more details.</p> |
| <a name="broadcastreceivers" id="broadcastreceivers"></a><h2>Listening For and Broadcasting Global Messages, and Setting Alarms</h2> |
| <p>You can create a listening class that can be notified or even instantiated whenever |
| a specific type of system message is sent. |
| </p> |
| <p>The listening classes, called broadcast receivers, extend {@link android.content.BroadcastReceiver |
| BroadcastReceiver}. If you want Android to instantiate the object whenever an appropriate |
| intent notification is sent, define the receiver with a <code><receiver></code> element |
| in the AndroidManifext.xml file. If the caller is expected to instantiate the |
| object in preparation to receive a message, this is not required. The receiver |
| will get a call to their {@link android.content.BroadcastReceiver#onReceive(android.content.Context,android.content.Intent) |
| BroadcastReceiver.onReceive()} method. A receiver can define an <code><intent-filter></code> tag |
| that describes the types of messages it will receive. Just as Android's IntentResolver |
| will look for appropriate Activity matches for a startActivity() call, it will |
| look for any matching Receivers (but it will send the message to all matching |
| receivers, not to the "best" match). </p> |
| <p>To send a notification, the caller creates an {@link android.content.Intent Intent} |
| object and calls {@link android.app.Activity#sendBroadcast(android.content.Intent) |
| Context.sendBroadcast()} with that Intent. Multiple recipients can receive |
| the same message. You can broadcast an Intent message to an intent receiver in |
| any application, not only your own. If the receiving class is not registered |
| using <code><receiver></code> in its manifest, you can dynamically instantiate |
| and register a receiver by calling {@link android.content.Context#registerReceiver(android.content.BroadcastReceiver,android.content.IntentFilter) |
| Context.registerReceiver()}. </p> |
| <p>Receivers can include intent filters to specify what kinds of intents they are |
| listening for. Alternatively, if you expect a single known caller to contact |
| a single known receiver, the receiver does not specify an intent filter, and |
| the caller specifies the receiver's class name in the Intent by calling {@link |
| android.content.Intent#setClassName(java.lang.String, java.lang.String) Intent.setClassName()} |
| with the recipient's class name. The recipient receives a {@link android.content.Context |
| Context} object that refers to its own package, not to the package of the sender.</p> |
| <p><em><strong>Note:</strong></em> If a receiver or broadcaster |
| enforces permissions, your application might need to request permission |
| to send or receive messages from that object. You can request permission by using |
| the <uses-permission> tag in the manifest. </p> |
| <p>Here is a code snippet of a sender and receiver. This example does not demonstrate |
| registering receivers dynamically. For a full code example, see the AlarmService |
| class in the ApiDemos project.</p> |
| <h3>Sending the message</h3> |
| <pre>// We are sending this to a specific recipient, so we will |
| // only specify the recipient class name. |
| Intent intent = new Intent(this, AlarmReceiver.class); |
| intent.putExtra("message","Wake up."); |
| sendBroadcast(intent); |
| </pre> |
| <h3>Receiving the message</h3> |
| <p><strong>Receiver AndroidManifest.xml </strong>(because there is no intent filter |
| child, this class will only receive a broadcast when the receiver class is specified |
| by name, as is done in this example):</p> |
| <pre> |
| <receiver class=".AlarmReceiver" /></pre> |
| <p><strong>Receiver Java code: </strong></p> |
| <pre> |
| public class AlarmReceiver extends BroadcastReceiver{ |
| // Display an alert that we've received a message. |
| @Override |
| public void onReceive(Context context, Intent intent){ |
| // Send a text notification to the screen. |
| NotificationManager nm = (NotificationManager) |
| context.getSystemService(Context.NOTIFICATION_SERVICE); |
| nm.notifyWithText(R.id.alarm, |
| "Alarm!!!", |
| NotificationManager.LENGTH_SHORT, |
| null); |
| } |
| } </pre> |
| <h3>Other system messages</h3> |
| <p>You can listen for other system messages sent by Android as well, such as USB |
| connection/removal messages, SMS arrival messages, and timezone changes. See |
| {@link android.content.Intent} for a list of broadcast messages to listen for. |
| Messages are marked "Broadcast Action" in the documentation. </p> |
| <h3>Listening for phone events<a name="phoneevents" id="phoneevents"></a></h3> |
| <p>The {@link android.telephony android.telephony} package overview page describes how to |
| register to listen for phone events. </p> |
| <a name="alarms" id="alarms"></a><h3>Setting Alarms </h3> |
| <p>Android provides an {@link android.app.AlarmManager AlarmManager} service that |
| will let you specify an Intent to send at a designated time. This intent is typically |
| used to start an application at a preset time. (Note: If you want to send |
| a notification to a sleeping or running application, use {@link android.os.Handler |
| Handler} instead.)</p> |
| <a name="alerts" id="alerts"></a><h2>Displaying Alerts</h2> |
| <p>There are two major kinds of alerts that you may display to the user: |
| (1) Normal alerts are displayed in response to a user action, such as |
| trying to perform an action that is not allowed. (2) Out-of-band alerts, |
| called notifications, are |
| displayed as a result of something happening in the background, such as the |
| user receiving new e-mail.</p> |
| |
| <a name="dialogsandalerts" id="dialogsandalerts"></a><h3>Normal Alerts</h3> |
| |
| <p>Android provides a number of ways for you to show popup notifications to your |
| user as they interact with your application. </p> |
| <table width="100%" border="1"> |
| <tr> |
| <th scope="col">Class</th> |
| <th scope="col">Description</th> |
| </tr> |
| <tr> |
| <td>{@link android.app.Dialog app.Dialog}</td> |
| <td>A generic floating dialog box with a layout that you design. </td> |
| </tr> |
| <tr> |
| <td><p>{@link android.app.AlertDialog app.AlertDialog}</p></td> |
| <td>A popup alert dialog with two buttons (typically OK and Cancel) that |
| take callback handlers. See the section after this table for more details. </td> |
| </tr> |
| <tr> |
| <td>{@link android.app.ProgressDialog ProgressDialog} </td> |
| <td>A dialog box used to indicate progress of an operation with a known progress |
| value or an indeterminate length (setProgress(bool)). See <strong>Views</strong> > <strong>Progress Bar</strong> in |
| ApiDemos for examples. </td> |
| </tr> |
| <tr> |
| <td>Activity</td> |
| <td>By setting the theme of an activity to |
| {@link android.R.style#Theme_Dialog |
| android:theme="@android:style/Theme.Dialog"}, |
| your activity will take on |
| the appearance of a normal dialog, floating on top of whatever was |
| underneath it. You usually set the theme through the |
| {@link android.R.attr#theme android:theme} attribute in your AndroidManifest.xml. |
| The advantage of this |
| over Dialog and AlertDialog is that Application has a much better managed |
| life cycle than dialogs: if a dialog goes to the background and is killed, |
| you cannot recapture state, whereas Application exposes a {@link android.os.Bundle |
| Bundle} of saved values in <code>onCreate()</code> to help you maintain state.</td> |
| </tr> |
| </table> |
| <h3>AlertDialog</h3> |
| <p>This is a basic warning dialog box that lets you configure a message, button text, |
| and callback. You can create one by calling using the {@link |
| android.app.AlertDialog.Builder} class, as shown here. </p> |
| <pre>private Handler mHandler = new Handler() { |
| public void handleMessage(Message msg) { |
| switch (msg.what) { |
| case ACCEPT_CALL: |
| answer(msg.obj); |
| break; |
| |
| case BOUNCE_TO_VOICEMAIL: |
| voicemail(msg.obj); |
| break; |
| |
| } |
| } |
| }; |
| |
| |
| private void IncomingMotherInlawCall(Connection c) { |
| String Text; |
| |
| // "Answer" callback. |
| Message acceptMsg = Message.obtain(); |
| acceptMsg.target = mHandler; |
| acceptMsg.what = ACCEPT_CALL; |
| acceptMsg.obj = c.getCall(); |
| |
| // "Cancel" callback. |
| final Message rejectMsg = Message.obtain(); |
| rejectMsg.target = mHandler; |
| rejectMsg.what = BOUNCE_TO_VOICEMAIL; |
| rejectMsg.obj = c.getCall(); |
| |
| new AlertDialog.Builder(this) |
| .setMessage("Phyllis is calling") |
| .setPositiveButton("Answer", acceptMsg) |
| .setOnCanceListener(new OnCancelListener() { |
| public void onCancel(DialogInterface dialog) { |
| rejectMsg.sendToTarget(); |
| }}); |
| .show(); |
| } </pre> |
| |
| <h3>Notifications</h3> |
| |
| <p>Out-of-band alerts should always be displayed using the |
| {@link android.app.NotificationManager}, which allows you to tell the user |
| about something they may be interested in without disrupting what they are |
| currently doing. A notification can be anything from a brief pop-up box |
| informing the user of the new information, through displaying a persistent |
| icon in the status bar, to vibrating, playing sounds, or flashing lights to |
| get the user's attention. In all cases, the user must explicitly shift their |
| focus to the notification before they can interact with it.</p> |
| |
| <p>The following code demonstrates using NotificationManager to display a basic text |
| popup when a new SMS message arrives in a listening service, and provides the |
| current message count. You can see several more examples in the ApiDemos application, |
| under app/ (named <em>notification</em>*.java).</p> |
| <pre>static void setNewMessageIndicator(Context context, int messageCount){ |
| // Get the static global NotificationManager object. |
| NotificationManager nm = NotificationManager.getDefault();</p> |
| |
| // If we're being called because a new message has been received, |
| // then display an icon and a count. Otherwise, delete the persistent |
| // message. |
| if (messageCount > 0) { |
| nm.notifyWithText(myApp.NOTIFICATION_GUID, // ID for this notification. |
| messageCount + " new message" + messageCount > 1 ? "s":"", // Text to display. |
| NotificationManager.LENGTH_SHORT); // Show it for a short time only. |
| } |
| }</pre> |
| <p>To display a notification in the status bar and have it launch an intent when |
| the user selects it (such as the new text message notification does), call {@link |
| android.app.NotificationManager#notify(int, android.app.Notification) NotificationManager.notify()}, |
| and pass in vibration patterns, status bar icons, or Intents to associate with |
| the notification. </p> |
| <a name="progressbar" id="progressbar"></a><h2>Displaying a Progress Bar</h2> |
| <p>An activity can display a progress bar to notify the user that something is happening. |
| To display a progress bar in a screen, call {@link android.app.Activity#requestWindowFeature(int) |
| Activity.requestWindowFeature(Window.FEATURE_PROGRESS)}. To set the value |
| of the progress bar, call {@link android.view.Window#setFeatureInt(int,int) |
| Activity.getWindow().setFeatureInt(Window.FEATURE_PROGRESS, <em>level</em>)}. |
| Progress bar values are from 0 to 9,999, or set the value to 10,000 to make the |
| progress bar invisible. </p> |
| <p>You can also use the {@link android.app.ProgressDialog ProgressDialog} class, |
| which enables a dialog box with an embedded progress bar to send a "I'm working |
| on it" notification to the user. </p> |
| <a name="addmenuitems" id="addmenuitems"></a><h2>Adding Items to the Screen Menu</h2> |
| <p>See <a href="{@docRoot}guide/topics/ui/menus.html">Creating Menus</a>.</p> |
| |
| <a name="webpage" id="webpage"></a><h2>Display a Web Page</h2> |
| <p>Use the {@link android.webkit.WebView webkit.WebView} object. </p> |
| <a name="binding" id="binding"></a><h2>Binding to Data</h2> |
| <p>You can bind a ListView to a set of underlying data by using a shim class called |
| {@link android.widget.ListAdapter ListAdapter} (or a subclass). ListAdapter subclasses |
| bind to a variety of data sources, and expose a common set of methods such as |
| getItem() and getView(), and uses them to pick View items to display in its list. |
| You can extend ListAdapter and override getView() to create your own custom list |
| items. There are essentially only two steps you need to perform to bind to data: </p> |
| <ol> |
| <li>Create a ListAdapter object and specify its data source</li> |
| <li>Give the ListAdapter to your ListView object.</li> |
| </ol> |
| <p>That's it!</p> |
| <p>Here's an example of binding a ListActivity screen to the results from a cursor |
| query. (Note that the setListAdapter() method shown is a convenience method that |
| gets the page's ListView object and calls setAdapter() on it.)</p> |
| <pre>// Run a query and get a Cursor pointing to the results. |
| Cursor c = People.query(this.getContentResolver(), null); |
| startManagingCursor(c); |
| |
| // Create the ListAdapter. A SimpleCursorAdapter lets you specify two interesting things: |
| // an XML template for your list item, and |
| // The column to map to a specific item, by ID, in your template. |
| ListAdapter adapter = new SimpleCursorAdapter(this, |
| android.R.layout.simple_list_item_1, // Use a template that displays a text view |
| c, // Give the cursor to the list adapter |
| new String[] {People.NAME} , // Map the NAME column in the people database to... |
| new String[] {"text1"}); // The "text1" view defined in the XML template |
| setListAdapter(adapter);</pre> |
| <p>See view/List4 in the ApiDemos project for an example of extending ListAdapter |
| for a new data type. </p> |
| |
| <a name="handle"></a> |
| |
| <h2>Getting a Handle to a Screen Element</h2> |
| <p>You can get a handle to a screen element by calling {@link |
| android.app.Activity#findViewById(int) Activity.findViewById}. You can then use |
| the handle to set or retrieve any values exposed by the object. </p> |
| <a name="captureimages" id="captureimages"></a><h2>Capture Images from the Phone Camera</h2> |
| <p>You can hook into the device's camera onto your own Canvas object by using the |
| {@link android.hardware.Camera Camera} class. See that class's documentation, |
| and the ApiDemos project's Camera Preview application (Graphics/Camera Preview) |
| for example code. </p> |
| |
| |
| <a name="threading" id="threading"></a><h2>Handling Expensive Operations in the UI Thread</h2> |
| <p>Avoid performing long-running operations (such as network I/O) directly in the UI thread — |
| the main thread of an application where the UI is run — or your application may be blocked |
| and become unresponsive. Here is a brief summary of the recommended approach for handling expensive operations:</p> |
| <ol> |
| <li>Create a Handler object in your UI thread</li> |
| <li>Spawn off worker threads to perform any required expensive operations</li> |
| <li>Post results from a worker thread back to the UI thread's handler either through a Runnable or a {@link android.os.Message}</li> |
| <li>Update the views on the UI thread as needed</li> |
| </ol> |
| |
| <p>The following outline illustrates a typical implementation:</p> |
| |
| <pre> |
| public class MyActivity extends Activity { |
| |
| [ . . . ] |
| // Need handler for callbacks to the UI thread |
| final Handler mHandler = new Handler(); |
| |
| // Create runnable for posting |
| final Runnable mUpdateResults = new Runnable() { |
| public void run() { |
| updateResultsInUi(); |
| } |
| }; |
| |
| @Override |
| protected void onCreate(Bundle savedInstanceState) { |
| super.onCreate(savedInstanceState); |
| |
| [ . . . ] |
| } |
| |
| protected void startLongRunningOperation() { |
| |
| // Fire off a thread to do some work that we shouldn't do directly in the UI thread |
| Thread t = new Thread() { |
| public void run() { |
| mResults = doSomethingExpensive(); |
| mHandler.post(mUpdateResults); |
| } |
| }; |
| t.start(); |
| } |
| |
| private void updateResultsInUi() { |
| |
| // Back in the UI thread -- update our UI elements based on the data in mResults |
| [ . . . ] |
| } |
| } |
| </pre> |
| |
| <p>For further discussions on this topic, see |
| <a href="{@docRoot}guide/practices/design/responsiveness.html">Designing for Responsiveness</a> |
| and the {@link android.os.Handler} documentation.</p> |
| |
| <a name="selectingtext" id="selectingtext"></a><h2>Selecting, Highlighting, or Styling Portions of Text</h2> |
| <p>You can highlight or style the formatting of strings or substrings of text in |
| a TextView object. There are two ways to do this:</p> |
| <ul> |
| <li>If you use a <a href="{@docRoot}guide/topics/resources/available-resources.html#stringresources">string resource</a>, |
| you can add some simple styling, such as bold or italic using HTML notation. |
| The currently supported tags are: <code>B</code> (bold), |
| <code>I</code> (italic), <code>U</code> (underline), |
| <code>TT</code> (monospace), <code>BIG</code>, <code>SMALL</code>, |
| <code>SUP</code> (superscript), <code>SUB</code> (subscript), |
| and <code>STRIKE</code> (strikethrough). |
| So, for example, in res/values/strings.xml you could declare this:<br /> |
| <code><resource><br /> |
| <string id="@+id/styled_welcome_message">We |
| are <b><i>so</i></b> glad to see you.</string><br /> |
| </resources></code></li> |
| <li>To style text on the fly, or to add highlighting or more complex styling, |
| you must use the Spannable object as described next. </li> |
| </ul> |
| <p>To style text on the fly, you must make sure the TextView is using {@link android.text.Spannable} |
| storage for the text (this will always be true if the TextView is an EditText), |
| retrieve its text with {@link android.widget.TextView#getText}, and call {@link |
| android.text.Spannable#setSpan}, passing in a new style class from the {@link |
| android.text.style} package and the selection range. </p> |
| <p>The following code snippet demonstrates creating a string with a highlighted section, |
| italic section, and bold section, and adding it to an EditText object. </p> |
| <pre>// Get our EditText object. |
| EditText vw = (EditText)findViewById(R.id.text); |
| |
| // Set the EditText's text. |
| vw.setText("Italic, highlighted, bold."); |
| |
| // If this were just a TextView, we could do: |
| // vw.setText("Italic, highlighted, bold.", TextView.BufferType.SPANNABLE); |
| // to force it to use Spannable storage so styles can be attached. |
| // Or we could specify that in the XML. |
| |
| // Get the EditText's internal text storage |
| Spannable str = vw.getText(); |
| |
| // Create our span sections, and assign a format to each. |
| str.setSpan(new StyleSpan(android.graphics.Typeface.ITALIC), 0, 7, Spannable.SPAN_EXCLUSIVE_EXCLUSIVE); |
| str.setSpan(new BackgroundColorSpan(0xFFFFFF00), 8, 19, Spannable.SPAN_EXCLUSIVE_EXCLUSIVE); |
| str.setSpan(new StyleSpan(android.graphics.Typeface.BOLD), 21, str.length() - 1, Spannable.SPAN_EXCLUSIVE_EXCLUSIVE); |
| </pre> |
| |
| <a name="querymap" id="querymap"></a><h2>Utilizing attributes in a Map query</h2> |
| <p> |
| When using a search intent to ask the Maps activity to search for something, the Maps activity responds to the following attributes in the optional context bundle: |
| </p> |
| <pre> |
| float "centerLatitude" default 0.0f |
| float "centerLongitude" default 0.0f |
| float "latitudeSpan" default 0.0f |
| float "longitudeSpan" default 0.0f |
| int "zoomLevel" default 10 |
| </pre> |
| <p> |
| This context information is used to center the search result in a particular area, and is equivalent to adjusting the Map activity to the described location and zoom level before issuing the query. |
| </p> |
| <p> |
| If the latitudeSpan, longitudeSpan, and zoomLevel attributes are not consistent, then it is undefined which one takes precedence. |
| </p> |
| |
| <a name="filelist" id="filelist"></a><h2>List of Files for an Android Application</h2> |
| <p>The following list describes the structure and files of an Android application. |
| Many of these files can be built for you (or stubbed out) by the android tool |
| shipped in the tools/ menu of the SDK. </p> |
| <table width="100%" border="0"> |
| <tr> |
| <td width="28%" valign="top">MyApp/<br /></td> |
| <td width="72%" valign="top"> </td> |
| </tr> |
| <tr> |
| <td valign="top"> AndroidManifest.xml</td> |
| <td valign="top">(<em>required</em>) Advertises the screens that this application provides, |
| where they can be launched (from the main program menu or elsewhere), |
| any content providers it implements and what kind of data they handle, |
| where the implementation classes are, and other application-wide |
| information. Syntax details for this file are described in <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">The AndroidManifest.xml File</a>.</td> |
| </tr> |
| <tr> |
| <td valign="top"> src/<br /> |
| /<em>myPackagePath</em>/.../<em>MyClass</em>.java</td> |
| <td valign="top">(<em>required</em>) This folder holds all the source code files for your |
| application, inside the appropriate package subfolders. </td> |
| </tr> |
| <tr> |
| <td valign="top"> res/</td> |
| <td valign="top">(<em>required</em>) This folder holds all the <em>resources</em> for |
| your application. Resources are external data files or description files |
| that are compiled into your code at build time. Files in different folders |
| are compiled differently, so you must put the proper resource into the |
| proper folder. (See <a href="{@docRoot}guide/topics/resources/resources-i18n.html">Resources</a> for details.)</td> |
| </tr> |
| <tr> |
| <td valign="top"> anim/<br /> |
| <em>animation1</em>.xml<br /> |
| <em>...</em></td> |
| <td valign="top">(<em>optional</em>) Holds any animation XML description files that the |
| application uses. The format of these files is described in <a href="{@docRoot}guide/topics/resources/resources-i18n.html">Resources</a>. </td> |
| </tr> |
| <tr> |
| <td valign="top"> drawable/<br /> |
| <em>some_picture</em>.png<br /> |
| <em>some_stretchable</em>.9.png<br /> |
| <em>some_background</em>.xml<br /> |
| ...</td> |
| <td valign="top">(<em>optional</em>) Zero or more files that will be compiled to {@link |
| android.graphics.drawable android.graphics.drawable} resources. Files |
| can be image files (png, gif, or other) or XML files describing other |
| graphics such as bitmaps, stretchable bitmaps, or gradients. Supported |
| bitmap file formats are PNG (preferred), JPG, and GIF (discouraged), |
| as well as the custom 9-patch stretchable bitmap format. These formats |
| are described in <a href="{@docRoot}guide/topics/resources/resources-i18n.html">Resources</a>. </td> |
| </tr> |
| <tr> |
| <td valign="top"> layout/<br /> |
| <em>screen_1_layout</em>.xml<br /> |
| ...<br /></td> |
| <td valign="top">(<em>optional</em>) Holds all the XML files describing screens or parts |
| of screens. Although you could create a screen in Java, defining them |
| in XML files is typically easier. A layout file is similar in concept |
| to an HTML file that describes the screen layout and components. See <a href="{@docRoot}guide/topics/ui/index.html">User Interface</a> for more information about designing screens, and <a href="{@docRoot}guide/topics/resources/available-resources.html#layoutresources">Available Resource Types</a> for the syntax of these files.</td> |
| </tr> |
| <tr> |
| <td valign="top"> values/<br /> |
| arrays<br /> |
| classes.xml<br /> |
| colors.xml<br /> |
| dimens.xml<br /> |
| strings.xml<br /> |
| styles.xml<br /> |
| values.xml<br /></td> |
| <td valign="top"><p>(<em>optional</em>) XML files describing additional resources |
| such as strings, colors, and styles. The naming, quantity, and number |
| of these files are not enforced--any XML file is compiled, but these |
| are the standard names given to these files. However, the syntax |
| of these files is prescribed by Android, and described in <a href="{@docRoot}guide/topics/resources/resources-i18n.html">Resources</a>. </p> |
| </td> |
| </tr> |
| <tr> |
| <td valign="top"> xml/</td> |
| <td valign="top">(<em>optional</em>) XML files that can be read at run time on the device. </td> |
| </tr> |
| <tr> |
| <td valign="top"> raw/</td> |
| <td valign="top">(<em>optional</em>) Any files to be copied directly to the device. </td> |
| </tr> |
| </table> |
| |
| |
| <a name="logging" ></a> |
| <h2>Print Messages to a Log File</h2> |
| |
| <p>To write log messages from your application:</p> |
| <ol><li>Import <code>android.util.Log</code>.</li> |
| <li>Use <code>Log.v()</code>, <code>Log.d()</code>, <code>Log.i()</code>, |
| <code>Log.w()</code>, or <code>Log.e()</code> to log messages. |
| (See the {@link android.util.Log} class.)<br/> E.g., |
| <code>Log.e(this.toString(), "error: " + err.toString())</code></li> |
| <li>Launch <a href="{@docRoot}guide/developing/tools/ddms.html">DDMS</a> from a terminal |
| by executing <code>ddms</code> in your Android SDK <code>/tools</code> path.</li> |
| <li>Run your application in the Android emulator.</li> |
| <li>From the DDMS application, select the emulator |
| (e.g., "emulator-5554") and click <b>Device > Run logcat...</b> |
| to view all the log data.</li> |
| </ol> |
| <p class="note"><strong>Note:</strong> If you are running Eclipse and |
| encounter a warning about the VM debug port when opening DDMS, you can ignore it |
| if you're only interested in logs. However, if you want to further inspect and |
| control your processes from DDMS, then you should close Eclipse before launching DDMS so that |
| it may use the VM debugging port.</p> |
| |
| |
