blob: 6c88146d7c846c4b0e14409babe7fb082a4e09cf [file] [log] [blame]
Scott Maind41ff8e2011-01-21 14:51:33 -08001page.title=Android 3.0 Platform Preview
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 Mainadaf5a72011-02-16 15:52:38 -080028 <li><a href="{@docRoot}sdk/android-3.0-optimize.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 Mainadaf5a72011-02-16 15:52:38 -080051<p>Also see the <a href="{@docRoot}sdk/android-3.0-optimize.html">Optimizing Apps for Android
523.0</a> document for information about how to optimize your existing applications for Android 3.0
53devices, even if you want to remain compatible with previous versions.</p>
54
Scott Maind41ff8e2011-01-21 14:51:33 -080055
56
Scott Mainea723292011-02-09 16:01:04 -080057<h2 id="relnotes">Revisions</h2>
Scott Main7fb538c2011-01-19 21:11:50 -080058
Scott Mainea723292011-02-09 16:01:04 -080059<p>To determine what revision of the Android {@sdkPlatformVersion} platform you have installed,
60refer to the "Installed Packages" listing in the Android SDK and AVD Manager.</p>
61
62
63<div class="toggle-content opened" style="padding-left:1em;">
64
65 <p><a href="#" onclick="return toggleContent(this)">
66 <img src="{@docRoot}assets/images/triangle-opened.png" class="toggle-content-img" alt="" />
67 Android {@sdkPlatformVersion}, Revision 1</a> <em>(February 2011)</em>
68 </a></p>
69
70 <div class="toggle-content-toggleme" style="padding-left:2em;">
71
72<dl>
73
74<dt>Dependencies:</dt>
75<dd>
76<p>Requires <a href="{@docRoot}sdk/tools-notes.html">SDK Tools r10</a> or higher.</p>
77</dd>
78
79</dl>
80
81 </div>
82</div>
Scott Main7fb538c2011-01-19 21:11:50 -080083
84
85
86<h2 id="#api">API Overview</h2>
87
88<p>The sections below provide a technical overview of what's new for developers in Android 3.0,
89including new features and changes in the framework API since the previous version.</p>
90
91
Scott Mainea723292011-02-09 16:01:04 -080092
93
94
Scott Main7fb538c2011-01-19 21:11:50 -080095<h3>Fragments</h3>
96
97<p>A fragment is a new framework component that allows you to separate distinct elements of an
98activity into self-contained modules that define their own UI and lifecycle. To create a
99fragment, you must extend the {@link android.app.Fragment} class and implement several lifecycle
100callback methods, similar to an {@link android.app.Activity}. You can then combine multiple
101fragments in a single activity to build a multi-pane UI in which each
102pane manages its own lifecycle and user inputs.</p>
103
104<p>You can also use a fragment without providing a UI and instead use the fragment as a worker
105for the activity, such as to manage the progress of a download that occurs only while the
106activity is running.</p>
107
108<p>Additionally:</p>
109
110<ul>
Scott Mainea723292011-02-09 16:01:04 -0800111 <li>Fragments are self-contained and you can reuse them in multiple activities</li>
112 <li>You can add, remove, replace and animate fragments inside the activity</li>
113 <li>You can add fragments to a back stack managed by the activity, preserving the state of
Scott Main7fb538c2011-01-19 21:11:50 -0800114fragments as they are changed and allowing the user to navigate backward through the different
115states</li>
116 <li>By <a
117href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">providing
Scott Main7afdaf02011-01-25 13:03:30 -0800118alternative layouts</a>, you can mix and match fragments, based
Scott Main7fb538c2011-01-19 21:11:50 -0800119on the screen size and orientation</li>
120 <li>Fragments have direct access to their container activity and can contribute items to the
121activity's Action Bar (discussed next)</li>
122</ul>
123
124<p>To manage the fragments in your activity, you must use the {@link
125android.app.FragmentManager}, which provides several APIs for interacting with fragments, such
Scott Mainea723292011-02-09 16:01:04 -0800126as finding fragments in the activity and popping fragments off the back stack to restore their
127previous state.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800128
Scott Main7afdaf02011-01-25 13:03:30 -0800129<p>To perform a transaction, such as add or remove a fragment, you must create a {@link
Scott Main7fb538c2011-01-19 21:11:50 -0800130android.app.FragmentTransaction}. You can then call methods such as {@link
131android.app.FragmentTransaction#add add()} {@link android.app.FragmentTransaction#remove
Scott Main7afdaf02011-01-25 13:03:30 -0800132remove()}, or {@link android.app.FragmentTransaction#replace replace()}. Once you've applied all
Scott Main7fb538c2011-01-19 21:11:50 -0800133the changes you want to perform for the transaction, you must call {@link
Scott Main7afdaf02011-01-25 13:03:30 -0800134android.app.FragmentTransaction#commit commit()} and the system applies the fragment transaction to
Scott Main7fb538c2011-01-19 21:11:50 -0800135the activity.</p>
136
Scott Main7afdaf02011-01-25 13:03:30 -0800137<p>For more information about using fragments, read the <a
Scott Main64b12ea2011-02-14 13:41:03 -0800138href="{@docRoot}guide/topics/fundamentals/fragments.html">Fragments</a> documentation. Several
139samples are also available in the <a
140href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/index.html#Fragment">
141API Demos</a> application.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800142
143
144
145
146<h3>Action Bar</h3>
147
Scott Main7afdaf02011-01-25 13:03:30 -0800148<p>The Action Bar is a replacement for the traditional title bar at the top of the activity window.
149It includes the application logo in the left corner and provides a new interface for items in the
Scott Mainea723292011-02-09 16:01:04 -0800150<a href="{@docRoot}guide/topics/ui/menus.html#options-menu">Options Menu</a>. Additionally, the
151Action Bar allows you to:</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800152
153<ul>
Scott Mainea723292011-02-09 16:01:04 -0800154 <li>Add menu items directly in the Action Bar&mdash;as "action items."
155 <p>In your XML declaration for the menu item, include the {@code
156android:showAsAction} attribute with a value of {@code "ifRoom"}. When there's enough room, the menu
157item appears directly in the Action Bar. Otherwise, the item is placed in the
158overflow menu, revealed by the menu icon on the right side of the Action Bar.</p></li>
Scott Main7afdaf02011-01-25 13:03:30 -0800159
Scott Mainea723292011-02-09 16:01:04 -0800160 <li>Replace an action item with a widget (such as a search box)&mdash;creating an
161"action view."
162 <p>In the XML declaration for the menu item, add the {@code android:actionViewLayout} attribute
163with a layout resource or the {@code android:actionViewClass} attribute with the class name of a
164widget. (You must also declare the {@code android:showAsAction} attribute so that the item appears
165in the Action Bar.) If there's not enough room in the Action Bar and the item appears in the
166overflow menu, it behaves like a regular menu item and does not show the widget.</p></li>
Scott Main7afdaf02011-01-25 13:03:30 -0800167
Scott Mainea723292011-02-09 16:01:04 -0800168 <li>Add an action to the application logo and replace it with a custom logo
Scott Main7fb538c2011-01-19 21:11:50 -0800169 <p>The application logo is automatically assigned the {@code android.R.id.home} ID,
Scott Mainea723292011-02-09 16:01:04 -0800170which the system delivers to your activity's {@link android.app.Activity#onOptionsItemSelected
171onOptionsItemSelected()} callback when touched. Simply respond to this ID in your callback
Scott Main7fb538c2011-01-19 21:11:50 -0800172method to perform an action such as go to your application's "home" activity.</p>
Scott Mainea723292011-02-09 16:01:04 -0800173 <p>To replace the icon with a logo, specify your application logo in the manifest file with the
174<a href="{@docRoot}guide/topics/manifest/application-element.html#logo">{@code android:logo}</a>
175attribute, then call {@link android.app.ActionBar#setDisplayUseLogoEnabled
176setDisplayUseLogoEnabled(true)} in your activity.</p></li>
Scott Main7afdaf02011-01-25 13:03:30 -0800177
Scott Mainea723292011-02-09 16:01:04 -0800178 <li>Add breadcrumbs to navigate backward through the back stack of fragments</li>
179 <li>Add tabs or a drop-down list to navigate through fragments</li>
180 <li>Customize the Action Bar with themes and backgrounds</li>
Scott Main7fb538c2011-01-19 21:11:50 -0800181</ul>
182
Scott Mainea723292011-02-09 16:01:04 -0800183<p>The Action Bar is standard for all applications that use the new holographic theme, which is
184also standard when you set either the <a
Scott Main7fb538c2011-01-19 21:11:50 -0800185href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code
186android:minSdkVersion}</a> or <a
187href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
Scott Mainea723292011-02-09 16:01:04 -0800188android:targetSdkVersion}</a> to {@code "11"}.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800189
Scott Main7afdaf02011-01-25 13:03:30 -0800190<p>For more information about the Action Bar, read the <a
Scott Main64b12ea2011-02-14 13:41:03 -0800191href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> documentation. Several
192samples are also available in the <a
193href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/index.html#ActionBar">
194API Demos</a> application.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800195
196
197
198
199<h3>System clipboard</h3>
200
201<p>Applications can now copy and paste data (beyond mere text) to and from the system-wide
202clipboard. Clipped data can be plain text, a URI, or an intent.</p>
203
Scott Mainea723292011-02-09 16:01:04 -0800204<p>By providing the system access to the data you want the user to copy, through a content provider,
205the user can copy complex content (such as an image or data structure) from your application and
206paste it into another application that supports that type of content.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800207
208<p>To start using the clipboard, get the global {@link android.content.ClipboardManager} object
209by calling {@link android.content.Context#getSystemService getSystemService(CLIPBOARD_SERVICE)}.</p>
210
Scott Mainea723292011-02-09 16:01:04 -0800211<p>To copy an item to the clipboard, you need to create a new {@link
Scott Main7fb538c2011-01-19 21:11:50 -0800212android.content.ClipData} object, which holds one or more {@link android.content.ClipData.Item}
Scott Mainea723292011-02-09 16:01:04 -0800213objects, each describing a single entity. To create a {@link android.content.ClipData} object
214containing just one {@link android.content.ClipData.Item}, you can use one of the helper methods,
215such as {@link android.content.ClipData#newPlainText newPlainText()}, {@link
Scott Main7fb538c2011-01-19 21:11:50 -0800216android.content.ClipData#newUri newUri()}, and {@link android.content.ClipData#newIntent
217newIntent()}, which each return a {@link android.content.ClipData} object pre-loaded with the
Scott Mainea723292011-02-09 16:01:04 -0800218{@link android.content.ClipData.Item} you provide.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800219
220<p>To add the {@link android.content.ClipData} to the clipboard, pass it to {@link
221android.content.ClipboardManager#setPrimaryClip setPrimaryClip()} for your instance of {@link
222android.content.ClipboardManager}.</p>
223
Scott Mainea723292011-02-09 16:01:04 -0800224<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 -0800225android.content.ClipboardManager#getPrimaryClip()} on the {@link
226android.content.ClipboardManager}. Handling the {@link android.content.ClipData} you receive can
Scott Mainea723292011-02-09 16:01:04 -0800227be complicated and you need to be sure you can actually handle the data type in the clipboard
228before attempting to paste it.</p>
229
230<p>The clipboard holds only one piece of clipped data (a {@link android.content.ClipData}
231object) at a time, but one {@link android.content.ClipData} can contain multiple {@link
232android.content.ClipData.Item}s.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800233
Scott Main64b12ea2011-02-14 13:41:03 -0800234<p>For more information, read the <a href="{@docRoot}guide/topics/clipboard/copy-paste.html">Copy
235and Paste</a> documentation. You can also see a simple implementation of copy and paste in the <a
236href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/content/ClipboardSample.
237html">API Demos</a> and a more complete implementation in the <a
238href="{@docRoot}resources/samples/NotePad/index.html">Note Pad</a> application.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800239
240
241
242
243<h3>Drag and drop</h3>
244
Scott Mainea723292011-02-09 16:01:04 -0800245<p>New APIs simplify drag and drop operations in your application's user interface. A drag
246operation is the transfer of some kind of data&mdash;carried in a {@link android.content.ClipData}
247object&mdash;from one place to another. The start and end point for the drag operation is a {@link
248android.view.View}, so the APIs that directly handle the drag and drop operations are
249in the {@link android.view.View} class.</p>
250
251<p>A drag and drop operation has a lifecycle that's defined by several drag actions&mdash;each
252defined by a {@link android.view.DragEvent} object&mdash;such as {@link
253android.view.DragEvent#ACTION_DRAG_STARTED}, {@link android.view.DragEvent#ACTION_DRAG_ENTERED}, and
254{@link android.view.DragEvent#ACTION_DROP}. Each view that wants to participate in a drag
255operation can listen for these actions.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800256
Scott Maind41ff8e2011-01-21 14:51:33 -0800257<p>To begin dragging content in your activity, call {@link android.view.View#startDrag startDrag()}
258on a {@link android.view.View}, providing a {@link android.content.ClipData} object that represents
Scott Mainea723292011-02-09 16:01:04 -0800259the data to drag, a {@link android.view.View.DragShadowBuilder} to facilitate the "shadow"
260that users see under their fingers while dragging, and an {@link java.lang.Object} that can share
261information about the drag object with views that may receive the object.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800262
Scott Mainea723292011-02-09 16:01:04 -0800263<p>To accept a drag object in a {@link android.view.View} (receive the "drop"), register the view
264with an {@link android.view.View.OnDragListener OnDragListener} by calling {@link
265android.view.View#setOnDragListener setOnDragListener()}. When a drag event occurs on the view, the
266system calls {@link android.view.View.OnDragListener#onDrag onDrag()} for the {@link
Scott Main7afdaf02011-01-25 13:03:30 -0800267android.view.View.OnDragListener OnDragListener}, which receives a {@link android.view.DragEvent}
Scott Mainea723292011-02-09 16:01:04 -0800268describing the type of drag action has occurred (such as {@link
269android.view.DragEvent#ACTION_DRAG_STARTED}, {@link android.view.DragEvent#ACTION_DRAG_ENTERED}, and
270{@link android.view.DragEvent#ACTION_DROP}). During a drag, the system repeatedly calls {@link
271android.view.View.OnDragListener#onDrag onDrag()} for the view underneath the drag, to deliver a
272stream of drag events. The receiving view can inquire the event type delivered to {@link
273android.view.View#onDragEvent onDragEvent()} by calling {@link android.view.DragEvent#getAction
274getAction()} on the {@link android.view.DragEvent}.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800275
Scott Mainea723292011-02-09 16:01:04 -0800276<p class="note"><strong>Note:</strong> Although a drag event may carry a {@link
277android.content.ClipData} object, this is not related to the system clipboard. A drag and drop
278operation should never put the dragged data in the system clipboard.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800279
Scott Main64b12ea2011-02-14 13:41:03 -0800280<p>For more information, read the <a href="{@docRoot}guide/topics/ui/drag-drop.html">Dragging and
281Dropping</a> documentation. You can also see an implementation of drag and drop in the <a
282href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/DragAndDropDemo.html">
283API Demos</a> application and the <a
284href="{@docRoot}resources/samples/HoneycombGallery/index.html">Honeycomb Gallery</a>
285application.</p>
286
Scott Main7fb538c2011-01-19 21:11:50 -0800287
288
Scott Maind41ff8e2011-01-21 14:51:33 -0800289<h3>App widgets</h3>
Scott Main7fb538c2011-01-19 21:11:50 -0800290
Scott Mainea723292011-02-09 16:01:04 -0800291<p>Android 3.0 supports several new widget classes for more interactive app widgets on the users
292Home screen, including: {@link android.widget.GridView}, {@link android.widget.ListView}, {@link
293android.widget.StackView}, {@link android.widget.ViewFlipper}, and {@link
294android.widget.AdapterViewFlipper}.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800295
Scott Mainea723292011-02-09 16:01:04 -0800296<p>More importantly, you can use the new {@link android.widget.RemoteViewsService} to create app
297widgets with collections, using widgets such as {@link android.widget.GridView}, {@link
298android.widget.ListView}, and {@link android.widget.StackView} that are backed by remote data,
299such as from a content provider.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800300
Scott Main5a44efb2011-02-15 10:45:46 -0800301<p>The {@link android.appwidget.AppWidgetProviderInfo} class (defined in XML with an {@code
302&lt;appwidget-provider&gt;} element) also supports two new fields: {@link
Scott Maind41ff8e2011-01-21 14:51:33 -0800303android.appwidget.AppWidgetProviderInfo#autoAdvanceViewId} and {@link
304android.appwidget.AppWidgetProviderInfo#previewImage}. The {@link
Scott Main7fb538c2011-01-19 21:11:50 -0800305android.appwidget.AppWidgetProviderInfo#autoAdvanceViewId} field lets you specify the view ID of the
Scott Mainea723292011-02-09 16:01:04 -0800306app widget subview that should be auto-advanced by the app widget’s host. The
Scott Main7fb538c2011-01-19 21:11:50 -0800307{@link android.appwidget.AppWidgetProviderInfo#previewImage} field specifies a preview of what the
Scott Main7afdaf02011-01-25 13:03:30 -0800308app 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 -0800309supplied, the app widget's icon is used for the preview.</p>
310
Scott Mainea723292011-02-09 16:01:04 -0800311<p>To help create a preview image for your app widget (to specify in the {@link
312android.appwidget.AppWidgetProviderInfo#autoAdvanceViewId} field), the Android emulator includes an
313application called "Widget Preview." To create a preview image, launch this application, select the
314app widget for your application and set it up how you'd like your preview image to appear, then save
315it and place it in your application's drawable resources.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800316
Scott Main64b12ea2011-02-14 13:41:03 -0800317<p>You can see an implementation of the new app widget features in the <a
318href="{@docRoot}resources/samples/StackWidget/index.html">StackView App Widget</a> and <a
319href="{@docRoot}resources/samples/WeatherListWidget/index.html">Weather List Widget</a>
320applications.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800321
322
323
Scott Maind41ff8e2011-01-21 14:51:33 -0800324<h3>Status bar notifications</h3>
Scott Main7fb538c2011-01-19 21:11:50 -0800325
326<p>The {@link android.app.Notification} APIs have been extended to support more content-rich status
327bar notifications, plus a new {@link android.app.Notification.Builder} class allows you to easily
Scott Mainea723292011-02-09 16:01:04 -0800328create {@link android.app.Notification} objects.</p>
Scott Main7afdaf02011-01-25 13:03:30 -0800329<p>New features include:</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800330<ul>
Scott Main7afdaf02011-01-25 13:03:30 -0800331 <li>Support for a large icon in the notification, using {@link
332android.app.Notification.Builder#setLargeIcon setLargeIcon()}. This is usually for
Scott Main7fb538c2011-01-19 21:11:50 -0800333social applications to show the contact photo of the person who is the source of the
Scott Main7afdaf02011-01-25 13:03:30 -0800334notification or for media apps to show an album thumbnail.</li>
Scott Main7fb538c2011-01-19 21:11:50 -0800335 <li>Support for custom layouts in the status bar ticker, using {@link
336android.app.Notification.Builder#setTicker(CharSequence,RemoteViews) setTicker()}.</li>
337 <li>Support for custom notification layouts to include buttons with {@link
Scott Mainea723292011-02-09 16:01:04 -0800338android.app.PendingIntent}s, for more interactive notification widgets. For example, a
339notification can control music playback without starting an activity.</li>
Scott Main7fb538c2011-01-19 21:11:50 -0800340</ul>
341
342
343
Scott Maind41ff8e2011-01-21 14:51:33 -0800344<h3>Content loaders</h3>
Scott Main7fb538c2011-01-19 21:11:50 -0800345
Scott Maind41ff8e2011-01-21 14:51:33 -0800346<p>New framework APIs facilitate asynchronous loading of data using the {@link
347android.content.Loader} class. You can use it in combination with UI components such as views and
Scott Main7afdaf02011-01-25 13:03:30 -0800348fragments to dynamically load data from worker threads. The {@link
Scott Mainea723292011-02-09 16:01:04 -0800349android.content.CursorLoader} subclass is specially designed to help you do so for data backed by
350a {@link android.content.ContentProvider}.</p>
Scott Maind41ff8e2011-01-21 14:51:33 -0800351
Scott Mainea723292011-02-09 16:01:04 -0800352<p>All you need to do is implement the {@link android.app.LoaderManager.LoaderCallbacks
353LoaderCallbacks} interface to receive callbacks when a new loader is requested or the data has
354changed, then call {@link android.app.LoaderManager#initLoader initLoader()} to initialize the
355loader for your activity or fragment.</p>
Scott Maind41ff8e2011-01-21 14:51:33 -0800356
Scott Main64b12ea2011-02-14 13:41:03 -0800357<p>For more information, read the <a
Scott Maina5647452011-02-15 17:25:26 -0800358href="{@docRoot}guide/topics/fundamentals/loaders.html">Loaders</a> documentation. You can also see
Scott Main64b12ea2011-02-14 13:41:03 -0800359example code using loaders in the <a
Scott Main13033ea2011-02-15 13:18:30 -0800360href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/FragmentListCursorLoader.html">FragmentListCursorLoader</a>
361and <a
Scott Main64b12ea2011-02-14 13:41:03 -0800362href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LoaderThrottle.html">
363LoaderThrottle</a> samples.</p>
Scott Maind41ff8e2011-01-21 14:51:33 -0800364
365
366
367<h3>Bluetooth A2DP and headset APIs</h3>
368
369<p>Android now includes APIs for applications to verify the state of connected Bluetooth A2DP and
Scott Main7afdaf02011-01-25 13:03:30 -0800370headset profile devices. For example, applications can identify when a Bluetooth headset is
371connected for listening to music and notify the user as appropriate. Applications can also receive
372broadcasts for vendor specific AT commands and notify the user about the state of the connected
373device, such as when the connected device's battery is low.</p>
374
375<p>You can initialize the respective {@link android.bluetooth.BluetoothProfile} by calling {@link
Scott Maind41ff8e2011-01-21 14:51:33 -0800376android.bluetooth.BluetoothAdapter#getProfileProxy getProfileProxy()} with either the {@link
377android.bluetooth.BluetoothProfile#A2DP} or {@link android.bluetooth.BluetoothProfile#HEADSET}
378profile constant and a {@link android.bluetooth.BluetoothProfile.ServiceListener} to receive
Scott Main7afdaf02011-01-25 13:03:30 -0800379callbacks when the Bluetooth client is connected or disconnected.</p>
Scott Maind41ff8e2011-01-21 14:51:33 -0800380
381
382
383
Scott Mainea723292011-02-09 16:01:04 -0800384<h3 id="animation">Animation framework</h3>
Scott Maind41ff8e2011-01-21 14:51:33 -0800385
Scott Main7afdaf02011-01-25 13:03:30 -0800386<p>An all new flexible animation framework allows you to animate arbitrary properties of any object
Scott Mainea723292011-02-09 16:01:04 -0800387(View, Drawable, Fragment, Object, or anything else). It allows you to define several aspects of an
Scott Main7afdaf02011-01-25 13:03:30 -0800388animation, such as:</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800389<ul>
390 <li>Duration</li>
391 <li>Repeat amount and behavior</li>
392 <li>Type of time interpolation</li>
393 <li>Animator sets to play animations together, sequentially, or after specified delays</li>
394 <li>Frame refresh delay</li>
395</ul>
Scott Main7fb538c2011-01-19 21:11:50 -0800396
Scott Mainea723292011-02-09 16:01:04 -0800397 <p>You can define these animation aspects, and others, for an object's int, float, and hexadecimal
398color values, by default. That is, when an object has a property field for one of these types, you
399can change its value over time to affect an animation. To animate any other type of value, you tell
400the system how to calculate the values for that given type, by implementing the {@link
401android.animation.TypeEvaluator} interface.</p>
402
403<p>There are two animators you can use to animate the values of a property: {@link
Scott Main7fb538c2011-01-19 21:11:50 -0800404android.animation.ValueAnimator} and {@link android.animation.ObjectAnimator}. The {@link
405android.animation.ValueAnimator} computes the animation values, but is not aware of the specific
406object or property that is animated as a result. It simply performs the calculations, and you must
407listen for the updates and process the data with your own logic. The {@link
408android.animation.ObjectAnimator} is a subclass of {@link android.animation.ValueAnimator} and
Scott Maind41ff8e2011-01-21 14:51:33 -0800409allows you to set the object and property to animate, and it handles all animation work.
410That is, you give the {@link android.animation.ObjectAnimator} the object to animate, the
411property 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 -0800412time, then start the animation.</p>
Scott Maind41ff8e2011-01-21 14:51:33 -0800413
414<p>Additionally, the {@link android.animation.LayoutTransition} class enables automatic transition
Scott Main7afdaf02011-01-25 13:03:30 -0800415animations for changes you make to your activity layout. To enable transitions for part of the
416layout, create a {@link android.animation.LayoutTransition} object and set it on
Scott Maind41ff8e2011-01-21 14:51:33 -0800417any {@link android.view.ViewGroup} by calling {@link
418android.view.ViewGroup#setLayoutTransition setLayoutTransition()}. This causes default
419animations to run whenever items are added to or removed from the group. To specify custom
420animations, call {@link android.animation.LayoutTransition#setAnimator setAnimator()} on the {@link
Scott Main7afdaf02011-01-25 13:03:30 -0800421android.animation.LayoutTransition} and provide a custom {@link android.animation.Animator},
Scott Maind41ff8e2011-01-21 14:51:33 -0800422such as a {@link android.animation.ValueAnimator} or {@link android.animation.ObjectAnimator}
423discussed above.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800424
425<p>For more information, see the <a
Scott Main64b12ea2011-02-14 13:41:03 -0800426href="{@docRoot}guide/topics/graphics/animation.html">Property Animation</a> documentation. You can
427also see several samples using the animation APIs in the <a
428href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/animation/index.html">API
429Demos</a> application.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800430
431
432
433
Scott Maind41ff8e2011-01-21 14:51:33 -0800434<h3>Extended UI framework</h3>
Scott Main7fb538c2011-01-19 21:11:50 -0800435
436<ul>
437
Scott Maind41ff8e2011-01-21 14:51:33 -0800438 <li><b>Multiple-choice selection for ListView and GridView</b>
Scott Main7fb538c2011-01-19 21:11:50 -0800439
Scott Maind41ff8e2011-01-21 14:51:33 -0800440<p>New {@link android.widget.AbsListView#CHOICE_MODE_MULTIPLE_MODAL} mode for {@link
Scott Mainea723292011-02-09 16:01:04 -0800441android.widget.AbsListView#setChoiceMode setChoiceMode()} allows users to select multiple items
442from a {@link android.widget.ListView} or {@link android.widget.GridView}. When used in
443conjunction with the Action Bar, users can select multiple items and then select the action to
444perform from a list of options in the Action Bar (which has transformed into a Multi-choice
445Action Mode).</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800446
Scott Maind41ff8e2011-01-21 14:51:33 -0800447<p>To enable multiple-choice selection, call {@link
448android.widget.AbsListView#setChoiceMode setChoiceMode(CHOICE_MODE_MULTIPLE_MODAL)} and register a
449{@link android.widget.AbsListView.MultiChoiceModeListener MultiChoiceModeListener} with {@link
450android.widget.AbsListView#setMultiChoiceModeListener setMultiChoiceModeListener()}.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800451
Scott Maind41ff8e2011-01-21 14:51:33 -0800452<p>When the user performs a long-press on an item, the Action Bar switches to the Multi-choice
453Action Mode. The system notifies the {@link android.widget.AbsListView.MultiChoiceModeListener
454MultiChoiceModeListener} when items are selected by calling {@link
455android.widget.AbsListView.MultiChoiceModeListener#onItemCheckedStateChanged
456onItemCheckedStateChanged()}.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800457
Scott Maind41ff8e2011-01-21 14:51:33 -0800458<p>For an example of multiple-choice selection, see the <a
459href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/List15.html">List15.
460java</a>
461class in the API Demos sample application.</p>
462 </li>
Scott Main7fb538c2011-01-19 21:11:50 -0800463
Scott Maind41ff8e2011-01-21 14:51:33 -0800464
465 <li><b>New APIs to transform views</b>
466
Scott Mainea723292011-02-09 16:01:04 -0800467 <p>New APIs allow you to easily apply 2D and 3D transformations to views in your activity
468layout. New transformations are made possible with a set of object properties that define the view's
Scott Maind41ff8e2011-01-21 14:51:33 -0800469layout position, orientation, transparency and more.</p>
Scott Mainea723292011-02-09 16:01:04 -0800470 <p>New methods to set the view properties include: {@link android.view.View#setAlpha
471setAlpha()}, {@link
Scott Maind41ff8e2011-01-21 14:51:33 -0800472android.view.View#setBottom setBottom()}, {@link android.view.View#setLeft setLeft()}, {@link
473android.view.View#setRight setRight()}, {@link android.view.View#setBottom setBottom()}, {@link
474android.view.View#setPivotX setPivotX()}, {@link android.view.View#setPivotY setPivotY()}, {@link
475android.view.View#setRotationX setRotationX()}, {@link android.view.View#setRotationY
476setRotationY()}, {@link android.view.View#setScaleX setScaleX()}, {@link android.view.View#setScaleY
477setScaleY()}, {@link android.view.View#setAlpha setAlpha()}, and others.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800478
Scott Maind41ff8e2011-01-21 14:51:33 -0800479 <p>Some methods also have a corresponding XML attribute that you can specify in your layout
Scott Mainea723292011-02-09 16:01:04 -0800480file, to apply a default transformation. Available attributes include: {@code translationX}, {@code
481translationY}, {@code rotation},
Scott Maind41ff8e2011-01-21 14:51:33 -0800482{@code rotationX}, {@code rotationY}, {@code scaleX}, {@code scaleY}, {@code transformPivotX},
483{@code transformPivotY}, and {@code alpha}.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800484
Scott Mainea723292011-02-09 16:01:04 -0800485 <p>Using some of these new view properties in combination with the new <a
486href="#animation">animation framework</a> (discussed
487above), you can easily apply some fancy animations to your views. For example, to rotate a
Scott Maind41ff8e2011-01-21 14:51:33 -0800488view on its y-axis, supply {@link android.animation.ObjectAnimator} with the {@link
Scott Mainea723292011-02-09 16:01:04 -0800489android.view.View}, the "rotationY" property, and the start and end values:</p>
Scott Maind41ff8e2011-01-21 14:51:33 -0800490<pre>
491ObjectAnimator animator = ObjectAnimator.ofFloat(myView, "rotationY", 0, 360);
492animator.setDuration(2000);
493animator.start();
494</pre>
495 </li>
Scott Main7fb538c2011-01-19 21:11:50 -0800496
Scott Maind41ff8e2011-01-21 14:51:33 -0800497
498 <li><b>New holographic themes</b>
Scott Main7fb538c2011-01-19 21:11:50 -0800499
Scott Mainea723292011-02-09 16:01:04 -0800500 <p>The standard system widgets and overall look have been redesigned and incorporate a new
501"holographic" user interface theme. The system applies the new theme
502using the standard <a href="{@docRoot}guide/topics/ui/themes.html">style and theme</a> system.</p>
503
504<p>Any application that targets the Android 3.0 platform&mdash;by setting either the <a
505href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a>
506or <a
507href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
508android:targetSdkVersion}</a> value to {@code "11"}&mdash;inherits the holographic theme by default.
509However, if your application also applies its own theme, then your theme will override the
510holographic theme, unless you update your styles to inherit the holographic theme.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800511
512<p>To apply the holographic theme to individual activities or to inherit them in your own theme
Scott Main7afdaf02011-01-25 13:03:30 -0800513definitions, use one of several new {@link android.R.style#Theme_Holo Theme.Holo}
Scott Mainea723292011-02-09 16:01:04 -0800514themes. If your application is compatible with version of Android lower than 3.0 and applies
515custom themes, then you should <a
516href="{@docRoot}guide/topics/ui/themes.html#SelectATheme">select a theme based on platform
517version</a>.</p>
518
Scott Maind41ff8e2011-01-21 14:51:33 -0800519 </li>
520
521
522 <li><b>New widgets</b>
523
524 <ul>
525 <li>{@link android.widget.AdapterViewAnimator}
526 <p>Base class for an {@link android.widget.AdapterView} that performs animations when switching
527 between its views.</p></li>
528
529 <li>{@link android.widget.AdapterViewFlipper}
530 <p>Simple {@link android.widget.ViewAnimator} that animates between two or more views that have
531 been added to it. Only one child is shown at a time. If requested, it can automatically flip
532 between
533 each child at a regular interval.</p></li>
534
535 <li>{@link android.widget.CalendarView}
Scott Mainea723292011-02-09 16:01:04 -0800536 <p>Allows users to select dates from a calendar by touching the date and can scroll or fling the
537calendar to a desired date. You can configure the range of dates available in the widget.</p></li>
Scott Maind41ff8e2011-01-21 14:51:33 -0800538
539 <li>{@link android.widget.ListPopupWindow}
540 <p>Anchors itself to a host view and displays a list of choices, such as for a list of
541 suggestions when typing into an {@link android.widget.EditText} view.</p></li>
542
543 <li>{@link android.widget.NumberPicker}
Scott Mainea723292011-02-09 16:01:04 -0800544 <p>Enables the user to select a number from a predefined range. The widget presents an input
545field and up and down buttons for selecting a number. Touching the input field allows the user to
546scroll through values or touch again to directly edit the current value. It also allows you to map
547positions to strings, so that the corresponding string is displayed instead of the index
548position.</p></li>
Scott Maind41ff8e2011-01-21 14:51:33 -0800549
550 <li>{@link android.widget.PopupMenu}
551 <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 -0800552popup appears below the anchor view if there is room, or above it if there is not. If the IME (soft
553keyboard) is visible, the popup does not overlap the IME it until the user touches the
554menu.</p></li>
Scott Maind41ff8e2011-01-21 14:51:33 -0800555
556 <li>{@link android.widget.SearchView}
Scott Mainea723292011-02-09 16:01:04 -0800557 <p>Provides a search box that works in conjunction with the Search Manager (in the same manner
558as the traditional <a href="{@docRoot}guide/topics/search/search-dialog.html">search dialog</a>). It
559can also display recent query suggestions or custom suggestions as configured by the search
560provider. This widget is particularly useful for offering search in the <a
561href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a>.</p></li>
Scott Maind41ff8e2011-01-21 14:51:33 -0800562
563 <li>{@link android.widget.StackView}
Scott Mainea723292011-02-09 16:01:04 -0800564 <p>A view that displays its children in a 3D stack and allows users to swipe through
565 views like a rolodex.</p></li>
Scott Maind41ff8e2011-01-21 14:51:33 -0800566
567 </ul>
568 </li>
569
570</ul>
Scott Main7fb538c2011-01-19 21:11:50 -0800571
572
573
Scott Main7fb538c2011-01-19 21:11:50 -0800574<h3>Graphics</h3>
575
576<ul>
Scott Maind41ff8e2011-01-21 14:51:33 -0800577 <li><b>Hardware accelerated 2D graphics</b>
Scott Main7fb538c2011-01-19 21:11:50 -0800578
579<p>You can now enable the OpenGL renderer for your application by setting {@code
580android:hardwareAccelerated="true"} in your manifest element's <a
581href="{@docRoot}guide/topics/manifest/application-element.html">{@code &lt;application&gt;}</a>
582element or for individual <a
583href="{@docRoot}guide/topics/manifest/activity-element.html">{@code &lt;activity&gt;}</a>
584elements.</p>
585
586<p>This flag helps applications by making them draw faster. This results in smoother animations,
587smoother scrolling, and overall better performance and response to user interaction.</p></li>
588
Scott Maind41ff8e2011-01-21 14:51:33 -0800589
590 <li><b>View support for hardware and software layers</b>
591
592 <p>By default, a {@link android.view.View} has no layer specified. You can specify that the
593view be backed by either a hardware or software layer, specified by values {@link
594android.view.View#LAYER_TYPE_HARDWARE} and {@link android.view.View#LAYER_TYPE_SOFTWARE}, using
595{@link android.view.View#setLayerType setLayerType()} or the <a
596href="{@docRoot}reference/android/view/View.html#attr_android:layerType">{@code layerType}</a>
597attribute.</p>
598 <p>A hardware layer is backed by a hardware specific texture (generally Frame Buffer Objects or
599FBO on OpenGL hardware) and causes the view to be rendered using Android's hardware rendering
600pipeline, but only if hardware acceleration is turned on for the view hierarchy. When hardware
601acceleration is turned off, hardware layers behave exactly as software layers.</p>
602 <p>A software layer is backed by a bitmap and causes the view to be rendered using Android's
603software rendering pipeline, even if hardware acceleration is enabled. Software layers should be
604avoided when the affected view tree updates often. Every update will require to re-render the
605software layer, which can potentially be slow.</p>
606 <p>For more information, see the {@link android.view.View#LAYER_TYPE_HARDWARE} and {@link
607android.view.View#LAYER_TYPE_SOFTWARE} documentation.</p>
608 </li>
609
610
611 <li><b>Renderscript 3D graphics engine</b>
Scott Main7fb538c2011-01-19 21:11:50 -0800612
613<p>Renderscript is a runtime 3D framework that provides both an API for building 3D scenes as well
614as a special, platform-independent shader language for maximum performance. Using Renderscript, you
615can accelerate graphics operations and data processing. Renderscript is an ideal way to create
Scott Main64b12ea2011-02-14 13:41:03 -0800616high-performance 3D effects for applications, wallpapers, carousels, and more.</p>
617<p>For more information, see the <a
618href="{@docRoot}guide/topics/graphics/renderscript.html">3D Rendering and Computation with
619Renderscript</a> documentation.</p></li>
Scott Main7fb538c2011-01-19 21:11:50 -0800620</ul>
621
622
623
624
Scott Main7fb538c2011-01-19 21:11:50 -0800625<h3>Media</h3>
626
627
628<ul>
Scott Main7fb538c2011-01-19 21:11:50 -0800629
Scott Main7afdaf02011-01-25 13:03:30 -0800630 <li><b>Time lapse video</b>
Scott Main7fb538c2011-01-19 21:11:50 -0800631
632<p>Camcorder APIs now support the ability to record time lapse video. The {@link
633android.media.MediaRecorder#setCaptureRate setCaptureRate()} sets the rate at which frames
634should be captured.</p></li>
635
Scott Main7afdaf02011-01-25 13:03:30 -0800636 <li><b>Texture support for image streams</b>
637
638<p>New {@link android.graphics.SurfaceTexture} allows you to capture an image stream as an OpenGL ES
639texture. By calling {@link android.hardware.Camera#setPreviewTexture setPreviewTexture()} for your
640{@link android.hardware.Camera} instance, you can specify the {@link
641android.graphics.SurfaceTexture} upon which to draw video playback or preview frames from the
642camera.</p></li>
643
644 <li><b>HTTP Live streaming</b>
645
646<p>Applications can now pass an M3U playlist URL to the media framework to begin an HTTP Live
647streaming session. The media framework supports most of the HTTP Live streaming specification,
Scott Mainea723292011-02-09 16:01:04 -0800648including adaptive bit rate. See the <a
649href="{@docRoot}guide/appendix/media-formats.html">Supported Media Formats</a> document for
650more information.</p></li>
Scott Main7afdaf02011-01-25 13:03:30 -0800651
652 <li><b>EXIF data</b>
653
654<p>The {@link android.media.ExifInterface} includes new fields for photo aperture, ISO, and exposure
655time.</p></li>
656
657 <li><b>Camcorder profiles</b>
658
659<p>New {@link android.media.CamcorderProfile#hasProfile hasProfile()} method and several video
660quality profiles (such as {@link android.media.CamcorderProfile#QUALITY_1080P}, {@link
661android.media.CamcorderProfile#QUALITY_720P}, {@link
662android.media.CamcorderProfile#QUALITY_CIF}, and others) allow you to determine camcorder
663quality options.</p></li>
664
Scott Maind41ff8e2011-01-21 14:51:33 -0800665 <li><b>Digital media file transfer</b>
Scott Main7fb538c2011-01-19 21:11:50 -0800666
667<p>The platform includes built-in support for Media/Picture Transfer Protocol (MTP/PTP) over USB,
668which lets users easily transfer any type of media files between devices and to a host computer.
669Developers can build on this support, creating applications that let users create or manage rich
670media files that they may want to transfer or share across devices. </p></li>
671
Scott Maind41ff8e2011-01-21 14:51:33 -0800672 <li><b>Digital rights management (DRM)</b>
Scott Main7fb538c2011-01-19 21:11:50 -0800673
674<p>New extensible digital rights management (DRM) framework for checking and enforcing digital
675rights. It's implemented in two architectural layers:</p>
676<ul>
677 <li>A DRM framework API, which is exposed to applications and runs through the Dalvik VM for
678standard applications.</li>
679 <li>A native code DRM manager that implements the framework API and exposes an interface for DRM
680plug-ins to handle rights management and decryption for various DRM schemes.</li>
681</ul>
682
683<p>For application developers, the framework offers an abstract, unified API that simplifies the
684management of protected content. The API hides the complexity of DRM operations and allows a
685consistent operation mode for both protected and unprotected content, and across a variety of DRM
686schemes.</p>
687
688<p>For device manufacturers, content owners, and Internet digital media providers the DRM
689framework?s plugin API provides a means of adding support for a DRM scheme of choice into the
690Android system, for secure enforcement of content protection.</p>
691
692<p>The preview release does not provide any native DRM plug-ins for checking and enforcing digital
693rights. However, device manufacturers may ship DRM plug-ins with their devices.</p>
694
695<p>You can find all of the DRM APIs in the {@link android.drm} package.</p></li>
696
697</ul>
698
699
700
Scott Mainea723292011-02-09 16:01:04 -0800701<h3>Keyboard support</h3>
702
703<ul>
704<li>Support for Control, Meta, Caps Lock, Num Lock and Scroll Lock modifiers. For more information,
705see {@link android.view.KeyEvent#META_CTRL_ON} and related fields.</li>
706
707<li>Support for full desktop-style keyboards, including support for keys such as Escape, Home, End,
708Delete and others. You can determine whether key events are coming from a full keyboard by
709querying {@link android.view.KeyCharacterMap#getKeyboardType()} and checking for {@link
710android.view.KeyCharacterMap#FULL KeyCharacterMap.FULL}</li>
711
712<li>{@link android.widget.TextView} now supports keyboard-based cut, copy, paste, and select-all,
713using the key combinations Ctrl+X, Ctrl+C, Ctrl+V, and Ctrl+A. It also supports PageUp/PageDown,
714Home/End, and keyboard-based text selection.</li>
715
716<li>{@link android.view.KeyEvent} adds several new methods to make it easier to check the key
717modifier state correctly and consistently. See {@link android.view.KeyEvent#hasModifiers(int)},
718{@link android.view.KeyEvent#hasNoModifiers()},
719{@link android.view.KeyEvent#metaStateHasModifiers(int,int) metaStateHasModifiers()},
720{@link android.view.KeyEvent#metaStateHasNoModifiers(int) metaStateHasNoModifiers()}.</li>
721
722<li>Applications can implement custom keyboard shortcuts by subclassing {@link
723android.app.Activity}, {@link android.app.Dialog}, or {@link android.view.View} and implementing
724{@link android.app.Activity#onKeyShortcut onKeyShortcut()}. The framework calls this method
725whenever a key is combined with Ctrl key. When creating an <a
726href="{@docRoot}guide/topics/ui/menus.html#options-menu">Options Menu</a>, you can register keyboard
727shortcuts by setting either the {@code android:alphabeticShortcut} or {@code
728android:numericShortcut} attribute for each <a
729href="{@docRoot}guide/topics/resources/menu-resource.html#item-element">{@code &lt;item&gt;}</a>
730element (or with {@link android.view.MenuItem#setShortcut setShortcut()}).</li>
731
732<li>Android 3.0 includes a new "virtual keyboard" device with the id {@link
733android.view.KeyCharacterMap#VIRTUAL_KEYBOARD KeyCharacterMap.VIRTUAL_KEYBOARD}. The virtual
734keyboard has a desktop-style US key map which is useful for synthesizing key events for testing
735input.</li>
736
737</ul>
738
739
740
741
742<h3>Split touch events</h3>
743
744<p>Previously, only a single view could accept touch events at one time. Android 3.0
745adds support for splitting touch events across views and even windows, so different views can accept
746simultaneous touch events.</p>
747
748<p>Split touch events is enabled by default when an application targets
749Android 3.0. That is, when the application has set either the <a
750href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a>
751or <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
752android:targetSdkVersion}</a> attribute's value to {@code "11"}.</p>
753
Scott Mainc2299de2011-02-14 11:37:50 -0800754<p>However, the following properties allow you to disable split touch events across views inside
755specific view groups and across windows.</p>
Scott Mainea723292011-02-09 16:01:04 -0800756
757<ul>
758<li>The {@link android.R.attr#splitMotionEvents android:splitMotionEvents} attribute for view groups
Scott Mainc2299de2011-02-14 11:37:50 -0800759allows you to disable split touch events that occur between child views in a layout. For example:
Scott Mainea723292011-02-09 16:01:04 -0800760<pre>
761&lt;LinearLayout android:splitMotionEvents="false" ... >
762 ...
763&lt;/LinearLayout>
764</pre>
Scott Mainc2299de2011-02-14 11:37:50 -0800765<p>This way, child views in the linear layout cannot split touch events&mdash;only one view can
766receive touch events at a time.</p>
Scott Mainea723292011-02-09 16:01:04 -0800767</li>
768
769<li>The {@link android.R.attr#windowEnableSplitTouch android:windowEnableSplitTouch} style property
Scott Mainc2299de2011-02-14 11:37:50 -0800770allows you to disable split touch events across windows, by applying it to a theme for the activity
Scott Mainea723292011-02-09 16:01:04 -0800771or entire application. For example:
772<pre>
773&lt;style name="NoSplitMotionEvents" parent="android:Theme.Holo">
774 &lt;item name="android:windowEnableSplitTouch">false&lt;/item>
775 ...
776&lt;/style>
777</pre>
778<p>When this theme is applied to an <a
779href="{@docRoot}guide/topics/manifest/activity-element.html">{@code &lt;activity&gt;}</a> or <a
780href="{@docRoot}guide/topics/manifest/application-element.html">{@code &lt;application&gt;}</a>,
781only touch events within the current activity window are accepted. For example, by disabling split
782touch events across windows, the system bar cannot receive touch events at the same time as the
Scott Mainc2299de2011-02-14 11:37:50 -0800783activity. This does <em>not</em> affect whether views inside the activity can split touch
784events&mdash;by default, the activity can still split touch events across views.</p>
Scott Mainea723292011-02-09 16:01:04 -0800785
786<p>For more information about creating a theme, read <a
787href="{@docRoot}guide/topics/ui/themes.html">Applying Styles and Themes</a>.</p>
788</li>
789</ul>
790
791
792
793<h3>WebKit</h3>
794
795<ul>
796 <li>New {@link android.webkit.WebViewFragment} class to create a fragment composed of a
797{@link android.webkit.WebView}.</li>
798 <li>New {@link android.webkit.WebSettings} methods:
799 <ul>
800 <li>{@link
801android.webkit.WebSettings#setDisplayZoomControls setDisplayZoomControls()} allows you to hide
802the on-screen zoom controls while still allowing the user to zoom with finger gestures ({@link
803android.webkit.WebSettings#setBuiltInZoomControls setBuiltInZoomControls()} must be set
804{@code true}).</li>
805 <li>New {@link android.webkit.WebSettings} method, {@link
806android.webkit.WebSettings#setEnableSmoothTransition setEnableSmoothTransition()}, allows you
807to enable smooth transitions when panning and zooming. When enabled, WebView will choose a solution
808to maximize the performance (for example, the WebView's content may not update during the
809transition).</li>
810 </ul>
811 <li>New {@link android.webkit.WebView} methods:
812 <ul>
813 <li>{@link android.webkit.WebView#onPause onPause()} callback, to pause any processing
814associated with the WebView when it becomes hidden. This is useful to reduce unnecessary CPU or
815network traffic when the WebView is not in the foreground.</li>
816 <li>{@link android.webkit.WebView#onResume onResume()} callback, to resume processing
817associated with the WebView, which was paused during {@link android.webkit.WebView#onPause
818onPause()}.</li>
819 <li>{@link android.webkit.WebView#saveWebArchive saveWebArchive()} allows you to save the
820current view as a web archive on the device.</li>
821 <li>{@link android.webkit.WebView#showFindDialog showFindDialog()} initiates a text search in
822the current view.</li>
823 </ul>
824 </li>
825</ul>
826
827
828
829<h3>Browser</h3>
830
831<p>The Browser application adds the following features to support web applications:</p>
832
833<ul>
834 <li><b>Media capture</b>
835 <p>As defined by the <a href="http://dev.w3.org/2009/dap/camera/">HTML Media Capture</a>
836specification, the Browser allows web applications to access audio, image and video capture
837capabilities of the device. For example, the following HTML provides an input for the user to
838capture a photo to upload:</p>
839<pre>
840&lt;input type="file" accept="image/*;capture=camera" />
841</pre>
842<p>Or by excluding the {@code capture=camera} parameter, the user can choose to either capture a
843new image with the camera or select one from the device (such as from the Gallery application).</p>
844 </li>
845
846 <li><b>Device Orientation</b>
847 <p>As defined by the <a
848href="http://dev.w3.org/geo/api/spec-source-orientation.html">Device Orientation Event</a>
849specification, the Browser allows web applications to listen to DOM events that provide information
850about the physical orientation and motion of the device.</p>
851 <p>The device orientation is expressed with the x, y, and z axes, in degrees and motion is
852expressed with acceleration and rotation rate data. A web page can register for orientation
853events by calling {@code window.addEventListener} with event type {@code "deviceorientation"}
854and register for motion events by registering the {@code "devicemotion"} event type.</p>
855 </li>
856
857 <li><b>CSS 3D Transforms</b>
858 <p>As defined by the <a href="http://www.w3.org/TR/css3-3d-transforms/">CSS 3D Transform
859Module</a> specification, the Browser allows elements rendered by CSS to be transformed in three
860dimensions.</p>
861 </li>
862</ul>
863
864
865
866<h3>JSON utilities</h3>
867
868<p>New classes, {@link android.util.JsonReader} and {@link android.util.JsonWriter}, help you
869read and write JSON streams. The new APIs compliment the {@link org.json} classes which manipulate a
870document in memory.</p>
871
872<p>You can create an instance of {@link android.util.JsonReader} by calling
873its constructor method and passing the {@link java.io.InputStreamReader} that feeds the JSON string.
874Then begin reading an object by calling {@link android.util.JsonReader#beginObject()}, read a
875key name with {@link android.util.JsonReader#nextName()}, read the value using methods
876respective to the type, such as {@link android.util.JsonReader#nextString()} and {@link
877android.util.JsonReader#nextInt()}, and continue doing so while {@link
878android.util.JsonReader#hasNext()} is true.</p>
879
880<p>You can create an instance of {@link android.util.JsonWriter} by calling its constructor and
881passing the appropriate {@link java.io.OutputStreamWriter}. Then write the JSON data in a manner
882similar to the reader, using {@link android.util.JsonWriter#name name()} to add a property name
883and an appropriate {@link android.util.JsonWriter#value value()} method to add the respective
884value.</p>
885
886<p>These classes are strict by default. The {@link android.util.JsonReader#setLenient setLenient()}
887method in each class configures them to be more liberal in what they accept. This lenient
888parse mode is also compatible with the {@link org.json}'s default parser.</p>
889
890
891
892
893<h3>New feature constants</h3>
894
895<p>The <a
896href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code &lt;uses-feature&gt;}</a>
897manfest element should be used to inform external entities (such as Android Market) of the set of
898hardware and software features on which your application depends. In this release, Android adds the
899following new constants that applications can declare with this element:</p>
900
901<ul>
902 <li>{@link android.content.pm.PackageManager#FEATURE_FAKETOUCH "android.hardware.faketouch"}
903 <p>When declared, this indicates that the application is compatible with a device that offers an
904emulated touchscreen (or better). A device that offers an emulated touchscreen provides a user input
905system that can emulate a subset of touchscreen
906capabilities. An example of such an input system is a mouse or remote control that drives an
907on-screen cursor. Such input systems support basic touch events like click down, click up, and drag.
908However, more complicated input types (such as gestures, flings, etc.) may be more difficult or
909impossible on faketouch devices (and multitouch gestures are definitely not possible).</p>
910 <p>If your application does <em>not</em> require complicated gestures and you do
911<em>not</em> want your application filtered from devices with an emulated touchscreen, you
912should declare {@link
913android.content.pm.PackageManager#FEATURE_FAKETOUCH "android.hardware.faketouch"} with a <a
914href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code &lt;uses-feature&gt;}</a>
915element. This way, your application will be available to the greatest number of device types,
916including those that provide only an emulated touchscreen input.</p>
917 <p>All devices that include a touchscreen also support {@link
918android.content.pm.PackageManager#FEATURE_FAKETOUCH "android.hardware.faketouch"}, because
919touchscreen capabilities are a superset of faketouch capabilities. Thus, unless you actually require
920a touchscreen, you should add a <a
921href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code &lt;uses-feature&gt;}</a>
922element for faketouch.</p>
923 </li>
924</ul>
925
926
927
928
929<h3>New permissions</h3>
930
931<ul>
932 <li>{@link android.Manifest.permission#BIND_REMOTEVIEWS
933"android.permission.BIND_REMOTEVIEWS"}
934 <p>This must be declared as a required permission in the <a
935href="{@docRoot}guide/topics/manifest/service-element.html">{@code &lt;service&gt;}</a> manifest
936element for an implementation of {@link android.widget.RemoteViewsService}. For example, when
937creating an App Widget that uses {@link android.widget.RemoteViewsService} to populate a
938collection view, the manifest entry may look like this:</p>
939<pre>
940&lt;service android:name=".widget.WidgetService"
941 android:exported="false"
942 android:permission="android.permission.BIND_REMOTEVIEWS" />
943</pre>
944</ul>
945
946
947
948<h3>New platform technologies</h3>
949
950<ul>
951<li><strong>Storage</strong>
952 <ul>
953 <li>ext4 file system support to enable onboard eMMC storage.</li>
954 <li>FUSE file system to support MTP devices.</li>
955 <li>USB host mode support to support keyboards and USB hubs.</li>
956 <li>Support for MTP/PTP </li>
957 </ul>
958</li>
959
960<li><strong>Linux Kernel</strong>
961 <ul>
962 <li>Upgraded to 2.6.36</li>
963 </ul>
964</li>
965
966<li><strong>Dalvik VM</strong>
967 <ul>
968 <li>New code to support and optimize for SMP</li>
969 <li>Various improvements to the JIT infrastructure</li>
970 <li>Garbage collector improvements:
971 <ul>
972 <li>Tuned for SMP</li>
973 <li>Support for larger heap sizes</li>
974 <li>Unified handling for bitmaps and byte buffers</li>
975 </ul>
976 </li>
977 </ul>
978</li>
979
980<li><strong>Dalvik Core Libraries</strong>
981 <ul>
982 <li>New, much faster implementation of NIO (modern I/O library)</li>
983 <li>Improved exception messages</li>
984 <li>Correctness and performance fixes throughout</li>
985 </ul>
986</li>
987</ul>
988
989
990
991<h3 id="api-diff">API differences report</h3>
992
993<p>For a detailed view of all API changes in Android {@sdkPlatformVersion} (API Level
994{@sdkPlatformApiLevel}), see the <a
995href="{@docRoot}sdk/api_diff/{@sdkPlatformApiLevel}/changes.html">API Differences Report</a>.</p>
Scott Main7fb538c2011-01-19 21:11:50 -0800996
997
998
999
1000
1001<h2 id="api-level">API Level</h2>
1002
Scott Mainea723292011-02-09 16:01:04 -08001003<p>The Android {@sdkPlatformVersion} platform delivers an updated version of
1004the framework API. The Android {@sdkPlatformVersion} API
1005is assigned an integer identifier &mdash;
1006<strong>{@sdkPlatformApiLevel}</strong> &mdash; that is
1007stored in the system itself. This identifier, called the "API Level", allows the
1008system to correctly determine whether an application is compatible with
1009the system, prior to installing the application. </p>
Scott Main7fb538c2011-01-19 21:11:50 -08001010
Scott Mainea723292011-02-09 16:01:04 -08001011<p>To use APIs introduced in Android {@sdkPlatformVersion} in your application,
1012you need compile the application against the Android library that is provided in
1013the Android {@sdkPlatformVersion} SDK platform. Depending on your needs, you might
1014also need to add an <code>android:minSdkVersion="{@sdkPlatformApiLevel}"</code>
1015attribute to the <code>&lt;uses-sdk&gt;</code> element in the application's
1016manifest. If your application is designed to run only on Android 2.3 and higher,
1017declaring the attribute prevents the application from being installed on earlier
1018versions of the platform.</p>
Scott Main7fb538c2011-01-19 21:11:50 -08001019
Scott Mainea723292011-02-09 16:01:04 -08001020<p>For more information about how to use API Level, see the <a
1021href="{@docRoot}guide/appendix/api-levels.html">API Levels</a> document. </p>
Scott Main7fb538c2011-01-19 21:11:50 -08001022
1023
1024<h2 id="apps">Built-in Applications</h2>
1025
1026<p>The system image included in the downloadable platform provides these
1027built-in applications:</p>
1028
1029<table style="border:0;padding-bottom:0;margin-bottom:0;">
1030<tr>
1031<td style="border:0;padding-bottom:0;margin-bottom:0;">
1032<ul>
Scott Mainea723292011-02-09 16:01:04 -08001033<li>API Demos</li>
Scott Main7fb538c2011-01-19 21:11:50 -08001034<li>Browser</li>
1035<li>Calculator</li>
1036<li>Camera</li>
1037<li>Clock</li>
1038<li>Contacts</li>
1039<li>Custom Locale</li>
1040<li>Dev Tools</li>
1041<li>Downloads</li>
1042<li>Email</li>
1043</ul>
1044</td>
1045<td style="border:0;padding-bottom:0;margin-bottom:0;padding-left:5em;">
1046<ul>
1047<li>Gallery</li>
Scott Mainea723292011-02-09 16:01:04 -08001048<li>Gestures Builder</li>
1049<li>Messaging</li>
Scott Main7fb538c2011-01-19 21:11:50 -08001050<li>Music</li>
1051<li>Search</li>
1052<li>Settings</li>
Scott Mainea723292011-02-09 16:01:04 -08001053<li>Spare Parts</li>
Scott Main7fb538c2011-01-19 21:11:50 -08001054<li>Speech Recorder</li>
Scott Mainea723292011-02-09 16:01:04 -08001055<li>Widget Preview</li>
Scott Main7fb538c2011-01-19 21:11:50 -08001056</ul>
1057</td>
1058</tr>
1059</table>
1060
1061
1062<h2 id="locs" style="margin-top:.75em;">Locales</h2>
1063
1064<p>The system image included in the downloadable SDK platform provides a variety of
1065built-in locales. In some cases, region-specific strings are available for the
1066locales. In other cases, a default version of the language is used. The
1067languages that are available in the Android 3.0 system
1068image are listed below (with <em>language</em>_<em>country/region</em> locale
1069descriptor).</p>
1070
1071<table style="border:0;padding-bottom:0;margin-bottom:0;">
1072<tr>
1073<td style="border:0;padding-bottom:0;margin-bottom:0;">
1074<ul>
1075<li>Arabic, Egypt (ar_EG)</li>
1076<li>Arabic, Israel (ar_IL)</li>
1077<li>Bulgarian, Bulgaria (bg_BG)</li>
1078<li>Catalan, Spain (ca_ES)</li>
1079<li>Czech, Czech Republic (cs_CZ)</li>
1080<li>Danish, Denmark(da_DK)</li>
1081<li>German, Austria (de_AT)</li>
1082<li>German, Switzerland (de_CH)</li>
1083<li>German, Germany (de_DE)</li>
1084<li>German, Liechtenstein (de_LI)</li>
1085<li>Greek, Greece (el_GR)</li>
1086<li>English, Australia (en_AU)</li>
1087<li>English, Canada (en_CA)</li>
1088<li>English, Britain (en_GB)</li>
1089<li>English, Ireland (en_IE)</li>
1090<li>English, India (en_IN)</li>
1091<li>English, New Zealand (en_NZ)</li>
1092<li>English, Singapore(en_SG)</li>
1093<li>English, US (en_US)</li>
1094<li>English, Zimbabwe (en_ZA)</li>
1095<li>Spanish (es_ES)</li>
1096<li>Spanish, US (es_US)</li>
1097<li>Finnish, Finland (fi_FI)</li>
1098<li>French, Belgium (fr_BE)</li>
1099<li>French, Canada (fr_CA)</li>
1100<li>French, Switzerland (fr_CH)</li>
1101<li>French, France (fr_FR)</li>
1102<li>Hebrew, Israel (he_IL)</li>
1103<li>Hindi, India (hi_IN)</li>
1104</ul>
1105</td>
1106<td style="border:0;padding-bottom:0;margin-bottom:0;padding-left:5em;">
1107<li>Croatian, Croatia (hr_HR)</li>
1108<li>Hungarian, Hungary (hu_HU)</li>
1109<li>Indonesian, Indonesia (id_ID)</li>
1110<li>Italian, Switzerland (it_CH)</li>
1111<li>Italian, Italy (it_IT)</li>
1112<li>Japanese (ja_JP)</li>
1113<li>Korean (ko_KR)</li>
1114<li>Lithuanian, Lithuania (lt_LT)</li>
1115<li>Latvian, Latvia (lv_LV)</li>
1116<li>Norwegian bokmål, Norway (nb_NO)</li>
1117<li>Dutch, Belgium (nl_BE)</li>
1118<li>Dutch, Netherlands (nl_NL)</li>
1119<li>Polish (pl_PL)</li>
1120<li>Portuguese, Brazil (pt_BR)</li>
1121<li>Portuguese, Portugal (pt_PT)</li>
1122<li>Romanian, Romania (ro_RO)</li>
1123<li>Russian (ru_RU)</li></li>
1124<li>Slovak, Slovakia (sk_SK)</li>
1125<li>Slovenian, Slovenia (sl_SI)</li>
1126<li>Serbian (sr_RS)</li>
1127<li>Swedish, Sweden (sv_SE)</li>
1128<li>Thai, Thailand (th_TH)</li>
1129<li>Tagalog, Philippines (tl_PH)</li>
1130<li>Turkish, Turkey (tr_TR)</li>
1131<li>Ukrainian, Ukraine (uk_UA)</li>
1132<li>Vietnamese, Vietnam (vi_VN)</li>
1133<li>Chinese, PRC (zh_CN)</li>
1134<li>Chinese, Taiwan (zh_TW)</li>
1135</td>
1136</tr>
1137</table>
1138
1139<p class="note"><strong>Note:</strong> The Android platform may support more
1140locales than are included in the SDK system image. All of the supported locales
1141are available in the <a href="http://source.android.com/">Android Open Source
1142Project</a>.</p>
1143
1144<h2 id="skins">Emulator Skins</h2>
1145
1146<p>The downloadable platform includes the following emulator skin:</p>
1147
1148<ul>
1149 <li>
1150 WXGA (1280x800, medium density, xlarge screen)
1151 </li>
1152</ul>
1153
1154<p>For more information about how to develop an application that displays
1155and functions properly on all Android-powered devices, see <a
1156href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple
1157Screens</a>.</p>