blob: 998c7c36b07a0e2d3711fe85abf618d2e046d46e [file] [log] [blame]
Scott Main1f694392011-02-21 22:19:27 -08001page.title=Android 3.0 Platform
Scott Mainea723292011-02-09 16:01:04 -08002sdk.platform.version=3.0
3sdk.platform.apiLevel=11
Scott Main7fb538c2011-01-19 21:11:50 -08004@jd:body
5
6<div id="qv-wrapper">
7<div id="qv">
8
9<h2>In this document</h2>
10<ol>
Scott Mainea723292011-02-09 16:01:04 -080011 <li><a href="#relnotes">Revisions</a></li>
Scott Main7fb538c2011-01-19 21:11:50 -080012 <li><a href="#api">API Overview</a></li>
13 <li><a href="#api-level">API Level</a></li>
14 <li><a href="#apps">Built-in Applications</a></li>
15 <li><a href="#locs">Locales</a></li>
16 <li><a href="#skins">Emulator Skins</a></li>
17</ol>
18
19<h2>Reference</h2>
20<ol>
21<li><a
Scott Mainea723292011-02-09 16:01:04 -080022href="{@docRoot}sdk/api_diff/11/changes.html">API
Scott Main7fb538c2011-01-19 21:11:50 -080023Differences Report &raquo;</a> </li>
24</ol>
25
26<h2>See Also</h2>
27<ol>
Scott Main1f694392011-02-21 22:19:27 -080028 <li><a href="{@docRoot}guide/practices/optimizing-for-3.0.html">Optimizing Apps for Android 3.0</a></li>
Scott Main7fb538c2011-01-19 21:11:50 -080029</ol>
30
31</div>
32</div>
33
Scott Main7fb538c2011-01-19 21:11:50 -080034
Scott Mainea723292011-02-09 16:01:04 -080035<p><em>API Level:</em>&nbsp;<strong>{@sdkPlatformApiLevel}</strong></p>
Scott Maind41ff8e2011-01-21 14:51:33 -080036
Scott Mainea723292011-02-09 16:01:04 -080037<p>For developers, the Android {@sdkPlatformVersion} platform is available as a downloadable
38component for the Android SDK. The downloadable platform includes an Android library and system
39image, as well as a set of emulator skins and more. The downloadable platform includes no external
40libraries.</p>
41
42<p>To get started developing or testing against Android {@sdkPlatformVersion}, use the Android SDK
43Manager to download the platform into your SDK. For more information, see <a
44href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>. If you are new to Android, <a
45href="{@docRoot}sdk/index.html">download the SDK Starter Package</a> first.</p>
46
47<p>For a high-level introduction to Android {@sdkPlatformVersion}, see the <a
48href="{@docRoot}sdk/android-{@sdkPlatformVersion}-highlights.html">Platform
49Highlights</a>.</p>
Scott Maind41ff8e2011-01-21 14:51:33 -080050
Scott Main1f694392011-02-21 22:19:27 -080051<p class="note"><strong>Note:</strong>
52If you've already published an Android application, please test and optimize your application on
53Android 3.0 as soon as possible. You should do so to be sure your application provides the best
54experience possible on the latest Android-powered devices. For information about what you can do,
55read <a href="{@docRoot}guide/practices/optimizing-for-3.0.html">Optimizing Apps for Android
563.0</a>.</p>
Scott Maind41ff8e2011-01-21 14:51:33 -080057
58
Scott Mainea723292011-02-09 16:01:04 -080059<h2 id="relnotes">Revisions</h2>
Scott Main7fb538c2011-01-19 21:11:50 -080060
Scott Mainea723292011-02-09 16:01:04 -080061<p>To determine what revision of the Android {@sdkPlatformVersion} platform you have installed,
62refer to the "Installed Packages" listing in the Android SDK and AVD Manager.</p>
63
64
65<div class="toggle-content opened" style="padding-left:1em;">
66
67 <p><a href="#" onclick="return toggleContent(this)">
68 <img src="{@docRoot}assets/images/triangle-opened.png" class="toggle-content-img" alt="" />
69 Android {@sdkPlatformVersion}, Revision 1</a> <em>(February 2011)</em>
70 </a></p>
71
72 <div class="toggle-content-toggleme" style="padding-left:2em;">
73
74<dl>
75
76<dt>Dependencies:</dt>
77<dd>
78<p>Requires <a href="{@docRoot}sdk/tools-notes.html">SDK Tools r10</a> or higher.</p>
79</dd>
80
81</dl>
82
83 </div>
84</div>
Scott Main7fb538c2011-01-19 21:11:50 -080085
86
87
88<h2 id="#api">API Overview</h2>
89
90<p>The sections below provide a technical overview of what's new for developers in Android 3.0,
91including new features and changes in the framework API since the previous version.</p>
92
93
Scott Mainea723292011-02-09 16:01:04 -080094
95
96
Scott Main7fb538c2011-01-19 21:11:50 -080097<h3>Fragments</h3>
98
99<p>A fragment is a new framework component that allows you to separate distinct elements of an
100activity into self-contained modules that define their own UI and lifecycle. To create a
101fragment, you must extend the {@link android.app.Fragment} class and implement several lifecycle
102callback methods, similar to an {@link android.app.Activity}. You can then combine multiple
103fragments in a single activity to build a multi-pane UI in which each
104pane manages its own lifecycle and user inputs.</p>
105
106<p>You can also use a fragment without providing a UI and instead use the fragment as a worker
107for the activity, such as to manage the progress of a download that occurs only while the
108activity is running.</p>
109
110<p>Additionally:</p>
111
112<ul>
Scott Mainea723292011-02-09 16:01:04 -0800113 <li>Fragments are self-contained and you can reuse them in multiple activities</li>
114 <li>You can add, remove, replace and animate fragments inside the activity</li>
115 <li>You can add fragments to a back stack managed by the activity, preserving the state of
Scott Main7fb538c2011-01-19 21:11:50 -0800116fragments as they are changed and allowing the user to navigate backward through the different
117states</li>
118 <li>By <a
119href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">providing
Scott Main7afdaf02011-01-25 13:03:30 -0800120alternative layouts</a>, you can mix and match fragments, based
Scott Main7fb538c2011-01-19 21:11:50 -0800121on the screen size and orientation</li>
122 <li>Fragments have direct access to their container activity and can contribute items to the
123activity's Action Bar (discussed next)</li>
124</ul>
125
126<p>To manage the fragments in your activity, you must use the {@link
127android.app.FragmentManager}, which provides several APIs for interacting with fragments, such
Scott Mainea723292011-02-09 16:01:04 -0800128as finding fragments in the activity and popping fragments off the back stack to restore their
129previous state.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800130
Scott Main7afdaf02011-01-25 13:03:30 -0800131<p>To perform a transaction, such as add or remove a fragment, you must create a {@link
Scott Main7fb538c2011-01-19 21:11:50 -0800132android.app.FragmentTransaction}. You can then call methods such as {@link
133android.app.FragmentTransaction#add add()} {@link android.app.FragmentTransaction#remove
Scott Main7afdaf02011-01-25 13:03:30 -0800134remove()}, or {@link android.app.FragmentTransaction#replace replace()}. Once you've applied all
Scott Main7fb538c2011-01-19 21:11:50 -0800135the changes you want to perform for the transaction, you must call {@link
Scott Main7afdaf02011-01-25 13:03:30 -0800136android.app.FragmentTransaction#commit commit()} and the system applies the fragment transaction to
Scott Main7fb538c2011-01-19 21:11:50 -0800137the activity.</p>
138
Scott Main7afdaf02011-01-25 13:03:30 -0800139<p>For more information about using fragments, read the <a
Scott Main64b12ea2011-02-14 13:41:03 -0800140href="{@docRoot}guide/topics/fundamentals/fragments.html">Fragments</a> documentation. Several
141samples are also available in the <a
142href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/index.html#Fragment">
143API Demos</a> application.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800144
145
146
147
148<h3>Action Bar</h3>
149
Scott Main7afdaf02011-01-25 13:03:30 -0800150<p>The Action Bar is a replacement for the traditional title bar at the top of the activity window.
151It includes the application logo in the left corner and provides a new interface for items in the
Scott Mainea723292011-02-09 16:01:04 -0800152<a href="{@docRoot}guide/topics/ui/menus.html#options-menu">Options Menu</a>. Additionally, the
153Action Bar allows you to:</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800154
155<ul>
Scott Mainea723292011-02-09 16:01:04 -0800156 <li>Add menu items directly in the Action Bar&mdash;as "action items."
157 <p>In your XML declaration for the menu item, include the {@code
158android:showAsAction} attribute with a value of {@code "ifRoom"}. When there's enough room, the menu
159item appears directly in the Action Bar. Otherwise, the item is placed in the
160overflow menu, revealed by the menu icon on the right side of the Action Bar.</p></li>
Scott Main7afdaf02011-01-25 13:03:30 -0800161
Scott Mainea723292011-02-09 16:01:04 -0800162 <li>Replace an action item with a widget (such as a search box)&mdash;creating an
163"action view."
164 <p>In the XML declaration for the menu item, add the {@code android:actionViewLayout} attribute
165with a layout resource or the {@code android:actionViewClass} attribute with the class name of a
166widget. (You must also declare the {@code android:showAsAction} attribute so that the item appears
167in the Action Bar.) If there's not enough room in the Action Bar and the item appears in the
168overflow menu, it behaves like a regular menu item and does not show the widget.</p></li>
Scott Main7afdaf02011-01-25 13:03:30 -0800169
Scott Mainea723292011-02-09 16:01:04 -0800170 <li>Add an action to the application logo and replace it with a custom logo
Scott Main7fb538c2011-01-19 21:11:50 -0800171 <p>The application logo is automatically assigned the {@code android.R.id.home} ID,
Scott Mainea723292011-02-09 16:01:04 -0800172which the system delivers to your activity's {@link android.app.Activity#onOptionsItemSelected
173onOptionsItemSelected()} callback when touched. Simply respond to this ID in your callback
Scott Main7fb538c2011-01-19 21:11:50 -0800174method to perform an action such as go to your application's "home" activity.</p>
Scott Mainea723292011-02-09 16:01:04 -0800175 <p>To replace the icon with a logo, specify your application logo in the manifest file with the
176<a href="{@docRoot}guide/topics/manifest/application-element.html#logo">{@code android:logo}</a>
177attribute, then call {@link android.app.ActionBar#setDisplayUseLogoEnabled
178setDisplayUseLogoEnabled(true)} in your activity.</p></li>
Scott Main7afdaf02011-01-25 13:03:30 -0800179
Scott Mainea723292011-02-09 16:01:04 -0800180 <li>Add breadcrumbs to navigate backward through the back stack of fragments</li>
181 <li>Add tabs or a drop-down list to navigate through fragments</li>
182 <li>Customize the Action Bar with themes and backgrounds</li>
Scott Main7fb538c2011-01-19 21:11:50 -0800183</ul>
184
Scott Mainea723292011-02-09 16:01:04 -0800185<p>The Action Bar is standard for all applications that use the new holographic theme, which is
186also standard when you set either the <a
Scott Main7fb538c2011-01-19 21:11:50 -0800187href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code
188android:minSdkVersion}</a> or <a
189href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
Scott Mainea723292011-02-09 16:01:04 -0800190android:targetSdkVersion}</a> to {@code "11"}.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800191
Scott Main7afdaf02011-01-25 13:03:30 -0800192<p>For more information about the Action Bar, read the <a
Scott Main64b12ea2011-02-14 13:41:03 -0800193href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> documentation. Several
194samples are also available in the <a
195href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/index.html#ActionBar">
196API Demos</a> application.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800197
198
199
200
201<h3>System clipboard</h3>
202
203<p>Applications can now copy and paste data (beyond mere text) to and from the system-wide
204clipboard. Clipped data can be plain text, a URI, or an intent.</p>
205
Scott Mainea723292011-02-09 16:01:04 -0800206<p>By providing the system access to the data you want the user to copy, through a content provider,
207the user can copy complex content (such as an image or data structure) from your application and
208paste it into another application that supports that type of content.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800209
210<p>To start using the clipboard, get the global {@link android.content.ClipboardManager} object
211by calling {@link android.content.Context#getSystemService getSystemService(CLIPBOARD_SERVICE)}.</p>
212
Scott Mainea723292011-02-09 16:01:04 -0800213<p>To copy an item to the clipboard, you need to create a new {@link
Scott Main7fb538c2011-01-19 21:11:50 -0800214android.content.ClipData} object, which holds one or more {@link android.content.ClipData.Item}
Scott Mainea723292011-02-09 16:01:04 -0800215objects, each describing a single entity. To create a {@link android.content.ClipData} object
216containing just one {@link android.content.ClipData.Item}, you can use one of the helper methods,
217such as {@link android.content.ClipData#newPlainText newPlainText()}, {@link
Scott Main7fb538c2011-01-19 21:11:50 -0800218android.content.ClipData#newUri newUri()}, and {@link android.content.ClipData#newIntent
219newIntent()}, which each return a {@link android.content.ClipData} object pre-loaded with the
Scott Mainea723292011-02-09 16:01:04 -0800220{@link android.content.ClipData.Item} you provide.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800221
222<p>To add the {@link android.content.ClipData} to the clipboard, pass it to {@link
223android.content.ClipboardManager#setPrimaryClip setPrimaryClip()} for your instance of {@link
224android.content.ClipboardManager}.</p>
225
Scott Mainea723292011-02-09 16:01:04 -0800226<p>You can then read a file from the clipboard (in order to paste it) by calling {@link
Scott Main7fb538c2011-01-19 21:11:50 -0800227android.content.ClipboardManager#getPrimaryClip()} on the {@link
228android.content.ClipboardManager}. Handling the {@link android.content.ClipData} you receive can
Scott Mainea723292011-02-09 16:01:04 -0800229be complicated and you need to be sure you can actually handle the data type in the clipboard
230before attempting to paste it.</p>
231
232<p>The clipboard holds only one piece of clipped data (a {@link android.content.ClipData}
233object) at a time, but one {@link android.content.ClipData} can contain multiple {@link
234android.content.ClipData.Item}s.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800235
Scott Main64b12ea2011-02-14 13:41:03 -0800236<p>For more information, read the <a href="{@docRoot}guide/topics/clipboard/copy-paste.html">Copy
237and Paste</a> documentation. You can also see a simple implementation of copy and paste in the <a
238href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/content/ClipboardSample.
239html">API Demos</a> and a more complete implementation in the <a
240href="{@docRoot}resources/samples/NotePad/index.html">Note Pad</a> application.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800241
242
243
244
245<h3>Drag and drop</h3>
246
Scott Mainea723292011-02-09 16:01:04 -0800247<p>New APIs simplify drag and drop operations in your application's user interface. A drag
248operation is the transfer of some kind of data&mdash;carried in a {@link android.content.ClipData}
249object&mdash;from one place to another. The start and end point for the drag operation is a {@link
250android.view.View}, so the APIs that directly handle the drag and drop operations are
251in the {@link android.view.View} class.</p>
252
253<p>A drag and drop operation has a lifecycle that's defined by several drag actions&mdash;each
254defined by a {@link android.view.DragEvent} object&mdash;such as {@link
255android.view.DragEvent#ACTION_DRAG_STARTED}, {@link android.view.DragEvent#ACTION_DRAG_ENTERED}, and
256{@link android.view.DragEvent#ACTION_DROP}. Each view that wants to participate in a drag
257operation can listen for these actions.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800258
Scott Maind41ff8e2011-01-21 14:51:33 -0800259<p>To begin dragging content in your activity, call {@link android.view.View#startDrag startDrag()}
260on a {@link android.view.View}, providing a {@link android.content.ClipData} object that represents
Scott Mainea723292011-02-09 16:01:04 -0800261the data to drag, a {@link android.view.View.DragShadowBuilder} to facilitate the "shadow"
262that users see under their fingers while dragging, and an {@link java.lang.Object} that can share
263information about the drag object with views that may receive the object.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800264
Scott Mainea723292011-02-09 16:01:04 -0800265<p>To accept a drag object in a {@link android.view.View} (receive the "drop"), register the view
266with an {@link android.view.View.OnDragListener OnDragListener} by calling {@link
267android.view.View#setOnDragListener setOnDragListener()}. When a drag event occurs on the view, the
268system calls {@link android.view.View.OnDragListener#onDrag onDrag()} for the {@link
Scott Main7afdaf02011-01-25 13:03:30 -0800269android.view.View.OnDragListener OnDragListener}, which receives a {@link android.view.DragEvent}
Scott Mainea723292011-02-09 16:01:04 -0800270describing the type of drag action has occurred (such as {@link
271android.view.DragEvent#ACTION_DRAG_STARTED}, {@link android.view.DragEvent#ACTION_DRAG_ENTERED}, and
272{@link android.view.DragEvent#ACTION_DROP}). During a drag, the system repeatedly calls {@link
273android.view.View.OnDragListener#onDrag onDrag()} for the view underneath the drag, to deliver a
274stream of drag events. The receiving view can inquire the event type delivered to {@link
275android.view.View#onDragEvent onDragEvent()} by calling {@link android.view.DragEvent#getAction
276getAction()} on the {@link android.view.DragEvent}.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800277
Scott Mainea723292011-02-09 16:01:04 -0800278<p class="note"><strong>Note:</strong> Although a drag event may carry a {@link
279android.content.ClipData} object, this is not related to the system clipboard. A drag and drop
280operation should never put the dragged data in the system clipboard.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800281
Scott Main64b12ea2011-02-14 13:41:03 -0800282<p>For more information, read the <a href="{@docRoot}guide/topics/ui/drag-drop.html">Dragging and
283Dropping</a> documentation. You can also see an implementation of drag and drop in the <a
284href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/DragAndDropDemo.html">
285API Demos</a> application and the <a
286href="{@docRoot}resources/samples/HoneycombGallery/index.html">Honeycomb Gallery</a>
287application.</p>
288
Scott Main7fb538c2011-01-19 21:11:50 -0800289
290
Scott Maind41ff8e2011-01-21 14:51:33 -0800291<h3>App widgets</h3>
Scott Main7fb538c2011-01-19 21:11:50 -0800292
Scott Mainea723292011-02-09 16:01:04 -0800293<p>Android 3.0 supports several new widget classes for more interactive app widgets on the users
294Home screen, including: {@link android.widget.GridView}, {@link android.widget.ListView}, {@link
295android.widget.StackView}, {@link android.widget.ViewFlipper}, and {@link
296android.widget.AdapterViewFlipper}.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800297
Scott Mainea723292011-02-09 16:01:04 -0800298<p>More importantly, you can use the new {@link android.widget.RemoteViewsService} to create app
299widgets with collections, using widgets such as {@link android.widget.GridView}, {@link
300android.widget.ListView}, and {@link android.widget.StackView} that are backed by remote data,
301such as from a content provider.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800302
Scott Main5a44efb2011-02-15 10:45:46 -0800303<p>The {@link android.appwidget.AppWidgetProviderInfo} class (defined in XML with an {@code
304&lt;appwidget-provider&gt;} element) also supports two new fields: {@link
Scott Maind41ff8e2011-01-21 14:51:33 -0800305android.appwidget.AppWidgetProviderInfo#autoAdvanceViewId} and {@link
306android.appwidget.AppWidgetProviderInfo#previewImage}. The {@link
Scott Main7fb538c2011-01-19 21:11:50 -0800307android.appwidget.AppWidgetProviderInfo#autoAdvanceViewId} field lets you specify the view ID of the
Scott Mainea723292011-02-09 16:01:04 -0800308app widget subview that should be auto-advanced by the app widget’s host. The
Scott Main7fb538c2011-01-19 21:11:50 -0800309{@link android.appwidget.AppWidgetProviderInfo#previewImage} field specifies a preview of what the
Scott Main7afdaf02011-01-25 13:03:30 -0800310app widget looks like and is shown to the user from the widget picker. If this field is not
Scott Main7fb538c2011-01-19 21:11:50 -0800311supplied, the app widget's icon is used for the preview.</p>
312
Scott Mainea723292011-02-09 16:01:04 -0800313<p>To help create a preview image for your app widget (to specify in the {@link
314android.appwidget.AppWidgetProviderInfo#autoAdvanceViewId} field), the Android emulator includes an
315application called "Widget Preview." To create a preview image, launch this application, select the
316app widget for your application and set it up how you'd like your preview image to appear, then save
317it and place it in your application's drawable resources.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800318
Scott Main64b12ea2011-02-14 13:41:03 -0800319<p>You can see an implementation of the new app widget features in the <a
320href="{@docRoot}resources/samples/StackWidget/index.html">StackView App Widget</a> and <a
321href="{@docRoot}resources/samples/WeatherListWidget/index.html">Weather List Widget</a>
322applications.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800323
324
325
Scott Maind41ff8e2011-01-21 14:51:33 -0800326<h3>Status bar notifications</h3>
Scott Main7fb538c2011-01-19 21:11:50 -0800327
328<p>The {@link android.app.Notification} APIs have been extended to support more content-rich status
329bar notifications, plus a new {@link android.app.Notification.Builder} class allows you to easily
Scott Mainea723292011-02-09 16:01:04 -0800330create {@link android.app.Notification} objects.</p>
Scott Main7afdaf02011-01-25 13:03:30 -0800331<p>New features include:</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800332<ul>
Scott Main7afdaf02011-01-25 13:03:30 -0800333 <li>Support for a large icon in the notification, using {@link
334android.app.Notification.Builder#setLargeIcon setLargeIcon()}. This is usually for
Scott Main7fb538c2011-01-19 21:11:50 -0800335social applications to show the contact photo of the person who is the source of the
Scott Main7afdaf02011-01-25 13:03:30 -0800336notification or for media apps to show an album thumbnail.</li>
Scott Main7fb538c2011-01-19 21:11:50 -0800337 <li>Support for custom layouts in the status bar ticker, using {@link
338android.app.Notification.Builder#setTicker(CharSequence,RemoteViews) setTicker()}.</li>
339 <li>Support for custom notification layouts to include buttons with {@link
Scott Mainea723292011-02-09 16:01:04 -0800340android.app.PendingIntent}s, for more interactive notification widgets. For example, a
341notification can control music playback without starting an activity.</li>
Scott Main7fb538c2011-01-19 21:11:50 -0800342</ul>
343
344
345
Scott Maind41ff8e2011-01-21 14:51:33 -0800346<h3>Content loaders</h3>
Scott Main7fb538c2011-01-19 21:11:50 -0800347
Scott Maind41ff8e2011-01-21 14:51:33 -0800348<p>New framework APIs facilitate asynchronous loading of data using the {@link
349android.content.Loader} class. You can use it in combination with UI components such as views and
Scott Main7afdaf02011-01-25 13:03:30 -0800350fragments to dynamically load data from worker threads. The {@link
Scott Mainea723292011-02-09 16:01:04 -0800351android.content.CursorLoader} subclass is specially designed to help you do so for data backed by
352a {@link android.content.ContentProvider}.</p>
Scott Maind41ff8e2011-01-21 14:51:33 -0800353
Scott Mainea723292011-02-09 16:01:04 -0800354<p>All you need to do is implement the {@link android.app.LoaderManager.LoaderCallbacks
355LoaderCallbacks} interface to receive callbacks when a new loader is requested or the data has
356changed, then call {@link android.app.LoaderManager#initLoader initLoader()} to initialize the
357loader for your activity or fragment.</p>
Scott Maind41ff8e2011-01-21 14:51:33 -0800358
Scott Main64b12ea2011-02-14 13:41:03 -0800359<p>For more information, read the <a
Scott Maina5647452011-02-15 17:25:26 -0800360href="{@docRoot}guide/topics/fundamentals/loaders.html">Loaders</a> documentation. You can also see
Scott Main64b12ea2011-02-14 13:41:03 -0800361example code using loaders in the <a
Scott Main13033ea2011-02-15 13:18:30 -0800362href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/FragmentListCursorLoader.html">FragmentListCursorLoader</a>
363and <a
Scott Main64b12ea2011-02-14 13:41:03 -0800364href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LoaderThrottle.html">
365LoaderThrottle</a> samples.</p>
Scott Maind41ff8e2011-01-21 14:51:33 -0800366
367
368
369<h3>Bluetooth A2DP and headset APIs</h3>
370
371<p>Android now includes APIs for applications to verify the state of connected Bluetooth A2DP and
Scott Main7afdaf02011-01-25 13:03:30 -0800372headset profile devices. For example, applications can identify when a Bluetooth headset is
373connected for listening to music and notify the user as appropriate. Applications can also receive
374broadcasts for vendor specific AT commands and notify the user about the state of the connected
375device, such as when the connected device's battery is low.</p>
376
377<p>You can initialize the respective {@link android.bluetooth.BluetoothProfile} by calling {@link
Scott Maind41ff8e2011-01-21 14:51:33 -0800378android.bluetooth.BluetoothAdapter#getProfileProxy getProfileProxy()} with either the {@link
379android.bluetooth.BluetoothProfile#A2DP} or {@link android.bluetooth.BluetoothProfile#HEADSET}
380profile constant and a {@link android.bluetooth.BluetoothProfile.ServiceListener} to receive
Scott Main7afdaf02011-01-25 13:03:30 -0800381callbacks when the Bluetooth client is connected or disconnected.</p>
Scott Maind41ff8e2011-01-21 14:51:33 -0800382
383
384
385
Scott Mainea723292011-02-09 16:01:04 -0800386<h3 id="animation">Animation framework</h3>
Scott Maind41ff8e2011-01-21 14:51:33 -0800387
Scott Main7afdaf02011-01-25 13:03:30 -0800388<p>An all new flexible animation framework allows you to animate arbitrary properties of any object
Scott Mainea723292011-02-09 16:01:04 -0800389(View, Drawable, Fragment, Object, or anything else). It allows you to define several aspects of an
Scott Main7afdaf02011-01-25 13:03:30 -0800390animation, such as:</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800391<ul>
392 <li>Duration</li>
393 <li>Repeat amount and behavior</li>
394 <li>Type of time interpolation</li>
395 <li>Animator sets to play animations together, sequentially, or after specified delays</li>
396 <li>Frame refresh delay</li>
397</ul>
Scott Main7fb538c2011-01-19 21:11:50 -0800398
Scott Mainea723292011-02-09 16:01:04 -0800399 <p>You can define these animation aspects, and others, for an object's int, float, and hexadecimal
400color values, by default. That is, when an object has a property field for one of these types, you
401can change its value over time to affect an animation. To animate any other type of value, you tell
402the system how to calculate the values for that given type, by implementing the {@link
403android.animation.TypeEvaluator} interface.</p>
404
405<p>There are two animators you can use to animate the values of a property: {@link
Scott Main7fb538c2011-01-19 21:11:50 -0800406android.animation.ValueAnimator} and {@link android.animation.ObjectAnimator}. The {@link
407android.animation.ValueAnimator} computes the animation values, but is not aware of the specific
408object or property that is animated as a result. It simply performs the calculations, and you must
409listen for the updates and process the data with your own logic. The {@link
410android.animation.ObjectAnimator} is a subclass of {@link android.animation.ValueAnimator} and
Scott Maind41ff8e2011-01-21 14:51:33 -0800411allows you to set the object and property to animate, and it handles all animation work.
412That is, you give the {@link android.animation.ObjectAnimator} the object to animate, the
413property of the object to change over time, and a set of values to apply to the property over
Scott Mainea723292011-02-09 16:01:04 -0800414time, then start the animation.</p>
Scott Maind41ff8e2011-01-21 14:51:33 -0800415
416<p>Additionally, the {@link android.animation.LayoutTransition} class enables automatic transition
Scott Main7afdaf02011-01-25 13:03:30 -0800417animations for changes you make to your activity layout. To enable transitions for part of the
418layout, create a {@link android.animation.LayoutTransition} object and set it on
Scott Maind41ff8e2011-01-21 14:51:33 -0800419any {@link android.view.ViewGroup} by calling {@link
420android.view.ViewGroup#setLayoutTransition setLayoutTransition()}. This causes default
421animations to run whenever items are added to or removed from the group. To specify custom
422animations, call {@link android.animation.LayoutTransition#setAnimator setAnimator()} on the {@link
Scott Main7afdaf02011-01-25 13:03:30 -0800423android.animation.LayoutTransition} and provide a custom {@link android.animation.Animator},
Scott Maind41ff8e2011-01-21 14:51:33 -0800424such as a {@link android.animation.ValueAnimator} or {@link android.animation.ObjectAnimator}
425discussed above.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800426
427<p>For more information, see the <a
Scott Main64b12ea2011-02-14 13:41:03 -0800428href="{@docRoot}guide/topics/graphics/animation.html">Property Animation</a> documentation. You can
429also see several samples using the animation APIs in the <a
430href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/animation/index.html">API
431Demos</a> application.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800432
433
434
435
Scott Maind41ff8e2011-01-21 14:51:33 -0800436<h3>Extended UI framework</h3>
Scott Main7fb538c2011-01-19 21:11:50 -0800437
438<ul>
439
Scott Maind41ff8e2011-01-21 14:51:33 -0800440 <li><b>Multiple-choice selection for ListView and GridView</b>
Scott Main7fb538c2011-01-19 21:11:50 -0800441
Scott Maind41ff8e2011-01-21 14:51:33 -0800442<p>New {@link android.widget.AbsListView#CHOICE_MODE_MULTIPLE_MODAL} mode for {@link
Scott Mainea723292011-02-09 16:01:04 -0800443android.widget.AbsListView#setChoiceMode setChoiceMode()} allows users to select multiple items
444from a {@link android.widget.ListView} or {@link android.widget.GridView}. When used in
445conjunction with the Action Bar, users can select multiple items and then select the action to
446perform from a list of options in the Action Bar (which has transformed into a Multi-choice
447Action Mode).</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800448
Scott Maind41ff8e2011-01-21 14:51:33 -0800449<p>To enable multiple-choice selection, call {@link
450android.widget.AbsListView#setChoiceMode setChoiceMode(CHOICE_MODE_MULTIPLE_MODAL)} and register a
451{@link android.widget.AbsListView.MultiChoiceModeListener MultiChoiceModeListener} with {@link
452android.widget.AbsListView#setMultiChoiceModeListener setMultiChoiceModeListener()}.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800453
Scott Maind41ff8e2011-01-21 14:51:33 -0800454<p>When the user performs a long-press on an item, the Action Bar switches to the Multi-choice
455Action Mode. The system notifies the {@link android.widget.AbsListView.MultiChoiceModeListener
456MultiChoiceModeListener} when items are selected by calling {@link
457android.widget.AbsListView.MultiChoiceModeListener#onItemCheckedStateChanged
458onItemCheckedStateChanged()}.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800459
Scott Maind41ff8e2011-01-21 14:51:33 -0800460<p>For an example of multiple-choice selection, see the <a
461href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/List15.html">List15.
462java</a>
463class in the API Demos sample application.</p>
464 </li>
Scott Main7fb538c2011-01-19 21:11:50 -0800465
Scott Maind41ff8e2011-01-21 14:51:33 -0800466
467 <li><b>New APIs to transform views</b>
468
Scott Mainea723292011-02-09 16:01:04 -0800469 <p>New APIs allow you to easily apply 2D and 3D transformations to views in your activity
470layout. New transformations are made possible with a set of object properties that define the view's
Scott Maind41ff8e2011-01-21 14:51:33 -0800471layout position, orientation, transparency and more.</p>
Scott Mainea723292011-02-09 16:01:04 -0800472 <p>New methods to set the view properties include: {@link android.view.View#setAlpha
473setAlpha()}, {@link
Scott Maind41ff8e2011-01-21 14:51:33 -0800474android.view.View#setBottom setBottom()}, {@link android.view.View#setLeft setLeft()}, {@link
475android.view.View#setRight setRight()}, {@link android.view.View#setBottom setBottom()}, {@link
476android.view.View#setPivotX setPivotX()}, {@link android.view.View#setPivotY setPivotY()}, {@link
477android.view.View#setRotationX setRotationX()}, {@link android.view.View#setRotationY
478setRotationY()}, {@link android.view.View#setScaleX setScaleX()}, {@link android.view.View#setScaleY
479setScaleY()}, {@link android.view.View#setAlpha setAlpha()}, and others.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800480
Scott Maind41ff8e2011-01-21 14:51:33 -0800481 <p>Some methods also have a corresponding XML attribute that you can specify in your layout
Scott Mainea723292011-02-09 16:01:04 -0800482file, to apply a default transformation. Available attributes include: {@code translationX}, {@code
483translationY}, {@code rotation},
Scott Maind41ff8e2011-01-21 14:51:33 -0800484{@code rotationX}, {@code rotationY}, {@code scaleX}, {@code scaleY}, {@code transformPivotX},
485{@code transformPivotY}, and {@code alpha}.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800486
Scott Mainea723292011-02-09 16:01:04 -0800487 <p>Using some of these new view properties in combination with the new <a
488href="#animation">animation framework</a> (discussed
489above), you can easily apply some fancy animations to your views. For example, to rotate a
Scott Maind41ff8e2011-01-21 14:51:33 -0800490view on its y-axis, supply {@link android.animation.ObjectAnimator} with the {@link
Scott Mainea723292011-02-09 16:01:04 -0800491android.view.View}, the "rotationY" property, and the start and end values:</p>
Scott Maind41ff8e2011-01-21 14:51:33 -0800492<pre>
493ObjectAnimator animator = ObjectAnimator.ofFloat(myView, "rotationY", 0, 360);
494animator.setDuration(2000);
495animator.start();
496</pre>
497 </li>
Scott Main7fb538c2011-01-19 21:11:50 -0800498
Scott Maind41ff8e2011-01-21 14:51:33 -0800499
500 <li><b>New holographic themes</b>
Scott Main7fb538c2011-01-19 21:11:50 -0800501
Scott Mainea723292011-02-09 16:01:04 -0800502 <p>The standard system widgets and overall look have been redesigned and incorporate a new
503"holographic" user interface theme. The system applies the new theme
504using the standard <a href="{@docRoot}guide/topics/ui/themes.html">style and theme</a> system.</p>
505
506<p>Any application that targets the Android 3.0 platform&mdash;by setting either the <a
507href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a>
508or <a
509href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
510android:targetSdkVersion}</a> value to {@code "11"}&mdash;inherits the holographic theme by default.
511However, if your application also applies its own theme, then your theme will override the
512holographic theme, unless you update your styles to inherit the holographic theme.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800513
514<p>To apply the holographic theme to individual activities or to inherit them in your own theme
Scott Main7afdaf02011-01-25 13:03:30 -0800515definitions, use one of several new {@link android.R.style#Theme_Holo Theme.Holo}
Scott Mainea723292011-02-09 16:01:04 -0800516themes. If your application is compatible with version of Android lower than 3.0 and applies
517custom themes, then you should <a
518href="{@docRoot}guide/topics/ui/themes.html#SelectATheme">select a theme based on platform
519version</a>.</p>
520
Scott Maind41ff8e2011-01-21 14:51:33 -0800521 </li>
522
523
524 <li><b>New widgets</b>
525
526 <ul>
527 <li>{@link android.widget.AdapterViewAnimator}
528 <p>Base class for an {@link android.widget.AdapterView} that performs animations when switching
529 between its views.</p></li>
530
531 <li>{@link android.widget.AdapterViewFlipper}
532 <p>Simple {@link android.widget.ViewAnimator} that animates between two or more views that have
533 been added to it. Only one child is shown at a time. If requested, it can automatically flip
534 between
535 each child at a regular interval.</p></li>
536
537 <li>{@link android.widget.CalendarView}
Scott Mainea723292011-02-09 16:01:04 -0800538 <p>Allows users to select dates from a calendar by touching the date and can scroll or fling the
539calendar to a desired date. You can configure the range of dates available in the widget.</p></li>
Scott Maind41ff8e2011-01-21 14:51:33 -0800540
541 <li>{@link android.widget.ListPopupWindow}
542 <p>Anchors itself to a host view and displays a list of choices, such as for a list of
543 suggestions when typing into an {@link android.widget.EditText} view.</p></li>
544
545 <li>{@link android.widget.NumberPicker}
Scott Mainea723292011-02-09 16:01:04 -0800546 <p>Enables the user to select a number from a predefined range. The widget presents an input
547field and up and down buttons for selecting a number. Touching the input field allows the user to
548scroll through values or touch again to directly edit the current value. It also allows you to map
549positions to strings, so that the corresponding string is displayed instead of the index
550position.</p></li>
Scott Maind41ff8e2011-01-21 14:51:33 -0800551
552 <li>{@link android.widget.PopupMenu}
553 <p>Displays a {@link android.view.Menu} in a modal popup window that's anchored to a view. The
Scott Mainea723292011-02-09 16:01:04 -0800554popup appears below the anchor view if there is room, or above it if there is not. If the IME (soft
555keyboard) is visible, the popup does not overlap the IME it until the user touches the
556menu.</p></li>
Scott Maind41ff8e2011-01-21 14:51:33 -0800557
558 <li>{@link android.widget.SearchView}
Scott Mainea723292011-02-09 16:01:04 -0800559 <p>Provides a search box that works in conjunction with the Search Manager (in the same manner
560as the traditional <a href="{@docRoot}guide/topics/search/search-dialog.html">search dialog</a>). It
561can also display recent query suggestions or custom suggestions as configured by the search
562provider. This widget is particularly useful for offering search in the <a
563href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a>.</p></li>
Scott Maind41ff8e2011-01-21 14:51:33 -0800564
565 <li>{@link android.widget.StackView}
Scott Mainea723292011-02-09 16:01:04 -0800566 <p>A view that displays its children in a 3D stack and allows users to swipe through
567 views like a rolodex.</p></li>
Scott Maind41ff8e2011-01-21 14:51:33 -0800568
569 </ul>
570 </li>
571
572</ul>
Scott Main7fb538c2011-01-19 21:11:50 -0800573
574
575
Scott Main7fb538c2011-01-19 21:11:50 -0800576<h3>Graphics</h3>
577
578<ul>
Scott Maind41ff8e2011-01-21 14:51:33 -0800579 <li><b>Hardware accelerated 2D graphics</b>
Scott Main7fb538c2011-01-19 21:11:50 -0800580
581<p>You can now enable the OpenGL renderer for your application by setting {@code
582android:hardwareAccelerated="true"} in your manifest element's <a
583href="{@docRoot}guide/topics/manifest/application-element.html">{@code &lt;application&gt;}</a>
584element or for individual <a
585href="{@docRoot}guide/topics/manifest/activity-element.html">{@code &lt;activity&gt;}</a>
586elements.</p>
587
588<p>This flag helps applications by making them draw faster. This results in smoother animations,
589smoother scrolling, and overall better performance and response to user interaction.</p></li>
590
Scott Maind41ff8e2011-01-21 14:51:33 -0800591
592 <li><b>View support for hardware and software layers</b>
593
594 <p>By default, a {@link android.view.View} has no layer specified. You can specify that the
595view be backed by either a hardware or software layer, specified by values {@link
596android.view.View#LAYER_TYPE_HARDWARE} and {@link android.view.View#LAYER_TYPE_SOFTWARE}, using
597{@link android.view.View#setLayerType setLayerType()} or the <a
598href="{@docRoot}reference/android/view/View.html#attr_android:layerType">{@code layerType}</a>
599attribute.</p>
600 <p>A hardware layer is backed by a hardware specific texture (generally Frame Buffer Objects or
601FBO on OpenGL hardware) and causes the view to be rendered using Android's hardware rendering
602pipeline, but only if hardware acceleration is turned on for the view hierarchy. When hardware
603acceleration is turned off, hardware layers behave exactly as software layers.</p>
604 <p>A software layer is backed by a bitmap and causes the view to be rendered using Android's
605software rendering pipeline, even if hardware acceleration is enabled. Software layers should be
606avoided when the affected view tree updates often. Every update will require to re-render the
607software layer, which can potentially be slow.</p>
608 <p>For more information, see the {@link android.view.View#LAYER_TYPE_HARDWARE} and {@link
609android.view.View#LAYER_TYPE_SOFTWARE} documentation.</p>
610 </li>
611
612
613 <li><b>Renderscript 3D graphics engine</b>
Scott Main7fb538c2011-01-19 21:11:50 -0800614
615<p>Renderscript is a runtime 3D framework that provides both an API for building 3D scenes as well
616as a special, platform-independent shader language for maximum performance. Using Renderscript, you
617can accelerate graphics operations and data processing. Renderscript is an ideal way to create
Scott Main64b12ea2011-02-14 13:41:03 -0800618high-performance 3D effects for applications, wallpapers, carousels, and more.</p>
619<p>For more information, see the <a
620href="{@docRoot}guide/topics/graphics/renderscript.html">3D Rendering and Computation with
621Renderscript</a> documentation.</p></li>
Scott Main7fb538c2011-01-19 21:11:50 -0800622</ul>
623
624
625
626
Scott Main7fb538c2011-01-19 21:11:50 -0800627<h3>Media</h3>
628
629
630<ul>
Scott Main7fb538c2011-01-19 21:11:50 -0800631
Scott Main7afdaf02011-01-25 13:03:30 -0800632 <li><b>Time lapse video</b>
Scott Main7fb538c2011-01-19 21:11:50 -0800633
634<p>Camcorder APIs now support the ability to record time lapse video. The {@link
635android.media.MediaRecorder#setCaptureRate setCaptureRate()} sets the rate at which frames
636should be captured.</p></li>
637
Scott Main7afdaf02011-01-25 13:03:30 -0800638 <li><b>Texture support for image streams</b>
639
640<p>New {@link android.graphics.SurfaceTexture} allows you to capture an image stream as an OpenGL ES
641texture. By calling {@link android.hardware.Camera#setPreviewTexture setPreviewTexture()} for your
642{@link android.hardware.Camera} instance, you can specify the {@link
643android.graphics.SurfaceTexture} upon which to draw video playback or preview frames from the
644camera.</p></li>
645
646 <li><b>HTTP Live streaming</b>
647
648<p>Applications can now pass an M3U playlist URL to the media framework to begin an HTTP Live
649streaming session. The media framework supports most of the HTTP Live streaming specification,
Scott Mainea723292011-02-09 16:01:04 -0800650including adaptive bit rate. See the <a
651href="{@docRoot}guide/appendix/media-formats.html">Supported Media Formats</a> document for
652more information.</p></li>
Scott Main7afdaf02011-01-25 13:03:30 -0800653
654 <li><b>EXIF data</b>
655
656<p>The {@link android.media.ExifInterface} includes new fields for photo aperture, ISO, and exposure
657time.</p></li>
658
659 <li><b>Camcorder profiles</b>
660
661<p>New {@link android.media.CamcorderProfile#hasProfile hasProfile()} method and several video
662quality profiles (such as {@link android.media.CamcorderProfile#QUALITY_1080P}, {@link
663android.media.CamcorderProfile#QUALITY_720P}, {@link
664android.media.CamcorderProfile#QUALITY_CIF}, and others) allow you to determine camcorder
665quality options.</p></li>
666
Scott Maind41ff8e2011-01-21 14:51:33 -0800667 <li><b>Digital media file transfer</b>
Scott Main7fb538c2011-01-19 21:11:50 -0800668
669<p>The platform includes built-in support for Media/Picture Transfer Protocol (MTP/PTP) over USB,
670which lets users easily transfer any type of media files between devices and to a host computer.
671Developers can build on this support, creating applications that let users create or manage rich
672media files that they may want to transfer or share across devices. </p></li>
673
Scott Maind41ff8e2011-01-21 14:51:33 -0800674 <li><b>Digital rights management (DRM)</b>
Scott Main7fb538c2011-01-19 21:11:50 -0800675
676<p>New extensible digital rights management (DRM) framework for checking and enforcing digital
677rights. It's implemented in two architectural layers:</p>
678<ul>
679 <li>A DRM framework API, which is exposed to applications and runs through the Dalvik VM for
680standard applications.</li>
681 <li>A native code DRM manager that implements the framework API and exposes an interface for DRM
682plug-ins to handle rights management and decryption for various DRM schemes.</li>
683</ul>
684
685<p>For application developers, the framework offers an abstract, unified API that simplifies the
686management of protected content. The API hides the complexity of DRM operations and allows a
687consistent operation mode for both protected and unprotected content, and across a variety of DRM
688schemes.</p>
689
690<p>For device manufacturers, content owners, and Internet digital media providers the DRM
691framework?s plugin API provides a means of adding support for a DRM scheme of choice into the
692Android system, for secure enforcement of content protection.</p>
693
694<p>The preview release does not provide any native DRM plug-ins for checking and enforcing digital
695rights. However, device manufacturers may ship DRM plug-ins with their devices.</p>
696
697<p>You can find all of the DRM APIs in the {@link android.drm} package.</p></li>
698
699</ul>
700
701
702
Scott Mainea723292011-02-09 16:01:04 -0800703<h3>Keyboard support</h3>
704
705<ul>
706<li>Support for Control, Meta, Caps Lock, Num Lock and Scroll Lock modifiers. For more information,
707see {@link android.view.KeyEvent#META_CTRL_ON} and related fields.</li>
708
709<li>Support for full desktop-style keyboards, including support for keys such as Escape, Home, End,
710Delete and others. You can determine whether key events are coming from a full keyboard by
711querying {@link android.view.KeyCharacterMap#getKeyboardType()} and checking for {@link
712android.view.KeyCharacterMap#FULL KeyCharacterMap.FULL}</li>
713
714<li>{@link android.widget.TextView} now supports keyboard-based cut, copy, paste, and select-all,
715using the key combinations Ctrl+X, Ctrl+C, Ctrl+V, and Ctrl+A. It also supports PageUp/PageDown,
716Home/End, and keyboard-based text selection.</li>
717
718<li>{@link android.view.KeyEvent} adds several new methods to make it easier to check the key
719modifier state correctly and consistently. See {@link android.view.KeyEvent#hasModifiers(int)},
720{@link android.view.KeyEvent#hasNoModifiers()},
721{@link android.view.KeyEvent#metaStateHasModifiers(int,int) metaStateHasModifiers()},
722{@link android.view.KeyEvent#metaStateHasNoModifiers(int) metaStateHasNoModifiers()}.</li>
723
724<li>Applications can implement custom keyboard shortcuts by subclassing {@link
725android.app.Activity}, {@link android.app.Dialog}, or {@link android.view.View} and implementing
726{@link android.app.Activity#onKeyShortcut onKeyShortcut()}. The framework calls this method
727whenever a key is combined with Ctrl key. When creating an <a
728href="{@docRoot}guide/topics/ui/menus.html#options-menu">Options Menu</a>, you can register keyboard
729shortcuts by setting either the {@code android:alphabeticShortcut} or {@code
730android:numericShortcut} attribute for each <a
731href="{@docRoot}guide/topics/resources/menu-resource.html#item-element">{@code &lt;item&gt;}</a>
732element (or with {@link android.view.MenuItem#setShortcut setShortcut()}).</li>
733
734<li>Android 3.0 includes a new "virtual keyboard" device with the id {@link
735android.view.KeyCharacterMap#VIRTUAL_KEYBOARD KeyCharacterMap.VIRTUAL_KEYBOARD}. The virtual
736keyboard has a desktop-style US key map which is useful for synthesizing key events for testing
737input.</li>
738
739</ul>
740
741
742
743
744<h3>Split touch events</h3>
745
746<p>Previously, only a single view could accept touch events at one time. Android 3.0
747adds support for splitting touch events across views and even windows, so different views can accept
748simultaneous touch events.</p>
749
750<p>Split touch events is enabled by default when an application targets
751Android 3.0. That is, when the application has set either the <a
752href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a>
753or <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
754android:targetSdkVersion}</a> attribute's value to {@code "11"}.</p>
755
Scott Mainc2299de2011-02-14 11:37:50 -0800756<p>However, the following properties allow you to disable split touch events across views inside
757specific view groups and across windows.</p>
Scott Mainea723292011-02-09 16:01:04 -0800758
759<ul>
760<li>The {@link android.R.attr#splitMotionEvents android:splitMotionEvents} attribute for view groups
Scott Mainc2299de2011-02-14 11:37:50 -0800761allows you to disable split touch events that occur between child views in a layout. For example:
Scott Mainea723292011-02-09 16:01:04 -0800762<pre>
763&lt;LinearLayout android:splitMotionEvents="false" ... >
764 ...
765&lt;/LinearLayout>
766</pre>
Scott Mainc2299de2011-02-14 11:37:50 -0800767<p>This way, child views in the linear layout cannot split touch events&mdash;only one view can
768receive touch events at a time.</p>
Scott Mainea723292011-02-09 16:01:04 -0800769</li>
770
771<li>The {@link android.R.attr#windowEnableSplitTouch android:windowEnableSplitTouch} style property
Scott Mainc2299de2011-02-14 11:37:50 -0800772allows you to disable split touch events across windows, by applying it to a theme for the activity
Scott Mainea723292011-02-09 16:01:04 -0800773or entire application. For example:
774<pre>
775&lt;style name="NoSplitMotionEvents" parent="android:Theme.Holo">
776 &lt;item name="android:windowEnableSplitTouch">false&lt;/item>
777 ...
778&lt;/style>
779</pre>
780<p>When this theme is applied to an <a
781href="{@docRoot}guide/topics/manifest/activity-element.html">{@code &lt;activity&gt;}</a> or <a
782href="{@docRoot}guide/topics/manifest/application-element.html">{@code &lt;application&gt;}</a>,
783only touch events within the current activity window are accepted. For example, by disabling split
784touch events across windows, the system bar cannot receive touch events at the same time as the
Scott Mainc2299de2011-02-14 11:37:50 -0800785activity. This does <em>not</em> affect whether views inside the activity can split touch
786events&mdash;by default, the activity can still split touch events across views.</p>
Scott Mainea723292011-02-09 16:01:04 -0800787
788<p>For more information about creating a theme, read <a
789href="{@docRoot}guide/topics/ui/themes.html">Applying Styles and Themes</a>.</p>
790</li>
791</ul>
792
793
794
795<h3>WebKit</h3>
796
797<ul>
798 <li>New {@link android.webkit.WebViewFragment} class to create a fragment composed of a
799{@link android.webkit.WebView}.</li>
800 <li>New {@link android.webkit.WebSettings} methods:
801 <ul>
802 <li>{@link
803android.webkit.WebSettings#setDisplayZoomControls setDisplayZoomControls()} allows you to hide
804the on-screen zoom controls while still allowing the user to zoom with finger gestures ({@link
805android.webkit.WebSettings#setBuiltInZoomControls setBuiltInZoomControls()} must be set
806{@code true}).</li>
807 <li>New {@link android.webkit.WebSettings} method, {@link
808android.webkit.WebSettings#setEnableSmoothTransition setEnableSmoothTransition()}, allows you
809to enable smooth transitions when panning and zooming. When enabled, WebView will choose a solution
810to maximize the performance (for example, the WebView's content may not update during the
811transition).</li>
812 </ul>
813 <li>New {@link android.webkit.WebView} methods:
814 <ul>
815 <li>{@link android.webkit.WebView#onPause onPause()} callback, to pause any processing
816associated with the WebView when it becomes hidden. This is useful to reduce unnecessary CPU or
817network traffic when the WebView is not in the foreground.</li>
818 <li>{@link android.webkit.WebView#onResume onResume()} callback, to resume processing
819associated with the WebView, which was paused during {@link android.webkit.WebView#onPause
820onPause()}.</li>
821 <li>{@link android.webkit.WebView#saveWebArchive saveWebArchive()} allows you to save the
822current view as a web archive on the device.</li>
823 <li>{@link android.webkit.WebView#showFindDialog showFindDialog()} initiates a text search in
824the current view.</li>
825 </ul>
826 </li>
827</ul>
828
829
830
831<h3>Browser</h3>
832
833<p>The Browser application adds the following features to support web applications:</p>
834
835<ul>
836 <li><b>Media capture</b>
837 <p>As defined by the <a href="http://dev.w3.org/2009/dap/camera/">HTML Media Capture</a>
838specification, the Browser allows web applications to access audio, image and video capture
839capabilities of the device. For example, the following HTML provides an input for the user to
840capture a photo to upload:</p>
841<pre>
842&lt;input type="file" accept="image/*;capture=camera" />
843</pre>
844<p>Or by excluding the {@code capture=camera} parameter, the user can choose to either capture a
845new image with the camera or select one from the device (such as from the Gallery application).</p>
846 </li>
847
848 <li><b>Device Orientation</b>
849 <p>As defined by the <a
850href="http://dev.w3.org/geo/api/spec-source-orientation.html">Device Orientation Event</a>
851specification, the Browser allows web applications to listen to DOM events that provide information
852about the physical orientation and motion of the device.</p>
853 <p>The device orientation is expressed with the x, y, and z axes, in degrees and motion is
854expressed with acceleration and rotation rate data. A web page can register for orientation
855events by calling {@code window.addEventListener} with event type {@code "deviceorientation"}
856and register for motion events by registering the {@code "devicemotion"} event type.</p>
857 </li>
858
859 <li><b>CSS 3D Transforms</b>
860 <p>As defined by the <a href="http://www.w3.org/TR/css3-3d-transforms/">CSS 3D Transform
861Module</a> specification, the Browser allows elements rendered by CSS to be transformed in three
862dimensions.</p>
863 </li>
864</ul>
865
866
867
868<h3>JSON utilities</h3>
869
870<p>New classes, {@link android.util.JsonReader} and {@link android.util.JsonWriter}, help you
871read and write JSON streams. The new APIs compliment the {@link org.json} classes which manipulate a
872document in memory.</p>
873
874<p>You can create an instance of {@link android.util.JsonReader} by calling
875its constructor method and passing the {@link java.io.InputStreamReader} that feeds the JSON string.
876Then begin reading an object by calling {@link android.util.JsonReader#beginObject()}, read a
877key name with {@link android.util.JsonReader#nextName()}, read the value using methods
878respective to the type, such as {@link android.util.JsonReader#nextString()} and {@link
879android.util.JsonReader#nextInt()}, and continue doing so while {@link
880android.util.JsonReader#hasNext()} is true.</p>
881
882<p>You can create an instance of {@link android.util.JsonWriter} by calling its constructor and
883passing the appropriate {@link java.io.OutputStreamWriter}. Then write the JSON data in a manner
884similar to the reader, using {@link android.util.JsonWriter#name name()} to add a property name
885and an appropriate {@link android.util.JsonWriter#value value()} method to add the respective
886value.</p>
887
888<p>These classes are strict by default. The {@link android.util.JsonReader#setLenient setLenient()}
889method in each class configures them to be more liberal in what they accept. This lenient
890parse mode is also compatible with the {@link org.json}'s default parser.</p>
891
892
893
894
895<h3>New feature constants</h3>
896
897<p>The <a
898href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code &lt;uses-feature&gt;}</a>
899manfest element should be used to inform external entities (such as Android Market) of the set of
900hardware and software features on which your application depends. In this release, Android adds the
901following new constants that applications can declare with this element:</p>
902
903<ul>
904 <li>{@link android.content.pm.PackageManager#FEATURE_FAKETOUCH "android.hardware.faketouch"}
905 <p>When declared, this indicates that the application is compatible with a device that offers an
906emulated touchscreen (or better). A device that offers an emulated touchscreen provides a user input
907system that can emulate a subset of touchscreen
908capabilities. An example of such an input system is a mouse or remote control that drives an
909on-screen cursor. Such input systems support basic touch events like click down, click up, and drag.
910However, more complicated input types (such as gestures, flings, etc.) may be more difficult or
911impossible on faketouch devices (and multitouch gestures are definitely not possible).</p>
912 <p>If your application does <em>not</em> require complicated gestures and you do
913<em>not</em> want your application filtered from devices with an emulated touchscreen, you
914should declare {@link
915android.content.pm.PackageManager#FEATURE_FAKETOUCH "android.hardware.faketouch"} with a <a
916href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code &lt;uses-feature&gt;}</a>
917element. This way, your application will be available to the greatest number of device types,
918including those that provide only an emulated touchscreen input.</p>
919 <p>All devices that include a touchscreen also support {@link
920android.content.pm.PackageManager#FEATURE_FAKETOUCH "android.hardware.faketouch"}, because
921touchscreen capabilities are a superset of faketouch capabilities. Thus, unless you actually require
922a touchscreen, you should add a <a
923href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code &lt;uses-feature&gt;}</a>
924element for faketouch.</p>
925 </li>
926</ul>
927
928
929
930
931<h3>New permissions</h3>
932
933<ul>
934 <li>{@link android.Manifest.permission#BIND_REMOTEVIEWS
935"android.permission.BIND_REMOTEVIEWS"}
936 <p>This must be declared as a required permission in the <a
937href="{@docRoot}guide/topics/manifest/service-element.html">{@code &lt;service&gt;}</a> manifest
938element for an implementation of {@link android.widget.RemoteViewsService}. For example, when
939creating an App Widget that uses {@link android.widget.RemoteViewsService} to populate a
940collection view, the manifest entry may look like this:</p>
941<pre>
942&lt;service android:name=".widget.WidgetService"
943 android:exported="false"
944 android:permission="android.permission.BIND_REMOTEVIEWS" />
945</pre>
946</ul>
947
948
949
950<h3>New platform technologies</h3>
951
952<ul>
953<li><strong>Storage</strong>
954 <ul>
955 <li>ext4 file system support to enable onboard eMMC storage.</li>
956 <li>FUSE file system to support MTP devices.</li>
957 <li>USB host mode support to support keyboards and USB hubs.</li>
958 <li>Support for MTP/PTP </li>
959 </ul>
960</li>
961
962<li><strong>Linux Kernel</strong>
963 <ul>
964 <li>Upgraded to 2.6.36</li>
965 </ul>
966</li>
967
968<li><strong>Dalvik VM</strong>
969 <ul>
970 <li>New code to support and optimize for SMP</li>
971 <li>Various improvements to the JIT infrastructure</li>
972 <li>Garbage collector improvements:
973 <ul>
974 <li>Tuned for SMP</li>
975 <li>Support for larger heap sizes</li>
976 <li>Unified handling for bitmaps and byte buffers</li>
977 </ul>
978 </li>
979 </ul>
980</li>
981
982<li><strong>Dalvik Core Libraries</strong>
983 <ul>
984 <li>New, much faster implementation of NIO (modern I/O library)</li>
985 <li>Improved exception messages</li>
986 <li>Correctness and performance fixes throughout</li>
987 </ul>
988</li>
989</ul>
990
991
992
993<h3 id="api-diff">API differences report</h3>
994
995<p>For a detailed view of all API changes in Android {@sdkPlatformVersion} (API Level
996{@sdkPlatformApiLevel}), see the <a
997href="{@docRoot}sdk/api_diff/{@sdkPlatformApiLevel}/changes.html">API Differences Report</a>.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800998
999
1000
1001
1002
1003<h2 id="api-level">API Level</h2>
1004
Scott Mainea723292011-02-09 16:01:04 -08001005<p>The Android {@sdkPlatformVersion} platform delivers an updated version of
1006the framework API. The Android {@sdkPlatformVersion} API
1007is assigned an integer identifier &mdash;
1008<strong>{@sdkPlatformApiLevel}</strong> &mdash; that is
1009stored in the system itself. This identifier, called the "API Level", allows the
1010system to correctly determine whether an application is compatible with
1011the system, prior to installing the application. </p>
Scott Main7fb538c2011-01-19 21:11:50 -08001012
Scott Mainea723292011-02-09 16:01:04 -08001013<p>To use APIs introduced in Android {@sdkPlatformVersion} in your application,
1014you need compile the application against the Android library that is provided in
1015the Android {@sdkPlatformVersion} SDK platform. Depending on your needs, you might
1016also need to add an <code>android:minSdkVersion="{@sdkPlatformApiLevel}"</code>
1017attribute to the <code>&lt;uses-sdk&gt;</code> element in the application's
1018manifest. If your application is designed to run only on Android 2.3 and higher,
1019declaring the attribute prevents the application from being installed on earlier
1020versions of the platform.</p>
Scott Main7fb538c2011-01-19 21:11:50 -08001021
Scott Mainea723292011-02-09 16:01:04 -08001022<p>For more information about how to use API Level, see the <a
1023href="{@docRoot}guide/appendix/api-levels.html">API Levels</a> document. </p>
Scott Main7fb538c2011-01-19 21:11:50 -08001024
1025
1026<h2 id="apps">Built-in Applications</h2>
1027
1028<p>The system image included in the downloadable platform provides these
1029built-in applications:</p>
1030
1031<table style="border:0;padding-bottom:0;margin-bottom:0;">
1032<tr>
1033<td style="border:0;padding-bottom:0;margin-bottom:0;">
1034<ul>
Scott Mainea723292011-02-09 16:01:04 -08001035<li>API Demos</li>
Scott Main7fb538c2011-01-19 21:11:50 -08001036<li>Browser</li>
1037<li>Calculator</li>
1038<li>Camera</li>
1039<li>Clock</li>
1040<li>Contacts</li>
1041<li>Custom Locale</li>
1042<li>Dev Tools</li>
1043<li>Downloads</li>
1044<li>Email</li>
1045</ul>
1046</td>
1047<td style="border:0;padding-bottom:0;margin-bottom:0;padding-left:5em;">
1048<ul>
1049<li>Gallery</li>
Scott Mainea723292011-02-09 16:01:04 -08001050<li>Gestures Builder</li>
1051<li>Messaging</li>
Scott Main7fb538c2011-01-19 21:11:50 -08001052<li>Music</li>
1053<li>Search</li>
1054<li>Settings</li>
Scott Mainea723292011-02-09 16:01:04 -08001055<li>Spare Parts</li>
Scott Main7fb538c2011-01-19 21:11:50 -08001056<li>Speech Recorder</li>
Scott Mainea723292011-02-09 16:01:04 -08001057<li>Widget Preview</li>
Scott Main7fb538c2011-01-19 21:11:50 -08001058</ul>
1059</td>
1060</tr>
1061</table>
1062
1063
1064<h2 id="locs" style="margin-top:.75em;">Locales</h2>
1065
1066<p>The system image included in the downloadable SDK platform provides a variety of
1067built-in locales. In some cases, region-specific strings are available for the
1068locales. In other cases, a default version of the language is used. The
1069languages that are available in the Android 3.0 system
1070image are listed below (with <em>language</em>_<em>country/region</em> locale
1071descriptor).</p>
1072
1073<table style="border:0;padding-bottom:0;margin-bottom:0;">
1074<tr>
1075<td style="border:0;padding-bottom:0;margin-bottom:0;">
1076<ul>
1077<li>Arabic, Egypt (ar_EG)</li>
1078<li>Arabic, Israel (ar_IL)</li>
1079<li>Bulgarian, Bulgaria (bg_BG)</li>
1080<li>Catalan, Spain (ca_ES)</li>
1081<li>Czech, Czech Republic (cs_CZ)</li>
1082<li>Danish, Denmark(da_DK)</li>
1083<li>German, Austria (de_AT)</li>
1084<li>German, Switzerland (de_CH)</li>
1085<li>German, Germany (de_DE)</li>
1086<li>German, Liechtenstein (de_LI)</li>
1087<li>Greek, Greece (el_GR)</li>
1088<li>English, Australia (en_AU)</li>
1089<li>English, Canada (en_CA)</li>
1090<li>English, Britain (en_GB)</li>
1091<li>English, Ireland (en_IE)</li>
1092<li>English, India (en_IN)</li>
1093<li>English, New Zealand (en_NZ)</li>
1094<li>English, Singapore(en_SG)</li>
1095<li>English, US (en_US)</li>
1096<li>English, Zimbabwe (en_ZA)</li>
1097<li>Spanish (es_ES)</li>
1098<li>Spanish, US (es_US)</li>
1099<li>Finnish, Finland (fi_FI)</li>
1100<li>French, Belgium (fr_BE)</li>
1101<li>French, Canada (fr_CA)</li>
1102<li>French, Switzerland (fr_CH)</li>
1103<li>French, France (fr_FR)</li>
1104<li>Hebrew, Israel (he_IL)</li>
1105<li>Hindi, India (hi_IN)</li>
1106</ul>
1107</td>
1108<td style="border:0;padding-bottom:0;margin-bottom:0;padding-left:5em;">
1109<li>Croatian, Croatia (hr_HR)</li>
1110<li>Hungarian, Hungary (hu_HU)</li>
1111<li>Indonesian, Indonesia (id_ID)</li>
1112<li>Italian, Switzerland (it_CH)</li>
1113<li>Italian, Italy (it_IT)</li>
1114<li>Japanese (ja_JP)</li>
1115<li>Korean (ko_KR)</li>
1116<li>Lithuanian, Lithuania (lt_LT)</li>
1117<li>Latvian, Latvia (lv_LV)</li>
1118<li>Norwegian bokmål, Norway (nb_NO)</li>
1119<li>Dutch, Belgium (nl_BE)</li>
1120<li>Dutch, Netherlands (nl_NL)</li>
1121<li>Polish (pl_PL)</li>
1122<li>Portuguese, Brazil (pt_BR)</li>
1123<li>Portuguese, Portugal (pt_PT)</li>
1124<li>Romanian, Romania (ro_RO)</li>
1125<li>Russian (ru_RU)</li></li>
1126<li>Slovak, Slovakia (sk_SK)</li>
1127<li>Slovenian, Slovenia (sl_SI)</li>
1128<li>Serbian (sr_RS)</li>
1129<li>Swedish, Sweden (sv_SE)</li>
1130<li>Thai, Thailand (th_TH)</li>
1131<li>Tagalog, Philippines (tl_PH)</li>
1132<li>Turkish, Turkey (tr_TR)</li>
1133<li>Ukrainian, Ukraine (uk_UA)</li>
1134<li>Vietnamese, Vietnam (vi_VN)</li>
1135<li>Chinese, PRC (zh_CN)</li>
1136<li>Chinese, Taiwan (zh_TW)</li>
1137</td>
1138</tr>
1139</table>
1140
1141<p class="note"><strong>Note:</strong> The Android platform may support more
1142locales than are included in the SDK system image. All of the supported locales
1143are available in the <a href="http://source.android.com/">Android Open Source
1144Project</a>.</p>
1145
1146<h2 id="skins">Emulator Skins</h2>
1147
1148<p>The downloadable platform includes the following emulator skin:</p>
1149
1150<ul>
1151 <li>
1152 WXGA (1280x800, medium density, xlarge screen)
1153 </li>
1154</ul>
1155
1156<p>For more information about how to develop an application that displays
1157and functions properly on all Android-powered devices, see <a
1158href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple
1159Screens</a>.</p>