blob: d73bd6309c6f796ef56a0f40929c000f4c05b5d4 [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
Scott Main48c187f2011-04-21 17:22:54 -0700314android.appwidget.AppWidgetProviderInfo#previewImage} field), the Android emulator includes an
Scott Mainea723292011-02-09 16:01:04 -0800315application 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 Mainabdf0d52011-02-08 10:20:27 -0800559 <p>Provides a search box that you can configure to deliver search queries to a specified
560activity and display search suggestions (in the same manner as the traditional search dialog). This
561widget is particularly useful for offering a search widget in the Action Bar. For more information,
Dirk Doughertyb7c7f152011-03-25 11:54:46 -0700562see <a href="{@docRoot}guide/topics/search/search-dialog.html">Creating a Search Interface.</p></li>
Scott Maind41ff8e2011-01-21 14:51:33 -0800563
564 <li>{@link android.widget.StackView}
Scott Mainea723292011-02-09 16:01:04 -0800565 <p>A view that displays its children in a 3D stack and allows users to swipe through
566 views like a rolodex.</p></li>
Scott Maind41ff8e2011-01-21 14:51:33 -0800567
568 </ul>
569 </li>
570
571</ul>
Scott Main7fb538c2011-01-19 21:11:50 -0800572
573
574
Scott Main7fb538c2011-01-19 21:11:50 -0800575<h3>Graphics</h3>
576
577<ul>
Scott Maind41ff8e2011-01-21 14:51:33 -0800578 <li><b>Hardware accelerated 2D graphics</b>
Scott Main7fb538c2011-01-19 21:11:50 -0800579
580<p>You can now enable the OpenGL renderer for your application by setting {@code
581android:hardwareAccelerated="true"} in your manifest element's <a
582href="{@docRoot}guide/topics/manifest/application-element.html">{@code &lt;application&gt;}</a>
583element or for individual <a
584href="{@docRoot}guide/topics/manifest/activity-element.html">{@code &lt;activity&gt;}</a>
585elements.</p>
586
587<p>This flag helps applications by making them draw faster. This results in smoother animations,
588smoother scrolling, and overall better performance and response to user interaction.</p></li>
589
Scott Maind41ff8e2011-01-21 14:51:33 -0800590
591 <li><b>View support for hardware and software layers</b>
592
593 <p>By default, a {@link android.view.View} has no layer specified. You can specify that the
594view be backed by either a hardware or software layer, specified by values {@link
595android.view.View#LAYER_TYPE_HARDWARE} and {@link android.view.View#LAYER_TYPE_SOFTWARE}, using
596{@link android.view.View#setLayerType setLayerType()} or the <a
597href="{@docRoot}reference/android/view/View.html#attr_android:layerType">{@code layerType}</a>
598attribute.</p>
599 <p>A hardware layer is backed by a hardware specific texture (generally Frame Buffer Objects or
600FBO on OpenGL hardware) and causes the view to be rendered using Android's hardware rendering
601pipeline, but only if hardware acceleration is turned on for the view hierarchy. When hardware
602acceleration is turned off, hardware layers behave exactly as software layers.</p>
603 <p>A software layer is backed by a bitmap and causes the view to be rendered using Android's
604software rendering pipeline, even if hardware acceleration is enabled. Software layers should be
605avoided when the affected view tree updates often. Every update will require to re-render the
606software layer, which can potentially be slow.</p>
607 <p>For more information, see the {@link android.view.View#LAYER_TYPE_HARDWARE} and {@link
608android.view.View#LAYER_TYPE_SOFTWARE} documentation.</p>
609 </li>
610
611
612 <li><b>Renderscript 3D graphics engine</b>
Scott Main7fb538c2011-01-19 21:11:50 -0800613
614<p>Renderscript is a runtime 3D framework that provides both an API for building 3D scenes as well
615as a special, platform-independent shader language for maximum performance. Using Renderscript, you
616can accelerate graphics operations and data processing. Renderscript is an ideal way to create
Scott Main64b12ea2011-02-14 13:41:03 -0800617high-performance 3D effects for applications, wallpapers, carousels, and more.</p>
618<p>For more information, see the <a
619href="{@docRoot}guide/topics/graphics/renderscript.html">3D Rendering and Computation with
620Renderscript</a> documentation.</p></li>
Scott Main7fb538c2011-01-19 21:11:50 -0800621</ul>
622
623
624
625
Scott Main7fb538c2011-01-19 21:11:50 -0800626<h3>Media</h3>
627
628
629<ul>
Scott Main7fb538c2011-01-19 21:11:50 -0800630
Scott Main7afdaf02011-01-25 13:03:30 -0800631 <li><b>Time lapse video</b>
Scott Main7fb538c2011-01-19 21:11:50 -0800632
633<p>Camcorder APIs now support the ability to record time lapse video. The {@link
634android.media.MediaRecorder#setCaptureRate setCaptureRate()} sets the rate at which frames
635should be captured.</p></li>
636
Scott Main7afdaf02011-01-25 13:03:30 -0800637 <li><b>Texture support for image streams</b>
638
639<p>New {@link android.graphics.SurfaceTexture} allows you to capture an image stream as an OpenGL ES
640texture. By calling {@link android.hardware.Camera#setPreviewTexture setPreviewTexture()} for your
641{@link android.hardware.Camera} instance, you can specify the {@link
642android.graphics.SurfaceTexture} upon which to draw video playback or preview frames from the
643camera.</p></li>
644
645 <li><b>HTTP Live streaming</b>
646
647<p>Applications can now pass an M3U playlist URL to the media framework to begin an HTTP Live
648streaming session. The media framework supports most of the HTTP Live streaming specification,
Scott Mainea723292011-02-09 16:01:04 -0800649including adaptive bit rate. See the <a
650href="{@docRoot}guide/appendix/media-formats.html">Supported Media Formats</a> document for
651more information.</p></li>
Scott Main7afdaf02011-01-25 13:03:30 -0800652
653 <li><b>EXIF data</b>
654
655<p>The {@link android.media.ExifInterface} includes new fields for photo aperture, ISO, and exposure
656time.</p></li>
657
658 <li><b>Camcorder profiles</b>
659
660<p>New {@link android.media.CamcorderProfile#hasProfile hasProfile()} method and several video
661quality profiles (such as {@link android.media.CamcorderProfile#QUALITY_1080P}, {@link
662android.media.CamcorderProfile#QUALITY_720P}, {@link
663android.media.CamcorderProfile#QUALITY_CIF}, and others) allow you to determine camcorder
664quality options.</p></li>
665
Scott Maind41ff8e2011-01-21 14:51:33 -0800666 <li><b>Digital media file transfer</b>
Scott Main7fb538c2011-01-19 21:11:50 -0800667
668<p>The platform includes built-in support for Media/Picture Transfer Protocol (MTP/PTP) over USB,
669which lets users easily transfer any type of media files between devices and to a host computer.
670Developers can build on this support, creating applications that let users create or manage rich
671media files that they may want to transfer or share across devices. </p></li>
672
Scott Maind41ff8e2011-01-21 14:51:33 -0800673 <li><b>Digital rights management (DRM)</b>
Scott Main7fb538c2011-01-19 21:11:50 -0800674
675<p>New extensible digital rights management (DRM) framework for checking and enforcing digital
676rights. It's implemented in two architectural layers:</p>
677<ul>
678 <li>A DRM framework API, which is exposed to applications and runs through the Dalvik VM for
679standard applications.</li>
680 <li>A native code DRM manager that implements the framework API and exposes an interface for DRM
681plug-ins to handle rights management and decryption for various DRM schemes.</li>
682</ul>
683
684<p>For application developers, the framework offers an abstract, unified API that simplifies the
685management of protected content. The API hides the complexity of DRM operations and allows a
686consistent operation mode for both protected and unprotected content, and across a variety of DRM
687schemes.</p>
688
689<p>For device manufacturers, content owners, and Internet digital media providers the DRM
690framework?s plugin API provides a means of adding support for a DRM scheme of choice into the
691Android system, for secure enforcement of content protection.</p>
692
693<p>The preview release does not provide any native DRM plug-ins for checking and enforcing digital
694rights. However, device manufacturers may ship DRM plug-ins with their devices.</p>
695
696<p>You can find all of the DRM APIs in the {@link android.drm} package.</p></li>
697
698</ul>
699
700
701
Scott Mainea723292011-02-09 16:01:04 -0800702<h3>Keyboard support</h3>
703
704<ul>
705<li>Support for Control, Meta, Caps Lock, Num Lock and Scroll Lock modifiers. For more information,
706see {@link android.view.KeyEvent#META_CTRL_ON} and related fields.</li>
707
708<li>Support for full desktop-style keyboards, including support for keys such as Escape, Home, End,
709Delete and others. You can determine whether key events are coming from a full keyboard by
710querying {@link android.view.KeyCharacterMap#getKeyboardType()} and checking for {@link
711android.view.KeyCharacterMap#FULL KeyCharacterMap.FULL}</li>
712
713<li>{@link android.widget.TextView} now supports keyboard-based cut, copy, paste, and select-all,
714using the key combinations Ctrl+X, Ctrl+C, Ctrl+V, and Ctrl+A. It also supports PageUp/PageDown,
715Home/End, and keyboard-based text selection.</li>
716
717<li>{@link android.view.KeyEvent} adds several new methods to make it easier to check the key
718modifier state correctly and consistently. See {@link android.view.KeyEvent#hasModifiers(int)},
719{@link android.view.KeyEvent#hasNoModifiers()},
720{@link android.view.KeyEvent#metaStateHasModifiers(int,int) metaStateHasModifiers()},
721{@link android.view.KeyEvent#metaStateHasNoModifiers(int) metaStateHasNoModifiers()}.</li>
722
723<li>Applications can implement custom keyboard shortcuts by subclassing {@link
724android.app.Activity}, {@link android.app.Dialog}, or {@link android.view.View} and implementing
725{@link android.app.Activity#onKeyShortcut onKeyShortcut()}. The framework calls this method
726whenever a key is combined with Ctrl key. When creating an <a
727href="{@docRoot}guide/topics/ui/menus.html#options-menu">Options Menu</a>, you can register keyboard
728shortcuts by setting either the {@code android:alphabeticShortcut} or {@code
729android:numericShortcut} attribute for each <a
730href="{@docRoot}guide/topics/resources/menu-resource.html#item-element">{@code &lt;item&gt;}</a>
731element (or with {@link android.view.MenuItem#setShortcut setShortcut()}).</li>
732
733<li>Android 3.0 includes a new "virtual keyboard" device with the id {@link
734android.view.KeyCharacterMap#VIRTUAL_KEYBOARD KeyCharacterMap.VIRTUAL_KEYBOARD}. The virtual
735keyboard has a desktop-style US key map which is useful for synthesizing key events for testing
736input.</li>
737
738</ul>
739
740
741
742
743<h3>Split touch events</h3>
744
745<p>Previously, only a single view could accept touch events at one time. Android 3.0
746adds support for splitting touch events across views and even windows, so different views can accept
747simultaneous touch events.</p>
748
749<p>Split touch events is enabled by default when an application targets
750Android 3.0. That is, when the application has set either the <a
751href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a>
752or <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
753android:targetSdkVersion}</a> attribute's value to {@code "11"}.</p>
754
Scott Mainc2299de2011-02-14 11:37:50 -0800755<p>However, the following properties allow you to disable split touch events across views inside
756specific view groups and across windows.</p>
Scott Mainea723292011-02-09 16:01:04 -0800757
758<ul>
759<li>The {@link android.R.attr#splitMotionEvents android:splitMotionEvents} attribute for view groups
Scott Mainc2299de2011-02-14 11:37:50 -0800760allows you to disable split touch events that occur between child views in a layout. For example:
Scott Mainea723292011-02-09 16:01:04 -0800761<pre>
762&lt;LinearLayout android:splitMotionEvents="false" ... >
763 ...
764&lt;/LinearLayout>
765</pre>
Scott Mainc2299de2011-02-14 11:37:50 -0800766<p>This way, child views in the linear layout cannot split touch events&mdash;only one view can
767receive touch events at a time.</p>
Scott Mainea723292011-02-09 16:01:04 -0800768</li>
769
770<li>The {@link android.R.attr#windowEnableSplitTouch android:windowEnableSplitTouch} style property
Scott Mainc2299de2011-02-14 11:37:50 -0800771allows you to disable split touch events across windows, by applying it to a theme for the activity
Scott Mainea723292011-02-09 16:01:04 -0800772or entire application. For example:
773<pre>
774&lt;style name="NoSplitMotionEvents" parent="android:Theme.Holo">
775 &lt;item name="android:windowEnableSplitTouch">false&lt;/item>
776 ...
777&lt;/style>
778</pre>
779<p>When this theme is applied to an <a
780href="{@docRoot}guide/topics/manifest/activity-element.html">{@code &lt;activity&gt;}</a> or <a
781href="{@docRoot}guide/topics/manifest/application-element.html">{@code &lt;application&gt;}</a>,
782only touch events within the current activity window are accepted. For example, by disabling split
783touch events across windows, the system bar cannot receive touch events at the same time as the
Scott Mainc2299de2011-02-14 11:37:50 -0800784activity. This does <em>not</em> affect whether views inside the activity can split touch
785events&mdash;by default, the activity can still split touch events across views.</p>
Scott Mainea723292011-02-09 16:01:04 -0800786
787<p>For more information about creating a theme, read <a
788href="{@docRoot}guide/topics/ui/themes.html">Applying Styles and Themes</a>.</p>
789</li>
790</ul>
791
792
793
794<h3>WebKit</h3>
795
796<ul>
797 <li>New {@link android.webkit.WebViewFragment} class to create a fragment composed of a
798{@link android.webkit.WebView}.</li>
799 <li>New {@link android.webkit.WebSettings} methods:
800 <ul>
801 <li>{@link
802android.webkit.WebSettings#setDisplayZoomControls setDisplayZoomControls()} allows you to hide
803the on-screen zoom controls while still allowing the user to zoom with finger gestures ({@link
804android.webkit.WebSettings#setBuiltInZoomControls setBuiltInZoomControls()} must be set
805{@code true}).</li>
806 <li>New {@link android.webkit.WebSettings} method, {@link
807android.webkit.WebSettings#setEnableSmoothTransition setEnableSmoothTransition()}, allows you
808to enable smooth transitions when panning and zooming. When enabled, WebView will choose a solution
809to maximize the performance (for example, the WebView's content may not update during the
810transition).</li>
811 </ul>
812 <li>New {@link android.webkit.WebView} methods:
813 <ul>
814 <li>{@link android.webkit.WebView#onPause onPause()} callback, to pause any processing
815associated with the WebView when it becomes hidden. This is useful to reduce unnecessary CPU or
816network traffic when the WebView is not in the foreground.</li>
817 <li>{@link android.webkit.WebView#onResume onResume()} callback, to resume processing
818associated with the WebView, which was paused during {@link android.webkit.WebView#onPause
819onPause()}.</li>
820 <li>{@link android.webkit.WebView#saveWebArchive saveWebArchive()} allows you to save the
821current view as a web archive on the device.</li>
822 <li>{@link android.webkit.WebView#showFindDialog showFindDialog()} initiates a text search in
823the current view.</li>
824 </ul>
825 </li>
826</ul>
827
828
829
830<h3>Browser</h3>
831
832<p>The Browser application adds the following features to support web applications:</p>
833
834<ul>
835 <li><b>Media capture</b>
836 <p>As defined by the <a href="http://dev.w3.org/2009/dap/camera/">HTML Media Capture</a>
837specification, the Browser allows web applications to access audio, image and video capture
838capabilities of the device. For example, the following HTML provides an input for the user to
839capture a photo to upload:</p>
840<pre>
841&lt;input type="file" accept="image/*;capture=camera" />
842</pre>
843<p>Or by excluding the {@code capture=camera} parameter, the user can choose to either capture a
844new image with the camera or select one from the device (such as from the Gallery application).</p>
845 </li>
846
847 <li><b>Device Orientation</b>
848 <p>As defined by the <a
849href="http://dev.w3.org/geo/api/spec-source-orientation.html">Device Orientation Event</a>
850specification, the Browser allows web applications to listen to DOM events that provide information
851about the physical orientation and motion of the device.</p>
852 <p>The device orientation is expressed with the x, y, and z axes, in degrees and motion is
853expressed with acceleration and rotation rate data. A web page can register for orientation
854events by calling {@code window.addEventListener} with event type {@code "deviceorientation"}
855and register for motion events by registering the {@code "devicemotion"} event type.</p>
856 </li>
857
858 <li><b>CSS 3D Transforms</b>
859 <p>As defined by the <a href="http://www.w3.org/TR/css3-3d-transforms/">CSS 3D Transform
860Module</a> specification, the Browser allows elements rendered by CSS to be transformed in three
861dimensions.</p>
862 </li>
863</ul>
864
865
866
867<h3>JSON utilities</h3>
868
869<p>New classes, {@link android.util.JsonReader} and {@link android.util.JsonWriter}, help you
Scott Main2788e4f2011-02-23 10:54:31 -0800870read and write JSON streams. The new APIs complement the {@link org.json} classes, which manipulate
871a document in memory.</p>
Scott Mainea723292011-02-09 16:01:04 -0800872
873<p>You can create an instance of {@link android.util.JsonReader} by calling
874its constructor method and passing the {@link java.io.InputStreamReader} that feeds the JSON string.
875Then begin reading an object by calling {@link android.util.JsonReader#beginObject()}, read a
876key name with {@link android.util.JsonReader#nextName()}, read the value using methods
877respective to the type, such as {@link android.util.JsonReader#nextString()} and {@link
878android.util.JsonReader#nextInt()}, and continue doing so while {@link
879android.util.JsonReader#hasNext()} is true.</p>
880
881<p>You can create an instance of {@link android.util.JsonWriter} by calling its constructor and
882passing the appropriate {@link java.io.OutputStreamWriter}. Then write the JSON data in a manner
883similar to the reader, using {@link android.util.JsonWriter#name name()} to add a property name
884and an appropriate {@link android.util.JsonWriter#value value()} method to add the respective
885value.</p>
886
887<p>These classes are strict by default. The {@link android.util.JsonReader#setLenient setLenient()}
888method in each class configures them to be more liberal in what they accept. This lenient
889parse mode is also compatible with the {@link org.json}'s default parser.</p>
890
891
892
893
894<h3>New feature constants</h3>
895
896<p>The <a
897href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code &lt;uses-feature&gt;}</a>
898manfest element should be used to inform external entities (such as Android Market) of the set of
899hardware and software features on which your application depends. In this release, Android adds the
900following new constants that applications can declare with this element:</p>
901
902<ul>
903 <li>{@link android.content.pm.PackageManager#FEATURE_FAKETOUCH "android.hardware.faketouch"}
904 <p>When declared, this indicates that the application is compatible with a device that offers an
905emulated touchscreen (or better). A device that offers an emulated touchscreen provides a user input
906system that can emulate a subset of touchscreen
907capabilities. An example of such an input system is a mouse or remote control that drives an
908on-screen cursor. Such input systems support basic touch events like click down, click up, and drag.
909However, more complicated input types (such as gestures, flings, etc.) may be more difficult or
910impossible on faketouch devices (and multitouch gestures are definitely not possible).</p>
911 <p>If your application does <em>not</em> require complicated gestures and you do
912<em>not</em> want your application filtered from devices with an emulated touchscreen, you
913should declare {@link
914android.content.pm.PackageManager#FEATURE_FAKETOUCH "android.hardware.faketouch"} with a <a
915href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code &lt;uses-feature&gt;}</a>
916element. This way, your application will be available to the greatest number of device types,
917including those that provide only an emulated touchscreen input.</p>
918 <p>All devices that include a touchscreen also support {@link
919android.content.pm.PackageManager#FEATURE_FAKETOUCH "android.hardware.faketouch"}, because
920touchscreen capabilities are a superset of faketouch capabilities. Thus, unless you actually require
921a touchscreen, you should add a <a
922href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code &lt;uses-feature&gt;}</a>
923element for faketouch.</p>
924 </li>
925</ul>
926
927
928
929
930<h3>New permissions</h3>
931
932<ul>
933 <li>{@link android.Manifest.permission#BIND_REMOTEVIEWS
934"android.permission.BIND_REMOTEVIEWS"}
935 <p>This must be declared as a required permission in the <a
936href="{@docRoot}guide/topics/manifest/service-element.html">{@code &lt;service&gt;}</a> manifest
937element for an implementation of {@link android.widget.RemoteViewsService}. For example, when
938creating an App Widget that uses {@link android.widget.RemoteViewsService} to populate a
939collection view, the manifest entry may look like this:</p>
940<pre>
941&lt;service android:name=".widget.WidgetService"
942 android:exported="false"
943 android:permission="android.permission.BIND_REMOTEVIEWS" />
944</pre>
945</ul>
946
947
948
949<h3>New platform technologies</h3>
950
951<ul>
952<li><strong>Storage</strong>
953 <ul>
954 <li>ext4 file system support to enable onboard eMMC storage.</li>
955 <li>FUSE file system to support MTP devices.</li>
956 <li>USB host mode support to support keyboards and USB hubs.</li>
957 <li>Support for MTP/PTP </li>
958 </ul>
959</li>
960
961<li><strong>Linux Kernel</strong>
962 <ul>
963 <li>Upgraded to 2.6.36</li>
964 </ul>
965</li>
966
967<li><strong>Dalvik VM</strong>
968 <ul>
969 <li>New code to support and optimize for SMP</li>
970 <li>Various improvements to the JIT infrastructure</li>
971 <li>Garbage collector improvements:
972 <ul>
973 <li>Tuned for SMP</li>
974 <li>Support for larger heap sizes</li>
975 <li>Unified handling for bitmaps and byte buffers</li>
976 </ul>
977 </li>
978 </ul>
979</li>
980
981<li><strong>Dalvik Core Libraries</strong>
982 <ul>
983 <li>New, much faster implementation of NIO (modern I/O library)</li>
984 <li>Improved exception messages</li>
985 <li>Correctness and performance fixes throughout</li>
986 </ul>
987</li>
988</ul>
989
990
991
992<h3 id="api-diff">API differences report</h3>
993
994<p>For a detailed view of all API changes in Android {@sdkPlatformVersion} (API Level
995{@sdkPlatformApiLevel}), see the <a
996href="{@docRoot}sdk/api_diff/{@sdkPlatformApiLevel}/changes.html">API Differences Report</a>.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800997
998
999
1000
1001
1002<h2 id="api-level">API Level</h2>
1003
Scott Mainea723292011-02-09 16:01:04 -08001004<p>The Android {@sdkPlatformVersion} platform delivers an updated version of
1005the framework API. The Android {@sdkPlatformVersion} API
1006is assigned an integer identifier &mdash;
1007<strong>{@sdkPlatformApiLevel}</strong> &mdash; that is
1008stored in the system itself. This identifier, called the "API Level", allows the
1009system to correctly determine whether an application is compatible with
1010the system, prior to installing the application. </p>
Scott Main7fb538c2011-01-19 21:11:50 -08001011
Scott Mainea723292011-02-09 16:01:04 -08001012<p>To use APIs introduced in Android {@sdkPlatformVersion} in your application,
1013you need compile the application against the Android library that is provided in
1014the Android {@sdkPlatformVersion} SDK platform. Depending on your needs, you might
1015also need to add an <code>android:minSdkVersion="{@sdkPlatformApiLevel}"</code>
1016attribute to the <code>&lt;uses-sdk&gt;</code> element in the application's
1017manifest. If your application is designed to run only on Android 2.3 and higher,
1018declaring the attribute prevents the application from being installed on earlier
1019versions of the platform.</p>
Scott Main7fb538c2011-01-19 21:11:50 -08001020
Scott Mainea723292011-02-09 16:01:04 -08001021<p>For more information about how to use API Level, see the <a
1022href="{@docRoot}guide/appendix/api-levels.html">API Levels</a> document. </p>
Scott Main7fb538c2011-01-19 21:11:50 -08001023
1024
1025<h2 id="apps">Built-in Applications</h2>
1026
1027<p>The system image included in the downloadable platform provides these
1028built-in applications:</p>
1029
1030<table style="border:0;padding-bottom:0;margin-bottom:0;">
1031<tr>
1032<td style="border:0;padding-bottom:0;margin-bottom:0;">
1033<ul>
Scott Mainea723292011-02-09 16:01:04 -08001034<li>API Demos</li>
Scott Main7fb538c2011-01-19 21:11:50 -08001035<li>Browser</li>
1036<li>Calculator</li>
1037<li>Camera</li>
1038<li>Clock</li>
1039<li>Contacts</li>
1040<li>Custom Locale</li>
1041<li>Dev Tools</li>
1042<li>Downloads</li>
1043<li>Email</li>
1044</ul>
1045</td>
1046<td style="border:0;padding-bottom:0;margin-bottom:0;padding-left:5em;">
1047<ul>
1048<li>Gallery</li>
Scott Mainea723292011-02-09 16:01:04 -08001049<li>Gestures Builder</li>
1050<li>Messaging</li>
Scott Main7fb538c2011-01-19 21:11:50 -08001051<li>Music</li>
1052<li>Search</li>
1053<li>Settings</li>
Scott Mainea723292011-02-09 16:01:04 -08001054<li>Spare Parts</li>
Scott Main7fb538c2011-01-19 21:11:50 -08001055<li>Speech Recorder</li>
Scott Mainea723292011-02-09 16:01:04 -08001056<li>Widget Preview</li>
Scott Main7fb538c2011-01-19 21:11:50 -08001057</ul>
1058</td>
1059</tr>
1060</table>
1061
1062
1063<h2 id="locs" style="margin-top:.75em;">Locales</h2>
1064
1065<p>The system image included in the downloadable SDK platform provides a variety of
1066built-in locales. In some cases, region-specific strings are available for the
1067locales. In other cases, a default version of the language is used. The
1068languages that are available in the Android 3.0 system
1069image are listed below (with <em>language</em>_<em>country/region</em> locale
1070descriptor).</p>
1071
1072<table style="border:0;padding-bottom:0;margin-bottom:0;">
1073<tr>
1074<td style="border:0;padding-bottom:0;margin-bottom:0;">
1075<ul>
1076<li>Arabic, Egypt (ar_EG)</li>
1077<li>Arabic, Israel (ar_IL)</li>
1078<li>Bulgarian, Bulgaria (bg_BG)</li>
1079<li>Catalan, Spain (ca_ES)</li>
1080<li>Czech, Czech Republic (cs_CZ)</li>
1081<li>Danish, Denmark(da_DK)</li>
1082<li>German, Austria (de_AT)</li>
1083<li>German, Switzerland (de_CH)</li>
1084<li>German, Germany (de_DE)</li>
1085<li>German, Liechtenstein (de_LI)</li>
1086<li>Greek, Greece (el_GR)</li>
1087<li>English, Australia (en_AU)</li>
1088<li>English, Canada (en_CA)</li>
1089<li>English, Britain (en_GB)</li>
1090<li>English, Ireland (en_IE)</li>
1091<li>English, India (en_IN)</li>
1092<li>English, New Zealand (en_NZ)</li>
1093<li>English, Singapore(en_SG)</li>
1094<li>English, US (en_US)</li>
1095<li>English, Zimbabwe (en_ZA)</li>
1096<li>Spanish (es_ES)</li>
1097<li>Spanish, US (es_US)</li>
1098<li>Finnish, Finland (fi_FI)</li>
1099<li>French, Belgium (fr_BE)</li>
1100<li>French, Canada (fr_CA)</li>
1101<li>French, Switzerland (fr_CH)</li>
1102<li>French, France (fr_FR)</li>
1103<li>Hebrew, Israel (he_IL)</li>
1104<li>Hindi, India (hi_IN)</li>
1105</ul>
1106</td>
1107<td style="border:0;padding-bottom:0;margin-bottom:0;padding-left:5em;">
1108<li>Croatian, Croatia (hr_HR)</li>
1109<li>Hungarian, Hungary (hu_HU)</li>
1110<li>Indonesian, Indonesia (id_ID)</li>
1111<li>Italian, Switzerland (it_CH)</li>
1112<li>Italian, Italy (it_IT)</li>
1113<li>Japanese (ja_JP)</li>
1114<li>Korean (ko_KR)</li>
1115<li>Lithuanian, Lithuania (lt_LT)</li>
1116<li>Latvian, Latvia (lv_LV)</li>
1117<li>Norwegian bokmål, Norway (nb_NO)</li>
1118<li>Dutch, Belgium (nl_BE)</li>
1119<li>Dutch, Netherlands (nl_NL)</li>
1120<li>Polish (pl_PL)</li>
1121<li>Portuguese, Brazil (pt_BR)</li>
1122<li>Portuguese, Portugal (pt_PT)</li>
1123<li>Romanian, Romania (ro_RO)</li>
1124<li>Russian (ru_RU)</li></li>
1125<li>Slovak, Slovakia (sk_SK)</li>
1126<li>Slovenian, Slovenia (sl_SI)</li>
1127<li>Serbian (sr_RS)</li>
1128<li>Swedish, Sweden (sv_SE)</li>
1129<li>Thai, Thailand (th_TH)</li>
1130<li>Tagalog, Philippines (tl_PH)</li>
1131<li>Turkish, Turkey (tr_TR)</li>
1132<li>Ukrainian, Ukraine (uk_UA)</li>
1133<li>Vietnamese, Vietnam (vi_VN)</li>
1134<li>Chinese, PRC (zh_CN)</li>
1135<li>Chinese, Taiwan (zh_TW)</li>
1136</td>
1137</tr>
1138</table>
1139
1140<p class="note"><strong>Note:</strong> The Android platform may support more
1141locales than are included in the SDK system image. All of the supported locales
1142are available in the <a href="http://source.android.com/">Android Open Source
1143Project</a>.</p>
1144
1145<h2 id="skins">Emulator Skins</h2>
1146
1147<p>The downloadable platform includes the following emulator skin:</p>
1148
1149<ul>
1150 <li>
1151 WXGA (1280x800, medium density, xlarge screen)
1152 </li>
1153</ul>
1154
1155<p>For more information about how to develop an application that displays
1156and functions properly on all Android-powered devices, see <a
1157href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple
1158Screens</a>.</p>