diff options
Diffstat (limited to 'docs/html/guide/faq/commontasks.jd')
| -rw-r--r-- | docs/html/guide/faq/commontasks.jd | 826 |
1 files changed, 0 insertions, 826 deletions
diff --git a/docs/html/guide/faq/commontasks.jd b/docs/html/guide/faq/commontasks.jd deleted file mode 100644 index 2943aef..0000000 --- a/docs/html/guide/faq/commontasks.jd +++ /dev/null @@ -1,826 +0,0 @@ -page.title=Common Tasks and How to Do Them in Android -excludeFromSuggestions=true -@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}training/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">Input Events</a>.</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">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/string-resource.html">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><resources><br /> - <string name="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> - - |